Update a Deployment Image, Then Roll It Back

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: update, record why, and roll back with evidence

Every time a Deployment's Pod template changes, the controller creates a new ReplicaSet and gradually moves Pods to it. The old ReplicaSet is scaled to zero but kept, and that retained ReplicaSet is the revision you can roll back to. Once you see revisions as ReplicaSets, the rollout commands stop being magic: history lists them, undo copies an old template back, and status waits for the move to finish.

revision 1  RS lantern-aaa  nginx:1.26-alpine   replicas 0  (kept for undo)
revision 2  RS lantern-bbb  nginx:1.27-alpine   replicas 3  (current)
scaling 3 -> 5 changes neither: it is not a template change

1. Start with one revision

kubectl create namespace prepium-tutorial
kubectl -n prepium-tutorial create deployment lantern --image=nginx:1.26-alpine --replicas=3
kubectl -n prepium-tutorial rollout status deployment/lantern
kubectl -n prepium-tutorial get deploy lantern -o jsonpath='{.spec.template.spec.containers[*].name}'

The last command prints the container name. kubectl set image addresses containers by name, so check it rather than guessing.

2. Update the image and record the reason

kubectl -n prepium-tutorial set image deployment/lantern nginx=nginx:1.27-alpine
kubectl -n prepium-tutorial annotate deployment/lantern kubernetes.io/change-cause="nginx 1.27 for TLS fixes"
kubectl -n prepium-tutorial rollout status deployment/lantern
kubectl -n prepium-tutorial rollout history deployment/lantern
kubectl -n prepium-tutorial get rs

The CHANGE-CAUSE column comes from the kubernetes.io/change-cause annotation on the Deployment, which the controller copies onto the revision. The old --record flag that used to fill it is deprecated, so set the annotation yourself (or put it in the manifest alongside the image change). get rs shows two ReplicaSets: the new one with three ready Pods and the old one at zero.

3. Break a rollout on purpose, then undo it

kubectl -n prepium-tutorial set image deployment/lantern nginx=nginx:1.27-alpne
kubectl -n prepium-tutorial rollout status deployment/lantern --timeout=60s
kubectl -n prepium-tutorial get pods
kubectl -n prepium-tutorial rollout undo deployment/lantern
kubectl -n prepium-tutorial rollout status deployment/lantern
kubectl -n prepium-tutorial get deploy lantern -o jsonpath='{.spec.template.spec.containers[0].image}'

The typo tag cannot be pulled, so new Pods sit in ImagePullBackOff while the old Pods keep serving: maxUnavailable (25% by default, rounded down to whole Pods) caps how many old Pods may be taken away before new ones are ready. undo with no flag returns to the previous revision; --to-revision=N targets a specific one, which you can inspect first with rollout history --revision=N. Only the Pod template is rolled back, never the replica count. Finish by reading the image back, not by trusting the "rolled back" message.

4. Batch several changes into one revision

kubectl -n prepium-tutorial rollout pause deployment/lantern
kubectl -n prepium-tutorial set image deployment/lantern nginx=nginx:1.26-alpine
kubectl -n prepium-tutorial set resources deployment/lantern -c nginx --requests=cpu=50m
kubectl -n prepium-tutorial rollout history deployment/lantern
kubectl -n prepium-tutorial rollout resume deployment/lantern

While paused, template edits are stored but no new ReplicaSet appears, so history does not grow. Resume produces a single rollout containing both changes.

Common mistakes

• A second kubectl annotate of the same key fails until you add --overwrite, leaving the old change-cause on the next revision.
• Trying rollout undo on a paused Deployment. Kubernetes refuses until you resume it.
• Expecting kubectl scale to appear in history. Scaling never creates a revision.
• Setting revisionHistoryLimit: 0. Old ReplicaSets are cleaned up, so there is nothing left to undo to.

Cleanup: kubectl delete namespace prepium-tutorial. References: Deployments, kubectl rollout undo, kubectl set image. Next, try a manual canary or the CKA rollout drill.