Plan and roll out

Deploying is two steps, like terraform plan and apply: you make a plan that shows exactly what each device will get, then start a rollout that applies exactly that plan, a few devices at a time.

Make a plan

1. In the directory with your suta.yaml, run:

   suta plan -m "Fix sensor calibration"

   -m is optional: one line saying what the deploy is for. It becomes the name of the plan and its rollout in the dashboard and CLI, shown in quotes as your words. Without it, a rollout is named after what it changes. In CI, you can pass the commit subject: -m "$(git log -1 --format=%s)".

   To plan for some devices only, add --device NAME, --tag TAG or --site SITE. Tags must all match; devices and sites may match any.

2. Review the output. Each device is listed as:

   • + update: it gets a new generation. The lines below say what changes: the Suta OS version and hardware settings (and whether the device restarts), apps added, changed or removed, volumes and probation.
   • = unchanged: it already runs exactly this generation.
   • ! pinned: it’s pinned and keeps its generation.

   Below the totals, the plan names every device that will restart. Their apps stop until each device is back.

3. Commit suta.lock, which the plan updated.

Plans don’t change anything on devices, and cover only the devices of the project named in suta.yaml. You can also review a plan in the project’s Deployments: plans waiting for a rollout appear under Ready to deploy, and every plan is listed under Plans.

Start a rollout

Start a rollout of a plan from the CLI:

suta deploy PLAN_ID --wait

Or open the plan in the project’s Deployments and select Start rollout. Without a plan ID, suta deploy makes a plan, shows it and asks before starting. When the plan restarts devices, the question says how many and defaults to no; in the dashboard, you tick the restart notice before Deploy is available.

Option	Default	Description
--canary	Sized to the plan	Devices that deploy first, alone, 0 to 20.
--batch	Sized to the plan	Devices that deploy at a time after the canary, 1 to 500.
--max-failures	0	Failures to allow before the rollout pauses, 0 to 100.
--wait		Follow the rollout; exit with 1 unless every device succeeds.

Choose stages

Unless you choose otherwise, Suta sizes the stages to how many devices the plan updates:

Devices updating	Stages
1	The device deploys on its own.
2 to 9	One device first, then the rest together.
10 or more	About 5% first (1 to 20 devices), then the rest in up to four even batches of at most 500.

In the web app, Start rollout offers this as the recommended choice, beside All at once and Custom, and shows each stage before you start. With a single device there is nothing to choose.

Each stage starts only when every device in the previous one accepted its new generation. Each project runs one rollout at a time; rollouts in different projects run side by side.

What each device does

Each device first checks that the change really comes from Suta. Then:

1. Preparing: downloads the Suta OS image if it changes, pulls every container image and fetches its secrets. Nothing running changes yet.
2. Activating: restarts only the apps that changed. A new Suta OS version or new hardware settings restart the device into them instead.
3. Probation: every app must stay running and pass its probe, and the device must reach Suta, for the probation time.
4. Committing: the device accepts the generation.

If anything fails, the device restores the previous generation on its own, without waiting for Suta, and won’t try the failed one again unless you retry it. A power cut or a hang during the first boot of a new OS or new hardware settings also returns the device to the previous ones.

When devices are skipped

A rollout skips a device, rather than guessing, when:

Reason	Meaning
offline	It hadn’t checked in for two minutes when its wave started. Retry includes it again.
pinned	It was pinned after the plan was made.
changed_since_plan	Its software changed after the plan was made. Make a new plan.
removed	It was removed from the workspace.

Follow a rollout and see why a device failed

A project’s Deployments lists every rollout, newest first, with what it shipped, how many devices took it, who started it and how long it took. Filter by status or search for an app, a person or an ID. Open a rollout to see:

• Devices: each device’s state. A failed device shows the reason it reported, with links to Logs around failure and its Device software.
• Timeline: when each stage started and the outcome each device reported, in order.
• What it ships: each generation the rollout assigns, with its apps and settings. Select a generation’s ID to open its page.

Failed and rolled-back deploys also appear in Activity with the device’s reason.

Pause, resume and cancel

A rollout pauses by itself when more devices fail than --max-failures allows, or when a device hasn’t finished within 60 minutes. Then you can:

• Resume to continue, accepting the failures so far.
• Retry to include failed and offline devices again.
• Cancel to stop starting new devices. Devices already deploying finish on their own.

suta rollout show
suta rollout resume

Tip

In CI, use an API token with the Deploy software permission and run suta deploy --yes --wait after your images are pushed.

Roll back

To return one device to its previous generation:

suta rollback DEVICE

To roll back many devices, check out the previous suta.yaml and suta.lock from your repository, then plan and roll them out. See Roll back, retry and pin for more.