deployment-rollout-debug

Deployment Rollout Failure Diagnosis

When a Deployment rollout is stuck, not progressing, or shows replica mismatches, follow this flow to identify the root cause.

Scope: This skill is for diagnosis only. Once you identify the root cause, report it to the user and stop. Do NOT attempt to roll back, scale, or modify the Deployment — that should be left to the user.

Diagnostic Flow

1. Check rollout status

kubectl rollout status deployment/<name> -n <ns> --timeout=5s

This shows whether the rollout is progressing, complete, or stuck. A timeout indicates the rollout is not making progress.

2. Get Deployment details

kubectl get deployment <name> -n <ns> -o wide

Compare the columns:

• DESIRED — target replica count
• CURRENT — total pods (old + new)
• UP-TO-DATE — pods running the new version
• AVAILABLE — pods ready to serve traffic

If UP-TO-DATE < DESIRED or AVAILABLE < DESIRED, the rollout is incomplete.

3. Describe the Deployment

kubectl describe deployment <name> -n <ns>

Focus on:

• Conditions — look for Progressing (status and reason) and Available
• Events — look for scaling events, errors, or warnings
• Strategy — note maxSurge and maxUnavailable settings

4. Check ReplicaSets

kubectl get rs -n <ns> -l app=<name>

If the label app=<name> doesn't match, find ReplicaSets owned by the Deployment:

kubectl get rs -n <ns> --sort-by='.metadata.creationTimestamp' | grep <name>

You should see the old RS (with reduced replicas) and the new RS (scaling up). If the new RS has 0 ready replicas, its pods are failing.

5. Check new ReplicaSet's pods

Find pods from the new RS:

kubectl get pods -n <ns> -l app=<name> --sort-by='.metadata.creationTimestamp'

Check the status of the newest pods. Based on their status:

• Pending → Use the pod-pending-debug skill
• CrashLoopBackOff / Error → Use the pod-crash-debug skill
• ImagePullBackOff / ErrImagePull → Use the image-pull-debug skill
• Running but not Ready → Check readiness probe below