Overview
The Agones Allocation API provides a gRPC service for allocating game servers from your fleet. This API enables matchmakers and game backends to request dedicated game server instances from available capacity, with sophisticated filtering and prioritization options.Service Definition
The Allocation API is defined in theallocation package and provides a single primary operation:
- Allocate: Request allocation of a game server with custom selection criteria
Key Features
Multi-Cluster Support
The Allocation API supports multi-cluster game server allocation, allowing you to manage game servers across multiple Kubernetes clusters. Enable this feature to:- Distribute player load across geographic regions
- Improve latency by allocating servers closer to players
- Implement failover strategies across clusters
Flexible Game Server Selection
Choose game servers based on:- Label matching: Select servers with specific labels
- State filtering: Choose from Ready or Allocated servers
- Player capacity: Filter by available player slots
- Counters and Lists: Use beta features for advanced capacity management
Scheduling Strategies
Two scheduling strategies optimize your infrastructure usage:Packed Strategy
Packed Strategy
Allocates game servers on the least number of nodes, maximizing resource efficiency by filling nodes before moving to new ones. Ideal for cost optimization.
Distributed Strategy
Distributed Strategy
Spreads game server allocations across available nodes to distribute load evenly. Useful for high-availability scenarios and reducing single-node failure impact.
Priority-Based Sorting
For beta CountsAndLists feature users, define custom priority rules to sort game servers before allocation. This enables sophisticated selection logic like:- Preferring servers with specific capacity characteristics
- Implementing custom load balancing strategies
- Prioritizing newer or older servers
Metadata and Actions
Customize allocated game servers by:- Adding labels and annotations at allocation time
- Incrementing or decrementing counter values
- Adding or removing list values
- Updating capacity limits
Protocol
The Allocation API uses:- Protocol: gRPC with Protocol Buffers (proto3)
- Package:
allocation - HTTP Gateway: REST endpoints available via gRPC-Gateway
- Transport: HTTPS for production deployments
Getting Started
To use the Allocation API:- Deploy the Agones allocator service in your cluster
- Configure TLS certificates for secure communication
- Set up authentication using mTLS or other mechanisms
- Create an
AllocationRequestwith your selection criteria - Call the
AllocateRPC method - Receive an
AllocationResponsewith connection details
Common Use Cases
Matchmaking Integration
Integrate with your matchmaking service to allocate dedicated game servers for matched players. The API returns connection information (IP, ports) to share with clients.Session-Based Games
Allocate a fresh game server for each game session, apply session metadata, and track capacity using counters and lists.Multi-Region Deployment
Use multi-cluster allocation policies to direct players to the nearest available game server, reducing latency and improving player experience.Dynamic Scaling
Combine allocation requests with fleet autoscaling to automatically provision capacity based on demand.Next Steps
Allocation Service
Explore the detailed gRPC service definition and RPC methods
SDK Overview
Learn about the Game Server SDK for managing server lifecycle