Skip to main content
Helm is the recommended installation method for Agones, providing a simple, repeatable way to deploy and configure all components.

​
Prerequisites

  • Kubernetes cluster running version 1.33 or later
  • kubectl configured to access your cluster
  • Helm 3.x installed (installation guide)
  • Cluster-admin privileges or equivalent

​
Installation

​
Basic Installation

1

Add Agones Helm Repository

Add the official Agones Helm repository:
helm repo add agones https://agones.dev/chart/stable
helm repo update
Verify the repository was added:
helm search repo agones
2

Install Agones

Install Agones with default settings:
helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --version 1.57.0-dev
Installation typically takes 2-3 minutes. Replace 1.57.0-dev with the specific version you want to install.
3

Verify Installation

Check that all pods are running:
kubectl get pods -n agones-system
Expected output:
NAME                                 READY   STATUS    RESTARTS   AGE
agones-allocator-xxx                 1/1     Running   0          2m
agones-allocator-yyy                 1/1     Running   0          2m
agones-allocator-zzz                 1/1     Running   0          2m
agones-controller-xxx                1/1     Running   0          2m
agones-controller-yyy                1/1     Running   0          2m
agones-extensions-xxx                1/1     Running   0          2m
agones-extensions-yyy                1/1     Running   0          2m
agones-ping-xxx                      1/1     Running   0          2m
agones-ping-yyy                      1/1     Running   0          2m

​
Installation with Custom Values

For production deployments, create a custom values file: 
# Agones configuration
agones:
  # Image configuration
  image:
    registry: us-docker.pkg.dev/agones-images/release
    tag: 1.57.0-dev
    controller:
      pullPolicy: IfNotPresent
  
  # Enable Prometheus metrics
  metrics:
    prometheusEnabled: true
    prometheusServiceDiscovery: true
    serviceMonitor:
      enabled: true
      interval: 30s
  
  # Controller configuration
  controller:
    replicas: 2
    logLevel: info
    numWorkers: 100
    apiServerQPS: 400
    apiServerQPSBurst: 500
    resources:
      requests:
        cpu: 500m
        memory: 256Mi
      limits:
        cpu: 1000m
        memory: 512Mi
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"
  
  # Extensions configuration
  extensions:
    replicas: 2
    logLevel: info
    resources:
      requests:
        cpu: 500m
        memory: 256Mi
      limits:
        cpu: 1000m
        memory: 512Mi
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"
  
  # Allocator configuration
  allocator:
    install: true
    replicas: 3
    logLevel: info
    apiServerQPS: 400
    apiServerQPSBurst: 500
    resources:
      requests:
        cpu: 500m
        memory: 256Mi
      limits:
        cpu: 1000m
        memory: 512Mi
    service:
      serviceType: LoadBalancer
      http:
        enabled: true
        port: 443
      grpc:
        enabled: true
        port: 443
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"
  
  # Ping service configuration
  ping:
    install: true
    replicas: 2
    http:
      expose: true
      port: 80
      serviceType: LoadBalancer
    udp:
      expose: true
      port: 50000
      serviceType: LoadBalancer
  
  # Feature gates
  featureGates: "CountsAndLists=true&PortRanges=true&PlayerTracking=false"

# Game server configuration
gameservers:
  namespaces:
  - default
  - game-servers
  minPort: 7000
  maxPort: 8000
  lists:
    maxItems: 1000
Install with your custom values: 
helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --values values.yaml

​
Configuration Options

​
Image Configuration

agones:
  image:
    registry: us-docker.pkg.dev/agones-images/release  # Image registry
    tag: 1.57.0-dev                                     # Agones version
    controller:
      name: agones-controller
      pullPolicy: IfNotPresent                          # Always, IfNotPresent, Never
    extensions:
      name: agones-extensions
      pullPolicy: IfNotPresent
    sdk:
      name: agones-sdk
      cpuRequest: 30m                                   # SDK sidecar CPU request
      cpuLimit: 0                                       # 0 = no limit
      memoryRequest: 0                                  # 0 = no limit
      memoryLimit: 0                                    # 0 = no limit
      alwaysPull: false                                 # Always pull SDK sidecar
    allocator:
      name: agones-allocator
      pullPolicy: IfNotPresent
    ping:
      name: agones-ping
      pullPolicy: IfNotPresent

​
Controller Configuration

agones:
  controller:
    replicas: 2                                # Number of controller replicas
    logLevel: info                            # debug, info, warn, error
    numWorkers: 100                           # Number of worker goroutines
    apiServerQPS: 400                         # Queries per second to API server
    apiServerQPSBurst: 500                    # Burst QPS to API server
    maxCreationParallelism: 16                # Max parallel GameServer creations
    maxGameServerCreationsPerBatch: 64        # Max GameServers created per batch
    maxDeletionParallelism: 64                # Max parallel GameServer deletions
    maxGameServerDeletionsPerBatch: 64        # Max GameServers deleted per batch
    maxPodPendingCount: 5000                  # Max pods in pending state
    persistentLogs: true                      # Enable persistent logging
    persistentLogsSizeLimitMB: 10000          # Log size limit in MB
    allocationBatchWaitTime: 500ms            # Wait time for batch allocations
    
    resources:
      requests:
        cpu: 500m
        memory: 256Mi
      limits:
        cpu: 1000m
        memory: 512Mi
    
    nodeSelector: {}
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"
    
    healthCheck:
      initialDelaySeconds: 3
      periodSeconds: 3
      failureThreshold: 3
      timeoutSeconds: 1
    
    pdb:
      minAvailable: 1                         # PodDisruptionBudget

