Terraform Installation

Terraform provides Infrastructure as Code (IaC) to create Kubernetes clusters and install Agones in a single, repeatable workflow.

Overview

Agones provides Terraform modules for:

Cluster Creation: GKE, EKS, and AKS cluster provisioning
Helm Installation: Agones installation via Helm provider
Complete Setup: End-to-end cluster and Agones deployment

Prerequisites

Terraform 1.0.0 or later (installation guide)
Cloud provider CLI configured:
- GKE: gcloud authenticated
- EKS: aws CLI configured
- AKS: az CLI authenticated
Sufficient cloud provider permissions

Terraform Modules

Agones provides the following Terraform modules in the source repository:

install/terraform/modules/
├── gke/              # Google Kubernetes Engine
├── gke-autopilot/   # GKE Autopilot
├── eks/             # Amazon Elastic Kubernetes Service
├── aks/             # Azure Kubernetes Service
└── helm3/           # Helm 3 installation module

Google Kubernetes Engine (GKE)

Complete GKE + Agones Setup

Create Terraform Configuration

Create a new directory and main.tf file:

main.tf

terraform {
  required_version = ">= 1.0.0"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 4.0"
    }
    helm = {
      source  = "hashicorp/helm"
      version = "~> 2.3"
    }
  }
}

variable "project_id" {
  description = "GCP Project ID"
  type        = string
}

# GKE Cluster Module
module "gke_cluster" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/gke"
  
  cluster = {
    project              = var.project_id
    name                 = "agones-cluster"
    location             = "us-west1-c"
    zone                 = "us-west1-c"
    machineType          = "e2-standard-4"
    initialNodeCount     = "4"
    network              = "default"
    subnetwork           = ""
    releaseChannel       = "REGULAR"
    kubernetesVersion    = "1.33"
    enableImageStreaming = true
    autoscale            = false
    workloadIdentity     = true
  }
  
  udpFirewall    = true
  ports          = "7000-8000"
  sourceRanges   = "0.0.0.0/0"
  firewallName   = "game-server-firewall"
  
  enable_agones_metrics_nodepool = true
}

# Helm Module for Agones Installation
module "helm_agones" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/helm3"
  
  depends_on = [module.gke_cluster]
  
  agones_version         = "1.57.0-dev"
  chart                  = "agones"
  host                   = module.gke_cluster.host
  token                  = module.gke_cluster.token
  cluster_ca_certificate = module.gke_cluster.cluster_ca_certificate
  
  image_registry       = "us-docker.pkg.dev/agones-images/release"
  pull_policy         = "IfNotPresent"
  log_level           = "info"
  feature_gates       = "CountsAndLists=true&PortRanges=true"
  
  gameserver_minPort     = "7000"
  gameserver_maxPort     = "8000"
  gameserver_namespaces  = ["default", "game-servers"]
  
  crd_cleanup = true
  udp_expose  = true
}

output "cluster_name" {
  value = module.gke_cluster.cluster_name
}

output "host" {
  value     = module.gke_cluster.host
  sensitive = true
}

Create Variables File

Create terraform.tfvars:

terraform.tfvars

project_id = "your-gcp-project-id"

Initialize Terraform

terraform init

Review Execution Plan

terraform plan

Review the resources that will be created.

Apply Configuration

terraform apply

Type yes to confirm. This process takes 10-15 minutes.

Configure kubectl

gcloud container clusters get-credentials agones-cluster --zone=us-west1-c
kubectl get pods -n agones-system

GKE Module Variables

The GKE module accepts the following variables:

GKE Cluster Configuration

