Skip to main content
This page provides a comprehensive reference for all configuration options available when installing Agones.

​
Configuration Overview

Agones configuration is organized into several major sections:

System

Core system settings like RBAC, CRDs, and cloud provider

Components

Controller, Extensions, Allocator, and Ping service

Game Servers

Port ranges, namespaces, and SDK settings

​
System Configuration

​
Global Settings

System Configuration
agones:
  # Feature gates (comma or ampersand separated)
  featureGates: "CountsAndLists=true&PortRanges=true&PlayerTracking=false"
  
  # Cloud product detection (auto, gke, eks, aks, generic)
  cloudProduct: "auto"
  
  # Require dedicated nodes with taints
  requireDedicatedNodes: false
  
  # RBAC configuration
  rbacEnabled: true
  registerServiceAccounts: true
  registerWebhooks: true
  registerApiService: true
  
  # Priority class
  createPriorityClass: true
  priorityClassName: agones-system

​
Custom Resource Definitions

CRD Configuration
agones:
  crds:
    install: true              # Install CRDs during Helm install
    cleanupOnDelete: true      # Delete CRDs on Helm uninstall
    cleanupJobTTL: 60          # TTL for cleanup job in seconds
Important: Setting cleanupOnDelete: true will delete all GameServers, Fleets, and FleetAutoscalers when uninstalling Agones. In production, consider setting this to false and managing CRDs separately.

​
Service Accounts

Service Account Configuration
agones:
  serviceaccount:
    allocator:
      name: agones-allocator
      annotations: {}
      labels: {}
    controller:
      name: agones-controller
      annotations: {}
    sdk:
      name: agones-sdk
      annotations: {}
    processor:
      name: agones-processor
      annotations: {}
      labels: {}

​
Image Configuration

Image Settings
agones:
  image:
    # Container registry
    registry: us-docker.pkg.dev/agones-images/release
    
    # Version tag
    tag: 1.57.0-dev
    
    # Controller image
    controller:
      name: agones-controller
      pullPolicy: IfNotPresent    # Always, IfNotPresent, Never
    
    # Extensions image
    extensions:
      name: agones-extensions
      pullPolicy: IfNotPresent
    
    # SDK sidecar image
    sdk:
      name: agones-sdk
      cpuRequest: 30m             # CPU request
      cpuLimit: 0                 # 0 = no limit
      memoryRequest: 0            # 0 = no limit
      memoryLimit: 0              # 0 = no limit
      alwaysPull: false           # Always pull SDK image
    
    # Ping service image
    ping:
      name: agones-ping
      pullPolicy: IfNotPresent
    
    # Allocator image
    allocator:
      name: agones-allocator
      pullPolicy: IfNotPresent
    
    # Processor image
    processor:
      name: agones-processor
      pullPolicy: IfNotPresent

​
Controller Configuration

Controller Settings
agones:
  controller:
    # Deployment settings
    replicas: 2
    updateStrategy: {}          # Rolling update strategy
    
    # Logging
    logLevel: info              # debug, info, warn, error
    persistentLogs: true
    persistentLogsSizeLimitMB: 10000
    
    # Performance tuning
    numWorkers: 100                        # Worker goroutines
    apiServerQPS: 400                      # QPS to Kubernetes API
    apiServerQPSBurst: 500                 # Burst QPS
    maxCreationParallelism: 16             # Parallel creations
    maxGameServerCreationsPerBatch: 64    # Max per batch
    maxDeletionParallelism: 64             # Parallel deletions
    maxGameServerDeletionsPerBatch: 64    # Max per batch
    maxPodPendingCount: 5000               # Max pending pods
    allocationBatchWaitTime: 500ms         # Batch wait time
    
    # Resources
    resources: {}
      # requests:
      #   cpu: 500m
      #   memory: 256Mi
      # limits:
      #   cpu: 1000m
      #   memory: 512Mi
    
    # Node placement
    nodeSelector: {}
    labels: {}
    annotations: {}
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"
    topologySpreadConstraints: []
    
    # Pod Disruption Budget
    pdb:
      minAvailable: 1
    
    # Safe to evict annotation
    safeToEvict: false
    
    # TLS configuration
    generateTLS: true
    tlsCert: ""
    tlsKey: ""
    disableSecret: false
    customCertSecretPath: []
    
    # Webhooks
    allocationApiService:
      annotations: {}
      disableCaBundle: false
    validatingWebhook:
      annotations: {}
      disableCaBundle: false
    mutatingWebhook:
      annotations: {}
      disableCaBundle: false
    
    # Health checks
    http:
      port: 8080
    healthCheck:
      initialDelaySeconds: 3
      periodSeconds: 3
      failureThreshold: 3
      timeoutSeconds: 1

