Platform Engineering · Lesson 198

Deployments & ReplicaSets: The Rolling Update, Step by Step

Two controllers, one promise. The Deployment controller watches Deployment objects and owns the ReplicaSet. The ReplicaSet controller counts Pods and closes the gap. I change one image tag, and the two of them walk the cluster from v1 to v2 one Pod at a time, never dropping below the floor I set. This lesson is that walk, Pod by Pod, with the arithmetic that bounds it and the failure modes that stop it.

Difficulty: Advanced · Know this first: Lesson 48, Lesson 197

What you will build

By the end of this lesson you will have read one rollout Pod by Pod and named who did each step: the Deployment controller, the ReplicaSet controller, or the kubelet on the node. You will have the rolling update arithmetic in your head: maxSurge is the ceiling, maxUnavailable is the floor, minReadySeconds is the proof, and progressDeadlineSeconds is the timer. You will have run the lab on your own cluster: apply a Deployment, change the image, watch the wave, read the revision history, and roll back with one command. You will know why a ConfigMap edit alone rolls nothing, and what to run instead.

What you need: a cluster you can reach with kubectl. The lab steps are reader-side: this build machine has no working cluster, so no kubectl output below is shown as run here. The k3s install was attempted for real on this machine and the server would not start: it fails with "failed to find cpu cgroup (v2)", so the lab runs on your machine, on a local k3s or kind cluster, and every expected output in the lab is marked reader-side. Your numbers will differ. The shape will not.

The story: two controllers, one promise

A Deployment is a promise: this many Pods, running this template, all the time. Two controllers keep it, and each one keeps a different half. The Deployment controller watches Deployment objects. When the template changes, it makes a new ReplicaSet and scales the old one down. The ReplicaSet controller watches ReplicaSets. It counts Pods against the number it was told to keep, and it creates or deletes Pods to close the gap. Lesson 48 already draws that gap math. This lesson shows the two controllers doing the work, one step at a time.

Deployment vs ReplicaSet

DeploymentReplicaSet
WatchesDeployment objects, for template changes.ReplicaSet objects, and the Pods behind them.
CreatesReplicaSets, one per template change.Pods, one per gap in the count.
OwnsThe ReplicaSet, through the chain of ownership.The Pods, through labels and owner references.
DecidesWhen a new version starts, and how fast it rolls.How many Pods exist right now.
Never doesIt never makes a Pod directly.It never reads the Deployment. It only counts.

The chain is short. I edit the Deployment. The Deployment controller makes a ReplicaSet. The ReplicaSet controller makes Pods. The scheduler places them, which Lesson 197 teaches step by step. The kubelet starts them. The Service sends traffic to the Ready ones. Each controller only knows its own level. That is why the system is simple to reason about and hard to break in a surprising way.

RollingUpdate vs Recreate

RollingUpdateRecreate
How it movesUp one, down one, until the old side is empty.All old Pods die first, then all new Pods start.
Traffic during the moveNever below the floor maxUnavailable sets.Zero, for the whole gap between old and new.
When it fitsAlmost always. It is the default for a reason.When two versions cannot run side by side at all, like a one-writer store.
The priceTwo versions serve at once, for a while.Downtime, priced in the open.

Recreate is honest downtime. It says the cost up front and it is the right call when the old and new versions cannot share the data. RollingUpdate is the default because most services can run two versions side by side for a minute. Pick Recreate on purpose, never by accident. If you did not choose it, you are rolling.

The arithmetic, in one table

The story runs 3 replicas, maxSurge 1, maxUnavailable 1. Here is what those two numbers buy at every replica count.

ReplicasmaxSurge 1maxUnavailable 1Most Pods at onceFewest serving
11 extra1 down20 (the one Pod goes down, then the new one comes up)
31 extra1 down42
51 extra1 down64
101 extra1 down119

