Upgrade and rollback¶
Upgrade and rollback¶
Rolling upgrade with compatible handoff versions¶
Upgrading the standby¶
- Check that both releases share a handoff version.
- Record the active router's
ha.epochfrom/narwhal/state. - Stop the standby.
- Install the new deployment set on that host.
- Start the upgraded router as standby.
- Check that
/healthreturns HTTP 200 on the new standby. - Check that
/readyreturns HTTP 503 on the new standby.
Handing off to the upgraded router¶
- Stop the old active router gracefully.
- Verify the upgraded router's
ha.epochexceeds the epoch recorded in Upgrading the standby. - Check that it is the only backend returning HTTP 200 from
/ready.
Upgrading the former active router¶
- Install the same deployment set on the stopped router's host.
- Start that router as standby.
- Wait for its
/readyto return HTTP 503.
Upgrading across a handoff-version change¶
Incompatible handoff versions need a maintenance window.
- Stop ingress.
- Stop both routers.
- Install the same deployment set on both hosts.
- Start the intended primary.
- Start its standby.
- Confirm the primary holds the lease.
- Confirm the primary is the only backend returning HTTP 200 from
/ready. - Restore ingress.
Rolling back¶
- Remove the router you are rolling back from the load balancer.
- Stop the new router gracefully.
-
Inspect the rollback build's contract support:
-
Restore these as one unit:
- the code
- the configuration
- the profiles
- the first-token calibration artifact for the live process generations
- a state handoff the restored build supports
- Run preflight. If its
profileorcalibrationgate reports a changed process generation, regenerate the profiles and the first-token calibration. - For fresh roles and zeroed counters, set
recovery.resume: falseand drop--resume. - Confirm exactly one router holds the lease: the rollback router or its fenced peer.
- Start the rollback build.
- Check that
/healthreportsstatus: ok. - Check that
/readyreturns HTTP 200. - Check that roles and cumulative counters are present.
- Send one completion request and confirm it succeeds.
- Return the router to service.
- Restore its standby.