highIntermediateSymptom-first#deployments#rollout#readiness

Deployment rollout stuck — progress deadline exceeded

kubectl rollout status hangs on 'Waiting for rollout to finish'

Likely source:availabilitydeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • kubectl rollout status hangs on 'Waiting for rollout to finish'
  • New pods never become Ready
  • Rollout stuck at partial completion

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • New pod status

    kubectl get pods -n <namespace> -l <selector> --sort-by=.metadata.creationTimestamp

  • Deployment conditions

    kubectl describe deployment <name> -n <namespace> | tail -20

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • describe shows Readiness probe failed
  • New pod logs show startup errors

Confirm before fixing

kubectl logs <new-pod> -n <namespace> --previous
READ

Read the failed pod's logs

Fix

kubectl rollout undo deployment/<name> -n <namespace>
CHANGE

Roll back to the last good revision

Expected: deployment.apps/<name> rolled back

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
kubectl rollout status deployment/<name> -n <namespace>
READ

Confirm it is actually stuck

2
kubectl get pods -n <namespace> -l <selector> --sort-by=.metadata.creationTimestamp
READ

Identify the newest pod

3
kubectl logs <new-pod> -n <namespace> --previous
READ

Read why readiness fails

4
kubectl rollout undo deployment/<name> -n <namespace>
CHANGE

Roll back if you need to restore service immediately

5
kubectl rollout pause deployment/<name> -n <namespace>
CHANGE

Pause to keep investigating a partially rolled-out state

Prevention

  • Set progressDeadlineSeconds to fail loudly instead of hanging.
  • Ship with correct readiness probes; test images in a review/staging namespace first.
  • Use canary/blue-green deployments for high-risk workloads.
  • Alert on rollout failing via kubernetes_statefulset/deployment condition metrics.

Related runbooks

Same stack, same failure family — worth a skim.

Service not routing traffic — no endpointshigh

curl to Service IP returns connection refused

KubernetesIntermediate2 causes
Open runbook
CrashLoopBackOff — container keeps crashing and restartingcritical

kubectl get pods shows CrashLoopBackOff status

KubernetesFoundation4 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.