Skip to main content
This guide walks you through deploying a simple game server on Agones, from installation to connecting to your first game server instance.

​
Prerequisites

Before you begin, ensure you have:
  • A Kubernetes cluster (1.27+) with at least 3 nodes
  • kubectl configured to access your cluster
  • Sufficient permissions to create namespaces and custom resources
For local development, you can use Minikube, kind, or Docker Desktop.

​
Installation

1

Create the Agones namespace

First, create a dedicated namespace for Agones system components:
kubectl create namespace agones-system
2

Install Agones using Helm

Add the Agones Helm repository and install the latest stable release:
helm repo add agones https://agones.dev/chart/stable
helm repo update
helm install agones --namespace agones-system --create-namespace agones/agones
The installation typically takes 2-3 minutes. Agones will create several deployments including the controller, allocator, and extensions components.
3

Verify the installation

Check that all Agones pods are running:
kubectl get pods -n agones-system
You should see output similar to:
NAME                                 READY   STATUS    RESTARTS   AGE
agones-allocator-xxx                 1/1     Running   0          2m
agones-allocator-yyy                 1/1     Running   0          2m
agones-controller-xxx                1/1     Running   0          2m
agones-controller-yyy                1/1     Running   0          2m
agones-extensions-xxx                1/1     Running   0          2m
agones-extensions-yyy                1/1     Running   0          2m
agones-ping-xxx                      1/1     Running   0          2m
agones-ping-yyy                      1/1     Running   0          2m

​
Deploy Your First GameServer

Now let’s deploy a simple game server to verify everything works.
1

Create a GameServer resource

Create a file named gameserver.yaml with the following content:
gameserver.yaml
apiVersion: agones.dev/v1
kind: GameServer
metadata:
  generateName: simple-game-server-
spec:
  ports:
    - name: default
      portPolicy: Dynamic
      containerPort: 7654
  template:
    spec:
      containers:
        - name: simple-game-server
          image: us-docker.pkg.dev/agones-images/examples/simple-game-server:0.41
          resources:
            requests:
              memory: 64Mi
              cpu: 20m
            limits:
              memory: 64Mi
              cpu: 20m
This defines a simple UDP game server that:
  • Uses dynamic port allocation
  • Listens on container port 7654
  • Includes basic resource requests and limits
2

Apply the GameServer manifest

Deploy the game server to your cluster:
kubectl create -f gameserver.yaml
Agones will automatically:
  • Create a Pod for your game server
  • Inject the Agones SDK sidecar container
  • Allocate a host port and expose it
  • Monitor the game server’s health
3

Check the GameServer status

Watch the GameServer transition through states:
kubectl get gameservers
Output:
NAME                       STATE   ADDRESS         PORT   NODE     AGE
simple-game-server-xxxxx   Ready   203.0.113.42    7234   node-1   30s
The GameServer will progress through these states:
  • Creating → Starting → Scheduled → RequestReady → Ready
The Ready state means the game server is healthy and available for allocation.
4

Get detailed GameServer information

View complete details about your game server:
kubectl describe gameserver simple-game-server-xxxxx
This shows:
  • Assigned IP address and port
  • Current state and state history
  • Pod details and events
  • Health check status

​
Connect to Your GameServer

Let’s test connectivity to the game server using netcat.
1

Retrieve connection details

Get the external IP and port:
kubectl get gameserver simple-game-server-xxxxx -o jsonpath='{.status.address}:{.status.ports[0].port}'
2

Send a test message

Use netcat (or your preferred UDP client) to send a message:
echo "Hello Agones!" | nc -u <IP-ADDRESS> <PORT>
The game server will respond with:
ACK: Hello Agones!
3

Try server commands

The simple game server supports several commands:
# Get the server name
echo "GAMESERVER" | nc -u <IP-ADDRESS> <PORT>

# Allocate the server
echo "ALLOCATE" | nc -u <IP-ADDRESS> <PORT>

# Check allocated status
kubectl get gameserver simple-game-server-xxxxx -o jsonpath='{.status.state}'

​
Deploy a Fleet

For production workloads, you’ll want to manage multiple game servers as a Fleet.
1

Create a Fleet manifest

Create fleet.yaml:
fleet.yaml
apiVersion: agones.dev/v1
kind: Fleet
metadata:
  name: simple-game-server
spec:
  replicas: 2
  template:
    spec:
      ports:
        - name: default
          containerPort: 7654
      template:
        spec:
          containers:
            - name: simple-game-server
              image: us-docker.pkg.dev/agones-images/examples/simple-game-server:0.41
              resources:
                requests:
                  memory: 64Mi
                  cpu: 20m
                limits:
                  memory: 64Mi
                  cpu: 20m
2

Deploy the Fleet

kubectl apply -f fleet.yaml
This creates 2 ready game servers that can be allocated on demand.
3

Monitor the Fleet

Check Fleet status:
kubectl get fleet
Output:
NAME                 SCHEDULING   DESIRED   CURRENT   ALLOCATED   READY   AGE
simple-game-server   Packed       2         2         0           2       1m
View the individual GameServers:
kubectl get gameservers

​
Allocate a GameServer

Allocate a GameServer from your Fleet for a game session.
1

Create an allocation request

Create gameserverallocation.yaml:
gameserverallocation.yaml
apiVersion: allocation.agones.dev/v1
kind: GameServerAllocation
metadata:
  name: simple-allocation
spec:
  selectors:
    - matchLabels:
        agones.dev/fleet: simple-game-server
2

Request an allocation

kubectl create -f gameserverallocation.yaml -o yaml
This will return the allocated GameServer details including its IP and port.
3

Verify allocation

Check that one server is now allocated:
kubectl get fleet simple-game-server
The ALLOCATED column should show 1:
NAME                 SCHEDULING   DESIRED   CURRENT   ALLOCATED   READY   AGE
simple-game-server   Packed       2         2         1           1       5m

​
Clean Up

When you’re done testing: 
kubectl delete gameserver simple-game-server-xxxxx

​
What’s Next?

Installation Guide

Learn about advanced installation options and configuration

GameServer Reference

Explore all GameServer configuration options

Fleet Management

Deep dive into Fleet management and scaling

SDK Integration

Integrate your game server with the Agones SDK

​
Troubleshooting

Check pod events:
kubectl get pods -l agones.dev/role=gameserver
kubectl describe pod <pod-name>
Common causes:
  • Image pull errors
  • Insufficient cluster resources
  • Node scheduling issues
Verify:
  • Firewall rules allow traffic on the allocated port range (default 7000-8000)
  • Load balancer configuration is correct
  • Network policies don’t block traffic
Check port allocation:
kubectl get gameserver <name> -o jsonpath='{.status.ports}'
Check Agones system logs:
kubectl logs -n agones-system -l app=agones
Verify RBAC permissions:
kubectl get clusterrole agones-controller
kubectl get clusterrolebinding agones-controller

Build docs developers (and LLMs) love

Get started for freeTalk to us