GameServerSet

A GameServerSet is a set of GameServers with a shared template. It manages the creation and lifecycle of identical GameServer replicas, similar to how Kubernetes ReplicaSets manage Pods. GameServerSets are typically created and managed by Fleets, but can also be created directly.

API Version

agones.dev/v1

Kind

GameServerSet

Resource Structure

apiVersion: agones.dev/v1
kind: GameServerSet
metadata:
  name: gameserverset-example
spec:
  replicas: 5
  scheduling: Packed
  allocationOverflow:
    labels:
      overflow: "true"
  priorities:
    - type: Counter
      key: sessions
      order: Descending
  template:
    metadata:
      labels:
        game: example
        version: "1.0"
    spec:
      ports:
        - name: default
          portPolicy: Dynamic
          containerPort: 7654
      health:
        initialDelaySeconds: 5
        periodSeconds: 5
      counters:
        sessions:
          count: 0
          capacity: 100
      template:
        spec:
          containers:
            - name: 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 GameServerSet.

replicas

spec.replicas

int32

required

Number of GameServers that should be in this set. This is the desired replica count that the GameServerSet controller will maintain.

scheduling

spec.scheduling

string

default:"Packed"

Scheduling strategy that determines how GameServers are distributed across the cluster:

Packed - Bin packs GameServers onto nodes to maximize resource efficiency (ideal for cloud/dynamic clusters)
Distributed - Spreads GameServers across nodes for better fault tolerance (ideal for static clusters)

allocationOverflow

spec.allocationOverflow

object

Labels and annotations to apply to GameServers when the number of Allocated GameServers drops below the desired replicas. This helps identify and manage GameServers that should be preserved despite being below the replica count.

Show Allocation Overflow Configuration

spec.allocationOverflow.labels

map[string]string

Labels to be applied to GameServers in allocation overflow state.

spec.allocationOverflow.annotations

map[string]string

Annotations to be applied to GameServers in allocation overflow state.

priorities

spec.priorities

array

Beta Feature (CountsAndLists flag)Configuration that alters scale down logic based on available capacity. Priority sorting is in descending importance (position 0 is checked first).

For Packed strategy: Priority list acts as a tie-breaker within nodes
For Distributed strategy: Entire set is sorted by this priority list for deletion order

Show Priority Configuration

Each priority entry contains:

spec.priorities[].type

string

required

Type of priority. 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 - Lower available capacity preferred (removed first)
Descending - Higher available capacity preferred (removed first)

template

spec.template

object

required

GameServer template to apply for this GameServerSet. All GameServers created by this set will use this template.

Show Template Structure

The template is a GameServerTemplateSpec containing:

spec.template.metadata

object

Metadata including labels and annotations that will be applied to each GameServer.

spec.template.spec

object

required

Complete GameServer specification. See GameServer for full reference.

Status Fields

The status field reflects the current state of the GameServerSet.

replicas

status.replicas

int32

Total number of current GameServer replicas in this set.

readyReplicas

status.readyReplicas

int32

Number of GameServer replicas that are in the Ready state and available for allocation.

reservedReplicas

status.reservedReplicas

int32

Number of GameServer replicas that are in the Reserved state. Reserved GameServers can be allocated but won’t be scaled down.

allocatedReplicas

status.allocatedReplicas

int32

Number of GameServer replicas that are in the Allocated state (actively hosting game sessions).

shutdownReplicas

status.shutdownReplicas

int32

Number of GameServer replicas that are in the Shutdown state (being terminated).

players

status.players

object

Alpha Feature (PlayerTracking flag)Current total player capacity and count aggregated across this GameServerSet.

Show Aggregated Player Status

status.players.count

int64

Total player count across all GameServers in this set.

status.players.capacity

int64

Total player capacity across all GameServers in this set.

counters

status.counters

map[string]AggregatedCounterStatus

Beta Feature (CountsAndLists flag)Aggregated counter capacity and count for this GameServerSet.

Show Aggregated Counter Status

status.counters[key].allocatedCount

int64

Count from allocated GameServers only.

status.counters[key].allocatedCapacity

int64

Capacity from allocated GameServers only.

status.counters[key].count

int64