Read the 1 replica row twice. With 1 replica and maxUnavailable 1, the floor is 0 serving Pods. The rollout still works, but it is a rolling update in name only: the one Pod goes down and the new one comes up after it. If that gap is not acceptable, the answer is more replicas, not different settings. Settings cannot invent capacity the Deployment does not have.

Do this now, before the diagram

Open Lesson 48 and find the flow diagram step where the ReplicaSet counts and closes the gap. That is the counting this lesson builds on. Then open Lesson 159, the hands-on lab where you applied a Deployment, scaled it, deleted a Pod, and watched it come back. The lab taught your hands. This lesson teaches the two controllers behind what your hands did.

Run it as:

When it breaks, I check

One thing to remember

Four paths, one family

The diagram above follows one rollout through the two controllers on 3 replicas with maxSurge 1 and maxUnavailable 1. These four paths are the same idea drawn four ways. One rollout, healthy. One rollout, stopped by a bad image. One rollout, frozen by settings too tight to move. One Recreate deploy, where the downtime is priced in the open. Run each path. One run takes 7.2 seconds across the path, so you can watch each hop light up in turn.

The return rule: the green dot only starts moving after the orange dot reaches the data hop. A return with no request is a lie. The diagram never draws one. The failure replay at the end of Run all four shows the other side of the rule. Run it and watch the orange dot stop at the new Pod that never turns Ready and never come back.

Path 1: the healthy rollout

Old version: fully replaced

One rollout walks the story. Edit the image, new ReplicaSet born, surge Pod up, new Pod Ready, old scales down, wave rolls on, old at zero, history kept, steady on v2. The answer is born at the steady hop, and the green dot starts back from there.

I edit the image1 s
New ReplicaSet2 s
Surge Pod up6 s
New Pod Ready12 s
Old scales down4 s
Wave rolls on14 s
Old at zero5 s
History kept1 s
Steady on v23 s

Not run yet.

Path 2: a bad image

Steady on v2: never reached

Same rollout, a bad image tag. The new Pod starts and crashes. The readiness probe fails every time. The new ReplicaSet never gets an available Pod, so the old ReplicaSet never scales down. At 600 s the deadline hits and the rollout is marked failed. The old version serves the whole time.

I edit the image1 s
New ReplicaSet2 s
Surge Pod up6 s
New Pod never Ready600 s
Deadline hitsfailed
Old keeps servingall traffic

Not run yet.

Path 3: too tight to move

Wave: never starts

Same rollout, maxSurge 0 and maxUnavailable 0. No extra Pod may exist, and no Pod may be down. The new ReplicaSet cannot scale up and the old one cannot scale down. Both rules are obeyed and nothing happens. The rollout freezes, and no deadline fires, because the deadline only counts a rollout that started moving.

I edit the image1 s
New ReplicaSet2 s
Surge blocked0
Unavailable blocked0
Nothing movesfrozen
Human loosens one numberthe fix

Not run yet.

Path 4: Recreate, the contrast

Zero downtime: not promised

The same deploy with strategy Recreate. All old Pods die first, then all new Pods start. Traffic stops for the whole gap, and the gap is priced in the open. The answer comes back only after the new Pods are Ready, which is why the green dot waits until the last hop.

I edit the image1 s
New ReplicaSet2 s
All old Pods diedowntime
New Pods startcold
New Pods Ready12 s
Traffic returnson v2

Not run yet.

Where the time goes

Every hop charges rent in seconds. The bar below is a worked example for one rollout of 3 replicas, not a measurement from a live cluster, but the shape is honest. The Ready hop and the wave hop are the big ones at 26 s of the 48 s total. Switch the scenario and watch the bar change. In the bad image story the Ready hop grows to 600 s, because the Pod never turns Ready and the deadline has to fire. In the frozen story the wave hop disappears, because the wave never starts. Move a simulator slider and watch the wave count, the floor, and the total move with it.

Replicas, surge, or the ready wait: move the sliders and watch the rollout bend

