Reference

• 1: GameServer Specification
• 2: Fleet Specification
• 3: GameServerAllocation Specification
• 4: Fleet Autoscaler Specification
• 5: Code Blind Kubernetes API

1 - GameServer Specification

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

apiVersion: "agones.dev/v1"
kind: GameServer
# GameServer Metadata
# https://v1-27.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta
metadata:
  # generateName: "gds-example" # generate a unique name, with the given prefix
  name: "gds-example" # set a fixed name
spec:
  # if there is more than one container, specify which one is the game server
  container: example-server
  # Array of ports that can be exposed as direct connections to the game server container
  ports:
    # name is a descriptive name for the port
  - name: default
    # portPolicy has three options:
    # - "Dynamic" (default) the system allocates a free hostPort for the gameserver, for game clients to connect to
    # - "Static", user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the
    # port is available. When static is the policy specified, `hostPort` is required to be populated
    # - "Passthrough" dynamically sets the `containerPort` to the same value as the dynamically selected hostPort.
    #      This will mean that users will need to lookup what port has been opened through the server side SDK.
    portPolicy: Static
    # The name of the container to open the port on. Defaults to the game server container if omitted or empty.
    container: simple-game-server
    # the port that is being opened on the game server process
    containerPort: 7654
    # the port exposed on the host, only required when `portPolicy` is "Static". Overwritten when portPolicy is "Dynamic".
    hostPort: 7777
    # protocol being used. Defaults to UDP. TCP and TCPUDP are other options
    # - "UDP" (default) use the UDP protocol
    # - "TCP", use the TCP protocol
    # - "TCPUDP", uses both TCP and UDP, and exposes the same hostPort for both protocols.
    #       This will mean that it adds an extra port, and the first port is set to TCP, and second port set to UDP
    protocol: UDP
  # Health checking for the running game server
  health:
    # Disable health checking. defaults to false, but can be set to true
    disabled: false
    # Number of seconds after the container has started before health check is initiated. Defaults to 5 seconds
    initialDelaySeconds: 5
    # If the `Health()` function doesn't get called at least once every period (seconds), then
    # the game server is not healthy. Defaults to 5
    periodSeconds: 5
    # Minimum consecutive failures for the health probe to be considered failed after having succeeded.
    # Defaults to 3. Minimum value is 1
    failureThreshold: 3
  # Parameters for game server sidecar
  sdkServer:
    # sdkServer log level parameter has three options:
    #  - "Info" (default) The SDK server will output all messages except for debug messages
    #  - "Debug" The SDK server will output all messages including debug messages
    #  - "Error" The SDK server will only output error messages
    logLevel: Info
    # grpcPort and httpPort control what ports the sdkserver listens on.
    # Starting with Code Blind 1.2 the default grpcPort is 9357 and the default
    # httpPort is 9358. In earlier releases, the defaults were 59357 and 59358
    # respectively but as these were in the ephemeral port range they could
    # conflict with other TCP connections.
    grpcPort: 9357
    httpPort: 9358
  # [Stage:Alpha]
  # [FeatureFlag:PlayerTracking]
  # Players provides the configuration for player tracking features.
  # Commented out since Alpha, and disabled by default
  # players:
  #   # set this GameServer's initial player capacity
  #   initialCapacity: 10
  #
  # [Stage:Alpha]
  # [FeatureFlag:CountsAndLists]
  # Counts and Lists provides the configuration for generic (player, room, session, etc.) tracking features.
  # Commented out since Alpha, and disabled by default
  # counters: # counters are int64 counters that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time.
  #   games: # arbitrary key.
  #     count: 1 # initial value.
  #     capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details.
  #   sessions:
  #     count: 1
  # lists: # lists are lists of values stored against this GameServer that can be added and deleted from. Keys must be declared at GameServer creation time.
  #   players: # an empty list, with a capacity set to 10.
  #     capacity: 10 # capacity value, defaults to 1000.
  #   rooms:
  #     capacity: 333
  #     values: # initial set of values in a list.
  #       - room1
  #       - room2
  #       - room3
  #  
  # Pod template configuration
  # https://v1-27.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplate-v1-core
  template:
    # pod metadata. Name & Namespace is overwritten
    metadata:
      labels:
        myspeciallabel: myspecialvalue
    # Pod Specification
    spec:
      containers:
      - name: simple-game-server
        image:  us-docker.pkg.dev/codeblind/examples/simple-server:0.27
        imagePullPolicy: Always
      # nodeSelector is a label that can be used to tell Kubernetes which host
      # OS to use. For Windows game servers uncomment the nodeSelector
      # definition below.
      # Details: https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/#ensuring-os-specific-workloads-land-on-the-appropriate-container-host
      # nodeSelector:
      #   kubernetes.io/os: windows

Since Code Blind defines a new Custom Resources Definition (CRD) we can define a new resource using the kind GameServer 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 Gameserver should not exceed 63 characters.

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

