Rolling Upgrade¶
Staged rollout process — instantiates Compatibility Management
Rolls a new version out in small batches while the old version keeps serving, so the system runs in a safe mixed state the whole way and never has to go fully dark to change.
Rolling Upgrade moves a whole population of instances from an old version to a new one incrementally — batch by batch, node by node, region by region — so that at every moment old and new are both running and both serving. Its defining move is that it deliberately lives in the mixed-version state instead of avoiding it: rather than a flag-day cutover where everything flips at once, it advances one batch at a time, and it only promotes the next batch while old and new keep interoperating within tolerance. If a batch goes bad, it halts and holds before the damage spreads. That safety rests on one precondition — the change must be compatible enough for old and new to coexist — which is exactly what separates a rolling upgrade from a hard cutover.
Example¶
A payment service runs forty API servers behind a load balancer, and checkout can never go dark. To ship v2, the team rolls it out in waves. First a canary: drain and upgrade two servers, then watch error rate and latency for both older and newer client traffic. It looks clean, so five more, then the rest. Throughout, the load balancer keeps routing live requests to whichever servers are healthy, so at any instant a mix of v1 and v2 servers is handling real checkouts — and because a client request can land on either, v2 was built to accept v1's request shape. This is a rolling deployment with a canary and connection draining, the standard shape behind orchestrators like Kubernetes.
The outcome is the full fleet on v2 with zero downtime and the failure surface never larger than the current batch. Had they flipped all forty at once, a bad v2 would have taken checkout down globally and simultaneously — the blast radius the staged roll exists to shrink.
How it works¶
- Partition and advance. Split the population into batches and upgrade one at a time, leaving the rest on the old version and serving; availability is preserved because the whole set is never offline at once.
- Hold the mixed-version invariant. Old and new must interoperate for the duration, so the change is constrained to be coexistence-safe — typically by an expand-then-contract sequence: add the new behavior compatibly first, remove the old path only after everyone has moved.
- Health-gate each step. Promote the next batch only while old-to-new traffic stays within tolerances; on a bad batch, halt and hold so the failure stays contained to that batch rather than reaching the fleet.
The distinguishing thing, against its siblings, is that it operates the move as a continuously-serving, health-gated fleet choreography — and its safety hinges on enforcing old-and-new compatibility live, at every step, not just asserting it on paper.
Tuning parameters¶
- Batch size — one node at a time versus large waves. Small batches shrink the blast radius and surface trouble early but stretch the rollout; large waves finish fast but put more at risk at once.
- Health gate and bake time — how clean, and for how long, each batch must look before advancing. Tight gates catch slow-burn regressions but slow the roll; loose gates move quickly but let a fault spread before it is noticed.
- Coexistence discipline — whether the change is split into a compatible add-then-remove (expand/contract) sequence. Full expand/contract lets almost any change roll safely but costs two releases; skipping it is faster but only safe for already-compatible changes.
- Halt threshold — the error or latency signal that automatically pauses the roll. A sensitive threshold pauses on noise and stalls delivery; a dull one lets real damage accumulate before stopping.
- Mixed-window duration — how long old and new are allowed to coexist. Short windows limit the compatibility surface you must keep working; long windows ease slow-moving dependents but mean carrying two versions in production longer.
When it helps, and when it misleads¶
Its strength is change with no global downtime and a small blast radius: each batch is evidence about the next, so trouble is caught while it is still local, and a large heterogeneous fleet can move without a flag day. It pairs naturally with staged commitment — you learn as you go and can stop advancing at any point.
Its central failure mode is the assumption hidden in its premise: that old and new can coexist. Push a genuinely breaking change through a rolling upgrade as if it were compatible, and the mixed state itself becomes the outage — v1 and v2 corrupt each other's requests or records while both are live, which is worse than a clean cutover would have been. The discipline that prevents this is the expand-and-contract (parallel-change) pattern[n1]: make the change compatible first, roll it, and only then remove the old path. A related misuse is treating the halt as an undo — a rolling upgrade contains a bad batch by stopping, but restoring a prior state is a rollback-and-checkpoint concern, not something the roll itself provides. Watch, too, for the slow tail: a batch that passes its gate but degrades gradually, which is why bake time and mixed-traffic monitoring matter as much as the pass/fail check.
How it implements the components¶
migration_path— it is the path from old to new, executed as a phased, continuously-serving rollout rather than a single cutover.compatibility_rule— it enforces the coexistence rule operationally: advance only while old and new interoperate within tolerance, making the rule a live gate on the rollout rather than a static declaration.
It does not write the instructions dependents follow to move (that is Migration Guide) or transform stored data and schemas across the change (Schema Migration); it does not declare the compatibility rule or its support window ahead of time (Backward Compatibility Policy, Support Lifecycle Schedule) or tabulate the supported combinations (Compatibility Matrix). It consumes those and carries out the move.
Related¶
- Instantiates: Compatibility Management — Rolling Upgrade is how a change is applied across a live population while old and new safely coexist.
- Consumes: the coexistence guarantee that makes the mixed window safe — the compatible interface promised by Backward Compatibility Policy and, for data, prepared by Schema Migration.
- Sibling mechanisms: Schema Migration · Migration Guide · Backward Compatibility Policy · Compatibility Matrix · Adapter Layer · API Versioning · Compatibility Test Suite · Semantic Versioning · Protocol Negotiation · Support Lifecycle Schedule
Editorial Notes¶
Form Classification¶
Form family: Intervention, Treatment & Transformation
Rationale: Rolling Upgrade operates by directly upgrades successive batches while preserving service and mixed-version compatibility. That concrete deployed or enacted form is Intervention, Treatment & Transformation under the frozen taxonomy.
Nearest alternative: Protocol, Workflow & Routine — Although Protocol, Workflow & Routine can support this mechanism, the frozen evidence makes its operative form the act that directly upgrades successive batches while preserving service and mixed-version compatibility; the alternative is therefore secondary rather than defining.
Review outcome: Adjudicated after independent review; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Specialized
Rationale: Small-batch mixed-version rollout without full outage is a canonical distributed-software upgrade pattern.
Related originating lineages:
- Engineering & Design — Engineering design, reliability, and systems-safety practice supplies a parallel or contributing lineage for the mechanism's defining operation: rolls a new version out in small batches while the old version keeps serving, so the system runs in a safe mixed state the whole way and never has to go fully dark to change.
Review resolution: Both blind reviewers agree that computer_science is the primary historical origin. Explicit reconciliation of alternate origin disagreement starts from reviewer_a’s mechanism-specific evidence: Small-batch mixed-version rollout without full outage is a canonical distributed-software upgrade pattern. Reviewer A proposed alternates=none, origin_mode=single_lineage, domain_reach=specialized, and encyclopedia_synthesis=false; reviewer B proposed alternates=engineering_design, origin_mode=single_lineage, domain_reach=specialized, and encyclopedia_synthesis=false. The final record retains every independently supported alternate from either review (engineering_design) without an arbitrary cap, selects origin_mode=single_lineage to represent the combined lineage evidence, and keeps domain_reach=specialized and encyclopedia_synthesis=false from the more mechanism-specific assessment. Present-day transfer is recorded as reach and is not treated as proof of historical origin.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
A rolling upgrade's safety is bought before it starts, not during it: the roll is the safe way to apply a compatible change, not a way to make a change compatible. If old and new genuinely cannot coexist, no batch size, gate, or bake time rescues it — the fix is compatibility work (an expand/contract split, an adapter, a schema migration) upstream of the first batch.
[n1] Expand-and-contract (also called parallel change): first widen the system to support old and new behavior at once, migrate everything across, then remove the old path — so no single deploy is ever breaking. It is the standard discipline that makes a rolling upgrade safe across schema or interface changes. ↩