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

This edition covers the 0.11 command tree. Review Changes in 0.11.x for configuration selection, enrollment and resource publication. For an existing deployment, follow the complete 0.11 procedure.

Current release and channel status

The current candidate is v0.11.0-rc.7; successful publication moves :rc to it. Documentation latest selects the 0.11 edition. The last final release is v0.9.0, which remains the target of :latest.

The channel inventories below describe the publication contract. RC publication requires the full gate and an independent reproducibility check.

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

alpha|tagged|signed|no-gate|none beta|tagged|signed|no-gate|none rc|tagged|signed|full-gate|rc release|tagged|signed|full-gate|latest

0.11.0-rc.7|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.

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.

1. 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.
2. 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.
3. Set or confirm store_auto_migrate = false for a planned migration, then run gdsgate --config authority.toml authority store 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.
4. Run gdsgate --config authority.toml authority audit verify and preserve the result with the change record. A failed chain verification stops the rollout.
5. 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.

1. 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.
2. 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.
3. Preserve the previous binary, configuration, store_url, and key set. Do not replace only one certificate or key in a pair.
4. With services stopped or with the approved migration lock, run:

gdsgate --config authority.toml authority store migrate --check
gdsgate --config authority.toml authority store 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:

1. gdsgate --config authority.toml doctor --json exits 0.
2. GET /healthz returns 200 and GET /readyz returns 200. A 503 readiness response is not success and traffic stays closed.
3. gdsgate --config authority.toml authority audit verify succeeds.
4. The policy version, catalog version, connector serving state, and audit event for the change match the recorded expectation.
5. 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.

To 0.11.x from v0.10.0-rc.10 or rc.13

This procedure upgrades v0.10.0-rc.10 or v0.10.0-rc.13 to v0.11.0-rc.7. Check the migration and compatibility notes for later 0.11 builds separately. The release changelog lists the changes.

An existing deployment keeps its configuration, node identities, users, policies and manual resource IDs. Reinstallation, another enrollment token, connect, join and first-install setup are not required for a binary replacement. Do not delete protected state or repeat first-install commands to upgrade. Regenerating a service unit is an in-place registration of that service.

The maintenance-window start order is Authority, Proxy, Connector, Client. Complete the Authority phase on every HA member before the Proxy phase. Existing sessions can end when their owning process stops. This procedure does not promise uninterrupted service or prolonged mixed-version HA. For versions earlier than rc.10, first apply the relevant procedures below, including their older Proxy and Connector ordering restrictions.

1. Inventory and preflight

1. Record the old version, service binary paths, config paths, store endpoint, state directories and HA owners. On Linux, inspect each installed unit with systemctl cat gdsgate-authority, systemctl cat gdsgate-proxy and systemctl cat gdsgate-connector, as applicable. Client system services use gdsgate-client@<user>.service; optional user services use gdsgate-client.service. Preserve custom environment files and unit drop-ins.
2. Stage the same verified release build for the whole fleet. Follow artifact verification to verify signatures and SHA256SUMS. Check the target architecture, platform runtime and configured KMS-provider support. A matching --version alone does not prove identical features or bytes.
3. With the old deployment still running, check doctor --json, audit integrity and current serving state. Resolve existing failures before using the upgrade to judge new behavior. Use an explicit config for every role:

gdsgate --version
gdsgate --config /etc/gdsgate/authority.toml doctor --json
gdsgate --config /etc/gdsgate/authority.toml authority verify-audit
gdsgate --config /etc/gdsgate/authority.toml authority list-resources

1. Pause scheduled CA/keyring rotation and do not prepare or activate a distribution-root transition during the rollout. Preserve the existing root provider, owner names, membership and credentials. When upgrading from rc.10, each updated Authority creates its own receiver credential; never copy another member's credential or reinitialize its root.

2. For a manually configured HA Proxy, check its Authority control pool. A single load-balanced address can keep a persistent RPC connection on a follower, leaving the Proxy unready although both Authorities are healthy. Configure the individual Authority addresses with endpoints.authority and endpoints.authority_failover, or use verified automatic topology. Keep the configured TLS verification name valid for every member. Public access and Connector load balancers do not replace this control pool.

