A GameServer is the fundamental building block of Agones. It represents a single dedicated game server instance and manages its lifecycle from creation through allocation to shutdown.
API Version agones.dev/v1Kind GameServerResource Structure apiVersion : agones.dev/v1 kind : GameServer metadata : name : gds-example spec : container : simple-game-server ports : - name : default portPolicy : Dynamic containerPort : 7654 protocol : UDP health : disabled : false initialDelaySeconds : 5 periodSeconds : 5 failureThreshold : 3 sdkServer : logLevel : Info grpcPort : 9357 httpPort : 9358 counters : rooms : count : 1 capacity : 100 lists : players : capacity : 10 template : metadata : labels : myspeciallabel : myspecialvalue spec : containers : - name : simple-game-server image : us-docker.pkg.dev/agones-images/examples/simple-game-server:0.41
Spec Fields The spec field defines the desired configuration for the GameServer.
container Specifies which Pod container is the game server. Only required if there is more than one container defined in the pod template. Example: "simple-game-server"
ports Array of ports that can be exposed via the game server. Each port configuration includes:
Descriptive name of the port.
Beta Feature (PortRanges flag)Port range name from which to select a port when using a Dynamic or Passthrough port policy. Defaults to "default".
Defines the policy for how the HostPort is populated. Options:
Dynamic - System allocates a free hostPort within the configured rangeStatic - User defines the hostPort (requires hostPort field)Passthrough - Dynamically sets containerPort to same value as dynamically selected hostPortNone - Beta Feature (PortPolicyNone flag) - HostPort is ignored, only containerPort is used Name of the container or sidecar container on which to open the port. Defaults to the game server container.
spec.ports[].containerPort
Port being opened on the specified container’s process. Required for Dynamic and Static policies. Cannot be specified with Passthrough policy.
Port exposed on the host for clients to connect to. Required when portPolicy is Static. Cannot be specified with Dynamic or Passthrough policies.
Network protocol being used. Options: UDP, TCP, TCPUDP
health Configures health checking for the running game server.
Show Health Configuration
Whether health checking is disabled. Set to true to disable health checks.
spec.health.initialDelaySeconds
Number of seconds after the container has started before health check is initiated.
spec.health.periodSeconds
Number of seconds between each health check. If the Health() SDK function doesn’t get called at least once every period, the game server is considered unhealthy.
spec.health.failureThreshold
Minimum consecutive failures for the health probe to be considered failed after having succeeded. Minimum value is 1.
scheduling Scheduling strategy for the GameServer pod. Options:
Packed - Aimed at dynamic Kubernetes clusters (cloud providers), bin packs resources onto nodesDistributed - Aimed at static Kubernetes clusters, distributes resources across the entire cluster sdkServer Parameters for the Agones SDK Server sidecar container.
Show SDK Server Configuration
Log level for SDK server (sidecar) logs. Options:
Info - All messages except debugDebug - All messages including debugError - Only error messagesTrace - All messages including detailed tracing Port on which the SDK Server binds the gRPC server to accept incoming connections.
Port on which the SDK Server binds the HTTP gRPC gateway server to accept incoming connections.
template Pod template that will be created for the GameServer. This is a standard Kubernetes PodTemplateSpec.
The template follows the standard Kubernetes pod specification with metadata and spec fields. The pod name and namespace will be overwritten to match the GameServer. Pod metadata including labels and annotations.
Standard Kubernetes pod specification including containers, volumes, etc.
players Alpha Feature (PlayerTracking flag)Configuration for player tracking features.
Show Player Configuration
spec.players.initialCapacity
Initial player capacity for this GameServer.
counters Beta Feature (CountsAndLists flag)Configuration for tracking int64 counter values. Keys must be declared at GameServer creation time and cannot be added later.
Show Counter Configuration
Each counter is a key-value pair where the key is the counter name and the value contains: Initial count value for the counter.
spec.counters[key].capacity
Maximum capacity for the counter. Setting to max(int64) may lead to issues and is not recommended.
lists Beta Feature (CountsAndLists flag)Configuration for tracking lists of values (up to 1000 values per list). Keys must be declared at GameServer creation time and cannot be added later.
Each list is a key-value pair where the key is the list name and the value contains: Maximum capacity for the list. Maximum value is 1000.
Initial values for the list. Can be empty.
eviction Specifies the eviction tolerance of the GameServer.
Show Eviction Configuration
Specifies whether game server supports termination via SIGTERM:
Always - Allow eviction for both Cluster Autoscaler and node drain for upgradesOnUpgrade - Allow eviction for upgrades aloneNever - Pod should run to completion Status Fields The status field reflects the current state of the GameServer.
state Current state of the GameServer. Possible values:
PortAllocation - Dynamically allocating GameServer is being created, port needs allocationCreating - Before the Pod is being createdStarting - Pod is being created but not yet scheduledScheduled - Pod has been scheduled (has a NodeName)RequestReady - GameServer has declared it is readyReady - GameServer is ready to accept connections from game clientsReserved - GameServer is reserved and can be allocated but not removedAllocated - GameServer has been allocated to a sessionShutdown - GameServer has shutdown, everything needs deletionError - Something went wrong, cannot be resolvedUnhealthy - GameServer has failed health checks ports Array of ports with their allocated host ports.
The allocated port number (hostPort for most policies, containerPort for None policy).
address Primary address at which the GameServer can be reached.
addresses Array of addresses at which the GameServer can be reached. Copy of Node.Status.addresses.
Each address contains: Type of address (e.g., InternalIP, ExternalIP, Hostname).
status.addresses[].address
The address value.
nodeName Name of the Kubernetes node hosting this GameServer.
reservedUntil Timestamp until which the GameServer is reserved. Only set when state is Reserved.
players Alpha Feature (PlayerTracking flag)Current player tracking status.
Show Player Status Fields
Current number of players.
List of player IDs currently connected.
counters Beta Feature (CountsAndLists flag)Current counter values and capacities.
Show Counter Status Fields
status.counters[key].count
Current count value.
status.counters[key].capacity
Current maximum capacity.
lists Beta Feature (CountsAndLists flag)Current list values and capacities.
status.lists[key].capacity
Current maximum capacity.
eviction Current eviction configuration (may differ from spec if pod annotations override it).
Lifecycle The GameServer follows this lifecycle:
PortAllocation/Creating - Initial creationStarting - Pod is being createdScheduled - Pod is scheduled to a nodeRequestReady - Game server signals readiness via SDKReady - Available for allocationReserved (optional) - Temporarily reservedAllocated - Assigned to a game sessionShutdown - Terminating
Terminal states (no recovery):
Notes Unlike Fleet and other Agones resources, GameServer does not define status as a subresource. This allows changing multiple aspects of a GameServer in a single atomic operation, which is particularly useful for allocation.
Counter capacity should not be set to max(int64) as this may lead to issues. See GitHub issue #3636 for details. Keys for counters and lists must be declared at GameServer creation time and cannot be dynamically added later.
