Roll Back a Failed Deployment to a Known-Good Revision

Original Prepium guide · Written for Kubernetes v1.35 and checked against the official documentation on 6 October 2026. Use a disposable practice cluster.

Deployment revisions, rolling-update arithmetic and a stalled rollout you can recover

Every time a Deployment's Pod template changes, the controller creates a new ReplicaSet and records it as a revision; older ReplicaSets are kept (ten by default) so you can return to them. How fast Pods are swapped is governed by two numbers, maxSurge and maxUnavailable, and how long the controller waits before declaring a rollout stuck is progressDeadlineSeconds. Recovering a bad release on the exam means reading the history, picking the right revision, and confirming the result rather than trusting the undo command's one-line reply.

revision 1 (ReplicaSet A, nginx:1.26-alpine)
revision 2 (ReplicaSet B, nginx:1.27-alpine)
revision 3 (ReplicaSet C, bad tag) ── stalled: Progressing=False, ProgressDeadlineExceeded
undo --to-revision=1 ──→ A's template comes back as the newest revision

1. Build a history with readable change causes

kubectl create namespace prepium-tutorial
kubectl -n prepium-tutorial create deployment ticker --image=nginx:1.26-alpine --replicas=4
kubectl -n prepium-tutorial annotate deployment ticker kubernetes.io/change-cause="initial 1.26"
C=$(kubectl -n prepium-tutorial get deploy ticker -o jsonpath='{.spec.template.spec.containers[0].name}')
kubectl -n prepium-tutorial set image deployment/ticker "$C=nginx:1.27-alpine"
kubectl -n prepium-tutorial annotate deployment ticker kubernetes.io/change-cause="upgrade to 1.27" --overwrite
kubectl -n prepium-tutorial rollout history deployment/ticker

The CHANGE-CAUSE column is copied from the kubernetes.io/change-cause annotation; without it the column shows <none>. The old --record flag is deprecated, so annotate instead. set image takes container=image pairs, which is why the container name is read first rather than guessed.

2. Set the strategy and understand the arithmetic

kubectl -n prepium-tutorial patch deployment ticker -p \
  '{"spec":{"progressDeadlineSeconds":45,"strategy":{"rollingUpdate":{"maxSurge":2,"maxUnavailable":1}}}}'
kubectl -n prepium-tutorial rollout history deployment/ticker

With 4 replicas, maxSurge: 2 allows up to 6 Pods during an update and maxUnavailable: 1 keeps at least 3 available. Percentages are converted to Pod counts, with surge rounded up and unavailable rounded down, which is why the 25% defaults never take a single-replica Deployment offline. The two cannot both be 0, because then no Pod could ever be replaced. Notice the history did not grow: strategy and deadline sit outside the Pod template, so changing them creates no revision.

3. Ship a broken release and watch it stall

kubectl -n prepium-tutorial set image deployment/ticker "$C=nginx:0.0.0-missing"
kubectl -n prepium-tutorial annotate deployment ticker kubernetes.io/change-cause="bad tag" --overwrite
kubectl -n prepium-tutorial rollout status deployment/ticker; echo "exit=$?"
kubectl -n prepium-tutorial get deployment ticker -o jsonpath='{.status.conditions[?(@.type=="Progressing")].reason}{"\n"}'
kubectl -n prepium-tutorial get pods

The new Pods cannot pull their image. Three old Pods stay available, as maxUnavailable: 1 promised, so the application keeps serving. After 45 seconds without progress, rollout status returns a non-zero exit code and the Progressing condition reports ProgressDeadlineExceeded. Kubernetes does nothing else: there is no automatic rollback.

4. Choose a revision, then roll back

kubectl -n prepium-tutorial rollout history deployment/ticker --revision=1
kubectl -n prepium-tutorial rollout undo deployment/ticker --to-revision=1
kubectl -n prepium-tutorial rollout status deployment/ticker
kubectl -n prepium-tutorial get deployment ticker -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
kubectl -n prepium-tutorial rollout history deployment/ticker

--revision=N prints that revision's Pod template, so you confirm the image before restoring it. Plain undo would only step back one revision, to 1.27; --to-revision lets you skip further. A rollback updates the Deployment's revision, so the restored template appears as the newest entry in the history.

Common mistakes

• Trusting rolled back as proof. Wait for rollout status and check the image and READY counts; the restored template can still fail.
• Expecting a strategy change to appear in history. Only Pod template changes create revisions.
• Setting both maxSurge and maxUnavailable to 0. That combination is invalid.
• Waiting for Kubernetes to undo a stalled rollout. ProgressDeadlineExceeded is a report, not an action.

Cleanup: kubectl delete namespace prepium-tutorial. References: Deployments, kubectl rollout undo, kubectl rollout history. Next, try CKAD rollout verification or probes that gate a rollout.