Upgrade and roll back

Before you start#

Steps#

1. Read what the release changes#

The platform has one version line: the gateway, Access and Data ship together at the same MAJOR.MINOR.PATCH. A PATCH release only fixes, a MINOR release adds to contracts without changing them, and only a MAJOR release may change a contract, with each change and its migration listed in the changelog (gateway spec §14.2).

Check these points for the target release:

The 1.0.0 changes and their effect on each service are summarized in Data internals: platform release 1.0.0.

2. Check the mix you will run mid-rollout#

A rolling upgrade runs old and new versions side by side, and a deployment may keep them mixed. Which combinations are proven is the compatibility baseline: each release's baseline is the revision it shipped at, pinned in compatibility.json.

To prove the published images of the target release against your old ones, point the suites at running services instead of local builds:

ACCESS_EXTERNAL_URL=https://access.staging.example.com \
ACCESS_EXTERNAL_ADMIN_TOKEN=… ACCESS_EXTERNAL_ACCESS_TOKEN=… \
  bun run compatibility

The variables are in live services and databases. Data stays unready while Access's discovery lists no access context version Data knows, which is why Access goes first in step 5 (Access spec §9.1).

3. Back up both databases#

Take a fresh Access dump and a fresh Data backup immediately before migrating. Access's older dump restores with its schema and catches up through the migration runner, while a database rollback of Data is not considered safe after a migration that changed data (Data spec §15.5). The commands are in Back up and restore.

4. Apply the migrations#

Each service treats its schema differently:

DATA_OWNER_DATABASE_URL=postgres://data_owner:…@postgres:5432/data \
  bun run --cwd packages/data migrate

migrate takes an advisory lock, applies the files in order and records each checksum in its ledger (migrations and drift). Never edit a migration that was already applied: the checksum mismatch is drift and fails readiness. If the changelog says a Data schema change breaks compatibility with the old release, drain the old Data replicas before you migrate. A destructive migration needs a reviewed plan and a restore you have tested.

On Kubernetes, run the new release's deploy/kubernetes/base/data/migrate-job.yaml by hand (Kubernetes manifests).

5. Roll the services in dependency order#

The docs fix no single upgrade order; this one follows the dependencies they do state. Promote the same digest from staging to production, and replace replicas one by one, gated on /readyz.

Keep each service's configuration and secrets unchanged during the upgrade, so a rollback only swaps the image. Do not write route-table fields that the new release adds until every gateway replica and the control plane run it, since an older replica refuses a table with a field it does not know. Data's manifests and policy bundles are versioned by content digest, so a new bundle is a release of its own: roll it the same way.

With the bundled Compose stack, change the image tags in deploy/compose/production/platform.compose.yaml; bun run deploy:check fails when image versions drift from the platform version (deploy rules).

6. Watch each step before the next#

7. Roll back a service#

Images carry both the release tag and the version, so rolling back means deploying the previous release's digest with the configuration and secrets it ran with (platform rollback). Roll back in the reverse of the upgrade order when several services moved.

docker pull ghcr.io/ggpwnkthx/access:<previous version>
kubectl -n platform rollout undo deployment/platform-access
kubectl -n platform rollout status deployment/platform-access

Check that it worked#

1. Each /healthz reports the version you meant to run, and Data's also reports the manifest's schemaVersion:

   curl -sS http://access:8081/healthz   # {"status":"ok","service":"access","version":"…"}
   curl -sS http://data:8082/healthz     # {"status":"ok","service":"data-backend","version":"…","schemaVersion":"…"}
   platformctl version

1. Every replica answers 200 on /readyz; for Data that also proves the ledger matches the release's migrations.
2. With store-mode route tables, GET /v1/replicas (or platformctl routes replicas) shows every gateway replica on the active revision with no last error.
3. The Access administration smoke test passes: ACCESS_URL=… ACCESS_ADMIN_TOKEN=… bun run --cwd packages/access admin:smoke.
4. A signed-in request through the gateway to /ws/{workspaceId}/v1/me returns the caller's identity from Data.
5. The alerts from Monitor the platform stay quiet for a full day before you call the upgrade done.

If something goes wrong#

Related#

• Platform operations: versions
• Platform internals: release
• Gateway spec §14: release compatibility
• Data spec §13: versions and compatibility
• Access deploy and roll back
• Gateway rollback
• Data migrations and drift
• Back up and restore
• Monitor the platform
• Respond to an incident