Roll back, retry and pin

Everything a device runs is one generation. Each time a device is given a generation is a numbered deploy on that device: deploy #1, #2 and so on. To see a device’s deploys, open the device and select the Software tab, or run suta device generations DEVICE.

Rollouts change many devices at once from suta.yaml. See Plan and roll out. This page covers changes to one device at a time.

What’s on the Software tab

• Running now: the accepted generation’s ID and deploy number, the Suta OS version, the board, the device’s site and the agent version.
• Deploying: while a new generation is on its way, its progress through Preparing, Activating, Rebooting (only when the OS changes), Probation and Committing. If the new generation fails its checks, the device shows Restoring and puts the previous one back on its own.
• Apps: each app’s state, restarts, health check result and the last error.
• Configuration: the suta.yaml and suta.lock behind the running generation. See See a device’s suta.yaml.
• History: every deploy to the device, newest first, with its result, how it was assigned (a rollout, a rollback, a retry or a move to Suta OS), who assigned it, when, why it failed, and a summary of what changed.

Select a generation’s ID to open its page: its full contents and every device given it.

See a device’s suta.yaml

Configuration on the Software tab shows the suta.yaml that produced the generation the device runs, as it was planned, with who planned it and a link to the rollout that applied it. Select suta.lock for the image digests, OS version and secret versions that plan pinned. Copy and Download give you either file as is. To see an older generation’s suta.yaml, select suta.yaml on it in History.

From the CLI:

suta device config DEVICE                 # the running generation's suta.yaml
suta device config DEVICE 5               # deploy #5's
suta device config DEVICE --lock          # its suta.lock
suta device config DEVICE > suta.yaml     # save it to plan from

The output is valid YAML: the lines about the device and plan are comments, so you can save it and deploy it again, or run suta device explain DEVICE -f suta.yaml against it.

A few things to know:

• Files you wrote with source: appear inline as content:, because Suta receives their content, not the file.
• Comments and formatting from your original file aren’t kept. The settings are the same.
• A rollback or retry reuses a generation, so it shows the suta.yaml of the plan that generation came from, not a new one.
• The file covers the whole project: its sites: and devices: overrides for other devices too. Use suta device explain to see which values apply to this device.

Anyone who can view the device can read its suta.yaml. Secret values are never part of it, only secret names.

Compare generations

To see exactly what changed between two generations, select Changes since deploy #N on a deploy in History. It lists changes to images, environment variables, secret versions, files, ports, volumes and health checks. Secret values are never shown. From the CLI:

suta device diff DEVICE          # the previous generation against the current one
suta device diff DEVICE 5 8      # the generations of deploys #5 and #8

Roll back

Select Roll back to return to the accepted generation before the current one. The dialog names its deploy number. To go further back, select Roll back to this on an older accepted generation in History. From the CLI:

suta rollback DEVICE
suta rollback DEVICE --to 5

A rollback is a new deploy with a new number. The device checks it during probation like any other generation, and keeps the current one if the older one fails.

Retry a failed generation

A device won’t try a generation again after it failed or was rolled back. Select Retry on that generation in History to assign it once more, for example after fixing a database it depends on. From the CLI, run suta device retry DEVICE NUMBER.

Pin a device

Select Pin to hold a device at its current generation, with an optional reason. Plans list a pinned device as Pinned and rollouts skip it until someone selects Unpin. You can still roll back a pinned device. From the CLI:

suta device pin DEVICE --reason "Trade show demo"
suta device unpin DEVICE

Note

Rolling back, retrying and pinning need the Deploy software permission. Without it, the Software tab is read-only.

When a deploy fails

A failed or rolled-back generation shows its reason in History, and the Deploy failed condition can open an alert. The device keeps running its previous generation.