The Linux examples use standard config paths. Substitute the paths inspected from the actual units. Run administrative checks as the service owner or an authorized operator with access to the protected files; a client context is not a substitute for a local Authority config.

2. Close traffic and preserve a recovery point

Schedule the interruption and close new access. Stop residents, Connectors and Proxies, then stop all Authorities and other store writers for the final backup and planned migration. Keep the old binaries available and follow paired backup and migration.

Preserve the following in one identified recovery generation:

State	What to preserve
Persistent store	A consistent backup of the exact configured database. For SQLite, stop writers and use a SQLite backup or include its journal/WAL state; copying a live main file alone is insufficient.
Each server node	Config, policy and environment files; enrolled transport identity; CA and audit/control keyrings; activation state; recording buffers and audit outboxes. Include paths outside the standard state root.
Each HA Authority	Distribution root/provider, snapshot cache, install journal and receiver credential when present. Preserve continued access to configured DB/KMS providers.
Each client	Protected client directory, selected and saved configs, identity/token storage, context records and endpoint/address cache. Preserve manually managed SSH and Kubernetes integrations.
Service definitions	Installed unit or service definition, drop-ins, executable location and previous binary.

Readiness must be checked again after replacement, even if the preflight passed. Do not restore only the shared DB while leaving newer node-local state in place.

3. Replace binaries and migrate once

With the relevant processes stopped, replace their executable at the existing persistent installation path. Do not point a server unit at a build under a home or temporary directory. For a regular Linux binary at /usr/local/bin, an atomic replacement is:

sudo install -m 0755 /path/to/staged/gdsgate /usr/local/bin/gdsgate.new
sudo mv /usr/local/bin/gdsgate.new /usr/local/bin/gdsgate
/usr/local/bin/gdsgate --version
sha256sum /usr/local/bin/gdsgate

If the installed path is a managed symlink, replace its intended target using the installation's update mechanism and retain the link. Install the new binary on each host before registering its units. Compare the checksum with the staged artifact for that host's target; do not infer the running process's version from the file on disk.

Both rc.10 and rc.13 have 79 store migrations. This release has 85 and adds:

Migration	Added state
m0080_bootstrap_identity	Stable bootstrap identity
m0081_resource_identities	Assigned resource identities and namespaces
m0082_connector_publication	Connector publication policy and assignments
m0083_manual_resource_bindings	Explicit manual-resource serving membership
m0084_manual_assignment_revision	Revision of manual-resource assignments
m0085_manual_inventory_generation	Manual inventory generations

Run these commands with the new binary and the existing Authority config:

gdsgate --config /etc/gdsgate/authority.toml authority store migrate --check
gdsgate --config /etc/gdsgate/authority.toml authority store migrate
gdsgate --config /etc/gdsgate/authority.toml authority store migrate --check

The initial check exits non-zero when migrations are pending; the final check must show a current schema. Run one planned migration for a shared PostgreSQL store, not one simultaneous command per Authority. Separate SQLite stores require their own migration and backup. These commands operate directly on the store and require the configured DB/KMS access.

With store_auto_migrate = true (the default), first Authority startup also applies pending migrations. The planned procedure applies them before startup; store_auto_migrate = false keeps a later restart from doing unexpected work. A schema with unknown applied migrations stops an older binary. There is no supported reverse migration.

4. Regenerate native service definitions

Linux

Run the installed new binary as root, once for each installed server role on that host, with its existing config:

sudo /usr/local/bin/gdsgate --config /etc/gdsgate/authority.toml service install authority
sudo /usr/local/bin/gdsgate --config /etc/gdsgate/proxy.toml service install proxy
sudo /usr/local/bin/gdsgate --config /etc/gdsgate/connector.toml service install connector

The installer rewrites the unit, records its config path, runs systemctl daemon-reload and enables boot startup. A separate daemon-reload is unnecessary after successful installation. Keep relevant custom drop-ins and inspect the resulting ExecStart, ExecReload and state paths.

Install the resident from its user's session so elevation preserves that user's protected state. Select the intended existing config explicitly:

sudo /usr/local/bin/gdsgate --config "$HOME/.gdsgate/config.toml" service install client

This example registers the default protected system service. An intentional user-service installation uses its existing account and access settings; see Resident service.

