# Rolling Deployments and Rolling Groups Source: https://www.jawsdeploy.net/guides/rolling-deployments Take one machine out of service, finish with it, put it back, and only then move to the next - with the exact settings for a one-at-a-time rollout, a canary, and stopping when a machine fails. Rolling deployments update machines in controlled batches, allowing you to define the deployment order, stop on failure, and determine how far each machine progresses before the next begins. This guide walks through five tasks for configuring a safe, predictable rolling deployment. If you are deploying a service that handles traffic, start with the first task. > **// The problem a rolling group solves - Four rolling steps still take the fleet down** > > Take the four actions most deployments are made of: stop service, deploy package, start service, smoke test. As four separate steps, each one finishes on every machine it targets before the next begins - so step 1 stops every machine before step 2 deploys anything. Lowering the window changes the rate, not the sequence, and machine order is resolved per step, so `web01` leading step 1 says nothing about step 2. > > A **rolling group** is the fix: `web01` stops, deploys, starts and smoke-tests, and only then does `web02` begin. ## Rolling steps compared with a rolling group On the left every step sweeps the fleet before the next starts. On the right one machine is out of service at a time. ``` Rolling steps Rolling group stop web01 web02 web03 web01 stop > deploy > start > smoke deploy web01 web02 web03 web02 stop > deploy > start > smoke start web01 web02 web03 web03 stop > deploy > start > smoke smoke web01 web02 web03 fleet stopped before the one machine out of first package lands service at a time ``` ## Where these settings live Everything below is on a project's **Steps** tab. There is no feature switch to turn on: a step already has a window and a machine order, and you change them. A rolling group is created by turning an existing step into one, then moving its neighbours in. ## Finding each control - **Create a rolling group**: **Step actions** on the step you want to start from, then **New rolling group from this step**. Add each adjacent step with **Move into '...'**. - **A step's window and order**: Open the step, then the **Rollout** card. - **A step's failure policies**: The **Failure** card on the same step. - **A group's settings**: Click the group's header row in the step list. That opens its own panel: **Rolling group**, **Rollout**, **Failure**, and **Steps in this group**. - **Move a step in or out**: **Step actions** on that row: **Move into '...'**, or **Take out of group**. - **Get rid of a group**: **Dissolve group**, at the bottom of the group's panel. Its steps stay in the project. In the step list a group is drawn as a header row with its members indented underneath, carrying a step count and a caret to collapse it. Dragging moves whole blocks - an ungrouped step, or a group with all its members - so a drag can never split a group. ## 1. Run several steps per machine before moving on Your deployment is the usual four actions and the fleet still goes down. Put the four steps in a rolling group. 1. Make sure the four steps sit next to each other in the step list, with nothing in between. 2. On the first step, open **Step actions** and choose **New rolling group from this step**. 3. On each of the other three, open **Step actions** and choose **Move into '...'**, naming the group you just made. The option only appears on steps that can legally join it. 4. Click the group's header row to open its settings, and give it a name under **Rolling group**. The name appears in the step list, the deployment preview and the logs. 5. Leave **Window size** at its default of 1. That is one machine out of service at a time. 6. **Save group.** ## Defaults worth confirming on the group - **Window size** - 1. Raise it only if you have capacity to spare. - **Deploy to machines in this order** - Machine name, unless you want a canary first. - **When the group fails on one machine** - *Stop, do not start the group on any further machine*. - **When a step in the group fails on one machine** - *Skip the group's remaining steps on that machine*. ### Rules the editor enforces - Members must be consecutive, with no non-member step in between. If one is in the way, the group is rejected and the message names it. - Every member's **Run on** must be *target machines*. A group works by moving from machine to machine, so a step that runs on a worker or drives cloud targets has no machines to roll across and cannot join. - Groups do not nest, and a group holds at least one step. ### What the group takes over Once a step is a member, the group owns the window, the machine order, the order tags, the barrier, and *when this step fails on one machine*. The step's **Rollout** card is replaced by a note naming the group and showing the settings actually in force. Those stored values are not erased - they apply again if the step leaves. Each member keeps its own machine filters, its own *when this step fails*, its own *run after stop*, and its own execute condition, evaluated per machine. > **// Output values - Inside a group, a step sees only the current machine's output** > > A step inside a group sees only the current machine's output from earlier steps in the same group. Once the group finishes, every machine's output from every member is visible to every later step. > > This is a fact about the run rather than a setting: the group works machine by machine, so when `web02` reaches member 2, `web01` may not have started member 1 and the value does not exist yet. Steps *before* a group are unaffected, because they completed on every machine. ## 2. Roll out one machine at a time The deployment is a single action - deploy the package, restart the service - and you want to control how many machines it touches at a time. You do not need a group for this. Open the step and go to the **Rollout** card. Set the window, labelled *Parallel execution - maximum number of machines*, to 1. It is already the default, so confirm it rather than assume it. Leave **Deploy to machines in this order** on **Machine name** for a stable, predictable order. Raise the window to move a few machines at a time instead. It is capped by your organization's `maxParallelMachines` setting, which defaults to 8; a window above the cap is rejected. The window controls how many machines one step touches at a time. It does not change that the step finishes on every machine before the next step starts. If the deployment is more than one action, task 1 is the answer. > **// Common misreading - The Rolling deployment tick box is not what enables any of this** > > It is a preset for the *ordering* controls: ticking it sets the machine order to tag priority and turns the barrier on, and unticking returns to machine-name order with no barrier. It does not change the window and it does not create a group. See task 3, which is where you would want it. ## 3. Deploy to a canary first You want one machine to take the release first and prove it before the rest of the fleet follows. 1. Tag your canary machine, for example `canary`. 2. Open the group's settings from its header row - or the step's **Rollout** card, for a single rolling step. 3. Set **Deploy to machines in this order** to **Tag priority**. 4. In the tag list it reveals, put `canary` first, then any further tags in the order you want them. 5. Tick **Wait between machine groups**, the barrier. A machine's rank is the index of the first tag it carries. Machines run in rank order, and by machine name within a rank, so the order is stable between deployments. Machines carrying none of the tags run last - they are not excluded, since excluding machines is still the job of the machine filter. If the tag list ends up empty, the order falls back to machine name rather than an arbitrary one. With the barrier on, every machine of one tag rank finishes before the next rank starts, so the canary goes alone all the way through the group. On a single step the **Rolling deployment** tick box does steps 3 and 5 in one click; you still pick the tags. Unticking keeps your tag list, so re-ticking restores the choice. A group's panel has the same two controls but no such preset. ### Running a smoke test only on the canary Give the smoke-test member a machine tag filter of `canary` and leave the other members unfiltered. A group's machine set is the union of the machines its members target, and on each machine only the members that target it run. Every machine enters the rollout and runs the other members; only the canary runs the smoke test, and on the rest that column reads `not targeted`. Grouping never widens a step's reach. A step targets exactly the machines it would have targeted on its own, environment scoping is untouched, and deployment-level machine include/exclude still applies ahead of everything else. > **// Watch for - A filter that matches nothing never runs anywhere** > > A member whose filter matches no machine in the group never runs at all. It is visible - the rollout summary shows `not targeted` in every cell of that member's column - but nothing warns you at the moment you save it. Check the deployment preview before you deploy: it lists, machine by machine, exactly which steps will run where. ## 4. Stop the rollout when a machine fails A machine fails part-way through and you do not want the rollout to carry on. Three settings answer three different questions, evaluated inside out. Getting the right one is the difference between stopping the rollout and stopping the deployment. ## The three levels **When a step in the group fails on one machine** Do the group's remaining steps run on this machine? *Skip the group's remaining steps on that machine* is the default; *Carry on with the group's remaining steps* is what a cleanup or notification member needs. On the group's **Failure** card. **When the group fails on one machine** Does the next machine start? *Stop, do not start the group on any further machine* is the default. On the group's **Failure** card. **When this step fails** Does the rest of the deployment run? This is the only one of the three that can stop the deployment. On the member's own **Failure** card. Walk it through. A member fails on `web01`. The first setting decides what happens on `web01` itself. `web01` is now a failed machine, so the second decides whether `web02` starts. The third, set on the member that failed, decides whether the steps *after* the group run. **The most common mistake.** Both group settings are about the rollout - which machines, and which of the group's steps, still run. Neither stops the deployment. To stop the deployment, open the member itself and set **When this step fails** to **Stop the deployment**. The step editor says so on every member. On a single rolling step the equivalents are both on that step's **Failure** card: **When this step fails on one machine** (*Carry on with the other machines* by default, or *Stop, do not start any more machines*) and **When this step fails** (*Continue to the next step* by default, or *Stop the deployment*). ### Rules that hold whatever you set - Cancellation always wins. A cancelled deployment stops between members, not just between steps. - Stopping never kills work in flight. It stops *new* machines and steps from starting; whatever is already running finishes. - **Run after stop** steps still run, members inside a group included. That is where cleanup and notification belong. - A failure is an Error-level log line, which raises the step's error count - and that count, not the status, is what every failure policy reads. > **// Expect this - A failed script reports the deployment as "Completed, with errors"** > > The headline status comes from the monitor status, and a failed script does not produce a failure status - it produces error-level log lines. The error counts are correct and the rollout stops correctly; the headline still says Completed. A step that *times out* does report Failed. If you are checking whether a rollout stopped, read the rollout summary and the error counts rather than the headline. > > Separately, **an unreachable agent aborts the whole deployment**, regardless of any failure setting above. The rollout summary is still written, so the machine left part-way through is named. If a deployment ends abruptly and none of your failure policies explain it, check whether an agent was unreachable. ## 5. Change a rollout setting and have it take effect You changed the group's window size, redeployed, and the deployment ran the old value. A release is a snapshot. When you create one, the group and all its settings are copied into the release alongside the steps, and each release step's membership is rewritten to point at the snapshotted group. Editing the project afterwards does not change what an existing release deploys. So: change the setting on the project, **create a new release**, and deploy that. Redeploying an existing release deploys the settings that release was snapshotted with. ## What you see while it runs The **deployment preview** shows the resolved machine order, the window, the barrier, and for a group a machine-by-machine list of exactly which steps will run where. The **log tree** runs Group to Machine to Step, with machine nodes created up front in resolved order and starting as *queued*, so machines not yet reached are visibly waiting rather than missing. A **rollout order line** names the machines in the order they will run and why that order was chosen. ## The rollout summary Written even when the rollout stops part-way - which is exactly when it matters, because that is when machines are left on mixed versions. ``` Rollout summary - rolling group 'web-rollout' Machine stop-service deploy-package start-service smoke-test web01 ok ok ok ok web02 ok failed skipped skipped web03 not run not run not run not run ``` ## Driving it from the API Every setting in this guide is also reachable over the REST API and from MCP clients. See [List rolling groups](https://www.jawsdeploy.net/rest-api/rolling-groups-list), [Create a rolling group](https://www.jawsdeploy.net/rest-api/rolling-group-create), [Update a rolling group](https://www.jawsdeploy.net/rest-api/rolling-group-update), [Dissolve a rolling group](https://www.jawsdeploy.net/rest-api/rolling-group-delete) and [Move a step in or out of a rolling group](https://www.jawsdeploy.net/rest-api/project-step-rolling-group). Related reading: [Project Steps Explained](https://www.jawsdeploy.net/guides/project-steps-explained) for how steps target machines in the first place, and [Projects and Deployment Logic](https://www.jawsdeploy.net/guides/projects-and-deployment-logic) for where the deployment process sits.