stratumctl admin upgrade

Release upgrades: plan, start and follow them, and what each node runs

stratumctl admin upgrade [flags]

Subcommands

stratumctl admin upgrade acknowledge: Acknowledge a failed upgrade: clear its readiness findings
stratumctl admin upgrade apply: Continue a stage-only upgrade: back up and upgrade the nodes
stratumctl admin upgrade available: List the releases newer than the cluster’s on the release mirror
stratumctl admin upgrade cancel: Cancel an upgrade that has not taken its backup yet
stratumctl admin upgrade check: Check the release mirror for newer releases now
stratumctl admin upgrade history: List the upgrades, newest first
stratumctl admin upgrade mirror: The release mirror the control plane checks for newer releases
stratumctl admin upgrade plan: Show what an upgrade to a release would do, and whether it would be refused
stratumctl admin upgrade prune: Remove fetched releases the cluster no longer needs
stratumctl admin upgrade release-token: The release token that opens the stable release channel
stratumctl admin upgrade rollback: Go back to the release the cluster ran before an upgrade
stratumctl admin upgrade start: Upgrade the cluster to a release
stratumctl admin upgrade status: Show the upgrade in progress, and the release each node runs

stratumctl admin upgrade acknowledge

Acknowledge a failed upgrade: clear its readiness findings

stratumctl admin upgrade acknowledge [UPGRADE_ID] [flags]

Acknowledge a failed upgrade (the latest one when no id is given): its readiness findings (the upgrade failed, a node rolled back) are cleared until the next upgrade.

Examples

stratumctl admin upgrade acknowledge upg-x7k2m9q4ab

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template

stratumctl admin upgrade apply

Continue a stage-only upgrade: back up and upgrade the nodes

stratumctl admin upgrade apply UPGRADE_ID [flags]

Examples

stratumctl admin upgrade apply upg-x7k2m9q4ab
stratumctl admin upgrade apply upg-x7k2m9q4ab --wait

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template
`--timeout`	duration	`1h30m0s`	with –wait, how long to wait
`--wait`	bool	`false`	follow the upgrade until it ends

stratumctl admin upgrade available

List the releases newer than the cluster’s on the release mirror

stratumctl admin upgrade available [flags]

List the releases the release mirror’s signed index offers that are newer than the version the cluster runs, newest first: their type (feature, fix or security), the CVEs a security release fixes, and the path to each: direct, via the releases to upgrade to first (a required stop), not recommended (a known-broken upgrade, with its ticket and the release to use instead), or reinstall (a release on the way starts the upgrade chain: install it fresh from its ISO). Nothing is installed: plan one with stratumctl admin upgrade plan <version> and start it with stratumctl admin upgrade start <version>.

Examples

stratumctl admin upgrade available
stratumctl admin upgrade available --output json

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template

stratumctl admin upgrade cancel

Cancel an upgrade that has not taken its backup yet

stratumctl admin upgrade cancel UPGRADE_ID [flags]

Examples

stratumctl admin upgrade cancel upg-x7k2m9q4ab

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template

stratumctl admin upgrade check

Check the release mirror for newer releases now

stratumctl admin upgrade check [flags]

Ask the control plane to read the release mirror’s index now instead of at the next check interval. With –wait, wait for the result and list the releases.

Examples

stratumctl admin upgrade check
stratumctl admin upgrade check --wait 2m

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template
`--wait`	duration	`0s`	wait up to this long for the check (e.g. 2m)

stratumctl admin upgrade history

List the upgrades, newest first

stratumctl admin upgrade history [flags]

Examples

stratumctl admin upgrade history
stratumctl admin upgrade history --limit 5 --output json

Flags

Flag	Type	Default	Description
`--limit`	int	`20`	how many to list
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template

stratumctl admin upgrade mirror

The release mirror the control plane checks for newer releases

stratumctl admin upgrade mirror [flags]

Subcommands

stratumctl admin upgrade mirror get: Show the release mirror setting
stratumctl admin upgrade mirror set: Change the release mirror setting

stratumctl admin upgrade mirror get

Show the release mirror setting

stratumctl admin upgrade mirror get [flags]

Examples

stratumctl admin upgrade mirror get
stratumctl admin upgrade mirror get --output json

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template

stratumctl admin upgrade mirror set

Change the release mirror setting

stratumctl admin upgrade mirror set [flags]

Change where the control plane looks for newer releases, whether it does, and how often. What is not given is kept. –disable turns the check off, for an install without internet access.

