Loading...
Loading...
Debug Kubernetes pods, nodes, and workloads using kubectl debug. Covers ephemeral containers, pod copying, node debugging, debug profiles, and interactive troubleshooting sessions. Use when user mentions kubectl debug, debugging pods, ephemeral containers, node debugging, or interactive troubleshooting in Kubernetes clusters.
npx skill4agent add laurigates/claude-plugins kubectl-debuggingkubectl debug--context# CORRECT: Explicit context
kubectl --context=prod-cluster debug mypod -it --image=busybox
# WRONG: Relying on current context
kubectl debug mypod -it --image=busybox # Which cluster?# Interactive debugging with busybox
kubectl --context=my-context debug mypod -it --image=busybox
# Target specific container's process namespace
kubectl --context=my-context debug mypod -it --image=busybox --target=mycontainer
# Use a specific debug profile
kubectl --context=my-context debug mypod -it --image=busybox --profile=netadmin# Create debug copy
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --image=busybox
# Copy and change container image
kubectl --context=my-context debug mypod --copy-to=mypod-debug --set-image=app=busybox
# Copy and modify command
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --container=myapp -- sh
# Copy on same node
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --same-node --image=busybox# Interactive node debugging (host namespaces, filesystem at /host)
kubectl --context=my-context debug node/mynode -it --image=busybox
# With sysadmin profile for full capabilities
kubectl --context=my-context debug node/mynode -it --image=ubuntu --profile=sysadmin| Profile | Use Case | Capabilities |
|---|---|---|
| Default, unrestricted | Full access (backwards compatible) |
| General purpose | Moderate restrictions |
| Minimal restrictions | Pod security baseline |
| Network troubleshooting | NET_ADMIN capability |
| High security environments | Strictest restrictions |
| System administration | SYS_PTRACE, SYS_ADMIN |
# Network debugging (tcpdump, netstat, ss)
kubectl --context=my-context debug mypod -it --image=nicolaka/netshoot --profile=netadmin
# System debugging (strace, perf)
kubectl --context=my-context debug mypod -it --image=ubuntu --profile=sysadmin| Image | Size | Use Case |
|---|---|---|
| ~1MB | Basic shell, common utilities |
| ~5MB | Shell with apk package manager |
| ~77MB | Full Linux with apt |
| ~350MB | Network debugging (tcpdump, dig, curl, netstat) |
| Varies | Official Kubernetes debug image |
# Add netshoot container for network debugging
kubectl --context=my-context debug mypod -it \
--image=nicolaka/netshoot \
--profile=netadmin
# Inside container:
# - tcpdump -i any port 80
# - dig kubernetes.default
# - curl -v http://service:port
# - ss -tlnp
# - netstat -an# Copy pod with different entrypoint to inspect
kubectl --context=my-context debug mypod -it \
--copy-to=mypod-debug \
--container=app \
-- sh
# Inside: check filesystem, env vars, config files# Target container's process namespace
kubectl --context=my-context debug mypod -it \
--image=busybox \
--target=mycontainer
# Inside: ps aux, /proc inspection# Debug node with host access
kubectl --context=my-context debug node/worker-1 -it \
--image=ubuntu \
--profile=sysadmin
# Inside:
# - Host filesystem at /host
# - chroot /host for full access
# - journalctl, systemctl, dmesg# Create copy, keeping original running
kubectl --context=my-context debug mypod -it \
--copy-to=mypod-debug \
--same-node \
--share-processes \
--image=busybox
# Original pod continues serving traffic
# Debug copy shares storage if on same node| Option | Description |
|---|---|
| Interactive TTY (required for shell access) |
| Debug container image |
| Name for the debug container |
| Share process namespace with this container |
| Create a copy instead of ephemeral container |
| Schedule copy on same node (with |
| Change container images in copy |
| Security profile (legacy, netadmin, sysadmin, etc.) |
| Enable process namespace sharing (default: true with --copy-to) |
| Delete original pod when creating copy |
--copy-to--same-node# List debug pod copies
kubectl --context=my-context get pods | grep -E "debug|copy"
# Delete debug pods
kubectl --context=my-context delete pod mypod-debug