cluster = {
  project              = "your-project-id"      # GCP project ID
  name                 = "agones-cluster"        # Cluster name
  location             = "us-west1-c"            # Cluster location
  zone                 = "us-west1-c"            # Cluster zone (if zonal)
  machineType          = "e2-standard-4"         # Node machine type
  initialNodeCount     = "4"                     # Initial node count
  network              = "default"               # VPC network
  subnetwork           = ""                      # Subnetwork (optional)
  releaseChannel       = "REGULAR"               # UNSPECIFIED, RAPID, REGULAR, STABLE
  kubernetesVersion    = "1.33"                  # Kubernetes version prefix
  windowsInitialNodeCount = "0"                  # Windows node count
  windowsMachineType   = "e2-standard-4"         # Windows node machine type
  enableImageStreaming = true                    # Enable image streaming
  autoscale            = false                   # Enable node autoscaling
  workloadIdentity     = false                   # Enable workload identity
  minNodeCount         = "1"                     # Min nodes (if autoscale)
  maxNodeCount         = "5"                     # Max nodes (if autoscale)
  maintenanceExclusionStartTime = null           # Maintenance exclusion start
  maintenanceExclusionEndTime   = null           # Maintenance exclusion end
}

udpFirewall  = true                              # Create UDP firewall rule
ports        = "7000-8000"                       # Port range
sourceRanges = "0.0.0.0/0"                       # Source CIDR ranges
firewallName = ""                                # Custom firewall name

enable_agones_metrics_nodepool = false           # Create metrics node pool

Amazon Elastic Kubernetes Service (EKS)

Complete EKS + Agones Setup

Create Terraform Configuration

Create main.tf:

main.tf

terraform {
  required_version = ">= 1.0.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 3.0"
    }
    helm = {
      source  = "hashicorp/helm"
      version = "~> 2.3"
    }
  }
}

variable "region" {
  default = "us-west-2"
}

variable "cluster_name" {
  default = "agones-cluster"
}

variable "machine_type" {
  default = "t3.xlarge"
}

variable "node_count" {
  default = 4
}

# EKS Cluster Module
module "eks_cluster" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/eks"
  
  region       = var.region
  cluster_name = var.cluster_name
  machine_type = var.machine_type
  node_count   = var.node_count
}

# Helm Module for Agones Installation
module "helm_agones" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/helm3"
  
  depends_on = [module.eks_cluster]
  
  agones_version         = "1.57.0-dev"
  chart                  = "agones"
  host                   = module.eks_cluster.host
  token                  = module.eks_cluster.token
  cluster_ca_certificate = module.eks_cluster.cluster_ca_certificate
  
  image_registry       = "us-docker.pkg.dev/agones-images/release"
  pull_policy         = "IfNotPresent"
  log_level           = "info"
  feature_gates       = "CountsAndLists=true&PortRanges=true"
  
  gameserver_minPort    = "7000"
  gameserver_maxPort    = "8000"
  gameserver_namespaces = ["default"]
  
  # EKS-specific settings
  set_values = [
    {
      name  = "agones.extensions.hostNetwork"
      type  = "string"
      value = "true"
    },
    {
      name  = "agones.extensions.webhooks.port"
      type  = "string"
      value = "8443"
    }
  ]
}

output "cluster_name" {
  value = module.eks_cluster.cluster_id
}

Initialize and Apply

terraform init
terraform plan
terraform apply

Configure kubectl

aws eks update-kubeconfig --name agones-cluster --region us-west-2
kubectl get pods -n agones-system

EKS Module Variables

EKS Configuration

region       = "us-west-2"     # AWS region
cluster_name = "agones-cluster" # Cluster name
machine_type = "t3.xlarge"      # EC2 instance type
node_count   = 4                # Number of worker nodes

The EKS module automatically creates:

VPC with public subnets
Security groups with game server port rules (7000-8000 UDP)
Three node groups: default, agones-system, agones-metrics

Azure Kubernetes Service (AKS)

Complete AKS + Agones Setup

Create Service Principal

az ad sp create-for-rbac --name agones-sp --role Contributor

Save the appId and password for use in Terraform.

Create Terraform Configuration

Create main.tf:

main.tf

