kubectl debug: Usage, Options & Common CI Errors
Drop a tool-laden container into a pod that has no shell.
kubectl debug adds debugging capability to a running pod without rebuilding its image - by attaching an ephemeral container, copying the pod with changes, or shelling into a node. It is the modern answer to "the image is distroless and exec has no shell".
What it does
kubectl debug POD -it --image=busybox attaches an ephemeral container sharing the pod's namespaces, so you get a shell and tools alongside a container that has none. --target=CONTAINER shares that container's process namespace. --copy-to makes a debuggable duplicate (e.g. with the command overridden). node/NAME debugs a node by scheduling a privileged pod onto it.
Common usage
kubectl debug -it my-pod --image=busybox --target=app
kubectl debug node/ip-10-0-1-5 -it --image=ubuntu
kubectl debug my-pod --copy-to=my-pod-debug --image=nicolaka/netshoot -it
kubectl debug -it my-pod --image=curlimages/curl -- curl localhost:8080Common errors in CI
Ephemeral containers require the EphemeralContainers feature (enabled by default on modern clusters); on very old clusters debug fails with "ephemeral containers are disabled". --target needs the container runtime to support process-namespace sharing (containerd/CRI-O do); without it you can attach but not see the target's processes. As always in CI, skip -t when there is no TTY. The ephemeral container cannot be removed from the pod once added. It lingers until the pod is recreated, so debug throwaway/test pods, not long-lived production ones, where practical.