Agones: GameServerAllocation

Hello, I'm @sugar235711.
This is the article for Day 4 of the "Reading All the Source Code of OSS I'm Interested in by Myself and Doing Something Advent Calendar 2025".

https://qiita.com/advent-calendar/2025/sugarcat

• General Overview
• GameServer Edition
• Fleet Edition
• GameServerAllocation Edition ← You are here
• FleetAutoscaler Edition

About GameServerAllocation

GameServerAllocation is a Custom Resource for dynamically allocating GameServers.
For example, it is used in combination with matchmaking systems such as OpenMatch to allocate a GameServer when players are matched.

• Automatically selects and allocates an available GameServer when a player connects to the game server after matchmaking
• Transitions the selected GameServer from the Ready state to the Allocated state
• Returns detailed information of the allocated GameServer (address, port, etc.) to the client

About Allocation Methods

In Agones, allocation can be performed using either GameServerAllocation or the Allocator Service.
The Allocator Service is provided as a service accessible from the outside via a LoadBalancer and is also available in multi-cluster environments.

https://agones.dev/site/docs/reference/gameserverallocation/
https://agones.dev/site/docs/advanced/allocator-service/

Internally, it utilizes the logic of GameServerAllocation, so we will look at the implementation of GameServerAllocation here.

Allocation Flow and Scheduling Policies

GameServer selection begins by searching for a list of candidate GameServers based on selector conditions (labels, state, etc.).
After selecting a GameServer, one of two scheduling methods is applied.

Packed

• A method that consolidates GameServers on as few nodes as possible.

Distributed

• A method that distributes GameServers across the entire cluster.

Regarding allocation, an in-memory gameServerCache is used, and sorting for allocation is performed.

//
//nolint:govet // ignore fieldalignment, singleton embedded in AllocationCache
type gameServerCache struct {
	mu    sync.RWMutex
	cache map[string]*agonesv1.GameServer
}

https://github.com/googleforgames/agones/blob/3b94c58f3819456ba259195e9785d87cf3392d9b/pkg/gameserverallocations/allocation_cache.go#L169-L238

if Scheduling == Packed:
    → ListSortedGameServers()  // Bin Packing sort
else if Scheduling == Distributed && Priorities set:
    → ListSortedGameServersPriorities()  // Priorities sort
else:
    → ListSortedGameServers() → rand.Shuffle()  // Random

Allocation is performed using sort functions corresponding to each scheduling policy.
https://github.com/googleforgames/agones/blob/3b94c58f3819456ba259195e9785d87cf3392d9b/pkg/gameserverallocations/find.go#L43-L68

High Density GameServers

By running multiple simultaneous game sessions in a single GameServer process, resources can be utilized efficiently.
Agones provides two approaches to this problem.

https://agones.dev/site/docs/integration-patterns/high-density-gameservers/

Session/Room Counters

This is a method to track the number of available sessions on a GameServer using the Counter feature.
Counter values can be updated both at the time of allocation and via the SDK, allowing Agones to track the number of sessions.

https://github.com/googleforgames/agones/blob/3b94c58f3819456ba259195e9785d87cf3392d9b/pkg/apis/allocation/v1/gameserverallocation.go#L295-L318

apiVersion: allocation.agones.dev/v1
kind: GameServerAllocation
spec:
  scheduling: Packed
  priorities:
    - type: Counter
      key: rooms
      order: Ascending # Prioritize "rooms" closest to being full
  selectors:
    # Search for GameServers already in the Allocated state that can accept one or more sessions
    - gameServerState: Allocated
      matchLabels:
        agones.dev/fleet: simple-game-server
      counters:
        rooms:
          minAvailable: 1
    # If not found, allocate a GameServer in the Ready state
    - gameServerState: Ready
      matchLabels:
        agones.dev/fleet: simple-game-server
      counters:
        rooms:
          minAvailable: 1
  counters:
    rooms:
      action: Increment
      amount: 1 # Increase the room count by 1 upon allocation

First, it searches for a GameServer that is already in the Allocated state and has enough capacity for "rooms". If none is found, it allocates a GameServer in the Ready state.
Upon allocation, it increments the rooms Counter by 1, and when a session ends, the GameServer process decrements the rooms Counter via the SDK to restore capacity.

Summary

We have confirmed the basic behavior of Allocation.
Tomorrow, we will look at FleetAutoscaler.