Install and configure Agones on Kubernetes

Follow this guide to create a cluster on Google Kubernetes Engine (GKE), Minikube, Amazon Elastic Kubernetes Service (EKS), or Azure Kubernetes Service (AKS), and install Agones.

In this quickstart, we will create a Kubernetes cluster, and populate it with the resource types that power Agones.

When running in production, Agones should be scheduled on a dedicated pool of nodes, distinct from where Game Servers are scheduled for better isolation and resiliency. By default Agones prefers to be scheduled on nodes labeled with and tolerates the node taint If no dedicated nodes are available, Agones will run on regular nodes.

Usage Requirements

Later versions of Kubernetes may work, but this project is tested against 1.12, and is therefore the supported version. Agones will update its support to n-1 version of what is available across all major cloud providers - GKE, EKS and AKS

Setting up a Google Kubernetes Engine (GKE) cluster

Follow these steps to create a cluster and install Agones directly on Google Kubernetes Engine (GKE).

Before you begin

Take the following steps to enable the Kubernetes Engine API:

  1. Visit the Kubernetes Engine page in the Google Cloud Platform Console.
  2. Create or select a project.
  3. Wait for the API and related services to be enabled. This can take several minutes.
  4. Enable billing for your project.
    • If you are not an existing GCP user, you may be able to enroll for a $300 US Free Trial credit.

Choosing a shell

To complete this quickstart, we can use either Google Cloud Shell or a local shell.

Google Cloud Shell is a shell environment for managing resources hosted on Google Cloud Platform (GCP). Cloud Shell comes preinstalled with the gcloud and kubectl command-line tools. gcloud provides the primary command-line interface for GCP, and kubectl provides the command-line interface for running commands against Kubernetes clusters.

If you prefer using your local shell, you must install the gcloud and kubectl command-line tools in your environment.

Cloud shell

To launch Cloud Shell, perform the following steps:

  1. Go to Google Cloud Platform Console
  2. From the top-right corner of the console, click the Activate Google Cloud Shell button: cloud shell
  3. A Cloud Shell session opens inside a frame at the bottom of the console. Use this shell to run gcloud and kubectl commands.
  4. Set a compute zone in your geographical region with the following command. The compute zone will be something like us-west1-a. A full list can be found here.

    gcloud config set compute/zone [COMPUTE_ZONE]

Local shell

To install gcloud and kubectl, perform the following steps:

  1. Install the Google Cloud SDK, which includes the gcloud command-line tool.
  2. Initialize some default configuration by running the following command.

    • When asked Do you want to configure a default Compute Region and Zone? (Y/n)?, enter Y and choose a zone in your geographical region of choice.

      gcloud init
  3. Install the kubectl command-line tool by running the following command:

    gcloud components install kubectl

Creating the cluster

A cluster consists of at least one cluster master machine and multiple worker machines called nodes: Compute Engine virtual machine instances that run the Kubernetes processes necessary to make them part of the cluster.

gcloud container clusters create [CLUSTER_NAME] --cluster-version=1.12 \
  --tags=game-server \
  --scopes=gke-default \
  --num-nodes=4 \

Flag explanations:

  • cluster-version: Agones requires Kubernetes version 1.12.
  • tags: Defines the tags that will be attached to new nodes in the cluster. This is to grant access through ports via the firewall created in the next step.
  • scopes: Defines the Oauth scopes required by the nodes.
  • num-nodes: The number of nodes to be created in each of the cluster’s zones. Default: 4. Depending on the needs of your game, this parameter should be adjusted.
  • machine-type: The type of machine to use for nodes. Default: n1-standard-4. Depending on the needs of your game, you may wish to have smaller or larger machines.

Optional: Create a dedicated node pool for the Agones controllers. If you choose to skip this step, the Agones controllers will share the default node pool with your game servers which is fine for kicking the tires but is not recommended for a production deployment.

gcloud container node-pools create agones-system \
  --cluster=[CLUSTER_NAME] \
  --node-taints \
  --node-labels \

Optional: Create a node pool for Metrics if you want to monitor the Agones system using Prometheus with Grafana or Stackdriver.

gcloud container node-pools create agones-metrics \
  --cluster=[CLUSTER_NAME] \
  --node-taints \
  --node-labels \

