Upgrades

Tunnex upgrades are forward-only. There is no supported database downgrade; the rollback is a restore of the verified pre-upgrade dump under its matching master key.

The public installer pins release artifacts to a signed descriptor. Its local upgrade helper verifies the target. With --apply, it takes and verifies a backup, runs preflight, pulls the approved images, restarts the deployment, and health-checks it.

• A control plane at protocol version N supports gateway agents at N and N-1.
• An older agent outside that window refuses a too-new artifact and installs a synthetic deny-all interlock rather than partially interpreting it.
• Database migrations are designed for a one-version rolling window.
• Existing gateway forwarding continues from last-applied state during a brief control-plane restart; new management changes wait for reconciliation.

1. Confirm the release notes and exact signed target shown by the deployment.
2. Confirm the separately stored master key is accessible to the recovery team.
3. Test the current backup/restore procedure, not merely the existence of files.
4. Resolve expired gateway certificates and agents below the N-1 window.
5. Record readiness, gateway health, and actual tunnel handshakes.
6. Use a maintenance window even though the data plane is designed to continue.

The current host helper uses pg_restore --list to validate its new dump. Install the PostgreSQL client tools on the host before --apply; the public installer’s base prerequisites do not currently check or install that command.

Run the read-only preflight manually when investigating readiness:

cd tunnex
sudo docker compose -f tunnex.yml exec -T api preflight

It refuses until you explicitly confirm a verified backup and master key:

sudo docker compose -f tunnex.yml exec -T \
  -e TUNNEX_PREFLIGHT_BACKUP_CONFIRMED=yes api preflight

Preflight checks database reachability, migration cleanliness, gateway certificate validity, agent compatibility, and the acknowledged rollback plan. An unknown result is a refusal, not a warning.

The default is a dry run:

cd tunnex
sudo ./upgrade.sh

Review the exact release and actions. Apply only after the dry run and recovery checks are satisfactory:

sudo ./upgrade.sh --apply

Do not hand-edit tunnex.yml. The helper checks its installer-recorded baseline and refuses a modified managed file. Re-running the current public installer can repair managed upgrade assets without intentionally replacing deployment secrets or applying an upgrade.

Newer public installations can also request the same bounded host-side workflow from the dashboard. The API does not receive the Docker socket or general root command execution; it writes a constrained request for the root-owned helper.

For a deployment administrator (cp_admin):

1. Open Overview.
2. In Upgrade Center, review Installed, Target, Upgrade state, Database backup, manifest verification, and release notes.
3. Select Upgrade control plane.
4. Confirm the exact server-verified target.
5. Follow request, signed-release verification, backup, preflight, pull, restart, health, and success/failure stages.

Ordinary organization administrators do not see this deployment-level control. The UI cannot choose an arbitrary release target.

Disabling discovery remains useful for an operator-supplied signed manifest:

TUNNEX_RELEASE_UPDATE_CHECK=false

The helper accepts local archives with:

sudo ./upgrade.sh --manifest ./release.json --airgap ./bundle

This command is not a side-effect-free dry run: it loads *.tar archives into the local Docker image store before stopping at the apply guard. An absent, altered, stale-sequence, or mismatched descriptor is a hard failure. Do not run --apply in a disconnected environment until a release explicitly documents a complete offline workflow.

sudo docker compose -f tunnex.yml ps
sudo docker compose -f tunnex.yml logs --since=15m api node-agent
sudo docker compose -f tunnex.yml exec -T api \
  wget -qO- http://127.0.0.1:8080/healthz
sudo docker compose -f tunnex.yml exec -T api \
  wget -qO- http://127.0.0.1:9090/readyz
sudo docker compose -f tunnex.yml exec -T node-agent wg show

Verify all of the following:

• database migrations completed and readiness is ok leader or ok follower;
• each gateway reconnects and applies the current revision;
• no gateway reports unsupported_policy_version;
• user sign-in and one representative management action work; and
• an established and a newly initiated tunnel both pass traffic.

The helper’s automated post-restart gate checks /healthz liveness only. The manual readiness, reconciliation, and traffic checks above are required before calling the upgrade healthy.

Upgrade gateway agents one at a time after the control plane, keeping the fleet in the supported window.

Stop and preserve the logs, signed descriptor, helper status, and pre-upgrade artifacts. Do not attempt an ad-hoc schema downgrade. Follow Backup and restore with the pre-upgrade dump, its digest-bound manifest, and the matching separately held master key.

After recovery, prove gateway identity and traffic before retrying the release.