Upgrading

OrbitalReg follows semantic versioning at the API layer. Within a major version, every minor and patch release is forward-compatible — existing tokens, webhooks, retention policies, and stored artifacts continue to work without operator action.

Supported upgrade path

Upgrades are only supported from the immediately preceding release (N-1) to the current one. Skipping releases (N-2 or older straight to HEAD) is not tested and may apply migrations out of the order the schema expects. If you are more than one release behind, upgrade through each intermediate release in turn.

scripts/upgrade-matrix-test.sh (make upgrade-matrix-test) exercises this exact path locally: it builds the latest tagged release and HEAD as two binaries, boots the tagged release against a throwaway Postgres/Redis/S3 stack, seeds data, then stops it and boots HEAD against the same database — verifying migrations apply forward with no boot failure and that data written under the old release stays byte-identical after the upgrade. Run it before cutting a release that changes migrations.

Pre-flight

Before any upgrade:

1. Confirm a recent backup. The Backup verification page surfaces the last successful restore-into-ephemeral-cluster run. If the most recent run is older than the configured horizon (default 8 days), block the upgrade and investigate.

2. Read the release notes. Each release tag carries a CHANGELOG.md entry listing every migration, every behaviour change, and every removed knob. Migrations that need operator action are flagged **Operator action required** at the top of the entry.

3. Take a manual snapshot of the Postgres cluster if the chart is upgrading the major Postgres version (e.g. 15 → 16).

Helm upgrade

For chart-managed installs:

helm repo update
helm upgrade orbitalreg ./charts/orbitalreg \
  --namespace orbitalreg \
  --values values-onprem.yaml \
  --reuse-values

The chart applies pending migrations as a Job that runs to completion before the new pod set rolls out, so the API never serves a request against an out-of-date schema.

Manual upgrade

For non-Helm installs:

1. Stop the API pods (or the binary).
2. Apply pending migrations:

   migrate -path ./api/internal/db/migrations \
           -database "$DATABASE_URL" up

3. Roll out the new image / binary.
4. Verify /api/admin/version reports the new version.

Major-version upgrades

Major-version bumps document each breaking change with a recipe:

• Schema migrations that take >1 minute on a 50-million-row table are flagged. Plan a maintenance window or run them out-of-band through the migrate CLI before the rollout.
• API breakages are introduced under /api/v2/… first; the /api/v1/… surface keeps working for at least one full minor cycle before being removed.
• Config-key renames ship a deprecation banner in the admin UI for one minor cycle before the old name stops working.

Downgrade

Downgrades are not supported across migrations. If a release applies migration N → N+1 and you need to roll back, restore the Postgres backup taken before the upgrade.

The chart's values.upgrade.allowDowngrade=true knob is intentionally absent — there's no "graceful" path that doesn't lose data when a new column has been written to by the new version.

Operator + Terraform provider

Both the Kubernetes operator and the Terraform provider follow the same forward-compatibility rule. A v1.x operator works against any v1.x API; a v2.x provider against any v2.x API.

Operator + provider major bumps are released with the matching API major bump so the compatibility matrix is one-to-one.

What broke last time?

Past releases' notable migration moments:

Version	Migration	Operator action
v183	Add customer_message to security_blocks	None — column nullable
v184	Add branding table for custom logos	None — single-row, autoseeded
v185	Add system_banners for scheduled announcements	None
v186	Terraform provider GA	None — additive
v187	OIDC trust policies	None
v188	Air-gapped-by-default + allow_service_pings	Whitelist needed integrations
v189	Postgres-backup via CloudNativePG	Migrate per chart guide