GameServerAllocation

A GameServerAllocation is used to allocate a GameServer from a Fleet, GameServerSet, or any set of GameServers that match specified selectors. The allocation process finds a suitable GameServer, marks it as Allocated, and returns its connection information.

API Version

allocation.agones.dev/v1

Kind

GameServerAllocation

Resource Structure

apiVersion: allocation.agones.dev/v1
kind: GameServerAllocation
metadata:
  name: allocation-example
spec:
  selectors:
    - matchLabels:
        agones.dev/fleet: green-fleet
    - matchLabels:
        agones.dev/fleet: blue-fleet
  scheduling: Packed
  metadata:
    labels:
      mode: deathmatch
    annotations:
      map: garden22

Spec Fields

The spec field defines the allocation criteria and actions.

selectors

spec.selectors

array

Ordered list of GameServer label selectors. If the first selector finds no match, the allocation attempts the second selector, and so on. This is useful for fallback scenarios like canary testing.Note: Either use selectors or the deprecated required/preferred fields, not both.

Show Selector Configuration

Each selector can include:

spec.selectors[].matchLabels

map[string]string

Key-value pairs that GameServers must match. All labels must match.

spec.selectors[].matchExpressions

array

List of label selector requirements. Supports operators like In, NotIn, Exists, DoesNotExist.Example: {key: tier, operator: In, values: [cache, backend]}

spec.selectors[].gameServerState

string

default:"Ready"

GameServer state to filter by. Options:

Ready - Select Ready GameServers (default)
Allocated - Select already Allocated GameServers (useful with label/annotation selectors for session re-connection)

spec.selectors[].players

object

Alpha Feature (PlayerAllocationFilter flag)Filter based on player capacity.

spec.selectors[].players.minAvailable

int64

default:"0"

Minimum available player slots (capacity - count). Must be non-negative.

spec.selectors[].players.maxAvailable

int64

default:"0"

Maximum available player slots. 0 means unlimited. Must be non-negative and ≥ minAvailable.

spec.selectors[].counters

map[string]CounterSelector

Beta Feature (CountsAndLists flag)Filter based on counter values and available capacity.

spec.selectors[].counters[key].minCount

int64

default:"0"

Minimum current count value. Must be non-negative.

spec.selectors[].counters[key].maxCount

int64

default:"0"

Maximum current count value. 0 means unlimited (max int64). Must be non-negative.

spec.selectors[].counters[key].minAvailable

int64

default:"0"

Minimum available capacity (capacity - count). Must be non-negative.

spec.selectors[].counters[key].maxAvailable

int64

default:"0"

Maximum available capacity. 0 means unlimited (max int64). Must be non-negative.

spec.selectors[].lists

map[string]ListSelector

Beta Feature (CountsAndLists flag)Filter based on list values and available capacity.

spec.selectors[].lists[key].containsValue

string

Only match GameServers that contain this value in the list. Empty string matches all.

spec.selectors[].lists[key].minAvailable

int64

default:"0"

Minimum available capacity (capacity - value count). Must be non-negative.

spec.selectors[].lists[key].maxAvailable

int64

default:"0"

Maximum available capacity. 0 means unlimited (max int64). Must be non-negative.

required (Deprecated)

spec.required

object

Deprecated: Use selectors instead.GameServer selector from which to choose GameServers. If selectors is set, this field is ignored.

preferred (Deprecated)

spec.preferred

array

Deprecated: Use selectors instead.Ordered list of preferred GameServer selectors. If selectors is set, this field is ignored.

scheduling

spec.scheduling

string

default:"Packed"

Defines how GameServers are organized for selection:

Packed - Aimed at dynamic clusters (cloud), bin packs onto nodes for efficient resource usage
Distributed - Aimed at static clusters, distributes across nodes for fault tolerance

priorities

spec.priorities

array

Beta Feature (CountsAndLists flag)Alters the order in which GameServers are searched. Priority sorting is in descending importance (position 0 checked first).

For Packed: Priority list is the tie-breaker within least-utilized infrastructure
For Distributed: Entire selection is sorted by this priority list