• container is the name of container running the GameServer in case you have more than one container defined in the pod. If you do, this is a mandatory field. For instance this is useful if you want to run a sidecar to ship logs.
• ports are an array of ports that can be exposed as direct connections to the game server container
  • name is an optional descriptive name for a port
  • portPolicy has three options: - Dynamic (default) the system allocates a random free hostPort for the gameserver, for game clients to connect to. - Static, user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the port is available. When static is the policy specified, hostPort is required to be populated. - Passthrough dynamically sets the containerPort to the same value as the dynamically selected hostPort. This will mean that users will need to lookup what port to open through the server side SDK before starting communications.
  • container (Alpha) the name of the container to open the port on. Defaults to the game server container if omitted or empty.
  • containerPort the port that is being opened on the game server process, this is a required field for Dynamic and Static port policies, and should not be included in Passthrough configuration.
  • protocol the protocol being used. Defaults to UDP. TCP and TCPUDP are other options.
• health to track the overall healthy state of the GameServer, more information available in the health check documentation.
• sdkServer defines parameters for the game server sidecar
  • logging field defines log level for SDK server. Defaults to “Info”. It has three options:
    • “Info” (default) The SDK server will output all messages except for debug messages
    • “Debug” The SDK server will output all messages including debug messages
    • “Error” The SDK server will only output error messages
  • grpcPort the port that the SDK Server binds to for gRPC connections
  • httpPort the port that the SDK Server binds to for HTTP gRPC gateway connections
• players (Alpha, behind “PlayerTracking” feature gate), sets this GameServer’s initial player capacity
• counters (Alpha, requires “CountsAndLists” feature flag) are int64 counters with a default capacity of 1000 that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time. Note that setting the capacity to max(int64) may lead to issues.
• lists (Alpha, requires “CountsAndLists” feature flag) are lists of values stored against this GameServer that can be added and deleted from. Key must be declared at GameServer creation time.
• template the pod spec template to run your GameServer containers, see for more information.

Stable Network ID

If you want to connect to a GameServer from within your Kubernetes cluster via a convention based DNS entry, each Pod attached to a GameServer automatically derives its hostname from the name of the GameServer.

To create internal DNS entries within the cluster, a group of Pods attached to GameServers can use a Headless Service to control the domain of the Pods, along with providing a subdomain value to the GameServer PodTemplateSpec to provide all the required details such that Kubernetes will create a DNS record for each Pod behind the Service.

You are also responsible for setting the labels on the GameServer.Spec.Template.Metadata to set the labels on the created Pods and creating the Headless Service responsible for the network identity of the pods, Code Blind will not do this for you, as a stable DNS record is not required for all use cases.

To ensure that the hostName value matches RFC 1123, any . values in the GameServer name are replaced by - when setting the underlying Pod.Spec.HostName value.

GameServer State Diagram

The following diagram shows the lifecycle of a GameServer.

Game Servers are created through Kubernetes API (either directly or through a Fleet) and their state transitions are orchestrated by:

• GameServer controller, which allocates ports, launches Pods backing game servers and manages their lifetime
• Allocation controller, which marks game servers as Allocated to handle a game session
• SDK, which manages health checking and shutdown of a game server session

Primary Address vs Addresses

GameServer.Status has two fields which reflect the network address of the GameServer: address and addresses. The address field is a policy-based choice of “primary address” that will work for many use cases, and will always be one of the addresses. The addresses field contains every address in the Node.Status.addresses, representing all known ways to reach the GameServer over the network.

To choose address from addresses, Code Blind looks for the following address types, in highest to lowest priorty:

• ExternalDNS
• ExternalIP
• InternalDNS
• InternalIP

e.g. if any ExternalDNS address is found in the respective Node, it is used as the address.

The policy for address will work for many use-cases, but for some advanced cases, such as IPv6 enablement, you may need to evaluate all addresses and pick the addresses that best suits your needs.

2 - Fleet Specification

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 Code Blind 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-27.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#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/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%
  # [Stage:Beta]
  # [FeatureFlag:FleetAllocationOverflow]
  # Labels and/or Annotations to apply to overflowing GameServers when the number of Allocated GameServers is more
  # than the desired replicas on the underlying `GameServerSet`
  allocationOverflow:
    labels:
      mykey: myvalue
      version: "" # empty an existing label value
    annotations:
      otherkey: setthisvalue
  #
  # [Stage:Alpha]
  # [FeatureFlag:CountsAndLists]
  # Which gameservers in the Fleet are most important to keep around - impacts scale down logic.
  # priorities:
  # - type: Counter # Sort by a “Counter”
  #   key: player # The name of the Counter. No impact if no GameServer found.
  #   order: Descending # Default is "Ascending" so smaller capacity will be removed first on down scaling.
  # - type: List # Sort by a “List”
  #   key: room # The name of the List. No impact if no GameServer found.
  #   order: Ascending # Default is "Ascending" so smaller capacity will be removed first on down scaling.
  #      
  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-game-server
            image: us-docker.pkg.dev/codeblind/examples/simple-server:0.27

Since Code Blind 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%
• allocationOverflow (Beta, requires FleetAllocationOverflow flag) The labels and/or Annotations to apply to GameServers when the number of Allocated GameServers exceeds the desired replicas in the underlying GameServerSet.
  • labels the map of labels to be applied
  • annotations the map of annotations to be applied
  • Fleet's Scheduling Strategy: The GameServers associated with the GameServerSet are sorted based on either Packed or Distributed strategy.
    • Packed: Code Blind maximizes resource utilization by trying to populate nodes that are already in use before allocating GameServers to other nodes.
    • Distributed: Code Blind employs this strategy to spread out GameServer allocations, ensuring an even distribution of GameServers across the available nodes.
