Debugging a Kubernetes cluster can be challenging, but by using systematic approaches and the right tools, you can efficiently diagnose and resolve issues. This guide provides an overview of common debugging methods and tools to help troubleshoot problems in a Kubernetes environment.

1. Understand the Problem Scope

Questions to Consider:

Is the issue affecting all nodes or a specific pod?
Are services unreachable?
Is the control plane responding correctly?
Are logs indicating specific errors?
Identifying the scope helps narrow down the troubleshooting process.

1. Check Cluster Components

a. Verify Node Status

Check if all nodes are healthy and ready:

kubectl get nodes

If a node is NotReady, inspect it further:

kubectl describe node <node-name>

Common issues:

Insufficient resources.
Network connectivity problems.
Crashed kubelet service.
Restart kubelet if needed:

sudo systemctl restart kubelet

b. Inspect Control Plane Components

Verify the health of control plane components on the master node(s):

Check etcd:

ETCDCTL_API=3 etcdctl endpoint health

Check Kubernetes API Server:

kubectl get --raw='/healthz'

Check Scheduler and Controller Manager logs:

sudo journalctl -u kube-schedulersudo journalctl -u kube-controller-manager

1. Investigate Pods

a. List All Pods

kubectl get pods -A

b. Describe the Problematic Pod

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

Look for:

Events section for errors (e.g., image pull errors, resource limits).
Status and readiness probes.
c. View Pod Logs

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

For multi-container pods:

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

1. Debugging Nodes and Networking

a. Check Node Resources

kubectl top node

b. Debug Networking Issues

Test pod-to-pod connectivity using kubectl exec:

kubectl exec -it <pod-name> -- curl <service-ip>

Inspect service endpoints:

kubectl get endpoints

Verify DNS resolution:

kubectl exec -it <pod-name> -- nslookup <service-name>

Inspect network policies:

kubectl describe networkpolicy -n <namespace>

1. Inspect Persistent Volume Issues

Check PersistentVolume (PV) and PersistentVolumeClaim (PVC) status:

kubectl get pvkubectl get pvc -n <namespace>

Describe the PVC for detailed information:

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

1. Advanced Debugging Tools

a. Use kubectl debug

Spin up a debug container in the same namespace:

kubectl debug <pod-name> -n <namespace> --image=busybox --target=<container-name>

b. Use strace and tcpdump

For deeper system-level debugging:

Install strace or tcpdump in the container.
Attach a terminal and analyze system calls or network packets.
c. Leverage Monitoring Tools

Prometheus/Grafana: Monitor cluster metrics.
ELK Stack: Analyze cluster and application logs.
K9s: A terminal-based UI for managing Kubernetes clusters.

1. Common Troubleshooting Commands

a. Restart Pod

Force a pod to restart:

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

b. Drain a Node

Safely remove workloads from a node:

kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

c. Restart Deployment

kubectl rollout restart deployment/<deployment-name> -n <namespace>

1. Consult Logs and Events

Check cluster-wide events:

kubectl get events -A

Inspect cluster-level logs on the master node:

sudo journalctl -u kubelet

Conclusion

Debugging a Kubernetes cluster involves a combination of high-level checks, log inspection, and targeted analysis. By following the steps outlined in this guide, you can systematically identify and resolve issues, ensuring a stable and reliable Kubernetes environment.