Installation does not restart a running process, even with --start. It does not require service uninstall, another enrollment or state deletion. Existing rc.10 units remain usable for restart with unchanged paths; regenerate them to receive the new acknowledged configuration reload command: gdsgate --config PATH reload --role ROLE. Earlier server units use HUP for certificate refresh, and earlier Connector units have no ExecReload. See reload.

The normal protected systemd state symlinks are supported. Unknown or untrusted links are refused. Private state and local control-channel directories must retain their service-owner protection; do not make them world-writable to get past a startup error. A reload-channel failure is logged and disables reload until repaired without by itself stopping an otherwise valid server.

Windows

Stop the affected services before replacing gdsgate.exe, then use the new installed executable from an elevated terminal with each existing config:

gdsgate.exe --config C:\ProgramData\gdsgate\authority.toml service install authority
gdsgate.exe --config C:\ProgramData\gdsgate\proxy.toml service install proxy
gdsgate.exe --config C:\ProgramData\gdsgate\connector.toml service install connector

This refreshes service registration and server config access. Use the same installation path and preserve custom state paths. Windows service install client registers the privileged network helper; the resident runs in its user's session. Restart that helper with the updated executable, then start the resident as the original user. See Windows resident.

After migration, start each installed server role in the phase order below, checking its readiness before proceeding. The service names are:

Start-Service gdsgate-authority
Start-Service gdsgate-proxy
Start-Service gdsgate-connector

On client machines, refresh the helper registration from an elevated terminal:

gdsgate.exe service install client
Restart-Service gdsgate-client-net

Then run gdsgate up in the original user's session with the intended client config selected. Apply these commands only to services installed on that host.

Containers and unmanaged processes

Replace the image or executable under the existing supervisor. Preserve config mounts, state volumes, service account, secret-provider access and the same store endpoint. Do not run service install inside a container. Recreate processes in the phase order below; persistent volumes must survive replacement. Keep the old image digest for paired recovery.

An existing agent host also needs its executable replaced and process restarted with its retained config and identity. Preserve its manually installed unit or supervisor definition; service install does not offer the agent-host role.

5. Start and verify each phase

Use the following order in the closed maintenance window. The Linux commands restart the applicable installed role; if it was stopped, they start it. Run them on its own host, not all roles on every machine.

1. Authorities: start the new members one at a time and check each before continuing. Restore a ready leader and verify membership and follower routes before progressing to Proxies.

sudo systemctl restart gdsgate-authority
gdsgate --config /etc/gdsgate/authority.toml doctor --role authority --json
gdsgate --config /etc/gdsgate/authority.toml authority store migrate --check
gdsgate --config /etc/gdsgate/authority.toml authority audit verify

Require that node's configured /healthz and /readyz to return 200. Where keyring sync is enabled, inspect every Authority locally:

gdsgate --config /etc/gdsgate/authority.toml authority keys sync root status

Confirm the expected root epoch, matching material revision and no unexpected preparation. Do not rotate the root before every retained Authority has completed the upgrade and acknowledged the current material.

1. Proxies: restart and check Authority routes, peer routes and readiness.

sudo systemctl restart gdsgate-proxy
gdsgate --config /etc/gdsgate/proxy.toml doctor --role proxy --json

1. Connectors: restart and confirm identity reuse, verified configured Proxy connections and admitted resources. Do not treat a connected tunnel as proof that every declared resource was admitted.

sudo systemctl restart gdsgate-connector
gdsgate --config /etc/gdsgate/connector.toml doctor --role connector --json
gdsgate --config /etc/gdsgate/authority.toml authority resources list

Run the catalog command from an authorized Authority/operator host. not_in_catalog means a manual declaration or assignment is missing; repeating enrollment is not its remedy. Inspect the existing publication assignment before making catalog changes.

1. Clients: from the original user's session, restart the system resident:

sudo systemctl restart "gdsgate-client@$(id -un).service"
gdsgate contexts list
gdsgate contexts show
gdsgate status --refresh --explain
gdsgate resources list

For an existing user unit, use systemctl --user restart gdsgate-client. Windows uses Start-Service/Restart-Service for registered server services in the same phase order, then restarts the helper and user resident. Unmanaged processes must also be replaced; reload or an already-running up does not load the new executable.

6. Check configuration and native access

