patternbashkubernetesTip

kubectl debug: ephemeral containers for live pod debugging

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

kubectl debugephemeral containerdistrolessdebuggingnetshootlive debuggingprocess namespacenetwork namespacetroubleshooting

Problem

A production pod is misbehaving but the container image does not include debugging tools (curl, netstat, strace). You cannot modify the Deployment and redeploy without risk.

Solution

Use kubectl debug to inject an ephemeral container into the running pod. The ephemeral container shares the pod's network and process namespaces.

# Attach a debug container sharing the pod's namespaces
kubectl debug -it <pod-name> \
  --image=nicolaka/netshoot \
  --target=<main-container-name> \
  -- bash

# From inside the debug container you can:
curl localhost:8080/healthz
netstat -tlnp
cat /proc/<pid>/environ

# Debug a node
kubectl debug node/<node-name> \
  -it --image=ubuntu

Why

Production images are often distroless or alpine-based with no shells or tools. Ephemeral containers were added in Kubernetes 1.23 (stable) as a way to attach debugging tooling to running pods without modifying the pod spec or restarting the container.

Gotchas

Ephemeral containers cannot be removed once added — they disappear when the pod restarts
The --target flag is required to share the process namespace with a specific container (otherwise you only see the debug container's own processes)
Ephemeral containers cannot have resource limits set in the same way as regular containers
kubectl debug requires Kubernetes 1.23+ for stable ephemeral containers; older clusters may need --feature-gates=EphemeralContainers=true

Code Snippets

Two approaches: copy-pod debug and ephemeral container injection

# Copy a pod and override the entrypoint for debugging
kubectl debug <pod-name> -it \
  --copy-to=debug-pod \
  --container=<container-name> \
  -- sh

# Inject ephemeral debug container
kubectl debug -it <pod-name> \
  --image=busybox \
  --target=<container-name>

Context

Debugging running pods in production without restarting them or modifying the image

Revisions (0)

No revisions yet.