​
Extensions Configuration

Extensions Settings
agones:
  extensions:
    # Deployment settings
    replicas: 2
    updateStrategy: {}
    
    # Host networking (required for some CNI plugins on EKS)
    hostNetwork: false
    
    # Logging
    logLevel: info
    persistentLogs: true
    persistentLogsSizeLimitMB: 10000
    
    # Performance
    numWorkers: 100
    apiServerQPS: 400
    apiServerQPSBurst: 500
    allocationBatchWaitTime: 500ms
    
    # Resources
    resources: {}
      # requests:
      #   cpu: 500m
      #   memory: 256Mi
    
    # Node placement
    nodeSelector: {}
    annotations: {}
    labels: {}
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"
    topologySpreadConstraints: []
    
    # Pod Disruption Budget
    pdb:
      minAvailable: 1
    
    # TLS configuration
    generateTLS: true
    tlsCert: ""
    tlsKey: ""
    disableSecret: false
    customCertSecretPath: []
    
    # Webhooks
    allocationApiService:
      annotations: {}
      disableCaBundle: false
    validatingWebhook:
      annotations: {}
      disableCaBundle: false
    mutatingWebhook:
      annotations: {}
      disableCaBundle: false
    
    # Ports
    webhooks:
      port: 8081
    http:
      port: 8080
    
    # Health checks
    healthCheck:
      initialDelaySeconds: 3
      periodSeconds: 3
      failureThreshold: 3
      timeoutSeconds: 1
    readiness:
      initialDelaySeconds: 3
      periodSeconds: 3
      failureThreshold: 3

​
Allocator Configuration

Allocator Settings
agones:
  allocator:
    # Installation
    install: true
    
    # Deployment
    replicas: 3
    updateStrategy: {}
    
    # Logging
    logLevel: info
    
    # Performance
    apiServerQPS: 400
    apiServerQPSBurst: 500
    allocationBatchWaitTime: 500ms
    
    # Multi-cluster allocation timeouts
    remoteAllocationTimeout: 10s
    totalRemoteAllocationTimeout: 30s
    
    # Resources
    resources: {}
      # requests:
      #   cpu: 500m
      #   memory: 256Mi
    
    # Node placement
    annotations: {}
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"
    topologySpreadConstraints: []
    
    # Pod Disruption Budget
    pdb:
      enabled: false
      minAvailable: 1
    
    # Service configuration
    service:
      name: agones-allocator
      serviceType: LoadBalancer    # LoadBalancer, NodePort, ClusterIP
      externalTrafficPolicy: Cluster
      clusterIP: ""
      loadBalancerIP: ""
      loadBalancerSourceRanges: []
      annotations: {}
      ipFamilyPolicy: ""
      ipFamilies: []
      
      # HTTP endpoint
      http:
        enabled: true
        appProtocol: ""
        port: 443
        portName: https
        targetPort: 8443
        nodePort: 0                 # For NodePort service type
        unallocatedStatusCode: 429  # HTTP status for no available servers
      
      # gRPC endpoint
      grpc:
        enabled: true
        appProtocol: ""
        port: 443
        portName: grpc
        targetPort: 8443
        nodePort: 0
    
    # Metrics service
    serviceMetrics:
      name: agones-allocator-metrics-service
      annotations: {}
      http:
        enabled: true
        port: 8080
        portName: http
    
    # TLS configuration
    disableSecretCreation: false
    generateTLS: true
    tlsCert: ""
    tlsKey: ""
    generateClientTLS: true
    clientCAs: {}                   # Client CA certificates
    disableMTLS: false              # Disable mutual TLS
    disableTLS: false               # Disable TLS entirely
    
    # Health checks
    healthCheck:
      initialDelaySeconds: 3
      periodSeconds: 3
      failureThreshold: 3
      timeoutSeconds: 1
    readiness:
      initialDelaySeconds: 3
      periodSeconds: 3
      failureThreshold: 3
    
    # Processor (allocation queue processor)
    processor:
      replicas: 2
      maxBatchSize: 100
      logLevel: info
      leaderElection: {}
      
      resources: {}
      nodeSelector: {}
      annotations: {}
      labels: {}
      tolerations:
      - key: "agones.dev/agones-system"
        operator: "Equal"
        value: "true"
        effect: "NoExecute"
      affinity: {}
      topologySpreadConstraints: []
      
      http:
        port: 8080
      grpc:
        address: agones-processor.agones-system.svc.cluster.local
        port: 9090
      
      readiness:
        initialDelaySeconds: 3
        periodSeconds: 3
        failureThreshold: 3
      healthCheck:
        initialDelaySeconds: 3
        periodSeconds: 3
        failureThreshold: 3
        timeoutSeconds: 1

