Service Definition The AllocationService provides game server allocation capabilities through a gRPC interface.
service AllocationService { rpc Allocate ( AllocationRequest ) returns ( AllocationResponse ); }
Allocate Allocates a game server from the available fleet based on the specified criteria.
Request: AllocationRequest The Kubernetes namespace hosting the target fleet of game servers to be allocated.
Configuration for multi-cluster allocation. If specified, multi-cluster policies are applied. Otherwise, allocation happens locally within the cluster.
scheduling
SchedulingStrategy
default: "Packed"
The scheduling strategy for selecting nodes. Available strategies:
Packed (0): Allocates game servers on the least number of nodes to maximize resource efficiencyDistributed (1): Spreads allocations across nodes for load distribution Custom metadata (labels and annotations) to add to the game server at allocation time. Use this to pass session-specific data to the server.
Ordered list of game server label selectors. The allocator tries each selector in order until a match is found. Useful for smoke testing new game server versions or implementing fallback logic. Show GameServerSelector fields
Label key-value pairs that game servers must match.
Filter by game server state:
READY (0): Server is ready for allocationALLOCATED (1): Server is already allocated Filter based on player capacity. Show PlayerSelector fields
Minimum available player slots required.
Maximum available player slots allowed.
counters
map<string, CounterSelector>
[Stage: Beta] [FeatureFlag: CountsAndLists] Filter based on counter values. Show CounterSelector fields
Minimum count value required.
Maximum count value allowed (0 means unlimited).
Minimum available capacity required.
Maximum available capacity allowed (0 means unlimited).
lists
map<string, ListSelector>
[Stage: Beta] [FeatureFlag: CountsAndLists] Filter based on list values. Only match game servers where the list contains this value (empty string ignores this field).
Minimum available capacity in the list.
Maximum available capacity in the list (0 means unlimited).
[Stage: Beta] [FeatureFlag: CountsAndLists] Priority configuration for sorting game servers. Priorities are evaluated in descending order of importance (position 0 is checked first).
For Packed strategy: Acts as a tie-breaker within least-utilized infrastructure
For Distributed strategy: Determines the complete sort order for allocation
The type of resource to prioritize:
Counter (0): Sort by a Counter’s capacityList (1): Sort by a List’s capacity The name of the Counter or List. If not found on a game server, it has no impact on that server’s priority.
Sort order:
Ascending (0): Prefer smaller capacity valuesDescending (1): Prefer larger capacity values counters
map<string, CounterAction>
[Stage: Beta] [FeatureFlag: CountsAndLists] Actions to perform on Counters during allocation. Show CounterAction fields
Action to perform: "Increment" or "Decrement" the Counter’s count. Must also define amount.
The amount to increment or decrement (must be positive).
Update the maximum capacity to this value (range: 0 to int64 max).
[Stage: Beta] [FeatureFlag: CountsAndLists] Actions to perform on Lists during allocation. Values to append to the List. Duplicate values are ignored.
Update the maximum capacity (range: 0 to 1000).
Values to remove from the List. Non-existent values are ignored.
requiredGameServerSelector
GameServerSelector
deprecated
Deprecated : Use gameServerSelectors instead. This field is ignored if gameServerSelectors is set.
preferredGameServerSelectors
GameServerSelector[]
deprecated
Deprecated : Use gameServerSelectors instead. This field is ignored if gameServerSelectors is set.
Deprecated : Use metadata instead. This field is ignored if metadata is set.
Response: AllocationResponse The name of the allocated game server resource.
The network ports exposed by the allocated game server. Show GameServerStatusPort fields
The primary IP address at which the game server can be reached.
addresses
GameServerStatusAddress[]
All addresses at which the game server can be reached (copy of Node.Status.addresses). Show GameServerStatusAddress fields
The address type (e.g., “ExternalIP”, “InternalIP”, “Hostname”).
The name of the Kubernetes node hosting the game server.
The source cluster if multi-cluster allocation was used.
The metadata of the allocated game server. Show GameServerMetadata fields
Labels applied to the game server.
Annotations applied to the game server.
counters
map<string, CounterStatus>
[Beta, CountsAndLists feature flag] Status of Counters on the allocated game server. Show CounterStatus fields
[Beta, CountsAndLists feature flag] Status of Lists on the allocated game server. Current values in the list.
Supporting Types MultiClusterSetting Specifies settings for multi-cluster allocation.
If set to true, multi-cluster allocation is enabled.
Selects which multi-cluster allocation policies to apply. If not specified, all policies are applied. Show LabelSelector fields
Label key-value pairs to match against policies.
Metadata to patch the game server at allocation time.
Labels to add or update on the game server.
Annotations to add or update on the game server.
Example Usage import ( " context " pb " agones.dev/agones/pkg/allocation/go " ) client := pb . NewAllocationServiceClient ( conn ) req := & pb . AllocationRequest { Namespace : "default" , GameServerSelectors : [] * pb . GameServerSelector { { MatchLabels : map [ string ] string { "game" : "my-game" , "version" : "1.0" , }, GameServerState : pb . GameServerSelector_READY , }, }, Scheduling : pb . AllocationRequest_Packed , Metadata : & pb . MetaPatch { Labels : map [ string ] string { "session-id" : "abc123" , }, }, } resp , err := client . Allocate ( context . Background (), req ) if err != nil { // Handle error } // Connect players to resp.Address and resp.Ports
HTTP Gateway The Allocate RPC is also available via HTTP/JSON:
POST /gameserverallocation Content-Type: application/json { "namespace" : "default", "gameServerSelectors" : [ { "matchLabels" : { "game" : "my-game" }, "gameServerState" : "READY" } ], "scheduling" : "Packed" }