The budget bar above shows three fixed stories. This simulator lets you write your own. It answers the sizing question at the heart of this lesson: how big is the wave, how low is the floor, and how long does the rollout take for your replicas, your surge, your unavailable, and your ready wait. You set how many replicas the Deployment keeps, how many extra Pods may exist, how many may be down, and how long a Pod must stay Ready before it counts. Move a slider and watch the wave size, the most Pods at once, the fewest serving, the wave count, and the total change. The numbers are a teaching example, built from the formulas below, not live measurements. The shape is the lesson: the wave is bounded by the two numbers you set, and the total is the wave count times the ready wait.

3 replicas

How many Pods the Deployment keeps. More replicas mean more wave steps, and a higher floor for serving traffic.

1 extra Pod

How many extra Pods may exist above the replica count. More surge means a bigger wave step and a faster rollout.

1 Pod may be down

How many Pods may be down at once. More unavailable means a bigger wave step, and a lower floor for serving traffic.

5 s

How long a Pod must stay Ready before it counts as available. Longer waits make each wave step slower, and a flaky Pod less likely to take traffic.

Try this: (1) At the defaults, 3 replicas, surge 1, unavailable 1, ready wait 5 s, the wave size is 2, the most Pods at once is 4, the fewest serving is 2, the wave count is 2, each wave step costs 12 s, and the total is 48 s. (2) Raise the surge to 3 and leave the rest at default. The wave size grows to 4, the most Pods at once grows to 6, the wave count falls to 1, and the total falls to 36 s. The rollout is faster, and it costs 3 extra Pods of headroom. (3) Set the unavailable to 0 and leave the rest at default. The wave size is 1, the fewest serving stays 3, the wave count grows to 3, and the total grows to 60 s. Nothing ever goes down. The price is time. (4) Set the surge to 0 and the unavailable to 0. The wave size is 0. The rollout is frozen. No wave step can ever happen, and the total is not a number, it is a wait for a human.

Formulas, in plain terms. Wave size is maxSurge plus maxUnavailable. Most Pods at once is replicas plus maxSurge. Fewest serving is replicas minus maxUnavailable. Wave count is replicas divided by wave size, rounded up. Each wave step costs 7 s plus minReadySeconds: 7 s for the Pod to start and the probe to pass, plus the ready wait. Total rollout time is the wave count times the wave step, plus 24 s of fixed work: the template write, the ReplicaSet create, the scale-downs, the history write, and the steady check. If the wave size is 0, the rollout is frozen and the total does not exist.

Lab: roll it, watch it, roll it back

Four steps, all run on your own cluster. This build machine has no working cluster, so no output below is shown as run here. The k3s install was attempted for real and the server would not start: it fails with "failed to find cpu cgroup (v2)". Run the steps on your own machine, on a local k3s or kind cluster, and compare your output with the expected shape. Your names, hashes, and times will differ. The shape will not. The YAML in steps 1 and 4 was parsed with a YAML parser during this build, so the files are valid YAML. The kubectl commands were not run against a cluster here.

Step 1: write the Deployment

Three replicas, image v1, RollingUpdate with maxSurge 1 and maxUnavailable 1, minReadySeconds 5, progressDeadlineSeconds 600, revisionHistoryLimit 10, and a readiness probe on a cheap endpoint. Save it as web.yaml.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 3
  revisionHistoryLimit: 10
  minReadySeconds: 5
  progressDeadlineSeconds: 600
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: web:v1
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            periodSeconds: 5

Read the file before you apply it. The selector matchLabels and the template labels must agree, or the ReplicaSet will not adopt the Pods it makes. The strategy block is where the rollout lives: type RollingUpdate, surge 1, unavailable 1. The probe is what Ready means. Without it, a Pod counts as Ready the moment its container starts, and a broken app takes traffic.

kubectl apply -f web.yaml

Expected output, reader-side, on your cluster:

deployment.apps/web created
kubectl get deployments web
kubectl get replicasets -l app=web

Expected shape, reader-side: one Deployment at 3 of 3 available, and one ReplicaSet at 3 replicas. The ReplicaSet name carries a hash of the template. That hash is revision 1.

Step 2: change the image and watch the wave

One command starts the rollout. Watch it in a second window while it runs.

kubectl set image deployment/web web=web:v2

Expected output, reader-side, on your cluster:

deployment.apps/web image updated
kubectl rollout status deployment/web
kubectl get pods -l app=web -w

Expected shape, reader-side: rollout status reports "Waiting for deployment spec update to be observed" and then "Waiting for deployment web rollout to finish", and finishes with "successfully rolled out". In the watch window, one new Pod appears while 3 old ones still run, the new Pod turns Ready, one old Pod is deleted, and the pattern repeats until 3 new Pods run and no old Pod is left. Run kubectl get replicasets in the middle of it and you will see two ReplicaSets: revision 1 scaling down and revision 2 scaling up. That is the wave, in the open.

Step 3: read the history, then roll back

The rollout is done. History is what makes the way back possible.

kubectl rollout history deployment/web
kubectl rollout undo deployment/web
kubectl rollout status deployment/web

Expected shape, reader-side: history lists revision 1 and revision 2, with the image each one ran. Undo re-points the Deployment at revision 1. The wave runs in reverse: the old ReplicaSet scales up, the new one scales down, and v1 serves again. Undo does not delete revision 2. It just stops using it. Run history again after the undo and you will see a revision 3, which is the old template pointed at again. Rollback is a pointer move, not a rebuild.

Step 4: the ConfigMap trap

Now change a ConfigMap the Deployment mounts, and change nothing in the Deployment. Watch what does not happen.

kubectl create configmap web-config --from-literal=APP_ENV=production
kubectl rollout status deployment/web

Expected shape, reader-side: nothing. No new ReplicaSet is born, no Pod restarts, and rollout status reports the rollout already finished. A Deployment watches its own pod template, not the ConfigMap. The fix is one command, which restarts every Pod with the new config:

kubectl rollout restart deployment/web

That is the config-change rollout pattern. The ConfigMap side of it, how the new values reach the Pod and how long the mounted update takes, lives in the fold-in for Lesson 160. This lesson is the rollout side: the Deployment only rolls when its template changes, and restart is how you change the template on purpose without changing the app.

Check yourself

Three questions. No score is saved anywhere. This is just you against the material.

Basic to master

Deployments and ReplicaSets are not two skills. They are four levels of the same job, and every team I have worked with sits on one of them. The levels are not about how many field names you can recite. They are about whether the numbers change what gets shipped. Read them in order. Each level fixes the failure that hurt the most at the level below it.

Basic · One Deployment, one rollout, watch it finish

At the basic level you apply a Deployment and you watch the rollout finish. You can say what a ReplicaSet is, and you can read kubectl get pods and tell the old Pods from the new ones. You can run kubectl rollout status and wait for it to say done. The failure that ends this level is the first bad image, and the rollout that sits there doing nothing while you wonder whether it is stuck or slow.

Do this: run steps 1 and 2 of the lab on your own cluster and write down the two ReplicaSets you see in the middle of the wave, with their replica counts.

Intermediate · The arithmetic, and the floor

At the intermediate level you set maxSurge and maxUnavailable on purpose, and you can say the ceiling and the floor before you deploy. You know the wave size is the two added together, and the wave count is the replicas divided by the wave size, rounded up. You know a 1 replica Deployment with maxUnavailable 1 has a floor of 0 serving Pods, and you add replicas before you promise no downtime. You can read kubectl rollout history and say which revision is running.

Do this: take the simulator defaults and set the unavailable to 0. Watch the total grow. Then set the surge to 3 and watch it fall. Same replicas, same app, different price.

Advanced · The deadline, the ready wait, and the frozen rollout

