Upgrade guide¶

This guide is the operational companion to the complete historical release reference. It records the source-derived release channel contract and the boundary at which an upgrade may be rolled back.

x86_64-unknown-linux-musl

Current release and channel status¶

The workspace source identifies version 0.8.23-rc.2, published under tag v0.8.23-rc.2. The current release is a release candidate: it is tagged and signed, runs the full gate and the reproducibility check before publishing, and moves the floating :rc container tag. :latest stays on the last final release. The exact channel inventories below are generated from the manifest, Git tag, CI rules, and release build script.

Channel	Tag shape	Published status	Gate before publish	Floating container tag
alpha	vX.Y.Z-alpha.N	tagged, signed	no gate	none
beta	vX.Y.Z-beta.N	tagged, signed	no gate	none
rc	vX.Y.Z-rc.N	tagged, signed	full gate + reproducibility	:rc
release	vX.Y.Z	tagged, signed	full gate + reproducibility	:latest

Alpha and beta are published without the full gate. RC and release run the full gate and the independent reproducibility check before publication. Only the rc channel moves :rc, and only the release channel moves :latest. Alpha and beta are requested by their immutable tag.

alpha beta rc release

0.8.23-rc.2|rc|signed|full-gate|rc

The release script produces the following artifact classes. A local dry-run may omit the detached signature, but a tagged CI publication is signed.

binary sbom checksums signature-optional

Rollout class chooser¶

Use this chooser before selecting a tag channel. It is an operational compatibility classification; when a change fits more than one row, use the stricter row.

Change class	Minimum rollout channel	Required boundary
Routine	alpha or beta	No certificate, wire, store, policy, audit-consumer, artifact, or security contract changes; do not imply that the full gate ran
Cert or wire	rc, then release	Roll the compatible Authority, proxy, connector, and consumer fleet together; complete the full gate and reproducibility check
Store	rc, then release	Take the paired store and key backup, run migration as a planned step, and keep the pre-migration restore point
Policy	rc, then release	Validate and migrate the policy vocabulary, preserve the break-glass invariant, and use the approval path
Audit or recording consumer	rc, then release	Check event names, codes, classes, recording format, and downstream parsers before opening traffic
Artifact or channel	rc, then release	Verify target, SBOM, checksum signature, floating-tag behavior, and reproducibility before publication
Security-sensitive	rc, then release	Require the full gate, independent rebuild, paired approval, and an explicit recovery owner

The chooser does not turn an alpha or beta into a tested candidate. Promote a build to rc when the compatibility evidence is required, then use the release channel only after the candidate evidence and recovery rehearsal are complete.

Fixed release-entry contract¶

Every new history entry uses one fixed shape:

## vX.Y.Z[-alpha.N|-beta.N|-rc.N]

### Added
### Changed
### Fixed
### Compatibility
### Migration and recovery
### Artifacts and channel
### Verification

The entry states the exact workspace version and tag, channel status, gate and reproducibility status, floating tag, artifact set, certificate or wire compatibility, store migration direction, policy and audit/recording consumer impact, and the tested recovery boundary. Empty sections say that they are empty. Historical entries are not rewritten: a stale command or spelling stays in its historical body and a current equivalent is added here or in the current reference.

Compatibility and preflight¶

This is the read-only preflight. The release owner records the exact tag, workspace version, target, change id, and store_url before changing a service.

Verify the checksum signature, then the checksums and SBOM: cosign verify-blob --key cosign.pub --signature SHA256SUMS.sig SHA256SUMS, sha256sum -c SHA256SUMS, and jq '.metadata.component.name, (.components | length)' gdsgate-<tag>.cdx.json. Any non-zero result is a stop condition.
Run gdsgate --config authority.toml doctor --json. Exit 0 is a passing preflight; exit 2 names a configuration or state finding to fix before the window. Doctor is read-only.
Set or confirm store_auto_migrate = false for a planned migration, then run gdsgate --config authority.toml authority migrate --check against the same store_url. Exit 0 means no pending migration. A non-zero pending result names the migration ids and is not an incident by itself; an unknown-applied result means this binary is older than the store and is a stop condition.
Run gdsgate --config authority.toml authority verify-audit and preserve the result with the change record. A failed chain verification stops the rollout.
Keep the old binary, configuration, identity directories, store endpoint, and key set available until post-change verification passes.

