Debugging Kubernetes Applications

Debugging Kubernetes Applications: Common Issues and Solutions

Debugging applications running in Kubernetes can be challenging, but with the right tools and techniques, you can quickly identify and resolve issues. This guide covers common problems and their solutions.

Common Debugging Scenarios

Pods Not Starting

Symptoms: Pods stuck in Pending or ContainerCreating state.

Debugging steps:

Check pod status:

kubectl describe pod <pod-name>

Check node resources:

kubectl top nodes
kubectl describe node <node-name>

Check events:

kubectl get events --sort-by='.lastTimestamp'

Common causes:

Insufficient node resources
Image pull errors
Resource quota limits
Node selectors not matching

For more details, see our guide on troubleshooting pods in Pending state.

Pods Crashing or Restarting

Symptoms: Pods in CrashLoopBackOff state.

Debugging steps:

Check pod logs:

kubectl logs <pod-name>
kubectl logs <pod-name> --previous  # Previous container instance

Execute into the pod:

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

Check container exit codes:

kubectl describe pod <pod-name>

Common causes:

Application errors
Missing environment variables
Incorrect resource limits
Health check failures

Learn more about troubleshooting CrashLoopBackOff pods and understanding pod error states.

Services Not Accessible

Symptoms: Can't reach services from other pods or external traffic.

Debugging steps:

Verify service endpoints:

kubectl get endpoints <service-name>

Check service selector:

kubectl get svc <service-name> -o yaml

Test connectivity:

kubectl run -it --rm debug --image=busybox --restart=Never -- wget -O- <service-name>

Common causes:

Selector mismatch between service and pods
Port configuration errors
Network policies blocking traffic

Application Performance Issues

Symptoms: Slow response times, high latency, resource exhaustion.

Debugging steps:

Check resource usage:

kubectl top pods
kubectl top pods --containers

Analyze metrics:

kubectl get --raw /apis/metrics.k8s.io/v1beta1/namespaces/<namespace>/pods

Check for throttling:

kubectl describe pod <pod-name> | grep -i throttl

Solutions:

Increase resource requests and limits
Optimize application code
Implement caching strategies
Use horizontal pod autoscaling

For memory-related issues, see our guide on troubleshooting OOM killed pods. Learn about monitoring pods and cost optimization strategies.

Essential Debugging Commands

Get Detailed Pod Information

kubectl get pod <pod-name> -o yaml
kubectl describe pod <pod-name>

View Logs

# Current logs
kubectl logs <pod-name>

# Follow logs
kubectl logs -f <pod-name>

# Logs from all containers
kubectl logs <pod-name> --all-containers=true

# Logs from specific container
kubectl logs <pod-name> -c <container-name>

Execute Commands in Pods

kubectl exec <pod-name> -- <command>
kubectl exec -it <pod-name> -- /bin/bash

Check Events

kubectl get events --all-namespaces
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

Inspect Resources

kubectl get all -n <namespace>
kubectl get pods -o wide
kubectl get pods --show-labels

Debugging Tools

kubectl Debug

Kubectl debug allows you to create debugging sessions in running pods:

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

Ephemeral Containers

Use ephemeral containers to debug running pods without modifying the original pod spec:

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

Best Practices

Enable detailed logging: Configure log levels appropriately
Use health checks: Implement liveness and readiness probes for better reliability
Monitor metrics: Set up Prometheus and Grafana for observability. Learn about monitoring pods and smart alerts
Document common issues: Keep a runbook of known problems and solutions
Use structured logging: Makes log analysis easier

For production deployments, follow our Kubernetes best practices guide and Day-2 operations checklist.

Related Resources

Learning Resources

What is Kubernetes? - Start with the basics
Kubernetes Core Components - Understand the architecture
Basic Troubleshooting Commands - Essential kubectl commands

Operations Guides

Monitor Pods & Resources - Monitoring strategies
Check Cluster Health - Health check procedures
Probes Configuration - Health check configuration

Troubleshooting Guides

Conclusion

Effective debugging in Kubernetes requires understanding the different layers (pods, services, nodes) and using the right tools. Start with basic commands like kubectl describe and kubectl logs, then gradually expand your debugging toolkit.

Remember: Most issues can be resolved by carefully examining pod status, logs, and events.