terraform {
  required_version = ">= 1.0.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 2.66"
    }
    helm = {
      source  = "hashicorp/helm"
      version = "~> 2.3"
    }
  }
}

variable "client_id" {
  description = "Azure Service Principal App ID"
}

variable "client_secret" {
  description = "Azure Service Principal Password"
  sensitive   = true
}

# AKS Cluster Module
module "aks_cluster" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/aks"
  
  resource_group_name     = "agones-rg"
  resource_group_location = "East US"
  cluster_name            = "agones-cluster"
  node_count              = 4
  machine_type            = "Standard_D4s_v3"
  disk_size               = 50
  kubernetes_version      = "1.33"
  enable_node_public_ip   = true
  
  client_id     = var.client_id
  client_secret = var.client_secret
}

# Helm Module for Agones Installation
module "helm_agones" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/helm3"
  
  depends_on = [module.aks_cluster]
  
  agones_version         = "1.57.0-dev"
  chart                  = "agones"
  host                   = module.aks_cluster.host
  token                  = module.aks_cluster.token
  cluster_ca_certificate = module.aks_cluster.cluster_ca_certificate
  
  gameserver_minPort    = "7000"
  gameserver_maxPort    = "8000"
  gameserver_namespaces = ["default"]
  
  log_level     = "info"
  feature_gates = "CountsAndLists=true&PortRanges=true"
}

Create Variables File

Create terraform.tfvars:

terraform.tfvars

client_id     = "your-service-principal-app-id"
client_secret = "your-service-principal-password"

Initialize and Apply

terraform init
terraform plan
terraform apply

Configure kubectl

az aks get-credentials --resource-group agones-rg --name agones-cluster
kubectl get pods -n agones-system

AKS Module Variables

AKS Configuration

resource_group_name     = "agones-rg"        # Resource group name
resource_group_location = "East US"          # Azure region
cluster_name            = "agones-cluster"   # Cluster name
node_count              = 4                  # Number of nodes
machine_type            = "Standard_D4s_v3" # VM size
disk_size               = 50                 # OS disk size in GB
kubernetes_version      = "1.33"             # Kubernetes version
enable_node_public_ip   = true               # Enable public IPs on nodes
client_id               = "..."              # Service principal app ID
client_secret           = "..."              # Service principal password

Helm3 Module Configuration

The Helm3 module accepts the following variables:

Helm Configuration

# Required variables
host                   = "..."                # Kubernetes API endpoint
token                  = "..."                # Authentication token
cluster_ca_certificate = "..."                # Cluster CA certificate

# Optional variables
chart           = "agones"                     # Chart name
agones_version  = "1.57.0-dev"                # Agones version
force_update    = "true"                      # Force update on install
values_file     = ""                          # Path to values.yaml

# Image settings
image_registry  = "us-docker.pkg.dev/agones-images/release"
pull_policy     = "IfNotPresent"              # IfNotPresent, Always, Never
always_pull_sidecar = "false"                 # Always pull SDK sidecar
image_pull_secret   = ""                      # Image pull secret name

# Logging and features
log_level       = "info"                      # debug, info, warn, error
feature_gates   = ""                          # Feature gate string

# Game server configuration
gameserver_minPort     = "7000"
gameserver_maxPort     = "8000"
gameserver_namespaces  = ["default"]          # Allowed namespaces

# Service configuration
ping_service_type = "LoadBalancer"            # Ping service type
udp_expose        = "true"                    # Expose UDP ping service
load_balancer_ip  = ""                        # Static IP for allocator

# CRD configuration
crd_cleanup = "true"                          # Cleanup CRDs on delete

# Advanced configuration via set_values
set_values = [
  {
    name  = "agones.controller.replicas"
    type  = "string"
    value = "2"
  }
]

set_list_values = []                          # List-type values
set_sensitive_values = []                     # Sensitive values

Advanced Patterns

Multi-Region Setup

Multi-Region Configuration

