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.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes