Fleet Specification

A Fleet is a set of warm GameServers that are available to be allocated from.

To allocate a GameServer from a Fleet, use a GameServerAllocation.

Like any other Kubernetes resource you describe a Fleet's desired state via a specification written in YAML or JSON to the Kubernetes API. The Agones controller will then change the actual state to the desired state.

A full Fleet specification is available below and in the example folder for reference :

apiVersion: "agones.dev/v1"
kind: Fleet
# Fleet Metadata
# https://v1-17.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#objectmeta-v1-meta
metadata:
  name: fleet-example
spec:
  # the number of GameServers to keep Ready or Allocated in this Fleet
  replicas: 2
  # defines how GameServers are organised across the cluster.
  # Options include:
  # "Packed" (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack
  # resources
  # "Distributed" is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire
  # cluster
  scheduling: Packed
  # a GameServer template - see:
  # https://agones.dev/site/docs/reference/gameserver/ for all the options
  strategy:
    # The replacement strategy for when the GameServer template is changed. Default option is "RollingUpdate",
    # "RollingUpdate" will increment by maxSurge value on each iteration, while decrementing by maxUnavailable on each
    # iteration, until all GameServers have been switched from one version to another.
    # "Recreate" terminates all non-allocated GameServers, and starts up a new set with the new details to replace them.
    type: RollingUpdate
    # Only relevant when `type: RollingUpdate`
    rollingUpdate:
      # the amount to increment the new GameServers by. Defaults to 25%
      maxSurge: 25%
      # the amount to decrements GameServers by. Defaults to 25%
      maxUnavailable: 25%
  template:
    # GameServer metadata
    metadata:
      labels:
        foo: bar
    # GameServer specification
    spec:
      ports:
      - name: default
        portPolicy: Dynamic
        containerPort: 26000
      health:
        initialDelaySeconds: 30
        periodSeconds: 60
      # Parameters for game server sidecar
      sdkServer:
        logLevel: Info
        grpcPort: 9357
        httpPort: 9358
      # The GameServer's Pod template
      template:
        spec:
          containers:
          - name: simple-udp
            image: gcr.io/agones-images/udp-server:0.21

Since Agones defines a new Custom Resources Definition (CRD) we can define a new resource using the kind Fleet with the custom group agones.dev and API version v1.

You can use the metadata field to target a specific namespaces but also attach specific annotations and labels to your resource. This is a very common pattern in the Kubernetes ecosystem.

The length of the name field of the fleet should be at most 63 characters.

The spec field is the actual Fleet specification and it is composed as follow:

  • replicas is the number of GameServers to keep Ready or Allocated in this Fleet
  • scheduling defines how GameServers are organised across the cluster. Affects backing Pod scheduling, as well as scale down mechanics. “Packed” (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack resources. “Distributed” is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire cluster. See Scheduling and Autoscaling for more details.
  • strategy is the GameServer replacement strategy for when the GameServer template is edited.
    • type is replacement strategy for when the GameServer template is changed. Default option is “RollingUpdate”, but “Recreate” is also available.
      • RollingUpdate will increment by maxSurge value on each iteration, while decrementing by maxUnavailable on each iteration, until all GameServers have been switched from one version to another.
      • Recreate terminates all non-allocated GameServers, and starts up a new set with the new GameServer configuration to replace them.
    • rollingUpdate is only relevant when type: RollingUpdate
      • maxSurge is the amount to increment the new GameServers by. Defaults to 25%
      • maxUnavailable is the amount to decrements GameServers by. Defaults to 25%
  • template a full GameServer configuration template. See the GameServer reference for all available fields.

Fleet Scale Subresource Specification

Scale subresource is defined for a Fleet. Please refer to Kubernetes docs.

You can use the following command to scale the fleet with name simple-udp:

$ kubectl scale fleet simple-udp --replicas=10
fleet.agones.dev/simple-udp scaled

You can also use Kubernetes API to get or update the Replicas count:

curl http://localhost:8001/apis/agones.dev/v1/namespaces/default/fleets/simple-udp/scale
...
{
  "kind": "Scale",
  "apiVersion": "autoscaling/v1",
  "metadata": {
    "name": "simple-udp",
    "namespace": "default",
    "selfLink": "/apis/agones.dev/v1/namespaces/default/fleets/simple-udp/scale",
    "uid": "4dfaa310-2566-11e9-afd1-42010a8a0058",
    "resourceVersion": "292652",
    "creationTimestamp": "2019-01-31T14:41:33Z"
  },
  "spec": {
    "replicas": 10
  },
  "status": {
    "replicas": 10
  }

Also exposing a Scale subresource would allow you to configure HorizontalPodAutoscaler and PodDisruptionBudget for a fleet in the future. However these features have not been tested, and are not currently supported - but if you are looking for these features, please be sure to let us know in the ticket.