Skip to main content
Agones can be installed on any Kubernetes cluster version 1.27 or later. This guide covers installation methods and configuration options for different environments.

​
Prerequisites

Before installing Agones, ensure you have:
  • Kubernetes cluster running version 1.27 or later
  • kubectl configured with cluster access and sufficient permissions
  • Cluster resources: Minimum 3 nodes with 2 CPU and 4GB RAM per node
  • Port range: UDP/TCP ports 7000-8000 available (configurable)
Agones requires privileged access to manage game server pods and network configuration. Ensure you have cluster-admin or equivalent permissions.

​
Installation Methods

Choose the installation method that best fits your workflow:

Helm

Recommended for most users. Provides easy configuration and upgrades.

Terraform

Infrastructure as Code approach for automated deployments.

YAML

Direct manifest installation for custom workflows.

​
Install with Helm

Helm is the recommended installation method, offering the easiest setup and configuration experience.
1

Add the Agones Helm repository

helm repo add agones https://agones.dev/chart/stable
helm repo update
2

Install Agones

Install Agones with default configuration:
helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace
This installs Agones version 1.57.0-dev from the stable repository.
3

Verify installation

Check that all Agones components are running:
kubectl get pods -n agones-system
You should see:
  • agones-controller (2 replicas)
  • agones-extensions (2 replicas)
  • agones-allocator (3 replicas)
  • agones-ping (2 replicas)

​
Helm Configuration Options

Customize your installation using Helm values: 
helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --set gameservers.minPort=10000 \
  --set gameservers.maxPort=20000

​
Using a values file

For complex configurations, create a values.yaml file:
values.yaml
agones:
  image:
    registry: us-docker.pkg.dev/agones-images/release
    tag: 1.57.0-dev
  
  metrics:
    prometheusEnabled: true
    stackdriverEnabled: false
  
  controller:
    logLevel: info
    replicas: 2
    resources:
      requests:
        cpu: 1
        memory: 256Mi
  
  allocator:
    replicas: 3
    service:
      serviceType: LoadBalancer

gameservers:
  namespaces:
    - default
    - game-servers
  minPort: 7000
  maxPort: 8000
Install with your custom values: 
helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --values values.yaml

​
Common Helm values

ParameterDescriptionDefault
agones.image.tagAgones version to install1.57.0-dev
agones.controller.replicasNumber of controller replicas2
agones.allocator.replicasNumber of allocator replicas3
agones.featureGatesComma-separated feature gates""
gameservers.minPortMinimum game server port7000
gameservers.maxPortMaximum game server port8000
agones.metrics.prometheusEnabledEnable Prometheus metricstrue
For a complete list of configuration options, see the Helm chart values.yaml.

​
Install with Terraform

Terraform modules are available for automated infrastructure provisioning.

​
Terraform + Helm

The helm3 module installs Agones using the Terraform Helm provider:
main.tf
terraform {
  required_version = ">= 1.0.0"
  required_providers {
    helm = {
      version = "~> 2.3"
      source  = "hashicorp/helm"
    }
  }
}

provider "helm" {
  kubernetes {
    host                   = var.kubernetes_host
    token                  = var.kubernetes_token
    cluster_ca_certificate = base64decode(var.cluster_ca_certificate)
  }
}

module "agones" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/helm3"

  agones_version       = "1.57.0-dev"
  host                 = var.kubernetes_host
  token                = var.kubernetes_token
  cluster_ca_certificate = var.cluster_ca_certificate
  
  gameserver_minPort   = 7000
  gameserver_maxPort   = 8000
  
  set_values = [
    {
      name  = "agones.controller.logLevel"
      value = "info"
      type  = "string"
    }
  ]
}
Apply the configuration: 
terraform init
terraform plan
terraform apply

​
Cloud-specific Terraform modules

Agones provides Terraform modules for major cloud providers:

Google Cloud (GKE)

Modules for both standard GKE and GKE Autopilot

AWS (EKS)

EKS cluster provisioning with Agones

Azure (AKS)

AKS cluster setup and Agones installation
These modules are located in install/terraform/modules/ and handle:
  • Kubernetes cluster creation
  • Network configuration
  • Node pool setup
  • Agones installation
For detailed usage, see the respective module documentation:

​
Install with YAML

For direct Kubernetes manifest installation:
1

Download the install manifest

kubectl create namespace agones-system
kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/release-1.57.0/install/yaml/install.yaml
2

Verify installation

kubectl get pods -n agones-system
kubectl get crds | grep agones
YAML installation uses default configuration. For customization, download the manifest, modify it, and apply:
curl -L https://raw.githubusercontent.com/googleforgames/agones/release-1.57.0/install/yaml/install.yaml > agones.yaml
# Edit agones.yaml as needed
kubectl apply -f agones.yaml

​
Post-Installation Configuration

​
Configure game server namespaces

By default, Agones watches the default namespace. To enable additional namespaces: 
helm upgrade agones agones/agones \
  --namespace agones-system \
  --reuse-values \
  --set gameservers.namespaces='{default,game-servers,production}'

​
Configure firewall rules

Ensure your firewall allows traffic on the game server port range: 
gcloud compute firewall-rules create game-server-firewall \
  --allow udp:7000-8000 \
  --target-tags game-server \
  --source-ranges 0.0.0.0/0

​
Enable monitoring

Agones exposes Prometheus metrics by default. To scrape metrics:
prometheus-config.yaml
scrape_configs:
  - job_name: 'agones'
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names:
            - agones-system
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_agones_dev_role]
        action: keep
        regex: (controller|allocator)

​
Upgrading Agones

​
Upgrade with Helm

helm repo update
helm upgrade agones agones/agones \
  --namespace agones-system \
  --reuse-values
Always review the changelog before upgrading. Some versions may include breaking changes.

​
Upgrade with Terraform

Update the agones_version variable and run: 
terraform plan
terraform apply

​
Uninstalling Agones

helm uninstall agones --namespace agones-system
kubectl delete namespace agones-system
Uninstalling Agones will not automatically delete GameServer pods. Delete all GameServers and Fleets before uninstalling:
kubectl delete fleets --all --all-namespaces
kubectl delete gameservers --all --all-namespaces

​
Platform-Specific Guides

For detailed installation instructions on specific platforms:

Google Kubernetes Engine

Install Agones on GKE or GKE Autopilot

Amazon EKS

Install Agones on Amazon EKS

Azure AKS

Install Agones on Azure Kubernetes Service

Local Development

Install Agones on Minikube, kind, or Docker Desktop

​
Troubleshooting

Ensure you have cluster-admin permissions:
kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole=cluster-admin \
  --user=$(gcloud config get-value account)
If using a private registry, configure image pull secrets:
kubectl create secret docker-registry agones-pull-secret \
  --docker-server=your-registry.com \
  --docker-username=your-username \
  --docker-password=your-password \
  --namespace=agones-system

helm upgrade agones agones/agones \
  --namespace agones-system \
  --set agones.image.controller.pullSecret=agones-pull-secret
Check controller logs:
kubectl logs -n agones-system -l app=agones,agones.dev/role=controller
Verify CustomResourceDefinitions are installed:
kubectl get crds | grep agones.dev
If the default port range (7000-8000) conflicts with existing services, change it during installation:
helm install agones agones/agones \
  --namespace agones-system \
  --set gameservers.minPort=10000 \
  --set gameservers.maxPort=20000

​
Next Steps

Quickstart Guide

Deploy your first game server

Configuration Reference

Explore all configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us