How to debug a failing Deployment?

· Category: Kubernetes

Short answer

Debug a failing Deployment by checking rollout status, describing the Deployment and ReplicaSet, inspecting Pod events and logs, and verifying resource and image availability.

Steps

  1. Check rollout status: kubectl rollout status deployment/name.
  2. Describe the Deployment for events.
  3. Inspect the ReplicaSet and Pods.
  4. Check logs and events.
  5. Verify image tags, secrets, and resource quotas.

Example

kubectl get deployment myapp
kubectl describe deployment myapp
kubectl get rs -l app=myapp
kubectl describe pod myapp-xxx
kubectl logs myapp-xxx
kubectl get events --sort-by='.lastTimestamp'

Tips

  • Use kubectl get events to see scheduling and image pull errors.
  • Use kubectl rollout undo to quickly revert a bad deployment.
  • Check kubectl top pod for resource exhaustion.

Common issues

  • ImagePullBackOff means the image is missing or inaccessible.
  • CrashLoopBackOff means the container exits immediately.
  • Pending means insufficient resources or node constraints.
  • FailedCreate often indicates quota or RBAC issues.