At the advanced level you set minReadySeconds and progressDeadlineSeconds from the app, not from a default. You know the deadline is a timer, not a rollback, and the save is that the old Pods were never deleted. You can tell a frozen rollout from a slow one: a frozen rollout has surge 0 and unavailable 0, and no deadline will ever fire, because the deadline only counts a rollout that started moving. You know a ConfigMap edit rolls nothing, and you reach for rollout restart without thinking.

Do this: run step 3 of the lab and read the history after the undo. Say out loud why the undo made a new revision instead of going back to the old number.

Master · Rollouts as a team contract, and the PodDisruptionBudget

At the master level the rollout settings are a contract the team writes down: the surge the cluster can afford, the floor the SLO needs, and the ready wait the app earned from its own startup time. You know the PodDisruptionBudget can block a rollout, because an eviction that would break minAvailable is refused, and the rollout waits instead of breaking the budget. Lesson 48 teaches the budget. This lesson is where it meets the wave. You set revisionHistoryLimit high enough that the way back survives a week of deploys, and you write the change cause on every rollout so history can say why, not just what.

Do this: pick one service you run, read its Deployment, and write down its surge, its unavailable, and its history limit. Then check whether the floor it promises matches the SLO it owes.

Go deeper

maxSurge and maxUnavailable as percentages

Both fields take a count or a percentage. A percentage is rounded up for maxSurge and rounded down for maxUnavailable, and the rounding is the whole story at small replica counts. Twenty-five percent of 3 replicas is 0.75, which rounds up to 1 for surge and down to 0 for unavailable. That is a rollout that can start but can never take a Pod down, which is a slow rollout, not a frozen one. At 10 replicas the same 25 percent is 3 and 2, a real wave. Percentages scale with the Deployment. Counts do not. Pick percentages when the replica count moves, and counts when the floor is a promise in Pods, like "never below 2 serving".

revisionHistoryLimit, and why 10 is the default

The default keeps 10 old ReplicaSets. Each one is a small object, so 10 costs almost nothing, and it buys 10 deploys of way back. Set it to 0 and there is no undo at all, because the old ReplicaSet is deleted the moment it scales to 0. Set it to 2 on a team that deploys 5 times a day and the way back to yesterday morning is gone by lunch. The limit is a retention policy, not a tuning knob. Set it from how far back you might need to go, in deploys, not in days.

progressDeadlineSeconds vs minReadySeconds

Two timers, two jobs. minReadySeconds is per Pod: how long a Pod must stay Ready before it counts as available. It guards against a Pod that starts, flips Ready for one second, and crashes. progressDeadlineSeconds is per rollout: how long the whole Deployment may go without making progress before it is marked failed. It guards against a rollout that is stuck, like a bad image that never turns Ready. The deadline counts from the last progress, not from the start, so a slow but moving rollout never hits it. A rollout that never starts moving, like the frozen one in this lesson, never hits it either, because there is no progress to time out on.

Recreate, in one more paragraph

Recreate deletes every old Pod before it creates any new one. The gap is total downtime, and the length of the gap is the new Pods' startup time. It fits when two versions cannot run side by side: a store with one writer, a migration that renames a table the old version still writes to, a license that allows one copy at a time. It does not fit anything else. If you run Recreate because the rollout was slow, you traded slow for down. Say the downtime out loud before you choose it, and put the number in the deploy note.

How rollout undo really works

kubectl rollout undo does not rebuild the old version. It re-points the Deployment at the old ReplicaSet, and the Deployment controller runs the same wave in reverse. The old ReplicaSet scales up, the new one scales down, and the old template makes the old Pods. The undo itself is a new revision, which is why history shows revision 3 after you undo revision 2 back to revision 1. The failed revision stays in history. Undo never deletes it. It just stops using it. That is the same rule as the rollout: nothing is rebuilt, only re-pointed.

The ConfigMap trap, in full

