kubectl Debug Cheat Sheet

Every kubectl command an on-call reaches for under a 3am page. Grouped by use case so you don't have to think, just type.

Triage in 30 seconds

Start wide, then narrow. The first three commands tell you whether the cluster is actually broken or just one pod misbehaving.

• kubectl get pods -A --field-selector=status.phase!=Running, every non-Running pod across all namespaces
• kubectl get events -A --sort-by=.lastTimestamp | tail -40, last 40 events cluster-wide, freshest at the bottom
• kubectl get nodes -o wide, node Ready state, kubelet version, IPs
• kubectl describe pod <pod> -n <ns>, events, conditions, container restart count
• kubectl get pod <pod> -n <ns> -o yaml, full spec when describe isn't enough
• kubectl rollout status deploy/<name> -n <ns>, is the rollout actually finished?
• kubectl rollout history deploy/<name> -n <ns>, revisions you can roll back to
• kubectl rollout undo deploy/<name> -n <ns>, instant rollback to previous revision

Logs

Most incidents resolve in this section. Tail the right container, the right time window, and you're 80% done.

• kubectl logs <pod> -n <ns>, current container logs
• kubectl logs <pod> -n <ns> -c <container>, specific container in a multi-container pod
• kubectl logs <pod> -n <ns> -p, previous container's logs (after a crash/restart)
• kubectl logs <pod> -n <ns> -f --tail=200, follow with last 200 lines as context
• kubectl logs <pod> -n <ns> --since=15m, last 15 minutes only
• kubectl logs -l app=api -n <ns> --max-log-requests=10 --tail=100, fan out across all matching pods
• kubectl logs deploy/<name> -n <ns>, picks one ready pod from the deployment

Exec and debug

When logs don't tell you enough, get inside. kubectl debug is criminally underused.

• kubectl exec -it <pod> -n <ns> -- sh, shell in (try bash first, fall back to sh)
• kubectl exec <pod> -n <ns> -- env, print environment without an interactive shell
• kubectl exec <pod> -n <ns> -- cat /etc/resolv.conf, DNS sanity check
• kubectl debug -it <pod> -n <ns> --image=nicolaka/netshoot --target=<container>, ephemeral debug container sharing the target's process namespace; works on distroless
• kubectl debug node/<node> -it --image=nicolaka/netshoot, root shell on a node via debug pod
• kubectl cp <ns>/<pod>:/path/file ./file, pull a file out for offline analysis

Networking

Half of "the app is down" pages are actually networking. Verify the service routes, the endpoints exist, and DNS resolves before you blame the app.

• kubectl get svc -A, services, ClusterIPs, ports
• kubectl get endpoints <svc> -n <ns>, empty endpoints means selector mismatch
• kubectl describe svc <svc> -n <ns>, selector, ports, session affinity
• kubectl port-forward svc/<svc> 8080:80 -n <ns>, bypass ingress to test the service directly
• kubectl port-forward pod/<pod> 8080:8080 -n <ns>, bypass the service to test the pod directly
• kubectl get netpol -A, NetworkPolicies that might be blocking traffic
• kubectl get ingress -A, ingress rules and host mappings

Resource pressure

OOMKills, throttling, evictions. Look here when pods restart on their own or latency spikes for no reason.

• kubectl top pods -A --sort-by=memory, heaviest memory consumers
• kubectl top pods -A --sort-by=cpu, heaviest CPU consumers
• kubectl top nodes, node-level pressure
• kubectl describe node <node>, Allocatable, Allocated, conditions, taints
• kubectl get pods -A -o jsonpath='{range .items[*]}{.metadata.namespace}{"/"}{.metadata.name}{"\t"}{.status.containerStatuses[*].restartCount}{"\n"}{end}' | sort -k2 -nr | head, restart leaderboard
• kubectl get events -A --field-selector reason=OOMKilling, recent OOMKills
• kubectl get events -A --field-selector reason=Evicted, recent evictions

Flags worth memorising

The flags that turn a 5-command investigation into a 1-command answer.

• -o wide, node, IP, and image columns added to get
• -o yaml / -o json, full object for grep/jq
• -o jsonpath='{.spec.containers[*].image}', surgical field extraction
• --watch / -w, stream changes in place
• --field-selector, server-side filter (faster than grep)
• -l key=value, label selector; chain with commas for AND
• --context / --namespace, set explicitly when juggling clusters; kubens + kubectx are worth installing
• --dry-run=client -o yaml, generate manifests without applying