Total count across all GameServers.

status.counters[key].capacity

int64

Total capacity across all GameServers.

lists

status.lists

map[string]AggregatedListStatus

Beta Feature (CountsAndLists flag)Aggregated list capacity and count for this GameServerSet.

Show Aggregated List Status

status.lists[key].allocatedCount

int64

Value count from allocated GameServers only.

status.lists[key].allocatedCapacity

int64

Capacity from allocated GameServers only.

status.lists[key].count

int64

Total value count across all GameServers.

status.lists[key].capacity

int64

Total capacity across all GameServers.

Immutability

The GameServerSet template is immutable after creation. Once a GameServerSet is created, you cannot modify the spec.template field. This is validated during updates and any attempt to change the template will be rejected. If you need to change the GameServer specification:

Create a new GameServerSet with the updated template
Scale up the new GameServerSet
Scale down the old GameServerSet
Delete the old GameServerSet when no longer needed

This pattern is automatically handled by Fleets during rolling updates.

Relationship to Fleets and GameServers

GameServerSets sit between Fleets and GameServers in the Agones resource hierarchy:

Fleet creates and manages one or more GameServerSets
GameServerSet creates and manages individual GameServers
Each GameServer is owned by exactly one GameServerSet

Labels are automatically applied to track relationships:

GameServers have label agones.dev/gameserverset: <gameserverset-name>
GameServers created by a Fleet also have agones.dev/fleet: <fleet-name>

Scale Subresource

GameServerSet supports the Kubernetes scale subresource, allowing you to scale the set using:

kubectl scale gameserverset <name> --replicas=10

This provides a convenient way to adjust replica counts without editing the full specification.

Common Use Cases

Direct Management

While typically created by Fleets, you can create GameServerSets directly when:

You want simple scaling without rolling update capabilities
You need multiple independent sets of GameServers with different configurations
You’re implementing custom fleet management logic

Testing and Development

GameServerSets are useful for:

Testing GameServer configurations before deploying a Fleet
Running smaller sets of game servers for development
Isolating different game server versions or configurations

Allocation Overflow Management

Use allocationOverflow to:

Mark GameServers that exceed desired capacity
Apply special handling for overflow instances
Track and manage surplus allocated GameServers

Notes

GameServerSet names are used as labels on GameServers, so they must not exceed 63 characters (Kubernetes label value maximum).

The GameServerSet status is defined as a subresource, similar to Kubernetes ReplicaSets. Status updates don’t change the resource version of the main object.

The template field is immutable after creation. Plan your GameServer configuration carefully or use Fleets for easier updates.

Allocated GameServers are never automatically deleted by the GameServerSet controller, even if replicas is reduced to 0. They must be explicitly shut down via the SDK or deleted manually.

Custom Resources

Allocation API

SDK API

API Version

Kind

Resource Structure

Spec Fields

replicas

scheduling

allocationOverflow

priorities

template

Status Fields

replicas

readyReplicas

reservedReplicas

allocatedReplicas

shutdownReplicas

players

counters

lists

Immutability

Relationship to Fleets and GameServers

Scale Subresource

Common Use Cases

Direct Management

Testing and Development

Allocation Overflow Management

Notes

Build docs developers (and LLMs) love

Custom Resources

Allocation API

SDK API

​API Version

​Kind

​Resource Structure

​Spec Fields

​replicas

​scheduling

​allocationOverflow

​priorities

​template

​Status Fields

​replicas

​readyReplicas

​reservedReplicas

​allocatedReplicas

​shutdownReplicas

​players

​counters

​lists

​Immutability

​Relationship to Fleets and GameServers

​Scale Subresource

​Common Use Cases

​Direct Management

​Testing and Development

​Allocation Overflow Management

​Notes

Build docs developers (and LLMs) love

API Version

Kind

Resource Structure

Spec Fields

replicas

scheduling

allocationOverflow

priorities

template

Status Fields

replicas

readyReplicas

reservedReplicas

allocatedReplicas

shutdownReplicas

players

counters

lists

Immutability

Relationship to Fleets and GameServers

Scale Subresource

Common Use Cases

Direct Management

Testing and Development

Allocation Overflow Management

Notes