Configuration and catalog. Existing command spellings remain aliases. Server operations use their installed role config; client and administrative RPCs can use the selected cluster. --config makes the choice explicit. Use contexts list to inspect history and discovered configs, and contexts show to inspect the current selection. A catalog from another selected cluster can appear not served even when the local Connector is healthy.

Existing clusters retain their shared publication policy and Connector assignments. Upgrade does not convert manual resources to automatic publication, activate an SSH epoch or grant new access. Existing manual IDs remain stable; changing to automatic publication is a separate operation with qualified IDs, names and collision checks. Existing SSH onward modes are retained; a row without a mode needs an explicit choice before enabling catalog-mode admission. See resource migration before changing assignments.

OIDC. Existing complete profiles keep their defaults. Issuer and client ID must be set together; partial or conflicting profiles are refused. When adopting the new scopes, resource, request parameters, device polling or claim mapping, configure the public Authority profile and upgrade Proxy/client consumers before distributing it. Existing Proxy and saved client configs are not rewritten merely by replacing the executable or editing Authority config. Copy the complete public profile into every existing Proxy, validate and restart affected server roles, then update client OIDC settings from the same public profile, or use the documented connect flow to refresh a saved configuration after reviewing its output paths and replacement options. See profile update procedure, OIDC configuration and connect.

Polling compatibility is opt-in: device.pending_errors matches an exact invalid_grant description prefix. Omission retains normal terminal-error handling. device.interval can only increase the provider polling interval; device.expires_in can only shorten the provider lifetime. Extra parameters must contain no credentials. Claims come from the verified identity token; group mapping does not grant a cluster role by itself. Test a fresh login, token refresh and the intended group policy.

Resident state and integrations. The new resident reads the old version-1 endpoint cache and writes version 2 with cluster binding. Keep the cache to preserve addresses. An older client cannot read a version-2 cache after downgrade. Check regenerated files before updating any manually copied integration.

In an already open Linux shell, load the generated environment again:

source ~/.gdsgate/env
kubectl config get-contexts
kubectl --context <resource-id> get pods

Alternatively pass --kubeconfig ~/.gdsgate/kube/<resource-id>.yaml. The resident's Kubernetes listener is HTTP on its protected local endpoint; the backend retains its configured transport. A missing context means the generated kubeconfig was not loaded or that resource was not generated. A Forbidden response needs both gdsgate policy and Kubernetes RBAC for the impersonated identity checked. See generated files and Kubernetes access.

In an already open Windows user shell, load the generated environment with . "$HOME\.gdsgate\env.ps1" before checking the generated Kubernetes contexts.

Test SSH with both the generated resource name and its resident address. The native session notice appears on stderr and leaves command stdout usable. Check an allowed session, a denied session, audit verification and finalized central recording delivery. Include configured Proxy failover and projected Kubernetes-token refresh where those features are used. Only reopen traffic and resume normal rotation after these checks pass.

Recovery

If schema verification, membership, readiness, authorization or recording checks fail, leave access closed and investigate the named failure. Do not erase state, change schema metadata or repeat setup to bypass it.

After migrations or new Authority/client state have been written, reverting only the executable is insufficient. Stop the changed fleet, restore the matching pre-upgrade database and every affected node's protected state, restore configs, service definitions and old binaries, then verify readiness and audit integrity before reopening traffic. Include the old client cache if reverting a resident. For HA distribution credentials and roots, follow paired state recovery.

Order within a mixed fleet

For a fleet whose proxies predate v0.8.19, upgrade every proxy before any authority that introduces the v0.8.23 admission contract. 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.

Connectors before the authority, on a cluster with the SSH gate on

Only where gdsgate authority epochs activate has already been run for epoch 1 or above; a cluster that has switched nothing on is unaffected in either order.

From the release that adds it, an authority admits an SSH resource to a connector only against a one-time receipt the connector got from its own activation-lease renewal. A connector older than that sends none, so an authority upgraded ahead of its connectors withholds every SSH resource from each one that has not been upgraded yet, answering gate_not_offered; the connector logs this node declared a resource the cluster is not giving it. Upgrading the connector restores it at its next registration, within a renewal interval. Nothing is lost and nothing has to be reprovisioned, but SSH through those connectors is refused in the meantime.

