Fleet

A Fleet is a set of warm GameServers that are available to be allocated from. Fleets manage the creation and scaling of GameServer resources, similar to how Kubernetes Deployments manage ReplicaSets.

API Version

agones.dev/v1

Kind

Fleet

Resource Structure

apiVersion: agones.dev/v1
kind: Fleet
metadata:
  name: fleet-example
spec:
  replicas: 2
  scheduling: Packed
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
  allocationOverflow:
    labels:
      mykey: myvalue
    annotations:
      otherkey: setthisvalue
  priorities:
    - type: Counter
      key: rooms
      order: Ascending
    - type: List
      key: players
      order: Ascending
  template:
    metadata:
      labels:
        foo: bar
    spec:
      ports:
        - name: default
          portPolicy: Dynamic
          containerPort: 26000
      health:
        initialDelaySeconds: 30
        periodSeconds: 60
      sdkServer:
        logLevel: Info
      counters:
        rooms:
          count: 0
          capacity: 10
      lists:
        players:
          capacity: 100
      template:
        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 Fleet.

replicas

spec.replicas

int32

default:"0"

Number of GameServers to keep Ready or Allocated in this Fleet. This is the desired replica count.

scheduling

spec.scheduling

string

default:"Packed"

Defines how GameServers are organized across the cluster:

Packed - Aimed at dynamic Kubernetes clusters (cloud providers), bin packs resources onto nodes for efficient resource usage
Distributed - Aimed at static Kubernetes clusters, distributes resources evenly across the entire cluster

strategy

spec.strategy

object

Deployment strategy for managing GameServer updates. Similar to Kubernetes Deployment strategies.

Show Strategy Configuration

spec.strategy.type

string

default:"RollingUpdate"

Type of deployment strategy. Options:

RollingUpdate - Incrementally update GameServers
Recreate - Terminate all non-allocated GameServers and create new ones

spec.strategy.rollingUpdate

object

Configuration for RollingUpdate strategy. Only applies when type: RollingUpdate.

spec.strategy.rollingUpdate.maxSurge

int or string

default:"25%"

Maximum number of GameServers to create above the desired replica count during update. Can be an absolute number (e.g., 5) or percentage (e.g., 25%). Must be between 1% and 99% for percentages, or at least 1 for absolute values.

spec.strategy.rollingUpdate.maxUnavailable

int or string

default:"25%"

Maximum number of GameServers that can be unavailable during update. Can be an absolute number (e.g., 5) or percentage (e.g., 25%). Must be between 1% and 99% for percentages, or at least 1 for absolute values.

allocationOverflow

spec.allocationOverflow

object

Labels and/or annotations to apply to GameServers when the number of Allocated GameServers exceeds the desired replicas in the underlying GameServerSet. This is useful for managing overflow capacity.

Show Allocation Overflow Configuration

spec.allocationOverflow.labels

map[string]string

Labels to be applied to overflow GameServers. Set a label to empty string ("") to remove it.

spec.allocationOverflow.annotations

map[string]string

Annotations to be applied to overflow GameServers.

priorities

spec.priorities

array

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

For Packed strategy: Priority list is the tie-breaker within nodes for optimal infrastructure usage
For Distributed strategy: Entire Fleet is sorted by this priority list to determine GameServer 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. Has no impact if the Counter/List is not found on the GameServer.

spec.priorities[].order

string

default:"Ascending"

Sort order for available capacity:

Ascending - Smaller available capacity is preferred (scaled down first)
Descending - Larger available capacity is preferred (scaled down first)

template

spec.template

object

required

GameServer template to apply for this Fleet. This template defines the specification for each GameServer created by the Fleet.

Show Template Structure

The template contains a GameServerTemplateSpec with:

spec.template.metadata

object

Metadata for the GameServer including labels and annotations.

spec.template.spec

object

required

Complete GameServer specification. See GameServer for full field reference.

Status Fields

The status field reflects the current state of the Fleet.

replicas

status.replicas

int32

Total number of current GameServer replicas managed by this Fleet.

readyReplicas

status.readyReplicas

int32

Number of GameServer replicas in the Ready state.

reservedReplicas

status.reservedReplicas

