skip to content

After `kubectl rollout undo deployment/transcoder --to-revision=4`, what exactly has Kubernetes reverted, and which revision number does the Deployment then report?

level: middleimportance: should knowfreq 42%

answer

  1. history is the ReplicaSets
  2. a client-side template patch
  3. reuse, then renumber
  4. template only, nothing else
  5. paused objects refuse undo

basics

~20 s

Only the pod template is reverted: kubectl copies revision 4's template back into the Deployment. The controller reuses that old ReplicaSet and renumbers it to the next revision, so the Deployment reports a new number, not 4.

solid answer

~40 s

`kubectl rollout undo` is a client-side patch. kubectl finds the ReplicaSet whose `deployment.kubernetes.io/revision` is 4, copies its pod template (and annotations such as `kubernetes.io/change-cause`) into `spec.template`, and the Deployment controller treats that as an ordinary rollout under the current strategy. The matching ReplicaSet already exists, so the controller reuses it and gives it the next revision number. If the Deployment was at 6, it now reports 7, and 4 disappears from `kubectl rollout history`. Nothing outside the template changes: `replicas`, the strategy, the deadlines, and the contents of any ConfigMap or Secret the pods reference all stay as they are. Undo refuses to run on a paused Deployment, and it prints `skipped rollback` if the template already matches.

code

bash · 5 lines
bash
kubectl rollout history deployment/transcoder -n media
kubectl rollout history deployment/transcoder -n media --revision=4
kubectl rollout undo deployment/transcoder -n media --to-revision=4
kubectl rollout status deployment/transcoder -n media
kubectl rollout history deployment/transcoder -n media

go deeper

for a junior

Remember the commands: rollout history lists revisions, and rollout undo goes back one revision, or to a specific one with --to-revision.

for a middle

Explain that undo copies an old ReplicaSet's template into the Deployment, that the controller reuses and renumbers that ReplicaSet, and what stays unchanged.

for a senior

Show you know when undo fails you: config edited in place, old images deleted from the registry, a GitOps controller reverting the undo, and scripts that pin revision numbers.

for a principal

Decide where rollback authority lives, in live-object undo or in a source-of-truth revert, and how config versioning makes a single rollback restore the whole release.

## Where Deployment revisions live A Deployment's history is **not** a separate object. It is the set of **ReplicaSets** the Deployment owns. Each ReplicaSet carries a `deployment.kubernetes.io/revision` annotation, and the Deployment carries the current revision number in the same annotation. Old ReplicaSets stay in place, scaled to 0, up to `spec.revisionHistoryLimit` (default **10**). Older ones are garbage-collected. - `kubectl rollout history deployment/transcoder` lists the revision numbers, with a `CHANGE-CAUSE` column read from the `kubernetes.io/change-cause` annotation when someone set it. - `kubectl rollout history deployment/transcoder --revision=4` prints the pod template stored for that revision. - `kubectl rollout undo deployment/transcoder` with no flag goes to the **previous** revision; `--to-revision` defaults to 0, which means the previous one. ## What undo actually does There is no rollback field in an `apps/v1` Deployment. The undo happens **in kubectl**: 1. kubectl reads the Deployment and its ReplicaSets and finds the one whose revision is 4. If that ReplicaSet was already garbage-collected, it fails with `unable to find specified revision 4 in history`. 2. If `spec.paused` is true, it refuses and tells you to run `kubectl rollout resume` first. 3. If the current template already equals revision 4's template (ignoring the `pod-template-hash` label), it prints `skipped rollback (current template already matches revision 4)` and changes nothing. 4. Otherwise it removes the hash label from the stored template and patches that template into `spec.template`, together with the old ReplicaSet's annotations (for example its change-cause). 5. The Deployment controller sees a template change. A ReplicaSet with that exact template already exists, so the controller **reuses** it and scales it up under the current `maxSurge`/`maxUnavailable` budget and `minReadySeconds`, while scaling the current ReplicaSet down. A rollback is therefore **a rollout**, and it has the same speed and capacity behaviour as the release it undoes. If the old image no longer pulls, or the old pods fail readiness, the undo can stall exactly like a forward rollout. ## Revision renumbering When the controller reuses a ReplicaSet, it sets that ReplicaSet's revision to **one more than the highest existing revision**. Suppose revisions 3, 4, 5 and 6 exist and 6 is live: | Before undo | After `--to-revision=4` | |---|---| | 3, 4, 5, 6 (live) | 3, 5, 6, 7 (live, same template as the old 4) | The consequences: - **Revision 4 no longer exists** under that number. A script that stored "known-good = 4" will fail next time. - A plain `kubectl rollout undo` right afterwards goes to the **previous** revision, which is now 6, the release you just rolled away from. - Track known-good releases by **content** (image digest, change-cause), not by revision number. ## What undo does not revert | Item | Reverted by undo? | |---|---| | Pod template: image, env, resources, probes | Yes | | `spec.replicas` | No | | `strategy`, `minReadySeconds`, `progressDeadlineSeconds` | No | | Data inside a ConfigMap or Secret referenced by name | No | | Data in volumes, database schema | No | | Services, autoscaler objects, other manifests | No | Suppose a bad release of the transcoding workers raised the memory limit to `2662Mi` **and** edited a ConfigMap in place. The undo restores the old limit, but the workers still read the edited config. With hash-suffixed ConfigMap names, the old template points at the old ConfigMap, so config is reverted too, as long as that object still exists. ## Undo inside a managed pipeline `kubectl rollout undo` changes the live object only. If a GitOps controller or a release tool owns the manifest, its next sync reapplies the newer template and cancels your undo. In that setup, `kubectl rollout undo` is at most an emergency brake to buy time, and the lasting rollback is a change to the source of truth, a process owned by those tools' own trees.

  • A GitOps controller manages this Deployment. What happens after you run kubectl rollout undo, and what should you do instead?
    The undo patches only the live object. On its next sync, the GitOps controller sees the live template differs from the source of truth and reapplies the newer one, which starts another rollout to the bad release. Use the kubectl undo only as a stopgap, and make the real rollback a revert in the managed source, or pause that controller's syncing for this object while you work.
  • Why does a rollback with kubectl rollout undo sometimes stall just like a failed release?
    An undo is an ordinary rollout toward an older template. The controller still has to schedule pods within the surge budget, pull the old image, and wait for readiness and minReadySeconds. If the old image tag was deleted from the registry, the nodes lack capacity for surge pods, or the old version fails its probes against the current config, the undo stops making progress and can hit its progress deadline.

saying these in an interview costs you the question

  • Rolling back to revision 4 makes the Deployment report revision 4 again.
  • kubectl rollout undo also restores the replica count from that revision.
  • An undo reverts ConfigMap data edited in place during the bad release.
  • A rollback bypasses maxSurge and maxUnavailable to finish faster.
  • The API server stores Deployment history separately from ReplicaSets.