Skip to main content
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:
  1. Reviewing release notes and breaking changes
  2. Testing in non-production environment
  3. Backing up current configuration
  4. Performing the upgrade
  5. 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

1

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
2

Review release notes

Visit the Agones releases page and review:
  • Breaking changes
  • New features and deprecations
  • Known issues
  • Recommended upgrade path
3

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
4

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

# 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.

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:
1

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
2

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
3

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.
4

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-name> \
  --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
  • 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:
1

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.
2

Update feature gates

helm upgrade agones agones/agones \
  --version 1.42.0 \
  --namespace agones-system \
  --set agones.featureGates="PlayerTracking=true,CountsAndLists=true" \
  --reuse-values
3

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

1

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
2

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
3

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
4

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-version> \
  --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 VersionKubernetes Versions
1.42.x1.28, 1.29, 1.30
1.41.x1.27, 1.28, 1.29
1.40.x1.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):
  1. Upgrade to latest 1.x version first
  2. Review 2.0 migration guide
  3. Test thoroughly in staging
  4. Plan for potential breaking changes
  5. 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.
  • Reduces impact on active players
  • Easier to observe metrics without load variance
  • More time to react if issues occur
# 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
  • 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

Build docs developers (and LLMs) love