k8s-debug

Debug Kubernetes Container

Launch an ephemeral debug container attached to a running pod for interactive debugging.

When to Use

• Pod is failing but you need to inspect it live
• Need debugging tools (curl, netstat, tcpdump) not available in production container
• Want to debug without modifying production container image
• Investigating network, process, or filesystem issues in running pod

Pre-flight Checks

Authentication and Context

# Check kubectl context
kubectl config current-context || {
  echo "No kubectl context. Run: kubectl config use-context <context>"
  exit 1
}

# Show current context
echo "K8s Context: $(kubectl config current-context)"

Workflow

1. Launch Debug Container

Basic debug container:

# Attach ephemeral debug container to running pod
kubectl debug -it <pod-name> \
  --image=nicolaka/netshoot \
  --namespace=<namespace>

With specific container target (for multi-container pods):

# Target specific container in pod
kubectl debug -it <pod-name> \
  --image=nicolaka/netshoot \
  --target=<container-name> \
  --namespace=<namespace>

With custom image:

# Use custom debug image
kubectl debug -it <pod-name> \
  --image=ubuntu:latest \
  --namespace=<namespace>

2. Common Debug Commands Inside Container

Once inside the debug container, use these commands:

Network debugging:

# Test HTTP endpoints
curl http://localhost:8080/health
curl -v http://database-service:5432

# Check listening ports
netstat -tulpn

# Capture network traffic
tcpdump -i any port 8080

# DNS resolution
nslookup database-service
dig +short database-service.default.svc.cluster.local

Process inspection:

# List processes
ps aux

# Monitor processes
top

# Check process details
ps aux | grep api-gateway

File system inspection:

# Check application directory
ls -la /app

# View config files
cat /app/config.yaml

# Check environment variables
env | grep API

# Check mounted volumes
df -h
mount | grep /app