Flag explanations:

  • cluster: The name of the cluster in which the node pool is created.
  • node-taints: The Kubernetes taints to automatically apply to nodes in this node pool.
  • node-labels: The Kubernetes labels to automatically apply to nodes in this node pool.
  • num-nodes: The Agones system controllers only require a single node of capacity to run. For faster recovery time in the event of a node failure, you can increase the size to 2.

Finally, let’s tell gcloud that we are speaking with this cluster, and get auth credentials for kubectl to use.

gcloud config set container/cluster [CLUSTER_NAME]
gcloud container clusters get-credentials [CLUSTER_NAME]

Creating the firewall

We need a firewall to allow UDP traffic to nodes tagged as game-server via ports 7000-8000.

gcloud compute firewall-rules create game-server-firewall \
  --allow udp:7000-8000 \
  --target-tags game-server \
  --description "Firewall to allow game server udp traffic"

Setting up a Minikube cluster

This will setup a Minikube cluster, running on an agones profile.

Installing Minikube

First, install Minikube, which may also require you to install a virtualisation solution, such as VirtualBox as well.

Creating an agones profile

Let’s use a minikube profile for agones.

minikube profile agones

Starting Minikube

The following command starts a local minikube cluster via virtualbox - but this can be replaced by a vm-driver of your choice.

minikube start --kubernetes-version v1.12.10 --vm-driver virtualbox

Setting up an Amazon Web Services EKS cluster

Create EKS Cluster

Create your EKS Cluster using the Getting Started Guide.

Possible steps are the following: 1. Create new IAM role for cluster management. 1. Run aws configure to authorize your awscli with proper AWS Access Key ID and AWS Secret Access Key. 1. Create an example cluster:

eksctl create cluster \
--name prod \
--version 1.12 \
--nodegroup-name standard-workers \
--node-type t3.medium \
--nodes 3 \
--nodes-min 3 \
--nodes-max 4 \
--node-ami auto

Note: EKS does not use the normal Kubernetes networking since it is incompatible with Amazon VPC networking.

Allowing UDP Traffic

For Agones to work correctly, we need to allow UDP traffic to pass through to our EKS cluster worker nodes. To achieve this, we must update the workers’ nodepool SG (Security Group) with the proper rule. A simple way to do that is:

  • Login to the AWS Management Console
  • Go to the VPC Dashboard and select Security Groups
  • Find the Security Group for the workers nodepool, which will be named something like eksctl-[cluster-name]-nodegroup-[cluster-name]-workers/SG
  • Select Inbound Rules
  • Edit Rules to add a new Custom UDP Rule with a 7000-8000 port range and an appropriate Source CIDR range ( allows all traffic)

Follow Normal Instructions to Install

Continue to Installing Agones.

Setting up an Azure Kubernetes Service (AKS) Cluster

Follow these steps to create a cluster and install Agones directly on Azure Kubernetes Service (AKS) .

Choosing your shell

You can use either Azure Cloud Shell or install the Azure CLI on your local shell in order to install AKS in your own Azure subscription. Cloud Shell comes preinstalled with az and kubectl utilities whereas you need to install them locally if you want to use your local shell. If you use Windows 10, you can use the WIndows Subsystem for Windows as well.

Creating the AKS cluster

If you are using Azure CLI from your local shell, you need to login to your Azure account by executing the az login command and following the login procedure.

Here are the steps you need to follow to create a new AKS cluster (additional instructions and clarifications are listed here):

# Declare necessary variables, modify them according to your needs
AKS_RESOURCE_GROUP=akstestrg     # Name of the resource group your AKS cluster will be created in
AKS_NAME=akstest     # Name of your AKS cluster
AKS_LOCATION=westeurope     # Azure region in which you'll deploy your AKS cluster

# Create the Resource Group where your AKS resource will be installed
az group create --name $AKS_RESOURCE_GROUP --location $AKS_LOCATION

# Create the AKS cluster - this might take some time. Type 'az aks create -h' to see all available options
# The following command will create a single Node AKS cluster. Node size is Standard A1 v1 and Kubernetes version is 1.11.8. Plus, SSH keys will be generated for you, use --ssh-key-value to provide your values
az aks create --resource-group $AKS_RESOURCE_GROUP --name $AKS_NAME --node-count 1 --generate-ssh-keys --node-vm-size Standard_A4_v2 --kubernetes-version 1.11.8

