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.

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