Skip to main content
Agones provides a powerful platform for orchestrating game servers on Kubernetes. To take advantage of Agones’ features like autoscaling, health checking, and allocation, your game server needs to integrate with the Agones SDK.

​
How Integration Works

When your game server runs on Agones, it runs alongside a sidecar container that manages communication with the Agones controller. Your game server code uses the Agones SDK to communicate with this sidecar via gRPC or HTTP.
Agones Sidecar Architecture

​
The Sidecar Pattern

The sidecar container:
  • Runs in the same pod as your game server
  • Listens on localhost:9357 by default (configurable via environment variables)
  • Handles all communication with the Agones control plane
  • Manages health checking and lifecycle state transitions

​
Connection Setup

The SDK automatically connects to the sidecar using environment variables: 
AGONES_SDK_GRPC_HOST=localhost  # Default
AGONES_SDK_GRPC_PORT=9357       # Default
You typically don’t need to set these values manually unless you’re running in a custom configuration.

​
Key Integration Concepts

​
1. Lifecycle Management

Your game server must signal when it’s ready to accept players and when it’s shutting down:
1

Initialize SDK

Create an SDK instance and establish connection to the sidecar
2

Call Ready()

Signal that your server has finished initialization and is ready for allocation
3

Handle Game Sessions

Accept player connections and run your game logic
4

Call Shutdown()

Signal when the server is shutting down gracefully

​
2. Health Checking

Agones needs to know your server is running correctly:
  • Send periodic health pings (typically every 2-5 seconds)
  • If health checks fail, Agones marks the server as Unhealthy
  • Health checking can be configured or disabled in your GameServer spec
See Health Checking for detailed information.

​
3. State Transitions

A GameServer progresses through several states:

GameServer States

  • Scheduled: Pod scheduled but not running
  • RequestReady: Pod running, waiting for Ready() call
  • Ready: Available for allocation
  • Reserved: Temporarily reserved (not allocatable)
  • Allocated: Assigned to a game session
  • Shutdown: Shutting down gracefully
  • Unhealthy: Failed health checks
Your SDK calls trigger these state transitions. Learn more in Lifecycle Management.

​
4. Metadata Management

The SDK allows you to:
  • Set Labels: Add metadata for filtering and organization
  • Set Annotations: Store arbitrary key-value data
  • Get GameServer: Retrieve current configuration and status
  • Watch GameServer: Receive updates when configuration changes

​
Available SDKs

Agones provides official SDKs for multiple languages:

Go

Full-featured SDK with excellent performance

C#

Perfect for Unity and .NET game servers

Node.js

Ideal for JavaScript/TypeScript servers

Rust

Type-safe SDK for Rust game servers

C++

Native SDK for C++ game engines

Unity

Specialized SDK for Unity game engines

Unreal

Plugin for Unreal Engine integration

REST API

Language-agnostic HTTP/REST interface
See SDK Overview for detailed information about each SDK.

​
Integration Patterns

​
Simple Integration

The minimal integration requires just a few SDK calls: 
package main

import (
    "log"
    "time"
    sdk "agones.dev/agones/sdks/go"
)

func main() {
    // Connect to Agones
    s, err := sdk.NewSDK()
    if err != nil {
        log.Fatalf("Could not connect to SDK: %v", err)
    }

    // Start health checking
    go func() {
        for {
            err := s.Health()
            if err != nil {
                log.Printf("Health ping failed: %v", err)
            }
            time.Sleep(2 * time.Second)
        }
    }()

    // Mark server as ready
    err = s.Ready()
    if err != nil {
        log.Fatalf("Could not mark server ready: %v", err)
    }

    // Run your game server...
    log.Println("Game server running")
    
    // When shutting down
    s.Shutdown()
}

​
Advanced Integration

For production deployments, consider:
Monitor configuration changes in real-time:
s.WatchGameServer(func(gs *sdk.GameServer) {
    log.Printf("GameServer updated: %s", gs.Status.State)
    log.Printf("Allocated: %v", gs.ObjectMeta.Annotations["agones.dev/last-allocated"])
})
Return servers to Ready state after sessions:
// After game session ends
err := s.Ready()
if err != nil {
    log.Printf("Could not return to ready: %v", err)
    s.Shutdown()
}
Reserve servers before allocation:
// Reserve for 30 seconds
duration := 30 * time.Second
err := s.Reserve(duration)

​
Testing Locally

You can test SDK integration locally without Kubernetes:
1

Install SDK Server

go install agones.dev/agones/cmd/sdk-server@latest
2

Run SDK Server

sdk-server --local
3

Run Your Game Server

Your game server will connect to the local SDK server
The local SDK server simulates the sidecar behavior for development and testing.

​
Next Steps

Choose an SDK

Select the right SDK for your tech stack

Lifecycle Management

Learn about Ready, Shutdown, and state transitions

Health Checking

Configure health monitoring for your servers

Advanced Features

Explore player tracking, counters, and lists

​
Common Issues

Connection Failures: Ensure your GameServer manifest includes the Agones sidecar container. The SDK cannot connect without it.
Health Check Failures: If your server initialization takes more than 5 seconds, configure spec.health.initialDelaySeconds in your GameServer manifest.

Build docs developers (and LLMs) love

Get started for freeTalk to us