Kubernetes pods are fundamental to applications deployed on the platform. But when things go wrong, debugging can be a challenge, especially in a system as complex as Kubernetes. This article provides a structured approach to troubleshoot and debug common issues with Kubernetes pods.

1. Understanding Pod Status

First, understand the current status of the pod:

kubectl get pods -n <namespace>

You might encounter states like Pending, Running, CrashLoopBackOff, ImagePullBackOff, among others. Each status provides a clue about the underlying issue.

2. Describing the Pod

The describe command gives a detailed view of the pod, including events and configuration:

kubectl describe pod <pod-name> -n <namespace>

Inspect the events at the bottom of the output; they often provide insights into what's wrong.

3. Inspecting Pod Logs

Logs provide crucial insights into application behavior:

kubectl logs <pod-name> -n <namespace>

For pods with multiple containers:

kubectl logs <pod-name> -c <container-name> -n <namespace>

4. Exec into the Pod

You can access the pod's shell, provided the container has one:

kubectl exec -it <pod-name> -n <namespace> -- /bin/sh

This gives a direct look inside the container and allows you to run diagnostic commands.

5. Checking Resource Quotas

Ensure that the pod isn't exceeding its resource quotas:

kubectl describe ns <namespace>

Look for sections like Resource Quotas and Resource Limits.

6. Liveness and Readiness Probes

Misconfigured probes can cause pods to restart frequently. Ensure that liveness and readiness probes are set up correctly and are pointing to the right endpoints with appropriate timeouts.

7. Image Issues

Ensure that:

• The image name and tag are correct.
• The image is accessible, and credentials are set up if it's in a private registry.
• The node has enough disk space to pull the image.

8. Network Troubleshooting

If your pod isn't reachable:

• Check network policies.
• Ensure services and ingress controllers are correctly set up.
• Use tools like nslookup and curl inside the pod to check connectivity.

9. Using Debug Containers

Introduced as an alpha feature in Kubernetes 1.18, debug containers provide a temporary container for debugging in a running pod:

kubectl alpha debug -it <pod-name> --image=<debug-image> -- <command>

Best Practices:

1. Always Monitor: Tools like Prometheus and Grafana can offer insights before issues become critical.
2. Limit Privileges: Run containers with the least privilege necessary; this reduces the potential impact of issues.
3. Use Linting Tools: Tools like kubeval or kube-score can validate configurations, highlighting potential issues before deployment.

In conclusion, debugging Kubernetes pods requires a combination of understanding Kubernetes constructs, monitoring, and hands-on troubleshooting techniques. With methodical investigation and the right tools, you can diagnose and resolve most pod-related issues efficiently.