Run commands with the correct environment#

Run the supplied Orkiva binary in an operator environment configured for the same database, encryption keys and artifact store as the installation. A command pointed at a different DB_DSN does not manage the running deployment. Commands below use an example backup directory; choose a protected destination with sufficient capacity.

Pause mutations and inspect writers#

orkiva maintenance on "planned backup and upgrade"
orkiva maintenance status
orkiva maintenance writers

Inspect the active writer report before proceeding. Maintenance coordinates installation writers; it does not mean every external Kubernetes controller has stopped. If a writer is stale, establish that its process has actually stopped before using the reconcile command with evidence. Record the checks that confirmed the writer has stopped before reconciling its registration.

Stop all writer processes before snapshotting. Maintenance mode alone is not a drained installation. Gracefully stop every control-plane process that can write, including serving, scheduler and applicable gateway roles, using your deployment system. Inspect maintenance writers again. Backup requires no active or unreconciled writers and freezes new writer registration while taking its snapshot.

Create a coordinated backup#

orkiva backup --output /protected-backups/orkiva-before-upgrade

Inspect the returned manifest and preserve the backup together with the corresponding key-recovery material. The optional --include-keys flag includes sensitive keys; use it only for a destination approved to hold them. The command intentionally leaves mutations paused. A backup of Orkiva configuration and artifacts is not a backup of every application volume in your Kubernetes clusters.

The output directory must not already exist. A failed attempt can leave its output directory behind; inspect and preserve that attempt for diagnosis and choose a fresh destination for a retry.

Check and apply an upgrade#

  1. Use the target release binary to inspect compatibility and the migration plan.
  2. Supply the fresh backup evidence required by the target release and configuration. If the check requires a backup, ORKIVA_DB_REQUIRE_BACKUP must be enabled with valid evidence; a directory name alone is not proof.
  3. Apply the controlled upgrade with application writers still stopped. Inspect the compatibility/migration results while maintenance is on.
  4. After offline checks pass, end maintenance to release the snapshot freeze, restart the intended processes under controlled access, and validate login, cluster access, Delivery state and artifacts before restoring normal user traffic.
orkiva upgrade check
orkiva migrate plan
orkiva upgrade apply
orkiva maintenance status
# After offline checks pass; then restart and validate under controlled access:
orkiva maintenance off

upgrade apply leaves maintenance enabled. migrate retry exists for the migration flow, but it is not a substitute for inspecting an interrupted upgrade and its recovery requirements.

Restore deliberately#

orkiva restore --input /protected-backups/orkiva-before-upgrade
# Inspect the restored installation and reconcile its state first.
orkiva restore complete

Restore is an operator recovery action that replaces persisted state. Use the matching binary/configuration and protect the failed state before replacement if you need it for diagnosis. The restore command leaves maintenance on; restore complete performs its reconciliation gate and turns maintenance off only when that succeeds. A database downgrade by simply starting an older binary is not the documented recovery path.

Restore requires the backup schema version to match the binary, the configured database type to match, and the backup encryption/audit keys to be configured. If the backup contains an external config file, restore that file to ORKIVA_CONFIG_FILE before restoring the database. Keep application writers stopped for the restore operation; use restore complete before resuming the processes and normal traffic.