Skip to main content
Agones can be installed on your Kubernetes cluster using several methods. Choose the approach that best fits your workflow and requirements.

​
Installation Methods

Helm

Recommended for most usersQuick and simple installation using Helm charts with full configuration options.

Terraform

Infrastructure as CodeAutomated cluster creation and Agones installation with version control.

YAML Manifests

Direct InstallationApply raw Kubernetes manifests for maximum control (advanced users).

Operator

Operator PatternManage Agones lifecycle with a Kubernetes operator (experimental).

​
Quick Start with Helm

The fastest way to get Agones running:
1

Add Helm Repository

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

Install Agones

helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --version 1.57.0-dev
3

Verify Installation

kubectl get pods -n agones-system
You should see all Agones components running:
NAME                                 READY   STATUS    RESTARTS   AGE
agones-allocator-xxx                 1/1     Running   0          60s
agones-allocator-yyy                 1/1     Running   0          60s
agones-allocator-zzz                 1/1     Running   0          60s
agones-controller-xxx                1/1     Running   0          60s
agones-controller-yyy                1/1     Running   0          60s
agones-extensions-xxx                1/1     Running   0          60s
agones-extensions-yyy                1/1     Running   0          60s
agones-ping-xxx                      1/1     Running   0          60s
agones-ping-yyy                      1/1     Running   0          60s

​
Choosing an Installation Method

​
Helm Installation

Best for:
  • Getting started quickly
  • Development and testing environments
  • Teams familiar with Helm
  • Easy upgrades and configuration management
Pros:
  • Simple one-command installation
  • Easy to customize with values files
  • Built-in rollback capabilities
  • Helm hooks for upgrade/cleanup tasks
Cons:
  • Requires Helm 3.x installed
  • Less control over individual resources
Learn more about Helm installation →

​
Terraform Installation

Best for:
  • Production deployments
  • Infrastructure as Code workflows
  • Multi-environment management
  • Automated CI/CD pipelines
Pros:
  • Complete infrastructure automation
  • Version-controlled configuration
  • Creates cluster and installs Agones in one workflow
  • Idempotent and declarative
Cons:
  • Requires Terraform knowledge
  • Additional complexity for simple deployments
  • State management required
Learn more about Terraform installation →

​
YAML Manifests

Best for:
  • Advanced users needing full control
  • Air-gapped or restricted environments
  • Custom resource modifications
  • Understanding Agones internals
Pros:
  • Maximum control and customization
  • No additional tools required (just kubectl)
  • Transparent resource management
Cons:
  • More complex to manage
  • Manual upgrades required
  • No built-in rollback mechanism
Install with YAML
kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/release-1.57.0/install/yaml/install.yaml
YAML manifest installation is recommended only for advanced users. Most users should prefer Helm or Terraform.

​
Installation Components

Regardless of installation method, Agones installs the following components:

​
Custom Resource Definitions (CRDs)

apiVersion: agones.dev/v1
kind: GameServer
metadata:
  name: my-gameserver
spec:
  container: gameserver
  ports:
  - name: default
    containerPort: 7654
    protocol: UDP
  template:
    spec:
      containers:
      - name: gameserver
        image: us-docker.pkg.dev/agones-images/examples/simple-game-server:0.36

​
System Components

The main Agones controller manages GameServer lifecycles, Fleet scaling, and resource reconciliation.Replicas: 2 (high availability)Features:
  • GameServer state management
  • Fleet and GameServerSet orchestration
  • Health checking
  • Port allocation
  • Node selection

​
Namespace Configuration

Agones components are installed in the agones-system namespace by default. Game servers can run in any namespace configured in the installation.
Default Namespace Configuration
gameservers:
  namespaces:
  - default
  minPort: 7000
  maxPort: 8000
To allow game servers in additional namespaces: 
helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --set gameservers.namespaces='{default,game-servers,prod-servers}'

​
Version Compatibility

Agones follows semantic versioning. Always check the compatibility matrix before upgrading.
Agones VersionKubernetes VersionHelm Version
1.57.0-dev1.33+3.0+
1.56.x1.32+3.0+
1.55.x1.31+3.0+

​
Post-Installation Verification

After installation, verify Agones is working correctly:
1

Check Pod Status

kubectl get pods -n agones-system
All pods should be in Running state.
2

Verify CRDs

kubectl get crds | grep agones
You should see:
  • fleetautoscalers.autoscaling.agones.dev
  • fleets.agones.dev
  • gameserverallocationpolicies.multicluster.agones.dev
  • gameservers.agones.dev
  • gameserversets.agones.dev
3

Test with Simple GameServer

Create a test game server:
kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/release-1.57.0/examples/simple-game-server/gameserver.yaml
Check its status:
kubectl get gameserver
It should transition through states: Creating → Starting → Ready
4

Check Allocator Service

kubectl get service agones-allocator -n agones-system
Verify the allocator service has an external IP assigned.

​
Troubleshooting

​
Pods Not Starting

Check pod events for errors: 
kubectl describe pod <pod-name> -n agones-system
Common issues:
  • Insufficient resources on nodes
  • Image pull errors
  • Node taints preventing scheduling

​
CRDs Not Installing

If CRDs fail to install: 
helm install agones agones/agones \
  --namespace agones-system \
  --create-namespace \
  --set agones.crds.install=true \
  --set agones.crds.cleanupOnDelete=true

​
Permission Errors

Ensure your user has cluster-admin privileges: 
kubectl auth can-i '*' '*' --all-namespaces

​
Next Steps

Helm Installation

Detailed Helm installation guide with configuration options

Terraform Installation

Complete Terraform setup for cluster and Agones

Configuration

Explore all configuration options for Agones

Create Your First GameServer

Deploy and test your first game server

Build docs developers (and LLMs) love

Get started for freeTalk to us