​
Ping Service Configuration

Ping Service Settings
agones:
  ping:
    # Installation
    install: true
    
    # Deployment
    replicas: 2
    updateStrategy: {}
    
    # Resources
    resources: {}
    
    # Node placement
    nodeSelector: {}
    annotations: {}
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"
    topologySpreadConstraints: []
    
    # Pod Disruption Budget
    pdb:
      enabled: false
      minAvailable: 1
    
    # HTTP service
    http:
      expose: true
      response: ok                  # Health check response
      port: 80
      nodePort: 0
      serviceType: LoadBalancer
      loadBalancerIP: ""
      externalTrafficPolicy: Cluster
      loadBalancerSourceRanges: []
      annotations: {}
      ipFamilyPolicy: ""
      ipFamilies: []
    
    # UDP service
    udp:
      expose: true
      rateLimit: 20                 # Packets per second
      port: 50000
      nodePort: 0
      serviceType: LoadBalancer
      loadBalancerIP: ""
      externalTrafficPolicy: Cluster
      loadBalancerSourceRanges: []
      annotations: {}
      ipFamilyPolicy: ""
      ipFamilies: []
    
    # Health checks
    healthCheck:
      initialDelaySeconds: 3
      periodSeconds: 3
      failureThreshold: 3
      timeoutSeconds: 1

​
SDK Server Configuration

SDK Server Settings
agones:
  sdkServer:
    requestsRateLimit: 500ms      # Rate limit for SDK requests

​
Game Server Configuration

Game Server Settings
gameservers:
  # Namespaces where GameServers can be created
  namespaces:
  - default
  
  # Port allocation range
  minPort: 7000
  maxPort: 8000
  
  # Additional port ranges (requires PortRanges feature gate)
  additionalPortRanges: {}
    # game: [9000, 10000]
    # voice: [20000, 21000]
  
  # Preserve unknown fields in pod template
  podPreserveUnknownFields: false
  
  # CountsAndLists feature configuration
  lists:
    maxItems: 1000                # Max items in a list

​
Port Allocation

The port range minPort to maxPort is allocated from the node’s host ports. Ensure your port range doesn’t conflict with other services and is covered by firewall rules.

​
Namespace Configuration

By default, Agones only monitors the default namespace. To allow GameServers in additional namespaces: 
helm install agones agones/agones \
  --set gameservers.namespaces='{default,game-servers,prod-servers}'

​
Metrics Configuration

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

​
Enabling Prometheus ServiceMonitor

agones:
  metrics:
    serviceMonitor:
      enabled: true
      interval: 30s
      additionalLabels:
        prometheus: kube-prometheus

​
Feature Gates Reference

​
Stable Features (Always Enabled)

