Pod Debug with Ephemeral Containers

Intermediate10 minTrending

Debug running pods using ephemeral debug containers, especially useful for distroless images that lack debugging tools.

Prerequisites

-kubectl configured
-Kubernetes 1.25+ cluster

Steps

Attach an ephemeral debug container to a running pod

Add a temporary debug container with a full toolkit to an existing pod without restarting it.

$ kubectl debug -it <pod-name> --image=busybox --target=<container-name>

The --target flag shares the process namespace with the specified container so you can see its processes.

Debug with a copy of the pod

Create a copy of the pod with a debug container added, useful when you cannot modify the running pod.

$ kubectl debug <pod-name> -it --image=nicolaka/netshoot --copy-to=debug-pod --share-processes

Debug a node directly

Create a privileged pod on a specific node for host-level debugging.

$ kubectl debug node/<node-name> -it --image=ubuntu

This creates a privileged pod with host filesystem access at /host. Use with caution.

Inspect pod events and conditions

View events and conditions to understand why a pod is failing.

$ kubectl describe pod <pod-name> | tail -30

Clean up debug pods

Remove any debug pod copies you created.

$ kubectl delete pod debug-pod

Full Script

full-script.sh

#!/bin/bash
# Pod Debug Workflow
set -euo pipefail

POD=${1:?"Usage: $0 <pod-name> [namespace]"}
NS=${2:-"default"}

echo "=== Pod Status ==="
kubectl get pod "$POD" -n "$NS" -o wide

echo ""
echo "=== Pod Events ==="
kubectl get events -n "$NS" --field-selector "involvedObject.name=$POD" --sort-by='.lastTimestamp' | tail -10

echo ""
echo "=== Container Statuses ==="
kubectl get pod "$POD" -n "$NS" -o jsonpath='{range .status.containerStatuses[*]}{.name}: {.state}{"
"}{end}'

echo ""
echo "=== Debug Commands ==="
echo "Ephemeral:  kubectl debug -it $POD -n $NS --image=busybox --target=<container>"
echo "Pod copy:   kubectl debug $POD -n $NS -it --image=nicolaka/netshoot --copy-to=debug-pod --share-processes"
echo "Logs:       kubectl logs $POD -n $NS --all-containers"

FAQ

Discussion

Loading comments...

#!/bin/bash # Pod Debug Workflow set -euo pipefail POD=${1:?"Usage: $0 <pod-name> [namespace]"} NS=${2:-"default"} echo "=== Pod Status ===" kubectl get pod "$POD" -n "$NS" -o wide echo "" echo "=== Pod Events ===" kubectl get events -n "$NS" --field-selector "involvedObject.name=$POD" --sort-by='.lastTimestamp' | tail -10 echo "" echo "=== Container Statuses ===" kubectl get pod "$POD" -n "$NS" -o jsonpath='{range .status.containerStatuses[*]}{.name}: {.state}{" "}{end}' echo "" echo "=== Debug Commands ===" echo "Ephemeral: kubectl debug -it $POD -n $NS --image=busybox --target=<container>" echo "Pod copy: kubectl debug $POD -n $NS -it --image=nicolaka/netshoot --copy-to=debug-pod --share-processes" echo "Logs: kubectl logs $POD -n $NS --all-containers"