This guide covers how to safely upgrade Agones in production environments while minimizing disruption to running game servers.
Overview
Agones follows semantic versioning and maintains backward compatibility within major versions. The upgrade process typically involves:
Reviewing release notes and breaking changes
Testing in non-production environment
Backing up current configuration
Performing the upgrade
Validating the upgrade
Always test upgrades in a non-production environment first. While Agones maintains backward compatibility, configuration changes and feature gate updates should be validated.
Pre-Upgrade Checklist
Check current version
# Get current Agones version
kubectl get deployment -n agones-system agones-controller \
-o jsonpath='{.spec.template.spec.containers[0].image}'
# Check Helm release
helm list -n agones-system
Review release notes
Visit the Agones releases page and review:
Breaking changes
New features and deprecations
Known issues
Recommended upgrade path
Backup current configuration
# Export current Helm values
helm get values agones -n agones-system > agones-values-backup.yaml
# Backup CRDs
kubectl get crd -o yaml | \
grep -E "agones.dev|multicluster.agones.dev" > agones-crds-backup.yaml
# Backup all Agones resources
kubectl get gameservers,fleets,fleetautoscalers --all-namespaces \
-o yaml > agones-resources-backup.yaml
Check for deprecation warnings
# Check controller logs for deprecation warnings
kubectl logs -n agones-system -l app=agones,component=controller \
--tail=1000 | grep -i deprecat
Upgrade Methods
Helm Upgrade (Recommended)
Standard Upgrade
With Custom Values
Dry Run
# Update Helm repository
helm repo update
# Check available versions
helm search repo agones/agones --versions
# Upgrade to specific version
helm upgrade agones agones/agones \
--version 1.42.0 \
--namespace agones-system \
--reuse-values
Using --reuse-values preserves your custom configuration. Alternatively, use -f values.yaml to explicitly specify values.
# Upgrade with custom values file
helm upgrade agones agones/agones \
--version 1.42.0 \
--namespace agones-system \
-f agones-custom-values.yaml
Example agones-custom-values.yaml: agones :
featureGates : "PlayerTracking=true&CountsAndLists=true"
controller :
logLevel : info
resources :
requests :
cpu : 100m
memory : 256Mi
limits :
cpu : 1000m
memory : 1Gi
metrics :
prometheusEnabled : true
prometheusServiceDiscovery : true
# Test upgrade without applying
helm upgrade agones agones/agones \
--version 1.42.0 \
--namespace agones-system \
--reuse-values \
--dry-run --debug
Review the output to see what changes will be applied.
YAML Installation Upgrade
If you installed via YAML manifests:
# Download new version
wget https://github.com/googleforgames/agones/releases/download/v1.42.0/install.yaml
# Review changes
kubectl diff -f install.yaml
# Apply upgrade
kubectl apply -f install.yaml
Upgrade Process
The typical upgrade sequence:
CRDs are updated first
Agones Custom Resource Definitions are updated. Existing resources remain compatible. # Verify CRD versions after upgrade
kubectl get crd gameservers.agones.dev -o yaml | grep version
Controller deployment updates
The Agones controller deployment performs a rolling update:
New controller pod starts
New pod becomes ready
Old pod terminates
# Watch controller rollout
kubectl rollout status deployment/agones-controller -n agones-system
Existing GameServers continue running
Running GameServers are NOT restarted during upgrade. They continue using the existing SDK sidecar version. New GameServers created after upgrade will use the new SDK sidecar version.
SDK sidecar updates on new GameServers
Only newly created GameServers get the updated SDK sidecar. Update your Fleet to roll out to all GameServers: # Trigger Fleet update to refresh all GameServers
kubectl patch fleet < fleet-nam e > \
--type merge \
-p '{"spec":{"template":{"metadata":{"annotations":{"agones.dev/sdk-version":"1.42.0"}}}}}'
Rollout Strategy for GameServers
After upgrading Agones, update your Fleets to use the new SDK version:
Controlled Rollout
apiVersion : agones.dev/v1
kind : Fleet
metadata :
name : my-fleet
spec :
replicas : 100
strategy :
type : RollingUpdate
rollingUpdate :
maxUnavailable : 25% # Maximum unavailable during update
maxSurge : 25% # Maximum extra GameServers during update
template :
metadata :
annotations :
agones.dev/sdk-version : "1.42.0" # Update this to trigger rollout
spec :
# ... rest of GameServer spec
Understanding RollingUpdate parameters
maxUnavailable : Maximum number/percentage of GameServers that can be unavailable during update
maxSurge : Maximum number/percentage of GameServers that can be created above desired replicas
Example with 100 replicas:
maxUnavailable: 25% = max 25 GameServers unavailable
maxSurge: 25% = max 125 total GameServers during rollout
Adjust based on your availability requirements and cluster capacity.
Recreate Strategy
For faster rollouts when downtime is acceptable:
strategy :
type : Recreate # Deletes all old GameServers before creating new ones
Feature Gate Updates
When enabling or disabling feature gates during upgrade:
Understand feature stability
Alpha : Disabled by default, may have bugs
Beta : Enabled by default, well-tested
GA : Stable, always enabled
Check feature stages for current status.
Update feature gates
helm upgrade agones agones/agones \
--version 1.42.0 \
--namespace agones-system \
--set agones.featureGates="PlayerTracking=true,CountsAndLists=true" \
--reuse-values
Verify feature gate configuration
# Check controller logs for feature gate configuration
kubectl logs -n agones-system -l app=agones,component=controller \
--tail=50 | grep featureGates
Look for: { "featureGates" : "PlayerTracking=true&CountsAndLists=true" , "message" : "starting gameServer operator..." }
Post-Upgrade Validation
Verify controller health
# Check controller is running
kubectl get pods -n agones-system -l app=agones,component=controller
# Check for errors in logs
kubectl logs -n agones-system -l app=agones,component=controller \
--tail=100 | grep -i error
# Verify metrics endpoint
kubectl port-forward -n agones-system svc/agones-controller 8080:8080
curl http://localhost:8080/metrics
Test GameServer creation
# Create a test GameServer
kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/release-1.42.0/examples/simple-game-server/gameserver.yaml
# Watch it become Ready
kubectl get gs simple-game-server -w
# Clean up
kubectl delete gs simple-game-server
Test allocation
# Create test fleet
kubectl apply -f - << EOF
apiVersion: agones.dev/v1
kind: Fleet
metadata:
name: test-fleet
spec:
replicas: 2
template:
spec:
ports:
- name: default
containerPort: 7654
template:
spec:
containers:
- name: simple-game-server
image: us-docker.pkg.dev/agones-images/examples/simple-game-server:0.34
EOF
# Wait for ready GameServers
kubectl wait --for=jsonpath= '{.status.readyReplicas}' =2 fleet/test-fleet --timeout=300s
# Test allocation
kubectl apply -f - << EOF
apiVersion: allocation.agones.dev/v1
kind: GameServerAllocation
metadata:
generateName: test-allocation-
spec:
required:
matchLabels:
agones.dev/fleet: test-fleet
EOF
# Verify allocation succeeded
kubectl get gsa -l agones.dev/fleet=test-fleet
# Clean up
kubectl delete fleet test-fleet
Verify metrics
# Check key metrics
kubectl port-forward -n agones-system svc/agones-controller 8080:8080
# GameServer counts
curl -s http://localhost:8080/metrics | grep agones_gameservers_count
# Allocation metrics
curl -s http://localhost:8080/metrics | grep agones_gameserver_allocations
# Controller health
curl -s http://localhost:8080/metrics | grep go_goroutines
Rollback Procedures
If issues occur during or after upgrade:
Rollback with Helm
# List release history
helm history agones -n agones-system
# Rollback to previous version
helm rollback agones -n agones-system
# Or rollback to specific revision
helm rollback agones 5 -n agones-system
# Verify rollback
kubectl get deployment -n agones-system agones-controller \
-o jsonpath='{.spec.template.spec.containers[0].image}'
Manual Rollback
If Helm rollback fails:
# Reinstall previous version
helm uninstall agones -n agones-system
helm install agones agones/agones \
--version < previous-versio n > \
--namespace agones-system \
-f agones-values-backup.yaml
# Restore backed up resources
kubectl apply -f agones-resources-backup.yaml
Rolling back the Agones controller doesn’t automatically rollback GameServer SDK versions. Existing GameServers continue running with their current SDK version.
Version Compatibility
Kubernetes Version Support
Agones maintains compatibility with the latest 3 minor versions of Kubernetes:
Agones Version Kubernetes Versions 1.42.x 1.28, 1.29, 1.30 1.41.x 1.27, 1.28, 1.29 1.40.x 1.26, 1.27, 1.28
Always upgrade Kubernetes before it falls out of Agones support window.
SDK Version Compatibility
SDK clients are forward and backward compatible within major versions:
SDK 1.x works with Agones 1.y (any x and y)
Always safe to use newer SDK with older Agones
Older SDK with newer Agones may lack new features
CRD Compatibility
Custom Resources created with older versions remain compatible:
New optional fields added with defaults
Existing required fields never removed in minor versions
Deprecated fields continue to work with warnings
Upgrading Across Multiple Versions
Skip Minor Versions
You can skip minor versions within the same major version:
# Safe: 1.38.0 -> 1.42.0
helm upgrade agones agones/agones --version 1.42.0 -n agones-system
Major Version Upgrades
For major version upgrades (e.g., 1.x -> 2.x):
Upgrade to latest 1.x version first
Review 2.0 migration guide
Test thoroughly in staging
Plan for potential breaking changes
Upgrade production with rollback plan
Best Practices
Test in Staging Always test upgrades in a non-production environment that mirrors production configuration.
Incremental Rollout Update one Fleet at a time to limit blast radius if issues occur.
Monitor Closely Watch metrics during and after upgrade:
Allocation success rate
GameServer ready count
Controller resource usage
Scheduled Maintenance Perform upgrades during maintenance windows when player traffic is lowest.
Upgrade during off-peak hours
Reduces impact on active players
Easier to observe metrics without load variance
More time to react if issues occur
Keep detailed upgrade logs
# Log upgrade process
{
date
echo "Starting Agones upgrade to 1.42.0"
helm upgrade agones agones/agones --version 1.42.0 -n agones-system
echo "Upgrade completed"
kubectl get pods -n agones-system
date
} 2>&1 | tee agones-upgrade- $( date +%Y%m%d-%H%M%S ) .log
Coordinate with game server deployments
Don’t upgrade Agones during game server rollouts
Update game server SDK versions in separate deployment
Verify game compatibility with new SDK version
Automation
Example upgrade automation script:
#!/bin/bash
set -e
VERSION = "1.42.0"
NAMESPACE = "agones-system"
BACKUP_DIR = "backups/$( date +%Y%m%d-%H%M%S)"
echo "Starting Agones upgrade to ${ VERSION }"
# Backup
mkdir -p "${ BACKUP_DIR }"
helm get values agones -n "${ NAMESPACE }" > "${ BACKUP_DIR }/values.yaml"
kubectl get gameservers,fleets,fleetautoscalers --all-namespaces -o yaml \
> "${ BACKUP_DIR }/resources.yaml"
# Test upgrade
echo "Testing upgrade (dry-run)..."
helm upgrade agones agones/agones \
--version "${ VERSION }" \
--namespace "${ NAMESPACE }" \
--reuse-values \
--dry-run
# Perform upgrade
echo "Performing upgrade..."
helm upgrade agones agones/agones \
--version "${ VERSION }" \
--namespace "${ NAMESPACE }" \
--reuse-values \
--wait \
--timeout 5m
# Validate
echo "Validating upgrade..."
kubectl rollout status deployment/agones-controller -n "${ NAMESPACE }"
kubectl get pods -n "${ NAMESPACE }"
echo "Upgrade completed successfully"
echo "Backup saved to ${ BACKUP_DIR }"
Next Steps
Monitoring Set up monitoring for upgraded components
Best Practices Follow production deployment guidelines