CKAD — kubectl debug
kubectl debug
The kubectl debug command creates a copy of a Pod or adds an ephemeral container for debugging. This is useful when the original container does not have debugging tools installed (no shell, no curl, no ps).
Debug with Ephemeral Container
Add a temporary debug container to a running Pod:
# Add a debug container to a running Pod
kubectl debug my-pod -it --image=busybox:1.36 --target=app
# This creates an ephemeral container that:
# - Runs in the same Pod
# - Shares the process namespace with the target container
# - Has debugging tools available
The --target=app flag shares the process namespace with the app container, so you can see its processes with ps aux.
Debug by Creating a Copy
Create a copy of the Pod for debugging without affecting the original:
# Create a copy of the Pod with a different image
kubectl debug my-pod -it --image=busybox:1.36 --copy-to=my-pod-debug
# Create a copy with a changed command (useful for crash loops)
kubectl debug my-pod -it --image=busybox:1.36 --copy-to=my-pod-debug -- /bin/sh
# Create a copy that shares process namespace
kubectl debug my-pod -it --image=busybox:1.36 --copy-to=my-pod-debug --share-processes
When to use copies: If the Pod is in CrashLoopBackOff, you can’t exec into it because the container keeps restarting. Create a debug copy with a shell command to keep it running, then investigate.
Debug a Node
Start a privileged Pod on a node for host-level debugging:
# Start a privileged Pod on a node for debugging
kubectl debug node/worker-1 -it --image=busybox:1.36
This gives you access to the node’s filesystem at /host and lets you inspect host-level issues.