Show Priority Configuration

spec.priorities[].type

string

required

Priority type. Options: Counter, List

spec.priorities[].key

string

required

Name of the Counter or List. No effect if not found on GameServers.

spec.priorities[].order

string

default:"Ascending"

Sort order:

Ascending - Smaller available capacity preferred
Descending - Larger available capacity preferred

metadata

spec.metadata

object

Custom metadata added to the GameServer at allocation time. Useful for passing session-specific data.

Show Metadata Configuration

spec.metadata.labels

map[string]string

Labels to add or update on the allocated GameServer.

spec.metadata.annotations

map[string]string

Annotations to add or update on the allocated GameServer.

counters

spec.counters

map[string]CounterAction

Beta Feature (CountsAndLists flag)Counter actions to perform during allocation.

Show Counter Actions

spec.counters[key].action

string

Action to perform. Options: Increment, DecrementMust be specified if amount is set.

spec.counters[key].amount

int64

Amount to increment or decrement. Must be positive. Must be specified if action is set.

spec.counters[key].capacity

int64

Update the counter’s maximum capacity to this value. Min 0, Max int64. Must be non-negative.

lists

spec.lists

map[string]ListAction

Beta Feature (CountsAndLists flag)List actions to perform during allocation.

Show List Actions

spec.lists[key].addValues

array of strings

Values to append to the list. Duplicate values are ignored.

spec.lists[key].deleteValues

array of strings

Values to remove from the list. Non-existent values are ignored.

spec.lists[key].capacity

int64

Update the list’s maximum capacity. Min 0, Max 1000. Must be non-negative.

multiClusterSetting

spec.multiClusterSetting

object

Configuration for multi-cluster allocation. If specified, allocation can span multiple clusters.

Show Multi-Cluster Configuration

spec.multiClusterSetting.enabled

boolean

default:"false"

Whether multi-cluster allocation is enabled.

spec.multiClusterSetting.policySelector

object

Label selector for choosing which multi-cluster policies to apply.

Status Fields

The status field contains the allocation result.

state

status.state

string

Allocation state. Possible values:

Allocated - Allocation successful
UnAllocated - No suitable GameServer found
Contention - Allocation failed due to race condition/contention

gameServerName

status.gameServerName

string

Name of the allocated GameServer. Empty if allocation failed.

ports

status.ports

array

Array of ports exposed by the allocated GameServer.

Show Port Fields

status.ports[].name

string

Port name.

status.ports[].port

int32

Port number to connect to.

address

status.address

string

Primary IP address or hostname to connect to the GameServer.

addresses

status.addresses

array

All available addresses for the GameServer (internal IP, external IP, hostname).

Show Address Fields

status.addresses[].type

string

Address type (e.g., InternalIP, ExternalIP, Hostname).

status.addresses[].address

string

Address value.

nodeName

status.nodeName

string

Kubernetes node hosting the allocated GameServer.

source

status.source

string

Source of the allocation:

local - Allocated from local cluster
<endpoint> - Allocated from remote cluster (endpoint of remote agones-allocator)

metadata

status.metadata

object

Metadata from the allocated GameServer at allocation time.

Show Metadata Fields

status.metadata.labels

map[string]string

Labels on the allocated GameServer.

status.metadata.annotations

map[string]string

Annotations on the allocated GameServer.

counters

status.counters

map[string]CounterStatus

Beta Feature (CountsAndLists flag)Counter values from the allocated GameServer after allocation actions.

Show Counter Status

status.counters[key].count

int64

Current count value.

status.counters[key].capacity

int64

Current capacity value.

lists

status.lists

map[string]ListStatus

Beta Feature (CountsAndLists flag)List values from the allocated GameServer after allocation actions.

Show List Status

status.lists[key].capacity

int64

Current capacity value.

status.lists[key].values

array of strings

Current list values.

Allocation Process

The allocation process follows these steps:

Selector Evaluation: Iterate through selectors in order until a match is found
Filtering: Apply all selector criteria (labels, state, counters, lists, players)
Sorting: Sort matching GameServers by:
- Scheduling strategy (Packed or Distributed)
- Priorities (if specified)
- Default tie-breakers
Selection: Choose the first GameServer from sorted list
State Update: Atomically update GameServer to Allocated state
Metadata Application: Apply labels/annotations from spec.metadata
Counter/List Actions: Perform counter/list operations
Response: Return GameServer connection details in status

Contention Handling

If multiple allocations target the same GameServer simultaneously:

Only one succeeds (winner of the race condition)
Others receive state: Contention
Client should retry the allocation

Selector Fallback

With multiple selectors:

selectors:
  - matchLabels:
      version: v2  # Try v2 first (canary)
  - matchLabels:
      version: v1  # Fall back to v1 (stable)

Allocation attempts v2, falls back to v1 if no v2 GameServers available.

Use Cases

Basic Fleet Allocation

Allocate any Ready GameServer from a Fleet:

selectors:
  - matchLabels:
      agones.dev/fleet: main-fleet

Canary Deployments

Try new version first, fall back to stable:

selectors:
  - matchLabels:
      version: canary
  - matchLabels:
      version: stable

Session Management

Allocate GameServer with room for specific player count:

selectors:
  - matchLabels:
      game: shooter
    counters:
      players:
        minAvailable: 4  # Need room for 4 players
counters:
  players:
    action: Increment
    amount: 4  # Reserve 4 slots

Re-connection

Find already allocated GameServer for reconnection:

selectors:
  - matchLabels:
      session-id: abc123
    gameServerState: Allocated

Geographic Distribution

Allocate from preferred region with fallback:

selectors:
  - matchLabels:
      region: us-west
  - matchLabels:
      region: us-east
  - matchLabels:
      region: eu-central

Notes

GameServerAllocation is a create-only resource. Each allocation creates a new GameServerAllocation object in the cluster that persists as a record of the allocation.

Counter and list actions are performed after allocation succeeds. If actions fail, the GameServer remains allocated but actions may not be applied.

The allocation process is atomic at the GameServer state transition level. However, metadata updates and counter/list actions happen in separate operations.

When using gameServerState: Allocated for re-connection scenarios, ensure proper label/annotation selectors to avoid allocating wrong sessions.

Multi-cluster allocation requires additional setup with agones-allocator service and AllocationEndpoint/GameServerAllocationPolicy resources. See multi-cluster documentation for details.

Custom Resources

Allocation API

SDK API

GameServerAllocation

API Version

Kind

Resource Structure

Spec Fields

selectors

required (Deprecated)

preferred (Deprecated)

scheduling

priorities

metadata

counters

lists

multiClusterSetting

Status Fields

state

gameServerName

ports

address

addresses

nodeName

source

metadata

counters

lists

Allocation Process

Contention Handling

Selector Fallback

Use Cases

Basic Fleet Allocation

Canary Deployments

Session Management

Re-connection

Geographic Distribution

Notes

Build docs developers (and LLMs) love

Custom Resources

Allocation API

SDK API

​API Version

​Kind

​Resource Structure

​Spec Fields

​selectors

​required (Deprecated)

​preferred (Deprecated)

​scheduling

​priorities

​metadata

​counters

​lists

​multiClusterSetting

​Status Fields

​state

​gameServerName

​ports

​address

​addresses

​nodeName

​source

​metadata

​counters

​lists

​Allocation Process

​Contention Handling

​Selector Fallback

​Use Cases

​Basic Fleet Allocation

​Canary Deployments

​Session Management

​Re-connection

​Geographic Distribution

​Notes

Build docs developers (and LLMs) love

API Version

Kind

Resource Structure

Spec Fields

selectors

required (Deprecated)

preferred (Deprecated)

scheduling

priorities

metadata

counters

lists

multiClusterSetting

Status Fields

state

gameServerName

ports

address

addresses

nodeName

source

metadata

counters

lists

Allocation Process

Contention Handling

Selector Fallback

Use Cases

Basic Fleet Allocation

Canary Deployments

Session Management

Re-connection

Geographic Distribution

Notes