Rolling update — incremental replacement, surge and unavailability

The rolling update is the workhorse of Kubernetes deployments. Old and new versions of a workload coexist during the rollout, each carrying a share of the traffic, until the old version is fully replaced. The pattern needs no extra infrastructure, no duplicate environment, and no traffic-routing layer beyond what Kubernetes already provides. Its limits - schema compatibility, rollback granularity, and a non-instant switch - are the price of that simplicity.

How a rolling update works

A rolling update replaces pods one batch at a time. The Deployment controller starts new pods, waits for them to become ready, terminates old pods, and repeats until the desired replicas are all the new version. During the rollout, both versions serve traffic because the Service routes to every pod that is ready.

flowchart LR
    A["Old v1 pods"] --> B["+ new v2 pods"]
    B --> C["- old v1 pods"]
    C --> D["All v2 pods"]

The shape of the curve is controlled by two fields on the Deployment spec:

• maxSurge controls how many pods can exist above the desired replica count during the rollout. A maxSurge: 25% on a 10-replica Deployment allows the controller to spin up 3 extra pods (rounded up) so the new version can become ready before the old version is terminated.
• maxUnavailable controls how many pods can be absent from the desired count during the rollout. A maxUnavailable: 25% allows the controller to terminate up to 3 old pods (rounded down) before their replacements are ready.

The two settings compose. maxSurge: 25%, maxUnavailable: 0% means the rollout doubles the fleet briefly but never drops below the desired count. maxSurge: 0%, maxUnavailable: 25% means the rollout never exceeds the fleet size but accepts a 25% capacity dip during the rollout. The trade-off is between extra capacity and continuity.

Observing a rolling update

The rollout produces a status that the controller tracks. The two commands that matter most:

kubectl rollout status deployment/$NAME
kubectl rollout undo deployment/$NAME

The first command blocks until the rollout completes or fails and prints the rollout state. The second command reverses the rollout by re-applying the previous ReplicaSet and scaling the new one down. Rollout history is kept by default; older revisions can be inspected and explicitly rolled back to.

sequenceDiagram
    participant K as kubectl
    participant C as Controller
    participant RS1 as ReplicaSet v1
    participant RS2 as ReplicaSet v2
    K->>C: rollout status deployment/$NAME
    C->>RS2: scale up
    RS2->>C: pods ready
    C->>RS1: scale down
    RS1->>C: pods terminated
    C-->>K: rollout complete

A failed rollout - one where new pods never become ready - is stuck, not retried indefinitely. The status command reports the failure; the undo command restores the previous ReplicaSet.

When rolling update is the right default

Rolling update fits workloads that are:

• Stateless or near-stateless. A pod that holds no in-memory state can be terminated and replaced without losing requests.
• Backward- and forward-compatible. Both versions can read and write the data the other produces. APIs are versioned; schemas are additive; messages ignore unknown fields.
• Replicable. The workload can run more than one instance simultaneously without coordination cost.

A REST API with a versioned URL, no in-pod session state, and additive database migrations is a textbook fit. So is a background worker that consumes a queue and writes to a durable store.

When rolling update is wrong

Rolling update is the wrong pattern when:

• The change is incompatible with the old version. A breaking API contract or a backward-incompatible schema change forces old and new to coexist in a state neither can read.
• The startup time is long. A rollout that takes 30 minutes is a rollout during which the old version is still serving production traffic; the slower the start, the longer the exposure window.
• The change is high-risk and the blast radius must be minimised. A 100% rolling update means the new version eventually serves every user. Canary is the pattern for small-blast-radius releases.

Production discipline

1. Default to rolling update for stateless services with additive schemas and versioned contracts.
2. Set maxSurge and maxUnavailable deliberately rather than relying on defaults; the defaults assume headroom you may not have.
3. Watch the rollout, do not fire and forget. A stuck rollout means new pods are not becoming ready; investigate, do not let it run.
4. Never use rolling update for breaking schema changes. Use expand-and-contract with multiple rolling updates.

Cross-course references

• Kubernetes for Production Sysadmins - Parts XIV (Workloads) and XXII (Updates) cover Deployments and the rolling update mechanism in depth.
• This course, Part LVIII-01 (The deployment pattern taxonomy) establishes where rolling update sits in the trade-off space.
• This course, Part LVIII-03 (Canary and progressive delivery) covers the pattern that addresses high-risk rolling updates.

Quiz