Kubernetes Troubleshooting Index 🛠️
When a Kubernetes workload or node fails, follow the systematic triage flow to isolate whether the failure is at the container, pod, node, network, or storage layer.
Quick Jump by Symptom
| Symptom | Layer | Detailed Playbook |
|---|---|---|
| Pod stuck in CrashLoopBackOff | Container / App | CrashLoopBackOff Playbook |
| Pod stuck in Pending | Scheduling / Capacity | Pod Pending Playbook |
Image pull error (ImagePullBackOff) | Registry / Auth | ImagePullBackOff Playbook |
| Service unreachable / connection timeout | CoreDNS / Kube-Proxy | Service Unreachable Playbook |
| DNS query fails inside Pod | CoreDNS / Resolv | DNS Resolution Playbook |
| Ingress 404 Not Found or 502 Bad Gateway | Gateway / Ingress | 502 Playbook |
| PersistentVolumeClaim stuck in Pending | Storage / CSI | PVC Stuck Playbook |
| Node status is NotReady | Kubelet / Runtime | Node NotReady Playbook |
Conceptual Diagnostic Toolkits
- Troubleshooting Mental Model: How Kubernetes reconciles state and where errors surface.
- kubectl Debug Toolkit: Using
describe,logs --previous,exec, and ephemeral debug containers. - Common Failure Modes Reference: Comprehensive matrix of exit codes, termination signals, and root causes.
External Reference: k8s-500-prod-issues