That is the fail-closed direction on purpose. The recorded capability alone cannot say which process is registering, and a connector rolled back to a binary from before the gate does not clear it, so admitting on the record would admit exactly what the gate exists to refuse.

An empty audit queue before an HA upgrade from v0.10.0-rc.6 or earlier

Upgrade only when gdsgate_audit_outbox_depth is 0 on every Authority, or doctor reports audit queue with 0 rows waiting: a row the old build left in the queue is held as unsigned after the upgrade.

gdsgate --config authority.toml doctor

To v0.10.0-rc.13

Against rc.10, this version changes distribution-root state and adds Kubernetes discovery-source configuration without adding store migrations. Complete the rc.10 procedure when upgrading from an earlier version. The operator needs administrative access to each Authority host and a recovery point containing the shared store and every node's protected local state.

1. Verify the artifact signature and checksums using the preflight. Preserve the shared store, keyrings, transport identity and each node's distribution provider, cache and journal together. Preserve receiver.key once it exists. Wrapped roots also require continued access to their KMS key. Keep these private files under their service owner's protected directory.
2. Upgrade all Authorities before starting any root preparation. Keep CA and keyring rotation paused during the rollout. Each Authority creates an independent receiver credential and binds it to its existing owner. Keep the configured owner and credential; do not copy another node's receiver.
3. On each Authority host, check doctor --json, /readyz and /healthz. Run authority keys sync root status with that node's configuration. Confirm the current root epoch, matching material revision and absence of an unexpected preparation. A failed store, membership or leader-route check must give not-ready; restore that dependency before opening traffic.
4. Upgrade Proxies and Connectors in the maintenance window. Preserve the Connector-before-Authority order when upgrading an activated SSH cluster from versions older than rc.10. Check configured distinct Proxy connections, an allowed session, a denied session, audit verification and central recording delivery.
5. For in-cluster Kubernetes, use the intended ServiceAccount projection and verify the next token refresh without a Pod restart. API backends need the configured impersonation permissions; discovery sources need only their read-only discovery permissions. Removing permission must refuse requests or withdraw discovery targets after their lease expires.

Root rotation is a separate operation: follow prepare, verify and activate. Every retained owner must provide a durable signed ACK. At least two owners must remain, so add a third Authority before withdrawing one from a two-node cluster. A retained owner can cancel a preparation after loss of the initiator; missing ACKs do not trigger timeout withdrawal. Wait for each retained node's new epoch and readiness before completing the change.

A binary downgrade alone cannot undo receiver bindings, pending transitions or committed root epochs. Stop the changed fleet and use the paired recovery procedure with the matching store and every node's local state. Do not restore only the DB or replace a receiver credential. Before reverting a Connector that uses discovery_sources, restore its compatible configuration as well; the older binary cannot run that source. Root membership withdrawal does not revoke CA, audit/control keys or separate DB/KMS credentials the removed node already held.

To v0.10.0-rc.10

Against rc.9, this version adds an Authority bootstrap RPC without adding store migrations. An upgrade from an earlier version must also complete the rc.9 migration procedure.

1. Preserve a paired store and key backup, each node's transport identity, and the client configuration. With keyring sync enabled, also back up the distribution root and protected cache with the store.
2. Upgrade the Authority and Proxy fleet in a maintenance window. Keep CA rotation paused until the replicas load the same keyring revision. Follow bootstrap and synchronization to enable automatic distribution; a binary upgrade alone does not enable it.
3. Upgrade Connectors and verify their configured Proxy connections. Existing tunnels end when their owning process stops. Check a resource session and its recording before reopening ordinary traffic.
4. Upgrade the client binary, stop the previous resident, and run sudo gdsgate --config "$CLIENT_CONFIG" up on the Linux client host. Verify the system unit uses the original user's identity and that gdsgate --config "$CLIENT_CONFIG" status --explain reports active endpoints.
5. For direct, adjust native application ports to the new values in status: the default maps 22 to 10022. Setting the offset to 0 retains low ports and requires bind privilege. Verify the owning UID can connect and another unprivileged UID cannot. This isolation guarantee applies only to Linux.

A downgrade does not undo firewall or service changes. Stop the upgraded resident before restoring the earlier binary. Before reverting automatic keyring distribution, preserve the current rings and use the paired restore procedure in Authority recovery.