A Deployment watches its own pod template. A ConfigMap is not part of the template, so editing it changes nothing the Deployment watches. The Pods keep running with the config they started with. Environment variables are frozen at Pod start, so a Pod that read the ConfigMap as env never sees the new value at all. A mounted ConfigMap file updates on a delay, through the kubelet cache, but the app has to re-read the file, and most apps do not. The reliable pattern is kubectl rollout restart, or a checksum annotation on the template that changes when the config changes, which makes the template change and the rollout start for real. The ConfigMap side of this, the watch and the latency, lives in the fold-in for Lesson 160.

The ReplicaSet counts, and adoption is by label

The ReplicaSet controller counts Pods by label. The selector in the ReplicaSet says which labels count, and the Pods it creates carry those labels, plus an owner reference that names the ReplicaSet. A Pod that matches the selector but was made by hand is adopted: the ReplicaSet counts it and owns it. A Pod whose labels change so it no longer matches is released: the ReplicaSet stops counting it. The selector is the membership rule, and the owner reference is the receipt. Change the selector on a live ReplicaSet and the Pods fall out of the count, which is why the Deployment owns the selector and you do not edit it by hand.

When the PodDisruptionBudget blocks the wave

A PodDisruptionBudget says how many Pods must stay up through voluntary disruptions, and a rollout scale-down is a voluntary disruption. If deleting the next old Pod would break minAvailable, the eviction is refused and the rollout waits. The rollout does not fail. It waits, and rollout status says so. The fix is not to force the eviction. The fix is to check whether the budget or the unavailable number is the wrong one. Lesson 48 teaches the budget itself. This is where it meets the wave.

kubectl rollout, flag by flag

The commands in this lesson are the ones Lesson 48 already uses, and this lesson is where they earn their meaning. status watches the rollout until it finishes or fails. history lists the revisions, with the change cause if one was written. undo re-points at an old revision, and --to-revision picks which one instead of going back one step. restart restarts every Pod without changing the app, which is the config-change pattern. set image changes the image tag, which is the most common way a rollout starts. All five take the workload by name. None of them touches a Pod directly. The controllers do that.

Chart-level rollback, link only

Helm keeps its own release history, one record per revision, and helm rollback points the release back at an old revision, the same pointer move this lesson teaches at the Deployment level. The Deployment rollback is the mechanism. The Helm rollback is the same move one level up, across every object in the chart at once. Lesson 104 teaches the chart side. This lesson does not re-teach it. Know which level you are rolling back at before you run either command, because a Helm rollback moves the whole chart and a Deployment undo moves one workload.

What changes at 10x and 100x

At 10x the replicas, the wave count is the number that matters, and percentages beat counts for surge and unavailable, because the wave scales with the Deployment. At 10x the deploys, revisionHistoryLimit is the number that matters, and 10 stops being enough, because the way back to yesterday is gone by lunch. At 100x, the rollout is a pipeline step, not a command I run by hand. The settings are code, the change cause is written by the pipeline, and the alert on a failed rollout fires before anyone has to ask whether the deploy is stuck. The arithmetic does not change. The number of Deployments it runs on does.

Further reading

The chain this lesson builds on, and the rollout commands already used: Lesson 48 Kubernetes Core. The scheduling step the wave depends on: Lesson 197 How a Pod Gets a Home and Starts Running. The hands-on scale and replace: Lesson 159 Kubernetes Lab: First Pod. ConfigMap and Secret propagation, and the mounted update: Lesson 160 Kubernetes Lab: Config and Storage. Chart-level rollback: Lesson 104 Helm. The controllers that care about names and nodes: Lesson 199 StatefulSets and DaemonSets. Work that finishes, for contrast with the loop that never does: Lesson 200 Jobs and CronJobs.

One time it broke

What broke

