Upgrades
Upgrade the guardian in place, keeping every realm, machine and sealed value, without re-commissioning any machine.
What an Upgrade Keeps
An upgrade keeps your data and your configuration. It handles each part of the deployment as follows:
| Part | On upgrade |
|---|---|
| The guardian's records | Migrated in place when the API server starts. Every realm, machine and sealed value is kept. |
| The secrets directory | Kept. Setup generates any secret the release adds and leaves the rest as it is. |
secrets/.env | Kept as it is. Setup never rewrites it, so a new default in .env.example does not reach it. |
| Sub-realm delegations | Re-signed once, on the first start after the upgrade to realm control, with the same roots and depth. Machines pick up the new chain when they next renew. |
| The identity service's realm | Imported only once. A release that changes it needs a re-import. See Identity Realm Changes. |
Upgrading to Realm Control
Realm control lets operators block machines, move them between compartments and set the networks they serve, from the console. On its first start, the release that adds realm control makes these changes:
- The node that each realm already had for telemetry becomes that realm's admin node. It keeps its identity and its compartment.
- Every sub-realm delegation made before admin nodes existed is re-signed once to carry the four powers. It keeps the same roots and depth, and gets a new validity period. No machine is re-commissioned.
- The guardian starts to record control actions and where each machine was moved.
The release also moves every image to Debian trixie, with node:24-trixie-slim as the default Node base. The API server's image builds on the FIPS base again.
Your secrets/.env keeps the NODE_BASE it was written with. To follow the release, set NODE_BASE=node:24-trixie-slim or your FIPS base yourself.
Upgrade Checklist
Pay particular attention to the identity service's notes, because its migrations are one-way.
Keep these changes in mind as well:
- Telemetry is no longer a setting. Setup ignores a leftover
GUARDIAN_TELEMETRYline and warns about it. - Machines enrolled before flow records existed export none. To turn flow records on for such a machine, set
export.flowstotruein itsconflux.jsonand restart conflux. - When a release changes what a manifest carries, upgrade conflux on your machines first.
Identity Realm Changes
The identity service imports its realm, the file that defines its roles and sign-in policy, only once, into an empty store. After that, it ignores the file.
A release that adds a role or changes the password policy therefore does not reach a deployment that has already run. Running setup again is not enough, because setup regenerates the realm file but does not apply it.
This failure is silent. If a new role is missing, everyone who should hold it is refused access, and no log says why.