​
Allocator Configuration

agones:
  allocator:
    install: true                             # Install allocator
    replicas: 3                               # Number of allocator replicas
    logLevel: info
    apiServerQPS: 400
    apiServerQPSBurst: 500
    
    service:
      name: agones-allocator
      serviceType: LoadBalancer               # LoadBalancer, NodePort, ClusterIP
      loadBalancerIP: ""                      # Static IP (if supported)
      annotations: {}                         # Service annotations
      http:
        enabled: true
        port: 443
        targetPort: 8443
      grpc:
        enabled: true
        port: 443
        targetPort: 8443
    
    # TLS configuration
    generateTLS: true                         # Auto-generate TLS certificates
    tlsCert: ""                               # Custom TLS certificate
    tlsKey: ""                                # Custom TLS key
    generateClientTLS: true                   # Generate client certificates
    disableMTLS: false                        # Disable mutual TLS
    disableTLS: false                         # Disable TLS entirely
    
    # Multi-cluster allocation
    remoteAllocationTimeout: 10s
    totalRemoteAllocationTimeout: 30s
    
    resources:
      requests:
        cpu: 500m
        memory: 256Mi
      limits:
        cpu: 1000m
        memory: 512Mi

​
Game Server Configuration

gameservers:
  namespaces:                                 # Namespaces where GameServers can be created
  - default
  - game-servers
  minPort: 7000                               # Minimum port for dynamic allocation
  maxPort: 8000                               # Maximum port for dynamic allocation
  
  additionalPortRanges: {}                    # Additional named port ranges
    # Requires PortRanges feature gate
    # game: [9000, 10000]
    # voice: [20000, 21000]
  
  podPreserveUnknownFields: false             # Preserve unknown fields in pod spec
  
  lists:
    maxItems: 1000                            # Max items in CountsAndLists feature

​
Metrics and Monitoring

agones:
  metrics:
    prometheusEnabled: true                   # Enable Prometheus metrics
    prometheusServiceDiscovery: true          # Enable service discovery
    
    # Prometheus ServiceMonitor (requires prometheus-operator)
    serviceMonitor:
      enabled: false                          # Enable ServiceMonitor CRD
      interval: 30s                           # Scrape interval
      additionalLabels: {}                    # Additional labels
    
    # Google Cloud Stackdriver (GKE only)
    stackdriverEnabled: false
    stackdriverProjectID: ""
    stackdriverLabels: ""

​
Feature Gates

Enable or disable Agones features: 
agones:
  featureGates: "CountsAndLists=true&PortRanges=true&PlayerTracking=false"
Available feature gates:
Stable features (always enabled):
  • DisableResyncOnSDKServer - Optimize SDK server performance
  • AutopilotPassthroughPort - GKE Autopilot port passthrough

​
RBAC and Service Accounts

agones:
  rbacEnabled: true                           # Enable RBAC
  registerServiceAccounts: true               # Create service accounts
  
  serviceaccount:
    controller:
      name: agones-controller
      annotations: {}
    allocator:
      name: agones-allocator
      annotations: {}
    sdk:
      name: agones-sdk
      annotations: {}

​
Custom Resource Definitions

agones:
  crds:
    install: true                             # Install CRDs
    cleanupOnDelete: true                     # Remove CRDs on uninstall
    cleanupJobTTL: 60                         # Cleanup job TTL in seconds
Setting cleanupOnDelete: true will delete all GameServers, Fleets, and related resources when uninstalling Agones. Use with caution in production.

​
Installation Patterns

​
Development Environment

helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --set agones.controller.logLevel=debug \
  --set agones.allocator.replicas=1 \
  --set agones.controller.replicas=1 \
  --set agones.extensions.replicas=1 \
  --set agones.ping.replicas=1

​
Production Environment

helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --values values-production.yaml \
  --wait \
  --timeout 10m

​
With Monitoring Stack

helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --set agones.metrics.prometheusEnabled=true \
  --set agones.metrics.serviceMonitor.enabled=true \
  --set agones.metrics.serviceMonitor.interval=30s

​
Upgrading Agones

1

Update Helm Repository

helm repo update
2

Check Available Versions

helm search repo agones --versions
3

Review Upgrade Notes

Check the Agones release notes for breaking changes.
4

Upgrade Agones

helm upgrade agones agones/agones \
  --namespace agones-system \
  --version 1.57.0-dev \
  --values values.yaml
5

Verify Upgrade

kubectl get pods -n agones-system
helm list -n agones-system

​
Rollback

If the upgrade fails, rollback to the previous version: 
helm rollback agones -n agones-system

​
Uninstalling Agones

Uninstalling Agones will delete all game servers and related resources if cleanupOnDelete is enabled.
Uninstall Agones
helm uninstall agones --namespace agones-system
Delete Namespace
kubectl delete namespace agones-system

​
Troubleshooting

​
Check Helm Release Status

helm status agones -n agones-system
helm get values agones -n agones-system
helm get manifest agones -n agones-system

​
Debug Installation Failures

helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --debug \
  --dry-run

​
Common Issues

Manually install CRDs:
kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/release-1.57.0/install/helm/agones/templates/crds/
Check node taints and tolerations:
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints
kubectl describe pod <pod-name> -n agones-system
Regenerate TLS certificates:
helm upgrade agones agones/agones \
  --namespace agones-system \
  --set agones.controller.generateTLS=true \
  --set agones.extensions.generateTLS=true

​
Next Steps

Configuration Reference

Complete configuration options reference

Create Your First GameServer

Deploy and test a game server

Build docs developers (and LLMs) love

Get started for freeTalk to us