Debugging with kubectl debug

The kubectl debug command provides three distinct debugging strategies: attaching ephemeral containers to running pods, copying pods with modifications, and creating node-level debug sessions.

Debug a Running Pod

Attach a debug container to an existing pod without restarting it:

# Add a debug container with networking tools
kubectl debug -it my-pod --image=nicolaka/netshoot

# Share process namespace with a specific container
kubectl debug -it my-pod --image=busybox --target=app

With --target, you can see the target container's processes using ps and inspect its filesystem under /proc/1/root/.

Copy a Pod for Debugging

Create a modified copy of a pod for safe investigation. The original pod keeps running:

# Copy pod and change its command to a shell
kubectl debug my-pod -it --copy-to=my-pod-debug --container=app -- sh

# Copy pod with a different image
kubectl debug my-pod -it --copy-to=my-pod-debug --set-image=app=ubuntu

# Enable shared process namespace in the copy
kubectl debug my-pod -it --copy-to=my-pod-debug --share-processes --image=busybox

This is useful when you need to start the container with a different entrypoint or replace a broken image.

Debug a Node

Create a privileged pod on a specific node to inspect host-level issues:

kubectl debug node/worker-1 -it --image=ubuntu

Inside the debug pod, the host filesystem is mounted at /host:

# Access host filesystem
chroot /host
systemctl status kubelet
journalctl -u kubelet --since "10 minutes ago"

Cleanup

Ephemeral containers cannot be removed from a running pod. Pod copies and node debug pods should be deleted manually:

kubectl delete pod my-pod-debug

List all debug pods to find leftover sessions:

kubectl get pods | grep debug