• priorities: (Alpha, requires CountsAndLists feature flag): Defines which gameservers in the Fleet are most important to keep around - impacts scale down logic.
  • type: Sort by a “Counter” or a “List”.
  • key: The name of the Counter or List. If not found on the GameServer, has no impact.
  • order: Order: Sort by “Ascending” or “Descending”. “Descending” a bigger Capacity is preferred. “Ascending” would be smaller Capacity is preferred.
• 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-game-server:

kubectl scale fleet simple-game-server --replicas=10

fleet.agones.dev/simple-game-server 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-game-server/scale

{
  "kind": "Scale",
  "apiVersion": "autoscaling/v1",
  "metadata": {
    "name": "simple-game-server",
    "namespace": "default",
    "selfLink": "/apis/agones.dev/v1/namespaces/default/fleets/simple-game-server/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.

3 - GameServerAllocation Specification

Allocation is the process of selecting the optimal GameServer that matches the filters defined in the GameServerAllocation specification below, and returning its details.

A successful Alloction moves the GameServer to the Allocated state, which indicates that it is currently active, likely with players on it, and should not be removed until SDK.Shutdown() is called, or it is explicitly manually deleted.

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

• selectors
• required & preferred (deprecated)

apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
  # GameServer selector from which to choose GameServers from.
  # Defaults to all GameServers.
  # matchLabels, matchExpressions, gameServerState and player filters can be used for filtering.
  # See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details on label selectors.
  # An ordered list of GameServer label selectors.
  # If the first selector is not matched, the selection attempts the second selector, and so on.
  # This is useful for things like smoke testing of new game servers.
  selectors:
    - matchLabels:
        agones.dev/fleet: green-fleet
        # [Stage:Alpha]
        # [FeatureFlag:PlayerAllocationFilter]
      players:
        minAvailable: 0
        maxAvailable: 99
    - matchLabels:
        agones.dev/fleet: blue-fleet
    - matchLabels:
        game: my-game
      matchExpressions:
        - {key: tier, operator: In, values: [cache]}
      # Specifies which State is the filter to be used when attempting to retrieve a GameServer
      # via Allocation. Defaults to "Ready". The only other option is "Allocated", which can be used in conjunction with
      # label/annotation/player selectors to retrieve an already Allocated GameServer.
      gameServerState: Ready
      # [Stage:Alpha]
      # [FeatureFlag:CountsAndLists]
      # counters: # selector for counter current values of a GameServer count
      #   rooms:
      #     minCount: 1 # minimum value. Defaults to 0.
      #     maxCount: 5 # maximum value. Defaults to max(int64)
      #     minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0.
      #     maxAvailable: 10 # maximum available (current capacity - current count) Defaults to max(int64)
      # lists:
      #   players:
      #     containsValue: "x6k8z" # only match GameServers who has this value in the list. Defaults to "", which is all.
      #     minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0.
      #     maxAvailable: 10 # maximum available (current capacity - current count) Defaults to 0, which translates to max(int64)
      # [Stage:Alpha]      
      # [FeatureFlag:PlayerAllocationFilter]
      # Provides a filter on minimum and maximum values for player capacity when retrieving a GameServer
      # through Allocation. Defaults to no limits.
      players:
        minAvailable: 0
        maxAvailable: 99
  # 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
  # Optional custom metadata that is added to the game server at allocation
  # You can use this to tell the server necessary session data
  metadata:
    labels:
      mode: deathmatch
    annotations:
      map:  garden22
    # [Stage:Alpha]
    # [FeatureFlag:CountsAndLists]
    # The first Priority on the array of Priorities is the most important for sorting. The allocator will
    # use the first priority for sorting GameServers by available Capacity in the Selector set. Acts as a
    # tie-breaker after sorting the game servers by State and Strategy Packed. Impacts which GameServer
    # is checked first. Optional.
    # priorities:
    # - type: List  # Whether a Counter or a List.
    #   key: rooms  # The name of the Counter or List.
    #   order: Ascending  # "Ascending" lists smaller available capacity first.
    # [Stage:Alpha]
    # [FeatureFlag:CountsAndLists]
    # Counter actions to perform during allocation. Optional.
    # counters:
    #   rooms:
    #     action: increment # Either "Increment" or "Decrement" the Counter’s Count.
    #     amount: 1 # Amount is the amount to increment or decrement the Count. Must be a positive integer.
    #     capacity: 5 # Amount to update the maximum capacity of the Counter to this number. Min 0, Max int64.
    # List actions to perform during allocation. Optional.
    # lists:
    #   players:
    #     addValues: # appends values to a List’s Values array. Any duplicate values will be ignored
    #       - x7un
    #       - 8inz
    #     capacity: 40 # Updates the maximum capacity of the Counter to this number. Min 0, Max 1000.
  

apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
  # Deprecated, use field selectors instead.
  # GameServer selector from which to choose GameServers from.
  # Defaults to all GameServers.
  # matchLabels, matchExpressions, gameServerState and player filters can be used for filtering.
  # See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details on label selectors.
  # Deprecated, use field selectors instead.
  required:
    matchLabels:
      game: my-game
    matchExpressions:
      - {key: tier, operator: In, values: [cache]}
    # Specifies which State is the filter to be used when attempting to retrieve a GameServer
    # via Allocation. Defaults to "Ready". The only other option is "Allocated", which can be used in conjunction with
    # label/annotation/player selectors to retrieve an already Allocated GameServer.
    gameServerState: Ready
    # [Stage:Alpha]
    # [FeatureFlag:PlayerAllocationFilter]
    # Provides a filter on minimum and maximum values for player capacity when retrieving a GameServer
    # through Allocation. Defaults to no limits.
    players:
      minAvailable: 0
      maxAvailable: 99
  # Deprecated, use field selectors instead.
  # An ordered list of preferred GameServer label selectors
  # that are optional to be fulfilled, but will be searched before the `required` selector.
  # If the first selector is not matched, the selection attempts the second selector, and so on.
  # If any of the preferred selectors are matched, the required selector is not considered.
  # This is useful for things like smoke testing of new game servers.
  # This also support matchExpressions, gameServerState and player filters.
  preferred:
    - matchLabels:
        agones.dev/fleet: green-fleet
      # [Stage:Alpha]
      # [FeatureFlag:PlayerAllocationFilter]
      players:
        minAvailable: 0
        maxAvailable: 99
    - matchLabels:
        agones.dev/fleet: blue-fleet
  # 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
  # Optional custom metadata that is added to the game server at allocation
  # You can use this to tell the server necessary session data
  metadata:
    labels:
      mode: deathmatch
    annotations:
      map:  garden22
  

The spec field is the actual GameServerAllocation specification, and it is composed as follows:

• Deprecated, use selectors instead. If selectors is set, this field will be ignored. required is a GameServerSelector (matchLabels. matchExpressions, gameServerState and player filters) from which to choose GameServers from.
• Deprecated, use selectors instead. If selectors is set, this field will be ignored. preferred is an ordered list of preferred GameServerSelector that are optional to be fulfilled, but will be searched before the required selector. If the first selector is not matched, the selection attempts the second selector, and so on. If any of the preferred selectors are matched, the required selector is not considered. This is useful for things like smoke testing of new game servers.
• selectors is an ordered list of GameServerSelector. If the first selector is not matched, the selection attempts the second selector, and so on. This is useful for things like smoke testing of new game servers.
• matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is “key”, the operator is “In”, and the values array contains only “value”. The requirements are ANDed. Optional.
• matchExpressions is a list of label selector requirements. The requirements are ANDed. Optional.
• gameServerState GameServerState specifies which State is the filter to be used when attempting to retrieve a GameServer via Allocation. Defaults to “Ready”. The only other option is “Allocated”, which can be used in conjunction with label/annotation/player selectors to retrieve an already Allocated GameServer.
• counters (Alpha, “CountsAndLists” feature flag) enables filtering based on game server Counter status, such as the minimum and maximum number of active rooms. This helps in selecting game servers based on their current activity or capacity. Optional.
• lists (Alpha, “CountsAndLists” feature flag) enables filtering based on game server List status, such as allowing for inclusion or exclusion of specific players. Optional.
• scheduling defines how GameServers are organised across the cluster, in this case specifically when allocating GameServers for usage. “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.
• metadata is an optional list of custom labels and/or annotations that will be used to patch the game server’s metadata in the moment of allocation. This can be used to tell the server necessary session data
• priorities (Alpha, requires CountsAndLists feature flag) manages counters and lists for game servers, setting limits on room counts and player inclusion/exclusion.
• counters (Alpha, “CountsAndLists” feature flag) Counter actions to perform during allocation.
• lists (Alpha, “CountsAndLists” feature flag) List actions to perform during allocation.

Once created the GameServerAllocation will have a status field consisting of the following:

• State is the current state of a GameServerAllocation, e.g. Allocated, or UnAllocated
• GameServerName is the name of the game server attached to this allocation, once the state is Allocated
• Ports is a list of the ports that the game server makes available. See the GameServer Reference for more details.
• Address is the primary network address where the game server can be reached.
• Addresses is an array of all network addresses where the game server can be reached. It is a copy of the Node.Status.addresses field for the node the GameServer is scheduled on.
• NodeName is the name of the node that the gameserver is running on.
• Source is “local” unless this allocation is from a remote cluster, in which case Source is the endpoint of the remote agones-allocator. See Multi-cluster Allocation for more details.
• Metadata conststs of:
  • Labels containing the labels of the game server at allocation time.
  • Annotations containing the annotations of the underlying game server at allocation time.

Each GameServerAllocation will allocate from a single namespace. The namespace can be specified outside of the spec, either with the --namespace flag when using the command line / kubectl or in the url when using an API call. If not specified when using the command line, the namespace will be automatically set to default.

Next Steps:

• Check out the Allocator Service as a richer alternative to GameServerAllocation.

4 - Fleet Autoscaler Specification

A full FleetAutoscaler specification is available below and in the example folder for reference, but here are several examples that show different autoscaling policies.

Ready Buffer Autoscaling

Fleet autoscaling with a buffer can be used to maintain a configured number of game server instances ready to serve players based on number of allocated instances in a Fleet. The buffer size can be specified as an absolute number or a percentage of the desired number of Ready game server instances over the Allocated count.

apiVersion: "autoscaling.agones.dev/v1"
kind: FleetAutoscaler
# FleetAutoscaler Metadata
# https://v1-27.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta
metadata:
  name: fleet-autoscaler-example
spec:
  # The name of the fleet to attach to and control. Must be an existing Fleet in the same namespace
  # as this FleetAutoscaler
  fleetName: fleet-example
  # The autoscaling policy
  policy:
    # type of the policy. for now, only Buffer is available
    type: Buffer
    # parameters of the buffer policy
    buffer:
      # Size of a buffer of "ready" game server instances
      # The FleetAutoscaler will scale the fleet up and down trying to maintain this buffer, 
      # as instances are being allocated or terminated
      # it can be specified either in absolute (i.e. 5) or percentage format (i.e. 5%)
      bufferSize: 5
      # minimum fleet size to be set by this FleetAutoscaler. 
      # if not specified, the actual minimum fleet size will be bufferSize
      minReplicas: 10
      # maximum fleet size that can be set by this FleetAutoscaler
      # required
      maxReplicas: 20
  # The autoscaling sync strategy
  sync:
    # type of the sync. for now, only FixedInterval is available
    type: FixedInterval
    # parameters of the fixedInterval sync
    fixedInterval:
      # the time in seconds between each auto scaling
      seconds: 30

Counter and List Autoscaling

A Counter based autoscaler can be used to autoscale GameServers based on a Count and Capacity set on each of the GameServers in a Fleet to ensure there is always a buffer of total capacity available.

For example, if you have a game server that can support 10 rooms, and you want to ensure that there are always at least 5 rooms available, you could use a counter-based autoscaler with a buffer size of 5. The autoscaler would then scale the Fleet up or down based on the difference between the count of rooms across the Fleet and the capacity of rooms across the Fleet to ensure the buffer is maintained.

Counter-based FleetAutoscaler specification below and in the example folder:

apiVersion: autoscaling.agones.dev/v1
kind: FleetAutoscaler
metadata:
  name: fleet-autoscaler-counter
spec:
  fleetName: fleet-example
  policy:
    type: Counter  # Counter based autoscaling
    counter:
      # Key is the name of the Counter. Required field.
      key: players
      # BufferSize is the size of a buffer of counted items that are available in the Fleet (available capacity).
      # Value can be an absolute number (ex: 5) or a percentage of the Counter available capacity (ex: 5%).
      # An absolute number is calculated from percentage by rounding up. Must be bigger than 0. Required field.
      bufferSize: 5
      # MinCapacity is the minimum aggregate Counter total capacity across the fleet.
      # If BufferSize is specified as a percentage, MinCapacity is required and cannot be 0.
      # If non zero, MinCapacity must be smaller than MaxCapacity and must be greater than or equal to BufferSize.
      minCapacity: 10
      # MaxCapacity is the maximum aggregate Counter total capacity across the fleet.
      # MaxCapacity must be greater than or equal to both MinCapacity and BufferSize. Required field.
      maxCapacity: 100

A List based autoscaler can be used to autoscale GameServers based on the List length and Capacity set on each of the GameServers in a Fleet to ensure there is always a buffer of total capacity available.

For example, if you have a game server that can support 10 players, and you want to ensure that there are always room for at least 5 players across GameServers in a Fleet, you could use a list-based autoscaler with a buffer size of 5. The autoscaler would then scale the Fleet up or down based on the difference between the total length of the players and the total players capacity across the Fleet to ensure the buffer is maintained.

List-based FleetAutoscaler specification below and in the example folder:

apiVersion: autoscaling.agones.dev/v1
kind: FleetAutoscaler
metadata:
  name: fleet-autoscaler-list
spec:
  fleetName: fleet-example
  policy:
    type: List  # List based autoscaling.
    list:
      # Key is the name of the List. Required field.
      key: rooms
      # BufferSize is the size of a buffer based on the List capacity that is available over the current
      # aggregate List length in the Fleet (available capacity).
      # It can be specified either as an absolute value (i.e. 5) or percentage format (i.e. 5%).
      # Must be bigger than 0. Required field.
      bufferSize: 5
      # MinCapacity is the minimum aggregate List total capacity across the fleet.
      # If BufferSize is specified as a percentage, MinCapacity is required must be greater than 0.
      # If non-zero, MinCapacity must be smaller than MaxCapacity and must be greater than or equal to BufferSize.
      minCapacity: 10
      # MaxCapacity is the maximum aggregate List total capacity across the fleet.
      # MaxCapacity must be greater than or equal to both MinCapacity and BufferSize. Required field.
      maxCapacity: 100

Webhook Autoscaling

A webhook-based FleetAutoscaler can be used to delegate the scaling logic to a separate http based service. This can be useful if you want to use a custom scaling algorithm or if you want to integrate with other systems. For example, you could use a webhook-based FleetAutoscaler to scale your fleet based on data from a match-maker or player authentication system or a combination of systems.

Webhook based autoscalers have the added benefit of being able to scale a Fleet to 0 replicas, since they are able to scale up on demand based on an external signal before a GameServerAllocation is executed from a match-maker or similar system.

In order to define the path to your Webhook you can use either URL or service. Note that caBundle parameter is required if you use HTTPS for webhook FleetAutoscaler, caBundle should be omitted if you want to use HTTP webhook server.

For Webhook FleetAutoscaler below and in example folder:

apiVersion: "autoscaling.agones.dev/v1"
kind: FleetAutoscaler
metadata:
  name: webhook-fleet-autoscaler
spec:
  fleetName: simple-game-server
  policy:
    # type of the policy - this example is Webhook
    type: Webhook
    # parameters for the webhook policy - this is a WebhookClientConfig, as per other K8s webhooks
    webhook:
      # use a service, or URL
      service:
        name: autoscaler-webhook-service
        namespace: default
        path: scale
      # optional for URL defined webhooks
      # url: ""
      # caBundle:  optional, used for HTTPS webhook type
  # The autoscaling sync strategy
  sync:
    # type of the sync. for now, only FixedInterval is available
    type: FixedInterval
    # parameters of the fixedInterval sync
    fixedInterval:
      # the time in seconds between each auto scaling
      seconds: 30

See the Webhook Endpoint Specification for the specification of the incoming and outgoing JSON packet structure for the webhook endpoint.

Spec Field Reference

The spec field of the FleetAutoscaler is composed as follows:

• fleetName is name of the fleet to attach to and control. Must be an existing Fleet in the same namespace as this FleetAutoscaler.
• policy is the autoscaling policy
  • type is type of the policy. “Buffer” and “Webhook” are available
  • buffer parameters of the buffer policy type
    • bufferSize is the size of a buffer of “ready” and “reserved” game server instances. The FleetAutoscaler will scale the fleet up and down trying to maintain this buffer, as instances are being allocated or terminated. Note that “reserved” game servers could not be scaled down. It can be specified either in absolute (i.e. 5) or percentage format (i.e. 5%)
    • minReplicas is the minimum fleet size to be set by this FleetAutoscaler. if not specified, the minimum fleet size will be bufferSize if absolute value is used. When bufferSize in percentage format is used, minReplicas should be more than 0.
    • maxReplicas is the maximum fleet size that can be set by this FleetAutoscaler. Required.
  • webhook parameters of the webhook policy type
    • service is a reference to the service for this webhook. Either service or url must be specified. If the webhook is running within the cluster, then you should use service. Port 8000 will be used if it is open, otherwise it is an error.
      • name is the service name bound to Deployment of autoscaler webhook. Required (see example) The FleetAutoscaler will scale the fleet up and down based on the response from this webhook server
      • namespace is the kubernetes namespace where webhook is deployed. Optional If not specified, the “default” would be used
      • path is an optional URL path which will be sent in any request to this service. (i. e. /scale)
      • port is optional, it is the port for the service which is hosting the webhook. The default is 8000 for backward compatibility. If given, it should be a valid port number (1-65535, inclusive).
    • url gives the location of the webhook, in standard URL form ([scheme://]host:port/path). Exactly one of url or service must be specified. The host should not refer to a service running in the cluster; use the service field instead. (optional, instead of service)
    • caBundle is a PEM encoded certificate authority bundle which is used to issue and then validate the webhook’s server certificate. Base64 encoded PEM string. Required only for HTTPS. If not present HTTP client would be used.
  • Note: only one buffer or webhook could be defined for FleetAutoscaler which is based on the type field.
  • counter parameters of the counter policy type
    • counter contains the settings for counter-based autoscaling:
      • key is the name of the counter to use for scaling decisions.
      • bufferSize is the size of a buffer of counted items that are available in the Fleet (available capacity). Value can be an absolute number or a percentage of desired game server instances. An absolute number is calculated from percentage by rounding up. Must be bigger than 0.
      • minCapacity is the minimum aggregate Counter total capacity across the fleet. If zero, MinCapacity is ignored. If non zero, MinCapacity must be smaller than MaxCapacity and bigger than BufferSize.
      • maxCapacity is the maximum aggregate Counter total capacity across the fleet. It must be bigger than both MinCapacity and BufferSize.
  • list parameters of the list policy type
    • list contains the settings for list-based autoscaling:
      • key is the name of the list to use for scaling decisions.
      • bufferSize is the size of a buffer based on the List capacity that is available over the current aggregate List length in the Fleet (available capacity). It can be specified either as an absolute value or percentage format.
      • minCapacity is the minimum aggregate List total capacity across the fleet. If zero, it is ignored. If non zero, it must be smaller than MaxCapacity and bigger than BufferSize.
      • maxCapacity is the maximum aggregate List total capacity across the fleet. It must be bigger than both MinCapacity and BufferSize. Required field.
• sync is autoscaling sync strategy. It defines when to run the autoscaling
  • type is type of the sync. For now only “FixedInterval” is available
  • fixedInterval parameters of the fixedInterval sync
    • seconds is the time in seconds between each autoscaling

Webhook Endpoint Specification

A webhook based FleetAutoscaler sends an HTTP POST request to the webhook endpoint every sync period (default is 30s) with a JSON body, and scale the target fleet based on the data that is returned.

The JSON payload that is sent is a FleetAutoscaleReview data structure and a FleetAutoscaleResponse data structure is expected to be returned.

The FleetAutoscaleResponse’s Replica field is used to set the target Fleet count with each sync interval, thereby providing the autoscaling functionality.

// FleetAutoscaleReview is passed to the webhook with a populated Request value,
// and then returned with a populated Response.
type FleetAutoscaleReview struct {
	Request  *FleetAutoscaleRequest  `json:"request"`
	Response *FleetAutoscaleResponse `json:"response"`
}

type FleetAutoscaleRequest struct {
	// UID is an identifier for the individual request/response. It allows us to distinguish instances of requests which are
	// otherwise identical (parallel requests, requests when earlier requests did not modify etc)
	// The UID is meant to track the round trip (request/response) between the Autoscaler and the WebHook, not the user request.
	// It is suitable for correlating log entries between the webhook and apiserver, for either auditing or debugging.
	UID types.UID `json:"uid""`
	// Name is the name of the Fleet being scaled
	Name string `json:"name"`
	// Namespace is the namespace associated with the request (if any).
	Namespace string `json:"namespace"`
	// The Fleet's status values
	Status v1.FleetStatus `json:"status"`
}

type FleetAutoscaleResponse struct {
	// UID is an identifier for the individual request/response.
	// This should be copied over from the corresponding FleetAutoscaleRequest.
	UID types.UID `json:"uid"`
	// Set to false if no scaling should occur to the Fleet
	Scale bool `json:"scale"`
	// The targeted replica count
	Replicas int32 `json:"replicas"`
}

// FleetStatus is the status of a Fleet
type FleetStatus struct {
	// Replicas the total number of current GameServer replicas
	Replicas int32 `json:"replicas"`
	// ReadyReplicas are the number of Ready GameServer replicas
	ReadyReplicas int32 `json:"readyReplicas"`
	// ReservedReplicas are the total number of Reserved GameServer replicas in this fleet.
	// Reserved instances won't be deleted on scale down, but won't cause an autoscaler to scale up.
	ReservedReplicas int32 `json:"reservedReplicas"`
	// AllocatedReplicas are the number of Allocated GameServer replicas
	AllocatedReplicas int32 `json:"allocatedReplicas"`
}

For Webhook Fleetautoscaler Policy either HTTP or HTTPS could be used. Switching between them occurs depending on https presence in URL or by the presence of caBundle. The example of the webhook written in Go could be found here.

It implements the scaling logic based on the percentage of allocated gameservers in a fleet.

5 - Code Blind Kubernetes API

Packages:

• allocation.agones.dev/v1
• autoscaling.agones.dev/v1
• multicluster.agones.dev/v1
• agones.dev/v1

allocation.agones.dev/v1

Package v1 is the v1 version of the API.

• GameServerAllocation

GameServerAllocation

GameServerAllocation is the data structure for allocating against a set of GameServers, defined selectors selectors

CounterAction

(Appears on: GameServerAllocationSpec)

CounterAction is an optional action that can be performed on a Counter at allocation.

CounterSelector

(Appears on: GameServerSelector)

CounterSelector is the filter options for a GameServer based on the count and/or available capacity.

GameServerAllocationSpec

(Appears on: GameServerAllocation)

GameServerAllocationSpec is the spec for a GameServerAllocation

GameServerAllocationState (string alias)

(Appears on: GameServerAllocationStatus)

GameServerAllocationState is the Allocation state

GameServerAllocationStatus

(Appears on: GameServerAllocation)

GameServerAllocationStatus is the status for an GameServerAllocation resource

GameServerMetadata

(Appears on: GameServerAllocationStatus)

GameServerMetadata is the metadata from the allocated game server at allocation time

GameServerSelector

(Appears on: GameServerAllocationSpec)

GameServerSelector contains all the filter options for selecting a GameServer for allocation.

ListAction

(Appears on: GameServerAllocationSpec)

ListAction is an optional action that can be performed on a List at allocation.

ListSelector

(Appears on: GameServerSelector)

ListSelector is the filter options for a GameServer based on List available capacity and/or the existence of a value in a List.

MetaPatch

(Appears on: GameServerAllocationSpec)

MetaPatch is the metadata used to patch the GameServer metadata on allocation

MultiClusterSetting

(Appears on: GameServerAllocationSpec)

MultiClusterSetting specifies settings for multi-cluster allocation.

PlayerSelector

(Appears on: GameServerSelector)

PlayerSelector is the filter options for a GameServer based on player counts

autoscaling.agones.dev/v1

Package v1 is the v1 version of the API.

• FleetAutoscaler

FleetAutoscaler

FleetAutoscaler is the data structure for a FleetAutoscaler resource

BufferPolicy

(Appears on: FleetAutoscalerPolicy)

BufferPolicy controls the desired behavior of the buffer policy.

CounterPolicy

(Appears on: FleetAutoscalerPolicy)

CounterPolicy controls the desired behavior of the Counter autoscaler policy.

FixedIntervalSync

(Appears on: FleetAutoscalerSync)

FixedIntervalSync controls the desired behavior of the fixed interval based sync.

FleetAutoscaleRequest

(Appears on: FleetAutoscaleReview)

FleetAutoscaleRequest defines the request to webhook autoscaler endpoint

FleetAutoscaleResponse

(Appears on: FleetAutoscaleReview)

FleetAutoscaleResponse defines the response of webhook autoscaler endpoint

FleetAutoscaleReview

FleetAutoscaleReview is passed to the webhook with a populated Request value, and then returned with a populated Response.

FleetAutoscalerPolicy

(Appears on: FleetAutoscalerSpec)

FleetAutoscalerPolicy describes how to scale a fleet

FleetAutoscalerPolicyType (string alias)

(Appears on: FleetAutoscalerPolicy)

FleetAutoscalerPolicyType is the policy for autoscaling for a given Fleet

FleetAutoscalerSpec

(Appears on: FleetAutoscaler)

FleetAutoscalerSpec is the spec for a Fleet Scaler

FleetAutoscalerStatus

(Appears on: FleetAutoscaler)

FleetAutoscalerStatus defines the current status of a FleetAutoscaler

FleetAutoscalerSync

(Appears on: FleetAutoscalerSpec)

FleetAutoscalerSync describes when to sync a fleet

FleetAutoscalerSyncType (string alias)

(Appears on: FleetAutoscalerSync)

FleetAutoscalerSyncType is the sync strategy for a given Fleet

ListPolicy

(Appears on: FleetAutoscalerPolicy)

ListPolicy controls the desired behavior of the List autoscaler policy.

WebhookPolicy

(Appears on: FleetAutoscalerPolicy)

WebhookPolicy controls the desired behavior of the webhook policy. It contains the description of the webhook autoscaler service used to form url which is accessible inside the cluster

multicluster.agones.dev/v1

Package v1 is the v1 version of the API.

• GameServerAllocationPolicy

GameServerAllocationPolicy

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

ClusterConnectionInfo

(Appears on: GameServerAllocationPolicySpec)

ClusterConnectionInfo defines the connection information for a cluster

ConnectionInfoIterator

ConnectionInfoIterator an iterator on ClusterConnectionInfo

GameServerAllocationPolicySpec

(Appears on: GameServerAllocationPolicy)

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

agones.dev/v1

Package v1 is the v1 version of the API.

• Fleet
• GameServer
• GameServerSet

Fleet

Fleet is the data structure for a Fleet resource

GameServer

GameServer is the data structure for a GameServer resource. It is worth noting that while there is a GameServerStatus Status entry for the GameServer, it is not defined as a subresource - unlike Fleet and other Code Blind resources. This is so that we can retain the ability to change multiple aspects of a GameServer in a single atomic operation, which is particularly useful for operations such as allocation.

GameServerSet

GameServerSet is the data structure for a set of GameServers. This matches philosophically with the relationship between Deployments and ReplicaSets

AggregatedCounterStatus

(Appears on: FleetStatus, GameServerSetStatus)

AggregatedCounterStatus stores total and allocated Counter tracking values

AggregatedListStatus

(Appears on: FleetStatus, GameServerSetStatus)

AggregatedListStatus stores total and allocated List tracking values

AggregatedPlayerStatus

(Appears on: FleetStatus, GameServerSetStatus)

AggregatedPlayerStatus stores total player tracking values

AllocationOverflow

(Appears on: FleetSpec, GameServerSetSpec)

AllocationOverflow specifies what labels and/or annotations to apply on Allocated GameServers if the desired number of the underlying GameServerSet drops below the number of Allocated GameServers attached to it.

CounterStatus

(Appears on: GameServerSpec, GameServerStatus)

CounterStatus stores the current counter values and maximum capacity

Eviction

(Appears on: GameServerSpec, GameServerStatus)

Eviction specifies the eviction tolerance of the GameServer

EvictionSafe (string alias)

(Appears on: Eviction)

EvictionSafe specified whether the game server supports termination via SIGTERM

FleetSpec

(Appears on: Fleet)

FleetSpec is the spec for a Fleet

FleetStatus

(Appears on: Fleet, FleetAutoscaleRequest)

FleetStatus is the status of a Fleet

GameServerPort

(Appears on: GameServerSpec)

GameServerPort defines a set of Ports that are to be exposed via the GameServer

GameServerSetSpec

(Appears on: GameServerSet)

GameServerSetSpec the specification for GameServerSet

GameServerSetStatus

(Appears on: GameServerSet)

GameServerSetStatus is the status of a GameServerSet

GameServerSpec

(Appears on: GameServer, GameServerTemplateSpec)

GameServerSpec is the spec for a GameServer resource

GameServerState (string alias)

(Appears on: GameServerSelector, GameServerStatus)

GameServerState is the state for the GameServer

GameServerStatus

(Appears on: GameServer)

GameServerStatus is the status for a GameServer resource

GameServerStatusPort

(Appears on: GameServerAllocationStatus, GameServerStatus)

GameServerStatusPort shows the port that was allocated to a GameServer.

GameServerTemplateSpec

(Appears on: FleetSpec, GameServerSetSpec)

GameServerTemplateSpec is a template for GameServers

Health

(Appears on: GameServerSpec)

Health configures health checking on the GameServer

ListStatus

(Appears on: GameServerSpec, GameServerStatus)

ListStatus stores the current list values and maximum capacity

PlayerStatus

(Appears on: GameServerStatus)

PlayerStatus stores the current player capacity values

PlayersSpec

(Appears on: GameServerSpec)

PlayersSpec tracks the initial player capacity

PortPolicy (string alias)

(Appears on: GameServerPort)

PortPolicy is the port policy for the GameServer

Priority

(Appears on: FleetSpec, GameServerAllocationSpec, GameServerSetSpec)

Priority is a sorting option for GameServers with Counters or Lists based on the Capacity.

SdkServer

(Appears on: GameServerSpec)

SdkServer specifies parameters for the Code Blind SDK Server sidecar container

SdkServerLogLevel (string alias)

(Appears on: SdkServer)

SdkServerLogLevel is the log level for SDK server (sidecar) logs

Generated with gen-crd-api-reference-docs.