Safe Deployments
Kubernetes Rollout Stuck Debugging Guide
Diagnose stuck Kubernetes rollouts through Deployment conditions, ReplicaSets, pod scheduling, image pulls, probes and availability budgets. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Read Deployment conditions | Identify progress deadline, unavailable replica and minimum availability signals. |
| Find the active ReplicaSet | Compare desired, current, ready and available counts across revisions. |
| Inspect the newest pods | Use events and container state to separate scheduling, image, configuration and probe failures. |
| Check rollout constraints | Review surge, unavailable limits, quotas and disruption budgets before changing strategy. |
Starter snippet
kubectl rollout status deployment/<name> && kubectl describe deployment <name>Review checks
- Record the intended image digest.
- Keep previous ReplicaSet evidence before rollback.
- Validate Secret and ConfigMap references.
- Confirm service endpoints include new ready pods.
Common mistakes
- Restarting all pods before reading events.
- Raising progress deadlines to hide a broken probe.
- Deleting the old ReplicaSet during investigation.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Kubernetes Pod Debugging Guide, Kubernetes Crashloopbackoff Guide, Deployment Rollback Checklist.