Skip to main content
Agones is built as a platform extension for Kubernetes, leveraging the Kubernetes control plane to orchestrate game server workloads. This architecture enables Agones to provide robust, scalable game server hosting while integrating seamlessly with Kubernetes tooling and workflows.

​
Kubernetes Extension Pattern

Agones extends Kubernetes through two primary mechanisms:

Custom Resource Definitions (CRDs)

Define game server resources like GameServer, Fleet, and GameServerAllocation as first-class Kubernetes objects

Custom Controllers

Implement reconciliation loops that manage the lifecycle of game server resources

​
Core Components

Agones consists of several key components that work together to manage game servers:

​
Control Plane Components

The GameServer controller manages individual game server instances. It:
  • Creates and manages Pods for each GameServer
  • Monitors game server health using SDK callbacks
  • Manages port allocation (Dynamic, Static, Passthrough, or None)
  • Handles state transitions through the GameServer lifecycle
  • Injects the Agones SDK sidecar container
Source Location: pkg/gameservers/controller.go
The Fleet controller manages groups of GameServers using a two-level hierarchy:
  • Creates and manages GameServerSets (similar to ReplicaSets)
  • Implements deployment strategies (RollingUpdate, Recreate)
  • Handles scaling operations
  • Aggregates status from underlying GameServerSets
Source Location: pkg/fleets/controller.go
The Allocation controller handles game server assignment:
  • Processes GameServerAllocation requests
  • Implements allocation strategies (Packed, Distributed)
  • Supports multi-cluster allocation
  • Applies label and annotation patches
  • Manages counter and list operations (Beta)
Source Location: pkg/gameserverallocations/controller.go
The FleetAutoscaler controller automatically scales Fleets based on policies:
  • Buffer-based scaling (maintain a ready game server buffer)
  • Webhook-based scaling (custom external logic)
  • Counter-based scaling (track custom metrics)
  • List-based scaling (track capacity metrics)
  • Schedule-based scaling (time-based policies)
Source Location: pkg/fleetautoscalers/controller.go
The Port Allocator manages host port assignment:
  • Maintains a pool of available ports per node
  • Allocates ports for Dynamic and Passthrough policies
  • Supports multiple port ranges (Alpha)
  • Prevents port conflicts
Source Location: pkg/portallocator/portallocator.go

​
SDK Server (Sidecar)

The Agones SDK Server runs as a sidecar container alongside each game server container:
1

Initialization

The SDK Server is automatically injected into the GameServer Pod and starts before the game server container.
2

Health Monitoring

Receives periodic health pings from the game server via SDK calls and reports to the controller.
3

State Management

Handles state transitions initiated by the game server (Ready, Allocated, Shutdown).
4

Metadata Updates

Allows game servers to update labels, annotations, counters, and lists at runtime.
Exposed Ports:
  • gRPC: 9357 (default)
  • HTTP: 9358 (default)
Source Location: pkg/sdkserver/sdkserver.go

​
Custom Resource Definitions

Agones defines several CRDs in the agones.dev API group:
ResourceAPI VersionPurpose
GameServeragones.dev/v1Represents a single game server instance
GameServerSetagones.dev/v1Manages a set of identical GameServers
Fleetagones.dev/v1High-level management of GameServerSets
GameServerAllocationallocation.agones.dev/v1Allocates a GameServer from available pool
FleetAutoscalerautoscaling.agones.dev/v1Automatically scales Fleets

​
Control Flow

​
GameServer Creation Flow

​
Allocation Flow

​
High Availability

Agones controllers are designed for high availability:
Agones controllers use Kubernetes leader election to ensure only one active controller manages each resource type. This prevents conflicting updates while allowing multiple controller replicas for redundancy.
Key HA Features:
  • Leader election for all controllers
  • Work queue-based processing with retries
  • Idempotent reconciliation logic
  • Graceful handling of controller restarts

​
Security Model

​
RBAC and Service Accounts

Agones uses Kubernetes RBAC to control access: 
# Agones controllers require permissions to:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: agones-controller
rules:
  - apiGroups: ["agones.dev"]
    resources: ["gameservers", "fleets", "gameserversets"]
    verbs: ["get", "list", "watch", "update", "patch"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["create", "delete", "get", "list", "watch"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]

​
Game Server Isolation

By default, game server containers have their service account tokens disabled to prevent access to the Kubernetes API: Source: gameserver.go:914-926 
// DisableServiceAccount disables the service account for the gameserver container
func (gs *GameServer) DisableServiceAccount(pod *corev1.Pod) error {
    // gameservers don't get access to the k8s api.
    emptyVol := corev1.Volume{Name: "empty", VolumeSource: corev1.VolumeSource{EmptyDir: &corev1.EmptyDirVolumeSource{}}}
    pod.Spec.Volumes = append(pod.Spec.Volumes, emptyVol)
    mount := corev1.VolumeMount{MountPath: "/var/run/secrets/kubernetes.io/serviceaccount", Name: emptyVol.Name, ReadOnly: true}
    // ...
}

​
Scheduling Strategies

Agones supports two scheduling strategies for placing GameServers across nodes:
Best for: Cloud environments with autoscaling nodesBehavior: Concentrates GameServers on fewer nodes to maximize resource utilization and minimize infrastructure costs.Implementation: Uses pod affinity to prefer nodes already running GameServers.

​
Observability

​
Metrics

Agones exports Prometheus metrics for monitoring:
  • GameServer metrics: State distribution, creation/deletion rates
  • Fleet metrics: Replica counts (ready, allocated, reserved)
  • Allocation metrics: Request rates, latencies, success/failure counts
  • Autoscaler metrics: Scaling decisions, buffer states
Metrics Port: 8080 (default)

​
Events

Agones generates Kubernetes Events for important state changes: 
kubectl get events --field-selector involvedObject.kind=GameServer

​
Next Steps

GameServer Lifecycle

Understand GameServer states and lifecycle management

Fleet Management

Learn about managing groups of GameServers

Allocation System

Explore how to allocate GameServers to players

Autoscaling

Set up automatic scaling for your Fleets

Build docs developers (and LLMs) love

Get started for freeTalk to us