module "gke_us" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/gke"
  
  cluster = {
    project  = var.project_id
    name     = "agones-us"
    location = "us-west1-c"
    // ... other config
  }
}

module "gke_eu" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/gke"
  
  cluster = {
    project  = var.project_id
    name     = "agones-eu"
    location = "europe-west1-b"
    // ... other config
  }
}

module "helm_agones_us" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/helm3"
  // ... configure for US cluster
}

module "helm_agones_eu" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/helm3"
  // ... configure for EU cluster
}

Custom Values File

Using Custom Values

module "helm_agones" {
  source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/helm3"
  
  # ... connection settings
  
  values_file = "${path.module}/custom-values.yaml"
}

State Management

Remote State (GCS)

backend.tf

terraform {
  backend "gcs" {
    bucket = "your-terraform-state-bucket"
    prefix = "agones/state"
  }
}

Remote State (S3)

backend.tf

terraform {
  backend "s3" {
    bucket = "your-terraform-state-bucket"
    key    = "agones/terraform.tfstate"
    region = "us-west-2"
  }
}

Destroying Infrastructure

This will destroy your cluster and all game servers. Ensure you have backups if needed.

terraform destroy

To destroy specific resources:

terraform destroy -target=module.helm_agones

Troubleshooting

Debug Terraform Execution

export TF_LOG=DEBUG
terraform apply

Validate Configuration

terraform validate
terraform fmt -check

Import Existing Resources

If you have an existing cluster:

terraform import module.gke_cluster.google_container_cluster.primary projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME

Get Started

Core Concepts

Installation

Game Server Integration

Client SDKs

Operations

Advanced

Terraform Installation

Overview

Prerequisites

Terraform Modules

Google Kubernetes Engine (GKE)

Complete GKE + Agones Setup

GKE Module Variables

Amazon Elastic Kubernetes Service (EKS)

Complete EKS + Agones Setup

EKS Module Variables

Azure Kubernetes Service (AKS)

Complete AKS + Agones Setup

AKS Module Variables

Helm3 Module Configuration

Advanced Patterns

Multi-Region Setup

Custom Values File

State Management

Remote State (GCS)

Remote State (S3)

Destroying Infrastructure

Troubleshooting

Debug Terraform Execution

Validate Configuration

Import Existing Resources

Next Steps

Configuration Reference

Deploy a GameServer

Build docs developers (and LLMs) love

Get Started

Core Concepts

Installation

Game Server Integration

Client SDKs

Operations

Advanced

​Overview

​Prerequisites

​Terraform Modules

​Google Kubernetes Engine (GKE)

​Complete GKE + Agones Setup

​GKE Module Variables

​Amazon Elastic Kubernetes Service (EKS)

​Complete EKS + Agones Setup

​EKS Module Variables

​Azure Kubernetes Service (AKS)

​Complete AKS + Agones Setup

​AKS Module Variables

​Helm3 Module Configuration

​Advanced Patterns

​Multi-Region Setup

​Custom Values File

​State Management

​Remote State (GCS)

​Remote State (S3)

​Destroying Infrastructure

​Troubleshooting

​Debug Terraform Execution

​Validate Configuration

​Import Existing Resources

​Next Steps

Configuration Reference

Deploy a GameServer

Build docs developers (and LLMs) love

Overview

Prerequisites

Terraform Modules

Google Kubernetes Engine (GKE)

Complete GKE + Agones Setup

GKE Module Variables

Amazon Elastic Kubernetes Service (EKS)

Complete EKS + Agones Setup

EKS Module Variables

Azure Kubernetes Service (AKS)

Complete AKS + Agones Setup

AKS Module Variables

Helm3 Module Configuration

Advanced Patterns

Multi-Region Setup

Custom Values File

State Management

Remote State (GCS)

Remote State (S3)

Destroying Infrastructure

Troubleshooting

Debug Terraform Execution

Validate Configuration

Import Existing Resources

Next Steps