kubectl debug (ephemeral containers)

Temporary debug containers added to a running Pod without restarting it. Essential for distroless / minimal images with no shell.

# Attach an ephemeral busybox, sharing its process namespace
kubectl debug pod/mypod -it --image=busybox:1.36.1 --target=app

# Without --target: ephemeral container runs isolated (can't see app processes)
kubectl debug pod/mypod -it --image=busybox:1.36.1
  • --target=<container>: share process namespace of that container
  • Ephemeral container disappears on exit; Pod not restarted
  • Not listed in kubectl get pod READY count

kubectl debug with pod copy 

# Create a copy with a different image (original keeps running)
kubectl debug pod/mypod -it --image=ubuntu:22.04 --copy-to=mypod-debug

# Change specific container's image
kubectl debug pod/mypod -it --image=busybox --copy-to=debug-pod --share-processes
  • --share-processes: all containers in copy share a PID namespace
  • Clean up: kubectl delete pod mypod-debug

When to use which

ScenarioApproach
App has no shell (distroless)debug --target=<container>
Need to inspect running processesdebug --target=<container> with --share-processes
Need to change the image entirelydebug --copy-to=<new-pod>
App crashes before exec is possibledebug --copy-to=<new-pod> with command: ["sleep", "3600"]

Override command in debug copy 

kubectl debug pod/crashing-pod --copy-to=debug --image=nginx:1.25.1 -- sleep 3600
kubectl exec -it debug -- /bin/sh

kubectl cp 

kubectl cp mypod:/etc/config/app.conf ./app.conf
kubectl cp mypod:/var/log/app.log ./app.log -c sidecar
kubectl cp ./app.conf mypod:/tmp/app.conf
kubectl cp ./config/ mypod:/etc/config/
kubectl cp mynamespace/mypod:/path/file.txt ./file.txt
  • Requires tar in the container image: not available in fully distroless images
  • For distroless: use ephemeral debug container first

Exam gotchas

  • --target requires K8s ≥ 1.23 GA: assume supported
  • Without --target, ephemeral container cannot see app processes
  • kubectl cp silently fails on distroless (no tar)
  • Clean up debug pods after use