Upgrades

One node means an upgrade is a short announced window rather than a rolling replacement. It is measured in seconds. Announcing it is more honest than pretending it does not happen.

What an upgrade moves and what it leaves

The binary changes. The data directory does not: it is a volume the new process opens, so every database, every sealed credential and every receipt carries over untouched.

Schema migrations run at startup, per module, from SQL embedded in the binary. There is no separate migration command to run, no window where the schema and the binary disagree, and no way to start a version against a directory it has not migrated. A migration that fails stops the start rather than leaving the database half moved.

The sequence

1. Announce the window.
2. Confirm the backup is current. The replication log is where you check it, and the check belongs before the upgrade rather than after.
3. Bring the new image up in place of the old one. The volume is untouched by a recreate.
4. Probe it: automaton health -url <your node> for alive, and the same command with -ready for whether it wants traffic. A node that answers both is serving.
5. Confirm data, not just liveness. automaton apikey list -data <dir> reads a real table.

A stopping node drains rather than dropping calls. It stops accepting new work, finishes what is in flight, and exits inside its grace window, so in-flight requests end as completed responses rather than reset connections.

Rolling back

Rolling back the binary is putting the previous image back and starting it. The asymmetry to plan around is the schema: a migration that has already run does not roll back with the binary.

That gives you two different operations wearing one name.

A rollback across no migration is a rebuild and a restart. Minutes.

A rollback across a migration is a restore from backup to a point before the upgrade, then the old binary. That loses whatever was written in between, which is why the decision is made before the upgrade rather than during the incident.

So read the release's migrations before you upgrade and decide which of the two a rollback would be. If it is the second, take a fresh restore point immediately before the window and write down what losing it would cost.

Pinning the catalog across an upgrade

An upgrade can change which apps and actions a node offers. If you want a project's behaviour held still across the change, freeze the catalog first and pin the project's environment to that snapshot:

automaton snapshot create -data /var/lib/automaton -project acme
automaton snapshot list   -data /var/lib/automaton
automaton snapshot pin    -data /var/lib/automaton -project acme -env prod -snapshot snp_...

The node loads the app definitions at startup, so the order is: start the new version once, then snapshot what it loaded, then decide whether to move the pin. automaton snapshot envs shows what each environment resolves through today, and automaton snapshot promote moves one environment onto another's snapshot with the evidence attached.

Key rotation

Rotating the vault key is not built. The sealed envelope format is ready for it and the re-sealing pass is not written, so today the key a deployment starts with is the key it keeps. Plan your key custody on that basis: the control you have is who can read the key, not how often it changes.