How to roll out a gateway update in stages
Wiki: Setup concepts, Releases
When to use this
You want to move a group of gateways onto a new signed build without pushing it to every device at once. A staged rollout pins the new version to a small first group, waits until those gateways have actually applied it, then moves on to the rest, so a bad build only ever reaches one small group before you notice.
Steps
- As a super_admin with two-factor authentication set up, click Operations under Admin at the bottom of the sidebar,
then Releases (
/ops/releases) on the console’s own left rail. - Find the release you want to roll out. It needs a Signed badge and an Artifact uploaded badge, an unsigned release or one with no uploaded build can never actually reach a gateway. Click Roll out on its row.
- In the dialog, assign gateways to Stage 1 or Stage 2 from the picker (each row shows the gateway’s name, site, and the build it is currently running). Stage 1 is the small first group, put your bench or lowest risk machines here. Every other gateway you want on this version eventually goes in Stage 2.
- Click Start rollout. Stage 1 is pinned to the new version right away, its gateways start showing update pending the same as a single manual pin.
- Watch the Active rollouts list on the same page. Each stage shows how many of its gateways have actually applied the version, for example Stage 1: 2 of 2. Advance only turns on once every gateway in the current stage has applied it, until then it stays visible but grayed out with the reason. Click Advance to pin Stage 2.
- Use Pause to hold a rollout in place without changing anything, and Resume to pick it back up. Use Roll back to stop it for good and clear the pin from every gateway it touched, you are asked to confirm first since this cannot be undone from here. A rolled back rollout does not undo an update a gateway already finished applying, it only stops pushing the version any further.
Notes
- While a rollout is running or paused, it owns the pin for every gateway it targets. That gateway’s own detail page shows an in rollout note next to its version picker and the picker is grayed out, so you always have one place controlling a given gateway’s pinned version at a time, never two controls fighting over the same setting. Once the rollout finishes or is rolled back, the picker on that gateway’s page goes back to normal.
- A rollout only ever has these two stages, there is no way to add a third. If you need finer control than that, roll out to Stage 1, confirm it looks right, then hand pick a smaller Stage 2 group before advancing further, or pin remaining gateways one at a time from their own detail pages once you are satisfied.
- To pin a single gateway outside of a rollout, use its own detail page instead, see How to manage gateways: the gateway home.