📖 Read-only preview — lessons, diagrams, and quizzes only. The hands-on labs, live grading, and progress tracking require running the real course locally against a Kubernetes cluster.Run it locally →

Module 3 · Lesson 3.2

Rolling Updates and Rollbacks

How a rolling update actually proceeds

Change the pod template (most often: the image) and the Deployment controller creates a new ReplicaSet, then shifts replicas from old to new according to two settings:

  • maxUnavailable — how many pods below desired count you'll tolerate during the rollout (default 25%).
  • maxSurge — how many extra pods above desired count you'll allow temporarily (default 25%).

Rolling update, one pod at a time

ReplicaSet web-v1 (old): 4 podsReplicaSet web-v2 (new): 0 pods
📦 pod 1app:v1
📦 pod 2app:v1
📦 pod 3app:v1
📦 pod 4app:v1
Default strategy: maxUnavailable=25%, maxSurge=25% of 4 replicas rounds to 1 — so Kubernetes replaces pods one at a time, never dropping below 3 ready pods serving traffic.

For 4 replicas, 25% of each rounds to 1 — so by default you get a strict one-at-a-time replacement: never fewer than 3 ready, briefly up to 5 while a new one comes up alongside the old ones. This is why a rolling update doesn't need a maintenance window: at every point, enough old, known-good pods are still serving traffic.

Revisions and rollback

Every pod-template change gets a revision number, and the old ReplicaSets stick around (scaled to 0) up to revisionHistoryLimit (default 10) so you can go back. kubectl rollout undo doesn't "restore a backup" — it simply re-points the Deployment's template at an older revision's template, which the normal rolling-update machinery then rolls out, old-becomes-new, same as any other update.

Why a bad rollout doesn't usually mean an outage

This is the part worth internalizing: because maxUnavailable keeps most old pods running, a broken new image (crashing, or in this lesson's lab, simply unpullable) typically gets stuck, not deployed. Readiness gating means Kubernetes won't shift more traffic to the new ReplicaSet until the pods it already created pass their readiness check — so a bad rollout stalls partway rather than taking the whole app down. You still have to notice it's stalled and roll back; it just won't page you for an outage while you do.

The infrastructure analogy

This is the built-in equivalent of a blue/green or canary deploy script you might have hand-rolled with a load balancer and two target groups — except the "shift traffic gradually, verify health, stop if it's not healthy" logic is native to the platform, governed by two numbers you set once.

In the lab, you'll run a clean rollout, then a broken one, and practice the exact sequence you'll use in production: notice it's stuck, find out why, roll back.

🧪 Lab: lab-06-rolling-updates

Preview only

Goal

Run a real rolling update, then run a bad one on purpose, diagnose it while it's stuck, and roll it back.

Tasks

Part 1 — a clean rolling update

  1. Apply the starting manifests: kubectl apply -f manifests/
  2. Confirm 4/4 pods Running on nginx:1.26.
  3. Trigger an update: kubectl set image deployment/web web=nginx:1.27 -n lab-06-rolling-updates
  4. Watch it roll: kubectl rollout status deployment/web -n lab-06-rolling-updates
  5. kubectl get rs -n lab-06-rolling-updates — now there are two ReplicaSets: the old one scaled to 0, the new one at 4. Changing the pod template (the image) is what creates a new revision — contrast with the scaling-only change in the previous lab.
  6. kubectl rollout history deployment/web -n lab-06-rolling-updates

Part 2 — break it, diagnose it, fix it

  1. Ship a typo'd tag on purpose: kubectl set image deployment/web web=nginx:1.27-nope -n lab-06-rolling-updates
  2. Run kubectl rollout status deployment/web -n lab-06-rolling-updates --timeout=20s — it will not complete. Note what it says.
  3. Find out why: kubectl get pods -n lab-06-rolling-updates (look for a pod that isn't Running), then kubectl describe pod <that-pod> -n lab-06-rolling-updates — check the Events at the bottom for the real reason.
  4. Because maxUnavailable: 25% on 4 replicas, the 3 old nginx:1.27 pods are still serving traffic — a bad rollout doesn't take you down, it just gets stuck. Roll back: kubectl rollout undo deployment/web -n lab-06-rolling-updates
  5. Confirm: kubectl rollout status deployment/web -n lab-06-rolling-updates completes, and every pod is back on nginx:1.27.

Check

Run the check once the rollback has completed.

This lab runs against a real local Kubernetes cluster with an automated grader — clone the repo and run make start to do it for real.

📝 Quiz

1. With the default maxUnavailable=25% and maxSurge=25% on 4 replicas, how many pods get replaced at a time?

2. What does `kubectl rollout undo` actually do under the hood?

3. You roll out a build with an image tag that doesn't exist. What's the most likely immediate impact on users?scenario

4. Why do old ReplicaSets stick around (scaled to 0) instead of being deleted after a rollout?

5. A rollout has been running for 10 minutes and `kubectl rollout status` hasn't returned. What's the fastest way to find out what's actually wrong?scenario

Progress isn't saved in this preview — run the course locally to track completion and grade labs for real.