stratumctl admin upgrade mirror set --url https://mirror.example.com
stratumctl admin upgrade mirror set --interval 1h
stratumctl admin upgrade mirror set --disable
stratumctl admin upgrade mirror set --default-url --default-interval

Examples

stratumctl admin upgrade mirror set --url https://mirror.example.com
stratumctl admin upgrade mirror set --interval 1h
stratumctl admin upgrade mirror set --disable

Flags

Flag	Type	Default	Description
`--default-interval`	bool	`false`	go back to the default interval (6h)
`--default-url`	bool	`false`	go back to the default mirror
`--disable`	bool	`false`	turn the update check off
`--enable`	bool	`false`	turn the update check on
`--interval`	duration	`0s`	how often to check, 15m to 168h
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template
`--url`	string		the release mirror URL

stratumctl admin upgrade plan

Show what an upgrade to a release would do, and whether it would be refused

stratumctl admin upgrade plan [RELEASE] [flags]

Show the plan for an upgrade to RELEASE: per node, the kind the release’s changes set (containers, host or os), what restarts, whether the node reboots and how many VMs stop for how long; then where the backup goes, how the upgrade could be undone, and every precheck. Nothing changes.

Name the release as the argument or with –release.

The release is found in a verified medium (POST /v1/admin/upgrades/media) or on the node when it was fetched before; –source reads it from a release mirror URL or a release directory under the node’s import root instead.

The upgrade-path precheck fails an upgrade the published upgrade paths refuse (a known-broken upgrade, or one that skips a required stop) and names the release to upgrade to instead or first.

It exits 2 when a precheck fails: the upgrade would be refused.

Examples

stratumctl admin upgrade plan 0.4.0
stratumctl admin upgrade plan --release 0.4.0 --output json

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template
`--release`	string		the release, instead of the RELEASE argument
`--source`	string		a release mirror URL, or a release directory on the node

stratumctl admin upgrade prune

Remove fetched releases the cluster no longer needs

stratumctl admin upgrade prune [flags]

Remove, on every node, the fetched releases under /var/lib/stratum/upgrade that the cluster no longer needs. Every node keeps the release the cluster runs, the one before it (what a rollback returns to), after a failed upgrade that upgrade’s release, and the release the node was installed with. The images only the removed releases pin go on the image reaper’s next pass.

Nodes also prune by themselves after an upgrade ends done. Refused while an upgrade is in progress. Each node prunes on its next pass, within a minute.

–dry-run lists what would be kept and removed on each node, from what each node last reported, and removes nothing.

Examples

stratumctl admin upgrade prune --dry-run
stratumctl admin upgrade prune

Flags

Flag	Type	Default	Description
`--dry-run`	bool	`false`	list what would be removed, and remove nothing
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template

stratumctl admin upgrade release-token

The release token that opens the stable release channel

stratumctl admin upgrade release-token [flags]

A release token from the Stratum Account (Company page, Enterprise support) opens the stable release channel. With one set, and the release mirror the default, the update check and release downloads read the stable channel with it; when that channel refuses it (revoked, or the plan ended) the cluster reads the default mirror. The token is stored in OpenBao and never shown.

Subcommands

stratumctl admin upgrade release-token clear: Remove the release token; the cluster reads the default mirror
stratumctl admin upgrade release-token get: Show whether a release token is set and what the stable channel answered
stratumctl admin upgrade release-token set: Set or replace the release token (read from the first line of stdin)

stratumctl admin upgrade release-token clear

Remove the release token; the cluster reads the default mirror

stratumctl admin upgrade release-token clear [flags]

Examples

stratumctl admin upgrade release-token clear

stratumctl admin upgrade release-token get

Show whether a release token is set and what the stable channel answered

stratumctl admin upgrade release-token get [flags]

Examples

stratumctl admin upgrade release-token get

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template

stratumctl admin upgrade release-token set

Set or replace the release token (read from the first line of stdin)

stratumctl admin upgrade release-token set [flags]

Reads the token from the first line of stdin, stores it in OpenBao (replacing any earlier one) and asks for an update check now, which reads the stable channel with it.

Examples

printf '%s\n' "$RELEASE_TOKEN" | stratumctl admin upgrade release-token set

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template

stratumctl admin upgrade rollback

Go back to the release the cluster ran before an upgrade

stratumctl admin upgrade rollback [UPGRADE_ID] [flags]

