Wardengate

Install

Upgrading

Wardengate upgrades are meant to be boring. The control plane rolls pods one at a time, schema migrations run in a pre-upgrade job, and gateways pick up the new version on their next heartbeat. The worst case — a failed migration — leaves the old version running and aborts the upgrade.

Version support policy

Wardengate uses semantic versioning. The current major receives feature releases and critical security fixes; the previous two minors receive security fixes only. Older versions are out of support.

  • Upgrade within a minor is always supported (2.4.1 to 2.4.7)
  • Upgrade across one minor is always supported (2.4.x to 2.5.x)
  • Upgrade across two minors requires landing on the interim release first (2.3.x to 2.4.x to 2.5.x)
  • Upgrade across majors requires a dedicated migration path documented in that release’s notes

Pre-upgrade checklist

  • Read the release notes end to end — breaking changes are called out at the top
  • Take a Postgres backup you know how to restore — see Backup & restore
  • Confirm object storage is healthy and has headroom for the recording drain
  • Drain or warn long-running sessions; schema-changing minors can recycle gateway pods
  • Run wgctl system preflight --target 2.5.0 and clear every warning
  • Make sure the current version is at its latest patch before jumping minors
wgctl system preflight --target 2.5.0

# Summary
# database          ok   postgres 16.2, 231 MB
# storage           ok   s3://wg-recordings reachable, 4.2 TB free
# replicas          ok   3 healthy / 3 expected
# gateways          ok   6 reporting / 6 expected
# clock_skew        ok   max 18ms across control plane
# breaking_changes  warn deprecated policy.hours syntax -- see 2.5 notes

Minor vs major upgrades

Minor upgrades (x.y) are designed to be rolling and backwards-compatible for one release. The control plane and gateways can run mixed versions for the duration of a rollout. Major upgrades (x) break that contract — expect a maintenance window and a dedicated runbook in the release notes.

Docker upgrade

Single-container and Compose deployments upgrade by pulling a newer image and recreating the container. Migrations run during container startup.

# single container
docker pull wardengate/server:2.5.0
docker stop wardengate
docker rm   wardengate
docker run -d --name wardengate ... wardengate/server:2.5.0

# compose
sed -i 's|wardengate/server:2.4|wardengate/server:2.5|' docker-compose.yml
docker compose pull wardengate
docker compose up -d wardengate
docker compose logs -f wardengate

Watch the logs until you see migration: completed followed by listening on 8443. If migrations fail, the container exits with code 2 and your old container is still stopped — address the cause before re-running.

Kubernetes rolling upgrade

helm repo update
helm upgrade wardengate wardengate/wardengate \
  --namespace wardengate \
  --version 2.5.0 \
  --reuse-values \
  --set image.tag=2.5.0

kubectl -n wardengate get jobs
kubectl -n wardengate logs job/wardengate-migrate-2-5-0
kubectl -n wardengate rollout status deploy/wardengate --timeout=10m

The chart runs a pre-upgrade Job that applies schema migrations. Only after it succeeds does Helm roll the Deployment. If the Job fails, Helm returns a non-zero exit and the Deployment is untouched — the old pods keep serving traffic.

Database migrations

Migrations are versioned and idempotent. Each release ships the full history since the last major; running them on an up-to-date database is a no-op. Migrations are forward-only: we do not ship down() steps because most schema changes cannot be rolled back safely without data loss once new writes land.

To roll back a release, restore the pre-upgrade database backup and redeploy the previous image. See the rollback section below.

Post-upgrade verification

wgctl system health
wgctl system version

# Expected
# Control plane: 2.5.0 (3 replicas)
# Gateways:      2.5.0 (6 healthy / 6 registered)
# Schema:        185 (up to date)
# License:       enterprise (valid)

Walk a real session end-to-end — sign in, open an SSH session to a canary target, confirm recording reaches the bucket, and verify an audit event shows up in the SIEM. The canary exercises the whole pipeline in about 60 seconds and catches issues the readiness probe cannot.

Rollback procedure

Rollback is stop, restore, redeploy. There is no in-place rollback once schema migrations have applied.

  • Scale the Deployment or stop the container to stop new writes
  • Restore the pre-upgrade Postgres snapshot into the same database
  • Redeploy the previous image tag (Helm: helm rollback wardengate; Docker: rerun with the old tag)
  • Run wgctl system verify to confirm the schema matches the binary
# Kubernetes
kubectl -n wardengate scale deploy/wardengate --replicas=0
# ... restore Postgres to pre-upgrade snapshot ...
helm rollback wardengate 1 -n wardengate
kubectl -n wardengate scale deploy/wardengate --replicas=3

Breaking-change notice patterns

Breaking changes are announced one minor release ahead of the break. A minor that deprecates a field emits runtime warnings in the audit log and in the admin console; the subsequent minor removes the field entirely. In practice:

  • 2.4.x — feature works, old syntax still accepted, deprecation warning emitted
  • 2.5.x — old syntax rejected; upgrade blocked until configuration is migrated

Run wgctl system deprecations ahead of an upgrade to print every deprecation currently logged by your install with a pointer to the release that removes each one.

Related