To v0.10.0-rc.9

This release adds store migrations m0078 and m0079. Take the paired store and key backup. Restoring an earlier binary requires restoring that pair. For an upgrade from rc.6 or earlier, also complete the audit queue and CA rotation preflight in the rc.7 procedure.

1. Withdraw client traffic and stop the older Proxies. Allow established sessions to finish within the maintenance window; remaining streams end when their owner stops.
2. Pause CA rotation, stop all older Authorities, and upgrade the Authority fleet in one window. Apply migrations with the first upgraded Authority; start the remaining instances with the same store and keyrings.
3. Configure each Authority with a unique lease owner and the full private peer address map. Verify every Authority is ready before resuming CA rotation. The TCP LB must admit ready followers as well as the leader.
4. Upgrade all Proxies, preserve their separate identity volumes, and configure their private peer addresses. Check readiness before opening the HA pool.
5. Upgrade Connectors. Set connector.proxy_connection_count = 2 for HA peer routing. A Connector configured for two connections can accept peer opens while one tunnel is available. The default 1 retains local-session compatibility behavior. Remove source-IP affinity from the tunnel LB pool.

Every role in the HA pool must run the same version. Use the HA configuration and ports for DNS or IP-only access. Keep peer listeners private; preserve the store, keyrings and each node's individual identity.

Verify Connector doctor reports the configured number of distinct Proxy connections. Complete the HA checks, including fresh access after stopping each Proxy and Authority, a policy denial, and authority audit verify. Existing streams do not migrate between owners.

To v0.10.0-rc.7

This release adds store migrations m0075 through m0077. Take the paired store and key backup, stop Authority writes, and apply the migrations as a planned operation. Restore the pair to return to an earlier binary.

Before the first Authority stops, require an empty audit queue as described above. Let every CA rotation already requested finish. Pause scheduled and manual CA rotation for the upgrade window. Upgrade every Authority instance in the same window, then resume rotation after every instance reports ready. An older instance does not enforce this release's leader and wait guarantees for an in-progress rotation.

Upgrade the proxies in the same window as Authority. This release adds policy history and review RPCs and changes how a proxy selects the Authority leader after a write refusal. Upgrade connectors afterwards; their established sessions continue under the existing session rules.

After the fleet is current, run authority audit verify, confirm gdsgate_audit_outbox_depth remains 0, and exercise one registration renewal and one administrative policy read through a proxy.

To v0.10.0-rc.6

On Linux hosts running the shipped systemd units, each role now has a state directory of its own under /var/lib/gdsgate. After installing the new binary, run gdsgate service install <role> as root for every role on the host, then restart the roles. The first run turns /var/lib/gdsgate from a link into a directory and names the installed units that still use StateDirectory=gdsgate. Reinstall each of them before starting it; a unit left on the old line exits with status 238.

Symptom	Cause	What to do
service install refuses: ... is outside /var/lib/gdsgate	The role writes outside the state root.	Move the path under /var/lib/gdsgate/<role> and update the configuration.
service install refuses: ... is where every role's directory is	The role writes directly in /var/lib/gdsgate.	Use /var/lib/gdsgate/<role> for that path.
A unit exits with status 238	The unit still has StateDirectory=gdsgate.	gdsgate service install <role> for that role.

A connector installed with install-connector.sh is installed again with --state-dir under /var/lib/gdsgate/connector.

Scripts that run gdsgate setup apply as root pass --approve-plan <digest> with the digest --dry-run printed.

Upgrade Authority and the proxies in the same window: authority users forget-name is forwarded by the Proxy, and an older Proxy does not forward it.

To v0.9.0-rc.11

Before starting the new Authority, add onward_auth to every [[discovery.auto_scopes]] entry whose kinds holds ssh, for example onward_auth = ["certificate"] for targets reached with the certificate gdsgate mints. Without it Authority refuses to start and names the scope. A scope managed with authority scopes set is re-applied with --onward-auth.

Upgrade the proxies in the same window as Authority. A proxy older than Authority drops the new fields from the administrative responses it relays, and authority agents list then shows - under seen for every agent; read with --route certificate until the proxies are upgraded.

A request to a web resource with a gdsgate-identity header is refused unless the person named in the header is also allowed. Remove the header from scripts that set it.

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.