Uninstall and environment decommission

Removing Gameplane requires careful inventory, explicit decisions on every retained resource, and an uninstall order that respects Kubernetes finalizers and state cleanup. This guide covers retention decisions, safe uninstall sequencing, and verification that no orphaned resources or costs remain.

Decide retention

Inventory platform and game state, classify every item, and obtain owner approval before removal.

Backup and export

Before removing anything, export or back up irreplaceable state:

• Game server worlds and data: Trigger a final backup for every active GameServer via the Backup CRD or dashboard. Export spec.storage.data volumes to external storage if they contain user-created content or mods.
• Database: Export audit logs and user credentials. For SQLite, the PVC gameplane-api-data contains gameplane.db; for PostgreSQL, dump the database with pg_dump.
• Module sources and credentials: Document all ModuleSource custom registries and their pull-secret names (usually a kubernetes.io/dockerconfigjson Secret). Note the uploads ModuleSource (created when uploadModuleSource.enabled is set) and, if it points at a mounted directory via operator.localModules.{hostPath,existingClaim}, back up that volume before uninstalling.
• OIDC and webhook credentials: Export Secret objects in gameplane-system namespace (OIDC client secret, webhook signing keys, etc.). These will be deleted when the namespace is removed.
• Cluster registrations: Document any registered remote Cluster CRDs and their kubeconfig Secrets for re-registration or archival.

Retention approval

Obtain sign-off from stakeholders (game owners, ops team, legal if applicable) on:

1. Which worlds and save files are being destroyed vs. exported.
2. How long backups are retained (restic repositories may continue accruing storage costs).
3. Whether to retain the gameplane-games namespace and PVCs if migrating to a new cluster.

Uninstall safely

Quiesce writes and remove controllers and dependencies in an order that allows finalizers to complete.

Uninstall sequence

Follow this order to allow finalizers to complete:

1. Scale down controllers: Set the operator and API Deployment replicas to 0.

   kubectl -n gameplane-system scale deployment gameplane-operator --replicas=0
   kubectl -n gameplane-system scale deployment gameplane-api --replicas=0

   This stops new reconciliation loops. Existing in-flight operations (e.g., restic Backup Jobs) may still be running.

2. Wait for in-flight operations: Wait for all Backup and Restore Jobs to complete or be explicitly deleted:

   kubectl -n gameplane-games get jobs
   kubectl delete -n gameplane-games jobs --all

   Quiesce any running GameServers and wait for pods to stop (or delete them forcefully).

3. Delete GameServers and Backups: GameServers delete immediately (no finalizer); a quiesced Backup (spec.quiesce: true) has a finalizer that blocks deletion until the operator sends the matching unquiesce — wait for that to clear before assuming it’s stuck.

   kubectl delete gameservers -A
   kubectl delete backups -A

   If a resource is stuck with DeletionTimestamp set, check the operator logs for the finalizer handler’s error, fix the underlying issue (e.g., orphaned cloud resource), and remove the finalizer manually only as a last resort (only for Backups with spec.quiesce: true):

   kubectl patch backup <name> -p '{"metadata":{"finalizers":[]}}' --type merge

4. Delete Helm release: Uninstall the chart. CRDs are not deleted automatically (see “CRD retention” below).

   helm uninstall gameplane -n gameplane-system

5. Delete the gameplane-system namespace: Removes API, operator, and all related resources.

   kubectl delete namespace gameplane-system

6. Delete or retain CRDs: By default, Helm does not delete CRDs (to prevent accidental data loss). If you are decommissioning entirely:

   kubectl delete crd backups.gameplane.local backupschedules.gameplane.local \
     clusters.gameplane.local gameservers.gameplane.local gametemplates.gameplane.local \
     modules.gameplane.local modulesources.gameplane.local restores.gameplane.local

   If keeping the CRDs for re-import or recovery, skip this step. CRDs without resources consume minimal cluster resources.

7. Delete or retain the gameplane-games namespace: If you are migrating GameServers to a new cluster and want to keep the PVCs and game data:

   # Keep PVCs and data, remove just the namespace and pods
   kubectl delete namespace gameplane-games --grace-period=60

   Or, if decommissioning entirely:

   # Deletes all PVCs and game data
   kubectl delete namespace gameplane-games

   If PVCs have a retain reclaim policy, they persist after namespace deletion and can be re-attached to another cluster.

Verify and close

Check for orphaned resources and costs, revoke credentials, and archive restoration and destruction evidence.

Final verification checklist

• No Gameplane pods running in gameplane-system or gameplane-games namespaces.
• No Gameplane Services, Ingress, or NetworkPolicies remain in the cluster.
• No Gameplane PersistentVolumeClaims or PersistentVolumes exist (or are retained intentionally with a documented reason).
• Cloud provider load balancers and IP addresses associated with Gameplane are released.
• DNS entries (e.g., gameplane.your-domain) are removed or point elsewhere.
• All exported backups and audit logs are stored in long-term archive (S3, GCS, etc.).
• Credentials have been rotated or revoked in the backup repository and any external systems (Slack for notifications, OIDC provider, etc.).
• A final audit log or summary document is archived, signed, and timestamped.

Environment migration (alternative to full decommission)

If you are shutting down Gameplane on one cluster but migrating to another:

1. Export all GameServers to YAML via kubectl get gameservers -A -o yaml > gameservers-export.yaml.
2. Export all Backup objects and their associated restic snapshots.
3. On the new cluster, install Gameplane and re-import the GameServer definitions via kubectl apply -f gameservers-export.yaml.
4. Re-register any Cluster resources and re-create ModuleSource configurations.
5. Once verified on the new cluster, proceed with full decommission on the old cluster (steps above).

This approach allows zero-downtime migration if you can tolerate a brief reconciliation window for the operator to re-create the StatefulSets and Services on the new cluster.

See also

• Platform disaster recovery — recover from cluster failure, restore all data, and re-register multi-cluster topology.
• Backup & recovery — backup retention policies and restore procedures.
• Kubernetes maintenance — node drains, cluster upgrades, and capacity management.