Paired backup and planned migration¶

This is a planned change, owned by the release operator and approved by the change owner. Stop writes or close the traffic window according to the deployment runbook before taking the final pair.

Take one transaction-consistent backup or snapshot of the persistent store addressed by store_url. Take the external audit-anchor, approval, delegation, revocation, inventory, and CA key material in the same backup generation. Include identity directories and any transport trust material required by the role.
Encrypt the backup, store a copy off the Authority host, record its generation and checksums, and prove that the restore owner can read it. A store-only backup cannot verify historical audit integrity. If either the store or paired keys is absent, mismatched, or unreadable, stop before migration.
Preserve the previous binary, configuration, store_url, and key set. Do not replace only one certificate or key in a pair.
With services stopped or with the approved migration lock, run:

gdsgate --config authority.toml authority migrate --check
gdsgate --config authority.toml authority migrate

The first command changes nothing and exits non-zero when pending work exists. The second opens the store directly, applies pending migrations, and is idempotent. Expected success is an applied-count message followed by a current schema; a second run reports nothing to apply. 5. Run only one planned migration against a shared PostgreSQL store. The store migration lock waits 120 seconds; a timeout is a stop condition to inspect the active writer, not a reason to run a second migration concurrently.

MigrationStatus distinguishes pending migrations, which this binary can apply, from unknown-applied versions, which a newer binary already wrote. An unknown-applied result must use the newer binary or the paired pre-migration restore. Do not delete migration rows, edit migration metadata, or downgrade schema rows.

Verification and recovery boundary¶

This is the post-change verification gate. Start the exact new binary with automatic migration still disabled, then require all of the following:

gdsgate --config authority.toml doctor --json exits 0.
GET /healthz returns 200 and GET /readyz returns 200. A 503 readiness response is not success and traffic stays closed.
gdsgate --config authority.toml authority verify-audit succeeds.
The policy version, catalog version, connector serving state, and audit event for the change match the recorded expectation.
One controlled session and its expected protocol operation succeed, and the relevant recording or audit consumer sees the current event/code shape.

If the binary refuses the store, readiness does not become 200, audit verification fails, or the controlled session shows an incompatibility, stop traffic and keep the old binary stopped or isolated. Restore the paired pre-migration store and keys, restore the previous configuration and binary, verify the audit chain and readiness again, and escalate to the release owner. There is no supported in-place reverse migration. A certificate or wire change requires the compatible fleet to be rolled together; do not mix an old peer with a release that changed its verification contract.

Upgrade notes¶

The v0.8 line uses the current Authority, proxy, connector, and client command families. Replace historical auth terminology with authority only when following a current command or configuration contract. Preserve the existing persistent store_url and identity directories across a service replacement.

Order within a mixed fleet¶

Upgrade every proxy before any authority. From v0.8.23 an authority refuses a connector registration that does not state the kind of each resource it declares, and a proxy older than v0.8.19 forwards no kinds. An authority upgraded ahead of its proxies therefore refuses every connector reaching it through one of them, and the proxy logs auth refused connector registration with the reason registration carries no resource kinds. Upgrading the proxy restores the registration; nothing on the authority side reopens it. The reverse order is safe: a proxy that forwards kinds to an older authority is answered as before.

Upgrading from v0.6.x¶

Back up the store and paired key material, validate the current policy, run the migration check, and deploy the exact target. Verify audit continuity and connector reconnects before opening traffic. Keep a tested restore path for a forward-only schema migration.

Upgrading from v0.3.x¶

Review endpoint and enrollment changes before replacing a node. Re-enroll only when the existing identity cannot renew. Confirm transport-CA fingerprints and resource catalog declarations after the first start.

Upgrading from v0.2.x¶

Treat the upgrade as an identity and data migration. Preserve the store and keys, validate the policy schema, and use the current command names from the CLI reference. Do not copy old listener defaults into a current file without checking [endpoints].

Upgrading from v0.1.x¶

Use an isolated restore rehearsal first. Verify the current binary version, store state, policy, audit chain, and readiness endpoint before connecting a production client.