# Install kubectl
sudo az aks install-cli

# Get credentials for your new AKS cluster
az aks get-credentials --resource-group $AKS_RESOURCE_GROUP --name $AKS_NAME

Alternatively, you can use the Azure Portal to create a new AKS cluster (instructions).

Allowing UDP traffic

For Agones to work correctly, we need to allow UDP traffic to pass through to our AKS cluster. To achieve this, we must update the NSG (Network Security Group) with the proper rule. A simple way to do that is:

  • Login to the Azure Portal
  • Find the resource group where the AKS resources are kept, which should have a name like MC_resourceGroupName_AKSName_westeurope. Alternative, you can type az resource show --namespace Microsoft.ContainerService --resource-type managedClusters -g $AKS_RESOURCE_GROUP -n $AKS_NAME -o json | jq .properties.nodeResourceGroup
  • Find the Network Security Group object, which should have a name like aks-agentpool-********-nsg
  • Select Inbound Security Rules
  • Select Add to create a new Rule with UDP as the protocol and 7000-8000 as the Destination Port Ranges. Pick a proper name and leave everything else at their default values

Alternatively, you can use the following command, after modifying the RESOURCE_GROUP_WITH_AKS_RESOURCES and NSG_NAME values:

az network nsg rule create \
  --nsg-name NSG_NAME \
  --name AgonesUDP \
  --access Allow \
  --protocol Udp \
  --direction Inbound \
  --priority 520 \
  --source-port-range "*" \
  --destination-port-range 7000-8000

Creating and assigning Public IPs to Nodes

Nodes in AKS don’t get a Public IP by default. To assign a Public IP to a Node, find the Resource Group where the AKS resources are installed on the portal (it should have a name like MC_resourceGroupName_AKSName_westeurope). Then, you can follow the instructions here to create a new Public IP and assign it to the Node/VM. For more information on Public IPs for VM NICs, see this document. If you are looking for an automated way to create and assign Public IPs for your AKS Nodes, check this project.

Continue to Installing Agones.

Installing Agones

This will install Agones in your cluster.

Install with YAML

We can install Agones to the cluster using the install.yaml file.

kubectl create namespace agones-system
kubectl apply -f

You can also find the install.yaml in the latest agones-install zip from the releases archive.

Note: Installing Agones with the install.yaml will setup the TLS certificates stored in this repository for securing kubernetes webhooks communication. If you want to generate new certificates or use your own, we recommend using the helm installation.

Install using Helm

Also, we can install Agones using Helm package manager. If you want more details and configuration options see the Helm installation guide for Agones

Confirming Agones started successfully

To confirm Agones is up and running, run the following command:

kubectl describe --namespace agones-system pods

It should describe six pods created in the agones-system namespace, with no error messages or status. All Conditions sections should look like this:

  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True

All this pods should be in a RUNNING state:

kubectl get pods --namespace agones-system

NAME                                 READY   STATUS    RESTARTS   AGE
agones-allocator-5c988b7b8d-cgtbs    1/1     Running   0          8m47s
agones-allocator-5c988b7b8d-hhhr5    1/1     Running   0          8m47s
agones-allocator-5c988b7b8d-pv577    1/1     Running   0          8m47s
agones-controller-7db45966db-56l66   1/1     Running   0          8m44s
agones-ping-84c64f6c9d-bdlzh         1/1     Running   0          8m37s
agones-ping-84c64f6c9d-sjgzz         1/1     Running   0          8m47s

That’s it! This creates the Custom Resource Definitions that power Agones and allows us to define resources of type GameServer.

What’s next

Install Agones using Helm

This chart install the Agones application and defines deployment on a Kubernetes cluster using the Helm package manager.

Deploy GKE/AKS cluster and install Agones using Terraform

This chart install the Agones application and defines deployment on a Kubernetes cluster using the Terraform.

Upgrading Agones and Kubernetes

Strategies and techniques for managing Agones and Kubernetes upgrades in a safe manner.