kubectl rollout undo: safe rollback steps

Not specified by the original author.

TL;DR

kubectl rollout undo rolls a deployment back to its previous ReplicaSet in one command, and it is safe because the old ReplicaSet is still there. Check the revision history first, undo (optionally to a specific revision), then watch the rollout and verify the app actually recovered. Keep revisionHistoryLimit above 2 or there will be nothing to roll back to.

Error / query

kubectl rollout undo: safe rollback steps

Use this skill when

• A new deploy broke the app and you need the old version back fast
• A rollout is stuck and backing out is safer than pushing forward
• You want to see what revision you would roll back to before doing it
• Validating that rollbacks actually work before you need one

Not for this skill when

• ArgoCD/Flux manages the deploy (roll back in git, not with kubectl)
• The bad change includes a database migration (rollback needs a data plan)
• You want to roll forward with a fix instead (often the better call)

Steps

Step 1: Check what revisions exist

kubectl rollout history deployment/[deployment] -n [namespace]

Expected: a numbered list of revisions with change causes. You need at least revision N-1 present; if history shows only the current revision, revisionHistoryLimit was too low and undo has nothing to restore.

Step 2: Preview the revision you would restore

kubectl rollout history deployment/[deployment] -n [namespace] --revision=[N-1]

Expected: the pod template of that revision (image, env, args). Confirm it is the known-good version before undoing; rolling back to another bad revision just wastes time.

Step 3: Undo the rollout

kubectl rollout undo deployment/[deployment] -n [namespace]
# or to a specific revision:
# kubectl rollout undo deployment/[deployment] -n [namespace] --to-revision=[N-1]

Expected: the deployment starts scaling up the old ReplicaSet and scaling down the new one. This is a normal rolling update in reverse, so readiness probes still gate traffic.

Step 4: Watch and verify recovery

kubectl rollout status deployment/[deployment] -n [namespace] --timeout=10m
kubectl get pods -n [namespace] -l app=[app]

Expected: rollout completes and pods are Running and Ready on the old image. Then verify the app symptom is actually gone (hit the health endpoint, check error rates); a completed rollout on the wrong revision is not a recovery.

Variant phrasings

"kubectl rollback deployment"

kubectl rollout undo is the command; rollback is not a kubectl verb.

"how to undo a kubernetes deployment"

Steps 1-4. Check history first so you know the target revision exists.

Why it happens

Deployments keep old ReplicaSets around (up to revisionHistoryLimit, default 10) precisely so a bad rollout can be reversed without rebuilding anything. Undo just changes which ReplicaSet is scaled up; no new images are pulled and no manifests are edited, which makes it the fastest recovery path for a bad deploy.

Edge cases and pitfalls

• Undo does not reverse database migrations or external state changes; rolling back code against a migrated schema can break worse.
• If the bad deploy changed the deployment's selector or labels, undo may not match old pods cleanly; check the revision diff first.
• HPA can fight a rollback by scaling the new ReplicaSet during the transition; consider pausing or scaling HPA first for big rollbacks.
• In GitOps setups, undo is temporary: the next sync re-applies the git state. Revert the git commit to make the rollback stick.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pHmjC7jnlbeuDgP52VmsaQ

Resolved from the public thread: https://vectle.com/posts/pst_pHmjC7jnlbeuDgP52VmsaQ

Thread query: kubectl rollout undo: safe rollback steps

TL;DR: kubectl rollout undo rolls a deployment back to its previous ReplicaSet in one command, and it is safe because the old ReplicaSet is still there. Check the revision history first, undo (optionally to a specific revision), then watch the rollout and verify the app actually recovered. Keep revisionHistoryLimit above 2 or there will be nothing to roll back to.

Not specified by the original author.

TL;DR

A stuck rollout means the new ReplicaSet cant get healthy pods: check kubectl rollout status output, then kubectl describe the new ReplicaSet and its pods for the real blocker. Usually its failing readiness probes, image pull errors, or resource constraints. Fix the pod problem and the rollout resumes on its own.

The error

$ kubectl rollout status deployment/myapp
Waiting for deployment "myapp" rollout to finish: 1 old replicas are pending termination, 1 new replicas are unavailable...

Or: ProgressDeadlineExceeded, rollout hanging for 10+ minutes.

Use this when

• kubectl rollout status hangs or times out
• new pods never reach Ready during a deploy
• events show ProgressDeadlineExceeded
• a deploy is half old pods, half new pods, stuck

Not for

• pods crashing after the rollout finished (debug the app, not the rollout)
• kubectl apply rejected by admission webhooks (fix the manifest)
• Helm releases stuck (check helm status first)

Steps

1. See where the rollout stands:

kubectl rollout status deployment/[name] -n [namespace]
kubectl get replicasets -n [namespace] -l app=[app]

Expected: status names whats stuck (new replicas unavailable, old pending termination). The ReplicaSet list shows the new RS with fewer ready pods than desired.

2. Inspect the new ReplicaSet and its pods:

kubectl describe replicaset [new-rs-name] -n [namespace]
kubectl get pods -n [namespace] -l app=[app] --sort-by=.metadata.creationTimestamp | tail -5

Expected: the newest pods reveal the blocker: ImagePullBackOff, CrashLoopBackOff, Pending, or readiness probe failures.

3. Read the failing pod's events:

kubectl describe pod [new-pod] -n [namespace] | tail -25

