How to Debug Pod in Kubernetes: Step-by-Step Guide

To debug a pod in Kubernetes, use kubectl logs <pod-name> to check container logs, kubectl describe pod <pod-name> to see events and status, and kubectl exec -it <pod-name> -- /bin/sh to open a shell inside the pod for live inspection.

Why This Happens

Pods in Kubernetes can fail or behave unexpectedly due to issues like container crashes, image pull errors, or misconfigurations. Without proper debugging, it is hard to know what went wrong.

bash

kubectl logs my-pod
kubectl describe pod my-pod
kubectl exec -it my-pod -- /bin/sh

Output

Error from server (NotFound): pods "my-pod" not found
Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Warning  Failed     2m    kubelet, node-1    Failed to pull image "myimage:latest": rpc error: code = Unknown desc = Error response from daemon: manifest not found

The Fix

Use kubectl logs to see what the container outputs before crashing. Use kubectl describe pod to check events like image pull errors or scheduling problems. Use kubectl exec to open a shell inside a running pod to inspect files and processes.

If the pod is crashing, check the logs for errors. If the image is missing, fix the image name or registry access. If the pod is stuck, check node status and resource limits.

bash

kubectl logs my-pod
kubectl describe pod my-pod
kubectl exec -it my-pod -- /bin/sh

Output

2024-06-01T12:00:00Z Error: missing config file
Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Normal   Pulled     1m    kubelet, node-1    Successfully pulled image "myimage:latest"
  Normal   Created    1m    kubelet, node-1    Created container
  Normal   Started    1m    kubelet, node-1    Started container
# ls /app
config.yaml  main.py
# cat /app/config.yaml
key: value

Prevention

To avoid pod debugging issues, always:

• Use clear and tested container images with correct tags.
• Check resource requests and limits to prevent scheduling failures.
• Use readiness and liveness probes to detect unhealthy containers early.
• Enable logging and monitoring tools to catch problems quickly.
• Validate your pod specs with kubectl apply --dry-run=client before deploying.

Related Errors

Common related errors include:

• CrashLoopBackOff: Container repeatedly crashes; check logs for errors.
• ImagePullBackOff: Image not found or access denied; verify image name and registry credentials.
• ErrImagePull: Similar to ImagePullBackOff, caused by image issues.
• ContainerCreating: Pod stuck creating; check node status and volume mounts.

Key Takeaways

Use kubectl logs to see container output and errors.

Use kubectl describe pod to check pod events and status details.

Use kubectl exec to open a shell inside a running pod for live debugging.

Check image names, resource limits, and node health to prevent pod failures.

Enable probes and monitoring to catch issues early.