A deploy went out on a Friday afternoon with a bad image tag. The tag pointed at a build that never finished, so the new Pods started and crashed in a loop. The readiness probe failed every time. The rollout sat there, one new Pod trying to start, three old Pods still serving. Nobody noticed for an hour, because the old version was still serving and the dashboard was green. The alert that fired was the rollout age, not an error rate. The deploy was stuck, not broken, and stuck looks exactly like slow until you read the deadline.

Timeline

  • 15:02The image tag is changed. The Deployment controller makes revision 2. The new ReplicaSet scales to 1.
  • 15:04The new Pod crashes on start. The readiness probe fails. The ReplicaSet controller keeps the Pod count at 1 and the Pod keeps restarting.
  • 15:10The old Pods still serve all traffic. No error rate moves. The rollout looks slow, not stuck.
  • 16:02progressDeadlineSeconds hits at 600 s. The rollout is marked failed. The age alert fires.
  • 16:05I read kubectl describe pod and see the image pull error naming the tag. The tag never existed. The build that was supposed to make it failed an hour earlier.
  • 16:12kubectl rollout undo. The wave runs in reverse. Revision 1 serves again, and the deploy is re-run on Monday with the right tag.

What changed after

Three things. First, the pipeline checks the image tag exists before it changes the Deployment, so a tag that never built cannot start a rollout. Second, the rollout age alert fires at 10 minutes, not at the deadline, so a stuck rollout is a page, not a Friday evening surprise. Third, every deploy writes a change cause, so history can say who shipped what and why. The fix that lasted was the tag check, not the undo. The undo buys the way back. The check stops the next bad tag from starting.

If you remember nothing else

Design exercise

Size the rollout. An API runs 10 replicas. The SLO says at least 8 Pods must serve traffic at all times. The cluster can hold at most 2 extra Pods of headroom. The app takes 20 s to start and prove it is Ready. How do you set maxSurge, maxUnavailable, and minReadySeconds, and how long does the rollout take? Name the trade-off you are making.

Clarifying questions to ask

  • Is the floor of 8 serving Pods a hard SLO, or a target? A hard floor changes maxUnavailable from a choice to a constraint.
  • Is the 2 extra Pods of headroom a cluster limit, or a budget? Headroom is the surge, and the surge is the speed.
  • Is the 20 s startup measured, or guessed? The ready wait is set from the measured startup, not from a round number.
  • Can two versions serve side by side? If the answer is no, this is a Recreate deploy, and the downtime is priced in the open.
  • What happens when a Pod fails its probe during the rollout? The deadline is the timer, and the undo is the way back.

Worked approach

Start with the floor. At least 8 of 10 must serve, so at most 2 may be down. maxUnavailable is 2. The floor is the constraint, so it is set first.

Then the ceiling. At most 2 extra Pods may exist, so maxSurge is 2. The wave size is 2 plus 2, which is 4. The wave count is 10 divided by 4, rounded up, which is 3 waves.

Then the ready wait. The app takes 20 s to start and prove it is Ready, so minReadySeconds is 20. Each wave step costs 7 s plus 20 s, which is 27 s. Three waves times 27 s is 81 s, plus 24 s of fixed work, which is 105 s. The rollout takes just under two minutes.

Trade-offs to name. Surge against headroom: more surge is faster and costs Pods the cluster may not have. Unavailable against the floor: more unavailable is faster and risks the SLO. Ready wait against flaky Pods: a longer wait is slower and keeps a Pod that flips Ready for one second from taking traffic. Say which number is the hard one before you size anything, because the sizing changes completely when it moves.

Saved in this browser, so the Lessons index can show your progress across the course.

Next lesson
Lesson 199: StatefulSets & DaemonSets: The Controllers That Care About Names and Nodes

Deployments count. The next two controllers care about which Pod and which node. StatefulSets give each Pod a stable name and a stable volume, in order. DaemonSets put exactly one Pod on every node that matches. Same controllers, different promises.

Next: Lesson 199 →

Or browse the full course from the Lessons index.