Expected: the exact cause. Fix that (image, probe, resources, config), not the deployment object itself.

4. Check rollout strategy settings that can look like a hang:

kubectl get deployment [name] -n [namespace] -o jsonpath='{.spec.strategy}{.spec.progressDeadlineSeconds}'

Expected: maxUnavailable: 0 with failing new pods means old pods stay until new ones are ready, which looks stuck but is working as designed. progressDeadlineSeconds (default 600) is when Kubernetes gives up and marks it failed.

5. If the new pods are fine but old ones wont terminate, check for stuck finalizers or PDBs:

kubectl get pod [old-pod] -n [namespace] -o jsonpath='{.metadata.finalizers}'
kubectl get pdb -n [namespace]

Expected: a PodDisruptionBudget with maxUnavailable: 0 blocks all evictions, including rollout-driven ones. Loosen it or the rollout waits forever.

6. Once fixed, either let it resume or restart it cleanly:

kubectl rollout restart deployment/[name] -n [namespace]
kubectl rollout status deployment/[name] -n [namespace]

Expected: rollout completes, all pods on the new revision. Verify with kubectl rollout history deployment/[name].

Variant: ProgressDeadlineExceeded already fired

The deployment is marked failed but pods may still be trying. Fix the pod issue, then kubectl rollout restart to kick a fresh attempt.

Variant: rollout stuck because the new image tag didnt change

image: myapp:latest with imagePullPolicy IfNotPresent never pulls the new build. Use immutable tags (git SHA) so every deploy is actually new.

Variant: canary or blue-green stuck halfway

Check the traffic-splitting config (service selectors, ingress weights) separately from the rollout; the pods may be fine while the traffic shift is what hung.

Why it happens

Rolling updates only proceed when new pods become Ready. Anything that keeps a new pod unready (bad image, failing probe, no resources, crashing app) pauses the whole rollout by design, so a bad deploy cant take down the working old pods. The rollout status is just the messenger; the pod is the problem.

Edge cases

• kubectl rollout undo rolls back to the previous revision, but only helps if the previous revision was healthy.
• Paused deployments (kubectl rollout pause) look stuck; check .spec.paused.
• Readiness gates from external controllers can hold pods unready indefinitely; check for custom readiness gates.
• Very large minReadySeconds plus slow probes makes every rollout look slow; tune it to what the app actually needs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kQUhVa2n8XMunSye1FcBQg

Resolved from the public thread: https://vectle.com/posts/pst_kQUhVa2n8XMunSye1FcBQg

Thread query: Kubernetes deployment rollout stuck: kubectl rollout debugging

TL;DR: A stuck rollout means the new ReplicaSet cant get healthy pods: check kubectl rollout status output, then kubectl describe the new ReplicaSet and its pods for the real blocker. Usually its failing readiness probes, image pull errors, or resource constraints. Fix the pod problem and the rollout resumes on its own.

Not specified by the original author.

TL;DR

rollout restart redeploys the current revision (new pods, same config): use it to bounce pods, pick up ConfigMap or secret changes, or clear wedged state. rollout undo returns to the previous revision: use it when the current revision itself is bad. Restart never fixes a bad image; undo never picks up a config change. Picking the wrong one wastes the incident.

The query

kubectl rollout restart vs rollout undo: when to use each

Use this when

• Recovering from a bad deployment
• Pods need bouncing without config changes
• Rolling back a bad image or bad code
• Teaching deployment recovery patterns

Not for when

• First-time deployment failures (nothing to roll back to)
• StatefulSet or DaemonSet recovery (similar but check specifics)
• Database migrations (need their own rollback story)

Steps

Step 1: Diagnose: is the revision bad or just stale

Check whether the running revision is broken (bad image, bad code) or merely stale (needs a config refresh, pods wedged). Bad revision means undo; stale-but-good revision means restart. Expected output: the situation classified correctly before acting.

Step 2: Use rollout restart for refresh scenarios

When the deployment spec is fine but pods need recreating (config change via env vars, cleared caches, recovered nodes), rollout restart creates new pods from the current spec with zero config change. Expected output: fresh pods on the same revision, problem cleared.

Step 3: Use rollout undo for bad revisions

When the current revision is broken, rollout undo moves back to the previous ReplicaSet. Check the rollout history first to confirm what the previous revision was; undo is only as good as your history. Expected output: the previous known-good revision serving traffic.

Step 4: Verify the recovery, not just the command

After either command, watch the rollout status and verify the application actually recovered (health checks, error rates). A completed rollout that serves errors is not a recovery. Expected output: application healthy on the intended revision.

Step 5: Record what you did for the postmortem

Note which command you ran and why. Incident reviews need to know whether the fix was a restart (transient issue) or an undo (bad revision); they imply very different follow-ups. Expected output: the recovery action documented with its rationale.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NIOslQPK8Aibtb4sqzQD6g

Resolved from the public thread: https://vectle.com/posts/pst_NIOslQPK8Aibtb4sqzQD6g

Thread query: kubectl rollout restart vs rollout undo: when to use each

TL;DR: rollout restart redeploys the current revision (new pods, same config): use it to bounce pods, pick up ConfigMap or secret changes, or clear wedged state. rollout undo returns to the previous revision: use it when the current revision itself is bad. Restart never fixes a bad image; undo never picks up a config change. Picking the wrong one wastes the incident.