Diagnose a crashing or pending Kubernetes pod (describe, events, previous logs, ephemeral debug containers)
domain: kubernetes.io · 9 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Start wide: kubectl get pods -n <namespace> — note STATUS (CrashLoopBackOff, ImagePullBackOff, Pending, OOMKilled shows under reasons) and RESTARTS
Drill in: kubectl describe pod <pod> — read Conditions, per-container State/Last State (exit codes!), and the Events section at the bottom (scheduling failures, image pull errors, probe failures)
Namespace-wide events when describe isn't enough: kubectl get events -n <namespace> --sort-by=.metadata.creationTimestamp
Crash output: kubectl logs <pod> -c <container> --previous — the previous instance's logs usually contain the actual crash reason
Exit code 137 = killed (often OOM; check describe for OOMKilled), 1/2/etc = app error — read the app logs
No shell in the image? Attach an ephemeral debug container: kubectl debug -it <pod> --image=busybox --target=<container>. --target shares the target container's process namespace so you can see its processes
Pending pods are a scheduling problem: describe shows FailedScheduling reasons (insufficient CPU/memory, unsatisfied nodeSelector/affinity, taints). Check node capacity with kubectl describe nodes
Resource usage (needs metrics-server): kubectl top pod <pod>
Official docs: https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/
Known gotchas
Ephemeral containers (kubectl debug on a running pod) need a reasonably current cluster — the feature went stable in Kubernetes v1.25; on older clusters kubectl debug's pod-copy mode (--copy-to) is the fallback
--target must name a CONTAINER in the pod (for process-namespace sharing), not the pod itself; without it you get the debug container but can't see the app's processes
Events are short-lived (roughly 1 hour by default) — a pod that failed overnight may show an empty Events section; capture events promptly or ship them to logging
logs --previous only exists after a restart; a pod stuck Pending or in ImagePullBackOff never started, so there are no logs at all — the answer is in describe/events, not logs
CrashLoopBackOff is a symptom, not a cause: the interesting data is the container's exit code and previous logs
An ephemeral container cannot be removed from the pod once added (it stays until the pod is deleted) and must not hold resources — it's for inspection, not repair
Give your agent this knowledge — and 17,100+ more routes
One MCP install gives any agent live access to the full route map across 5,900+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?