FeatureDescription
DisableResyncOnSDKServerOptimizes SDK server performance by disabling periodic resyncs
AutopilotPassthroughPortEnables port passthrough on GKE Autopilot

​
Beta Features (Enabled by Default)

FeatureDescription
CountsAndLists=trueCounters and Lists for GameServers
GKEAutopilotExtendedDurationPods=trueExtended duration pods on GKE Autopilot
PortPolicyNone=trueDisable dynamic port allocation
PortRanges=trueMultiple port ranges per GameServer
ScheduledAutoscaler=trueSchedule-based Fleet autoscaling
RollingUpdateFix=trueImproved rolling update behavior
SidecarContainers=trueAdditional sidecar containers in GameServers
FleetAutoscaleRequestMetaData=trueInclude metadata in autoscaler requests

​
Alpha Features (Disabled by Default)

FeatureDescription
PlayerAllocationFilter=falseFilter allocations by player criteria
PlayerTracking=falseTrack connected players in GameServer
WasmAutoscaler=falseWebAssembly-based autoscaling policies

​
Dev Features (Experimental)

FeatureDescription
ProcessorAllocator=falseProcessor-based allocation queue
Example=falseExample feature for testing

​
Setting Feature Gates

Command Line
helm install agones agones/agones \
  --set agones.featureGates="CountsAndLists=true&PortRanges=true&PlayerTracking=true"
values.yaml
agones:
  featureGates: "CountsAndLists=true&PortRanges=true&PlayerTracking=true"

​
Cloud-Specific Settings

​
Google Kubernetes Engine (GKE)

GKE Configuration
agones:
  cloudProduct: "gke"
  requireDedicatedNodes: true
  
  metrics:
    stackdriverEnabled: true
    stackdriverProjectID: "your-project-id"
  
  controller:
    tolerations:
    - key: "agones.dev/agones-system"
      operator: "Equal"
      value: "true"
      effect: "NoExecute"

​
Amazon EKS

EKS Configuration
agones:
  cloudProduct: "eks"
  requireDedicatedNodes: true
  
  extensions:
    hostNetwork: true             # Required for custom CNI
    webhooks:
      port: 8443                  # Non-conflicting port
    http:
      port: 8081
  
  allocator:
    service:
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-type: "nlb"

​
Azure AKS

AKS Configuration
agones:
  cloudProduct: "aks"
  requireDedicatedNodes: true
  
  allocator:
    service:
      serviceType: LoadBalancer

​
Example Configurations

​
Development Environment

values-dev.yaml
agones:
  controller:
    replicas: 1
    logLevel: debug
  extensions:
    replicas: 1
  allocator:
    replicas: 1
  ping:
    replicas: 1
  featureGates: "CountsAndLists=true&PortRanges=true&PlayerTracking=true"

gameservers:
  namespaces:
  - default
  minPort: 7000
  maxPort: 7100

​
Production Environment

values-prod.yaml
agones:
  controller:
    replicas: 3
    logLevel: info
    resources:
      requests:
        cpu: 1000m
        memory: 512Mi
      limits:
        cpu: 2000m
        memory: 1Gi
    pdb:
      minAvailable: 2
  
  extensions:
    replicas: 3
    resources:
      requests:
        cpu: 1000m
        memory: 512Mi
      limits:
        cpu: 2000m
        memory: 1Gi
    pdb:
      minAvailable: 2
  
  allocator:
    replicas: 5
    resources:
      requests:
        cpu: 1000m
        memory: 512Mi
      limits:
        cpu: 2000m
        memory: 1Gi
    pdb:
      enabled: true
      minAvailable: 3
  
  ping:
    replicas: 3
  
  metrics:
    prometheusEnabled: true
    serviceMonitor:
      enabled: true
  
  featureGates: "CountsAndLists=true&PortRanges=true"

gameservers:
  namespaces:
  - default
  - game-servers
  - prod-servers
  minPort: 7000
  maxPort: 8000

​
Next Steps

Deploy Your First GameServer

Create and test a simple game server

Fleet Management

Learn about scaling game servers

Build docs developers (and LLMs) love

Get started for freeTalk to us