Upgrades and migrations

Gameplane releases are pinned with signed container images and strict Kubernetes compatibility. Every upgrade is reversible if planned carefully; every migration is documented in the release notes.

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.

Plan the change

Read release notes and compatibility constraints. Export your current configuration. Verify you have recent, recoverable backups in place.

Export your current values

Before upgrading, save your Helm configuration so you can rollback if needed:

# Export your installed Helm values (including OIDC, storage, and other overrides)
helm get values gameplane -n gameplane-system > gameplane-values-backup.yaml

# List all installed CRDs
kubectl get gameservers,gametemplates,clusters,backups,modules -A -o yaml > crds-backup.yaml

# Check the current version
helm list -n gameplane-system

Check for breaking changes

Most releases are backward-compatible, but some introduce schema changes or require manual steps. Always check:

• CHANGELOG — upgrade notes at the top of the release section
• Supported Versions Matrix — which clusters/Kubernetes versions are compatible
• Network changes — if the release adds new NetworkPolicy or changes to spec.networking
• CRD migrations — if any CRD fields were removed, renamed, or changed in meaning (CRDs are applied automatically by the chart’s crds.autoApply hook; see CRD updates on upgrade)

Stage and observe

Upgrade a non-production or canary environment first. Watch the rollout, check migrations, and verify core workflows.

Run the upgrade

Once you have verified your values and backups, apply the upgrade to your cluster:

# Upgrade to a specific version (e.g., 0.2.0-beta.8)
helm upgrade gameplane oci://ghcr.io/valgulnecron/charts/gameplane \
  --namespace gameplane-system \
  --version 0.2.0-beta.8 \
  --values gameplane-values-backup.yaml \
  --wait

# Watch the rollout
kubectl rollout status deploy/gameplane-operator -n gameplane-system
kubectl rollout status deploy/gameplane-api -n gameplane-system

# Check for errors in operator and API logs
kubectl logs -n gameplane-system deploy/gameplane-operator -f

Observe the cluster

During and after the upgrade, monitor for issues:

# Watch CRD reconciliation
kubectl describe gameserver <name> -n default  # Check Status and Conditions

# Check API health
kubectl logs -n gameplane-system deploy/gameplane-api --tail=50

# Verify connectivity to pods
kubectl get pods -n gameplane-system
kubectl get pods -n default -l app=gameplane  # Game server pods

Rollback or complete

If migrations fail or core workflows are broken, use the release-specific rollback procedure. Otherwise, verify your environment and close the rollback window.

Rollback if needed

Only use the rollback procedure if migrations failed or core workflows are broken:

# 1. Review the release notes for this version's rollback procedure
# 2. Export current CRDs in case you need to debug
kubectl get crds -o yaml > crds-upgrade-state.yaml

# 3. Roll back the Helm chart (example: rolling back from 0.2.0-beta.8 to 0.2.0-beta.7)
helm upgrade gameplane oci://ghcr.io/valgulnecron/charts/gameplane \
  --namespace gameplane-system \
  --version 0.2.0-beta.7 \
  --values gameplane-values-backup.yaml \
  --wait

# 4. Verify operator and API pods are running
kubectl rollout status deploy/gameplane-operator -n gameplane-system
kubectl rollout status deploy/gameplane-api -n gameplane-system

# 5. Test core workflows again (create server, check console, etc.)

CRD updates on upgrade

helm upgrade never updates CRDs (a Helm limitation: files under a chart’s crds/ directory are installed once and ignored afterwards). The chart works around this with crds.autoApply (enabled by default), a pre-install/pre-upgrade hook that runs kubectl apply --server-side over the current CRDs. No manual kubectl apply step is needed. The hook runs on every helm upgrade, and on a helm install only when the cluster holds CRDs from a different chart version that an earlier, uninstalled release left behind. A genuinely fresh install never depends on pulling the hook’s kubectl image.

If you set crds.autoApply.enabled=false, apply the CRDs yourself:

kubectl apply --server-side -f charts/gameplane/crds/

• Helm 3, reinstalling over leftover CRDs: the hook runs, so air-gapped clusters need crds.autoApply.image mirrored for that case.
• Helm 4: crds/ is applied natively with a server-side apply under the field manager helm. CRDs last applied by v0.2.0-beta.8 or earlier were applied under the kubectl manager, so a Helm 4 helm install over such leftovers stops with conflict with "kubectl" ... .spec.versions. Re-run it once with --force-conflicts:

helm install gameplane charts/gameplane -n gameplane-system --create-namespace --force-conflicts

Upgrade notes for v0.3.0

Read these before upgrading from v0.2.0-beta.8:

• Every existing GameServer rolls once. Network capture needs a pre-provisioned volume on every game pod, because Kubernetes ephemeral containers can add containers to a running pod but not volumes. The capture emptyDir is therefore added to every pod template, and each pod is recreated once on upgrade, interrupting active player sessions. This does not repeat on later starts. Servers that do not opt into capture carry only an empty, unused volume: no capture sidecar, no CAP_NET_RAW, no network change. Plan the upgrade window accordingly.
• Owner-only server operations. Transferring ownership, editing collaborators, wiping data and deleting a server now need the server’s owner or an admin. Operator-role users keep their other server permissions but can no longer run these four operations on servers they do not own. Servers with no recorded owner (for example created with kubectl or GitOps) can be transferred, wiped or deleted only by an admin.
• Playit tunnel egress widened. The operator-managed NetworkPolicy for a GameServer using the playit tunnel provider now adds an unrestricted egress rule (all ports and protocols, any destination) alongside the DNS/advertised-ports rule every provider gets. Previously playit could not reach its relay.
• Helm 3 and Helm 4 CRD handling. See the section above, including the one-time --force-conflicts for Helm 4.
• Tunnel credential Secrets must be owned by their GameServer. The operator refuses a tunnel credentials Secret whose ownerReference does not match the GameServer’s name and UID, scales the tunnel to zero and reports TunnelReady=False with reason TunnelCredentialRefused. Secrets created with plain kubectl create secret for v0.2.0-beta.8 are refused after the upgrade: re-enter the credential in the server’s Networking tab (which writes an owned <server>-tunnel-auth Secret) or add the ownerReference. See Server Networking & Tunnels.

Rollback decision

Close the rollback window only when:

• Data integrity verified: All CRD records migrated cleanly (check kubectl describe for migration errors in Conditions).
• Workflows tested: Logged in, created a server, ran console commands, verified backups and authentication.
• Version recorded: Note the new version in your runbooks and team docs so you can rollback to the exact prior version if needed in the next 24 hours.

Once 24 hours have passed without issues, backups of the pre-upgrade state become less relevant (newer backups have accumulated). At that point, safely delete old backup snapshots to reclaim storage.

Next steps

If you encounter issues during upgrade:

• Check the Troubleshooting guide for common errors and recovery steps.
• Review operator logs: kubectl logs -n gameplane-system deploy/gameplane-operator
• Review the CHANGELOG for known issues in your target version.
• For help, reach out in the community channels.