debug pod

Debug a failing or unhealthy Kubernetes pod by analyzing events, logs, and configuration.

Steps

1. Get pod status: kubectl get pod <name> -n <namespace> -o wide.
2. Describe the pod for events and conditions: kubectl describe pod <name> -n <namespace>.
3. Analyze the pod state:
   • Pending: Check node resources, scheduling constraints, PVC binding.
   • CrashLoopBackOff: Check container logs for startup errors.
   • ImagePullBackOff: Verify image name, tag, and registry credentials.
   • OOMKilled: Check memory limits vs actual usage.
   • Running but unhealthy: Check probe configuration and endpoints.
4. Fetch container logs: kubectl logs <pod> -n <ns> --previous for crash logs.
5. Check resource usage: kubectl top pod <name> -n <namespace>.
6. Verify configuration:
   • ConfigMaps and Secrets are mounted correctly.
   • Environment variables are set.
   • Service account has required permissions.
7. Suggest fixes based on the diagnosis.

Format

Pod: <name> in <namespace>
Status: <status>
Restarts: <count>
Node: <node-name>

Diagnosis:
  Root cause: <description>
  Evidence: <log lines or events>

Fix:
  1. <action to take>
  2. <verification command>

Rules

• Always check events first; they often reveal the root cause immediately.
• Fetch logs from the previous container instance for crash analysis.
• Check node-level issues if multiple pods on the same node are affected.
• Verify DNS resolution if the pod cannot reach other services.
• Check RBAC permissions if the pod gets authorization errors.