Go back to the release the cluster ran before an upgrade (the latest one when no id is given): its containers, its host binaries and, for an OS upgrade, its OS, which the node reboots into.

The previous control plane must run on the database as it is. When the upgrade’s migrations moved it past that, –restore restores the pre-upgrade backup in place first (single node only): the database and the secrets store go back to the moment of the backup, and everything that changed after it is lost, sign-ins included. The upgrade refused changes through the API from the backup on, so on a single node nothing accepted through the API is lost. A restore asks you to type the upgrade’s id, or takes it with –confirm.

The command shows what it would do first; –dry-run stops there (-o json prints it). Without –yes (or –confirm for a restore) it asks before it starts.

A backup encrypted to the backup recipient is restored with the recipient’s identity: put it at /var/lib/stratum/upgrade/restore-identity.txt on the node (root only, mode 0600) first. The restore removes it when it is done.

The restore signs out every session made after the backup. With –wait at a terminal, you are asked to sign in again and the wait goes on; without one, it stops and says what to run.

Exit codes: 0 done; 2 refused; 3 the rollback failed; 4 –wait timed out (it goes on); 5 signed out.

Examples

stratumctl admin upgrade rollback --dry-run
stratumctl admin upgrade rollback upg-x7k2m9q4ab --yes --wait
stratumctl admin upgrade rollback upg-x7k2m9q4ab --restore --confirm upg-x7k2m9q4ab

Flags

Flag	Type	Default	Description
`--confirm`	string		with –restore: the upgrade’s id, instead of typing it
`--dry-run`	bool	`false`	show what the rollback would do, and change nothing
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template
`--restore`	bool	`false`	restore the pre-upgrade backup in place first (single node; loses what changed after it)
`--timeout`	duration	`1h30m0s`	with –wait, how long to wait
`--wait`	bool	`false`	follow the rollback until it ends
`-y`, `--yes`	bool	`false`	do not ask before a rollback without –restore

stratumctl admin upgrade start

Upgrade the cluster to a release

stratumctl admin upgrade start [RELEASE] [flags]

Start an upgrade to RELEASE. The control plane checks the cluster and the release, has every node fetch it, takes a backup, then upgrades each node by the kind the release’s changes set: restarts the changed containers, switches the host binaries, or switches the OS and reboots. From the backup until the upgrade ends, changes through the API are refused. Name the release as the argument or with –release.

–stage-only fetches the release and stops; nothing that runs changes until “stratumctl admin upgrade apply <id>”. –wait follows the upgrade until it ends; the API restarts during it, and the command waits through that.

Run “stratumctl admin upgrade plan RELEASE” first to see what it would do.

Exit codes: 0 recorded (with –wait: done, or staged with –stage-only); 2 refused; 3 the upgrade failed or was canceled; 4 –wait timed out (it goes on); 5 the control plane no longer accepts this session.

Examples

stratumctl admin upgrade start 0.4.0 --wait
stratumctl admin upgrade start 0.4.0 --stage-only

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template
`--release`	string		the release, instead of the RELEASE argument
`--source`	string		a release mirror URL, or a release directory on the node
`--stage-only`	bool	`false`	fetch the release on every node and wait for apply
`--timeout`	duration	`1h30m0s`	with –wait, how long to wait
`--wait`	bool	`false`	follow the upgrade until it ends (or is staged)

stratumctl admin upgrade status

Show the upgrade in progress, and the release each node runs

stratumctl admin upgrade status [UPGRADE_ID] [flags]

Without an id: the upgrade in progress, or the last one, then the release each node runs: its OS image (on an image-mode node), its control plane, its host binaries and how its container images compare with the pins of its control plane.

Below the table, “Skew” lists each field whose value differs between nodes and “Drift” what a node runs other than its own release says. Every node records its own release every minute; a node whose record is older than ten minutes is listed under Drift. -o json prints the full record of every node.

With an id: that upgrade, step by step on each node.

–wait follows the upgrade (the one given, or the one in progress) until it ends, and signs in again at a terminal when a restore signed this session out. Exit codes: 0 done; 3 it failed or was canceled; 4 –wait timed out (it goes on); 5 signed out.

Examples

stratumctl admin upgrade status
stratumctl admin upgrade status upg-x7k2m9q4ab --wait

Flags

Flag	Type	Default	Description
`-o`, `--output`	string	`text`	Output format: text \| json \| yaml \| template
`--timeout`	duration	`1h30m0s`	with –wait, how long to wait
`--wait`	bool	`false`	follow the upgrade until it ends