gameplane / docs
LIFECYCLE

Executable upgrades and rollback

Turn release notes into a staged change plan with compatibility gates, migration ownership, verification evidence, and a safe recovery boundary.

Upgradesv0.220 MIN
Never assume schema or CRD downgrade is safe.

Use only the release-specific rollback window.

Releases up to and including v0.3.0 are published under ghcr.io/valgulnecron, so this page uses that registry; releases after v0.3.0 move to ghcr.io/gameplanepanel.

Preflight compatibility

Define the supported source/target path and capture the complete current environment before changing it.

Environment snapshotCheck Kubernetes, Helm, database, CRDs, values, and downtime.
Recovery setExport values and rendered manifests; verify the recovery set.
Success criteriaDefine success, abort, rollback, and forward-fix criteria.

Capture the entire current state before starting the upgrade:

  • Kubernetes version: kubectl version --short
  • Helm chart version: helm list -n gameplane-system
  • Database version: Query the migration ledger directly: sqlite3 <db-path> "SELECT version, applied_at FROM schema_migrations ORDER BY version;" (or the equivalent psql query when running with --db-driver=postgres)
  • CRD versions: kubectl get crd -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.names.kind}{"\n"}{end}'
  • Helm values: helm get values gameplane -n gameplane-system > current-values.yaml
  • Rendered manifest diff: helm diff upgrade gameplane oci://ghcr.io/valgulnecron/charts/gameplane --version <target-version> -n gameplane-system (requires helm-diff plugin)

Execute in release order

Follow release-specific CRD, migration, chart, and workload ordering through canary and production.

Canary firstDiff manifests and run a non-production canary first.
Observe migrationObserve migration jobs, rollouts, leaders, conditions, events, and logs.
No cross-domain changesDo not combine unrelated server, storage, auth, or network changes.

Verify the manifest diff reflects only the version change you intend. Run a non-production canary cluster through the same sequence: helm upgrade --install the target chart version, wait for the pre-upgrade CRD hook to complete (check the Job logs in gameplane-system), then observe all migration Jobs, operator rollout, API rollout, and game server reconciliations. Check kubectl get events -n gameplane-system and operator logs (kubectl logs -l app=gameplane-operator -n gameplane-system -f).

Validate or recover

Test every core workflow and roll back only when data and CRD compatibility explicitly permit it.

Test every core workflow after the upgrade completes:

  • Create a test GameServer and verify it starts.
  • Verify console connectivity, file manager access, and player list population.
  • Trigger a backup and verify it completes.
  • Check audit logs are being recorded.
  • Run at least one complete login → server create → player join → graceful stop cycle.

Roll back only if validation fails and the release-specific downgrade window permits it. CHANGELOG.md currently documents upgrade-impacting changes only under the “Upgrade Notes” section of [Unreleased]; released versions do not yet carry a per-release rollback-window annotation. If you must rollback:

  1. Note the last-known-good version before the upgrade.
  2. Until a per-release rollback-window convention exists, treat any CRD field removal or required-field addition as rollback-unsafe by default. Confirm compatibility by diffing operator/api/v1alpha1/*_types.go between your source and target tags before attempting a downgrade.
  3. If the path is not explicitly safe, do not attempt rollback; instead, open a GitHub issue or contact the maintainers.

UPGRADE GATE

01   Supported path + recovery set + rendered diff + canary
02   Apply documented CRD/migration/chart order; observe every job
03   Validate core workflows; rollback only inside compatibility window

Release order details

Every release’s CHANGELOG includes an “Upgrade Notes” section that documents:

  • CRD order: Which CRDs must be applied first (if any are dropped or renamed, the order matters for downgrade safety).
  • Migration jobs: Sequencing for any database schema or data transformations (e.g., backfilling a new column before a NOT NULL constraint is added).
  • Operator behavior: Whether the operator has breaking changes (e.g., new required fields, behavior changes on certain CRD values).
  • Chart-only changes: Helm value renames or restructures that require manifest diffing.

If the upgrade adds a CRD or modifies CRD schema in a backward-incompatible way (e.g., removing a field), assess rollback safety by examining the CRD field changes. For example, if a field is removed in v0.3.0 but the v0.2 operator still reads it, you can safely rollback v0.3.0 → v0.2; if the field is required in v0.3.0 and v0.2 will fail on its absence, the rollback window is closed — you are committed to v0.3.0 and must forward-fix any issues instead.

NEXT GUIDESupported versions and compatibility