Agones Documentation

Agones is a library designed for hosting, running, and scaling dedicated game servers on Kubernetes. It extends Kubernetes with a custom Controller and Custom Resource Definitions (CRDs) to provide native abilities for managing game server processes.

Key capabilities include:

• Defining individual GameServer resources or large Fleets via YAML or the Kubernetes API.
• Managing the lifecycle of GameServer instances, including health checking and connection metadata.
• Fleet autoscaling that integrates with Kubernetes' native cluster autoscaling.
• Exporting game server-specific metrics and dashboards for operational monitoring.

The agones-allocator is an mTLS-based gRPC and REST service used to allocate game servers. It is designed to be accessible from outside the Agones Kubernetes cluster and can scale independently of the Agones controller.

Key use cases include:

• Multi-cluster allocation.
• Creating allocations from outside the Agones Kubernetes cluster.
• Using SSL-based authentication instead of Kubernetes RBAC.
• Preferring gRPC or REST APIs over direct Kubernetes API integration.

Note on Performance: By default, gRPC and REST are served on the same port using an HTTP multi-plexer. If you require high-performance gRPC or a fully compatible gRPC implementation, you should separate the gRPC and REST ports or disable the REST service via Helm configuration.

Agones provides several client SDKs that act as integration points for game servers to communicate with the Agones controller. These SDKs are thin wrappers around gRPC clients or REST API implementations.

Supported SDKs include:

• Unreal Engine
• Unity
• C++
• C#
• Node.js
• Go
• Rust
• Python
• REST

Additionally, third-party libraries and tools may provide support for other languages.

The Agones Rust SDK allows game servers written in Rust to communicate with the Agones controller. This enables game servers to report their state (e.g., Ready, Allocated) and receive lifecycle signals from the Agones orchestrator.

For detailed API references and function descriptions, refer to the official Rust SDK Documentation.

For general information on all Agones Client SDKs, including how to run the SDK locally for development, see the Client SDK Documentation.

GameServers are created via the Kubernetes API (directly or through a Fleet). Their lifecycle and state transitions are managed by three primary components:

• GameServer controller: Allocates ports, launches the Pods backing the game servers, and manages their lifetime.
• Allocation controller: Marks game servers as Allocated to handle active game sessions.
• SDK: Manages health checking and the shutdown of game server sessions.

Agones provides several patterns for integrating external systems (such as matchmakers) with the GameServer lifecycle, specifically covering the stages of starting, allocating, and shutting down game servers.

While the documentation examples primarily use the GameServerAllocation resource for convenience, these integration patterns are also applicable when using the [Allocation Service]({{% ref "/docs/Advanced/allocator-service.md" %}}).

Shulker is a Kubernetes operator that builds on top of Agones GameServer and Fleet primitives. It provides simplified abstractions specifically tailored for orchestrating complex and dynamic Minecraft infrastructure, including game servers and proxies.

Note: Testing Shulker requires a genuine Minecraft account.

The Agones Go SDK provides methods for managing game server lifecycles, configuration, metadata, counters, and lists. Supported areas include:

• Lifecycle: Ready, Health, Reserve, Allocate, and Shutdown.
• Configuration: Accessing GameServer state and using Watch.
• Metadata: Managing server state via SetAnnotation and SetLabel.
• Counters: Managing numeric values with GetCounterCount, SetCounterCount, IncrementCounter, DecrementCounter, SetCounterCapacity, and GetCounterCapacity.
• Lists: Managing collections with AppendListValue, DeleteListValue, SetListCapacity, GetListCapacity, ListContains, GetListLength, and GetListValues.

A GameServerAllocation is a resource used to atomically select and allocate a GameServer from a set of available servers (such as a single Fleet, multiple Fleets, or a self-managed group).

When an allocation is successful, the selected GameServer is moved to the Allocated state. This state indicates the server is active and should not be removed until SDK.Shutdown() is called or it is manually deleted.

Note: For performance reasons, the query cache used for allocations is eventually consistent. While updates are usually near-instant, high Kubernetes control plane load may cause a delay in selectable features appearing in the cache, though the allocation operation itself remains atomic.

A Game Server runs within a Kubernetes Pod that includes specific components for interfacing with Agones:

1. Dedicated Game Server: The actual game process. Game clients connect to this directly or via a proxy (e.g., Quilkin).
2. Client SDK: A thin wrapper used by the game server to communicate via the SDK gRPC protocol.
3. SDK Sidecar (sdk-server): A container in the same Pod that receives requests from the Client SDK and handles Agones business logic, such as health checks and counters/lists.