int32

Total number of Reserved GameServer replicas. Reserved instances won’t be deleted on scale down but won’t cause an autoscaler to scale up.

allocatedReplicas

status.allocatedReplicas

int32

Number of Allocated GameServer replicas.

players

status.players

object

Alpha Feature (PlayerTracking flag)Current total player capacity and count aggregated across all GameServers in this Fleet.

Show Aggregated Player Status

status.players.count

int64

Total player count across the Fleet.

status.players.capacity

int64

Total player capacity across the Fleet.

counters

status.counters

map[string]AggregatedCounterStatus

Beta Feature (CountsAndLists flag)Aggregated counter capacity and count across all GameServers in this Fleet.

Show Aggregated Counter Status

status.counters[key].allocatedCount

int64

Total count from allocated GameServers.

status.counters[key].allocatedCapacity

int64

Total capacity from allocated GameServers.

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 values across all GameServers in this Fleet.

Show Aggregated List Status

status.lists[key].allocatedCount

int64

Total value count from allocated GameServers.

status.lists[key].allocatedCapacity

int64

Total capacity from allocated GameServers.

status.lists[key].count

int64

Total value count across all GameServers.

status.lists[key].capacity

int64

Total capacity across all GameServers.

Relationship to GameServerSets

Fleets create and manage GameServerSets, which in turn create and manage individual GameServers. This hierarchy is similar to:

Kubernetes: Deployment → ReplicaSet → Pod
Agones: Fleet → GameServerSet → GameServer

Each Fleet creates one or more GameServerSets based on:

Initial creation (creates one GameServerSet)
Rolling updates (temporarily creates a second GameServerSet during transition)
Strategy changes

The Fleet controller ensures that the desired number of GameServers across all GameServerSets matches the spec.replicas value.

Scaling Behavior

Scale Up

When increasing replicas:

Fleet increases the replica count on the active GameServerSet
GameServerSet creates new GameServers
GameServers transition through states until Ready
Status counters update to reflect new totals

Scale Down

When decreasing replicas:

Fleet identifies GameServers to remove based on:
- Priority configuration (if specified)
- Scheduling strategy (Packed vs Distributed)
- Current state (Ready servers removed before Reserved)
Selected GameServers are deleted
Allocated GameServers are never scaled down
Reserved GameServers are preserved but don’t trigger scale up

Rolling Updates

During template updates with RollingUpdate strategy:

New GameServerSet is created with updated template
Fleet scales up new GameServerSet by maxSurge
Fleet scales down old GameServerSet by maxUnavailable
Process repeats until all GameServers use new template
Old GameServerSet remains with 0 replicas (not deleted)

Notes

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

The Fleet status is defined as a subresource, meaning status updates don’t trigger a new resource version for the main Fleet object.

Changing the Fleet template triggers a rolling update. Allocated GameServers are not affected and will continue running with the old specification until they are deallocated and deleted.

Custom Resources

Allocation API

SDK API

API Version

Kind

Resource Structure

Spec Fields

replicas

scheduling

strategy

allocationOverflow

priorities

template

Status Fields

replicas

readyReplicas

reservedReplicas

allocatedReplicas

players

counters

lists

Relationship to GameServerSets

Scaling Behavior

Scale Up

Scale Down

Rolling Updates

Notes

Build docs developers (and LLMs) love

Custom Resources

Allocation API

SDK API

​API Version

​Kind

​Resource Structure

​Spec Fields

​replicas

​scheduling

​strategy

​allocationOverflow

​priorities

​template

​Status Fields

​replicas

​readyReplicas

​reservedReplicas

​allocatedReplicas

​players

​counters

​lists

​Relationship to GameServerSets

​Scaling Behavior

​Scale Up

​Scale Down

​Rolling Updates

​Notes

Build docs developers (and LLMs) love

API Version

Kind

Resource Structure

Spec Fields

replicas

scheduling

strategy

allocationOverflow

priorities

template

Status Fields

replicas

readyReplicas

reservedReplicas

allocatedReplicas

players

counters

lists

Relationship to GameServerSets

Scaling Behavior

Scale Up

Scale Down

Rolling Updates

Notes