Agones – Reference

Docs: GameServer Specification

Thu, 03 Jan 2019 03:58:48 +0000

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 Agones 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/agones-images/examples/simple-game-server:0.31
        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 Agones 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.

Note

The GameServer resource does not support updates. If you need to make regular updates to the GameServer spec, consider using a Fleet.

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, Agones 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 and Pod.Status.podIPs (to allow a direct pod access), representing all known ways to reach the GameServer over the network.

To choose address from addresses, Agones 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. (PodIP is not considered for 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.

Docs: Fleet Specification

Thu, 03 Jan 2019 03:58:52 +0000

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-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/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%
  # [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: rooms # The name of the Counter. No impact if no GameServer found.
  #   order: Descending # Default is "Ascending" so smaller available capacity will be removed first on down scaling.
  # - type: List # Sort by a “List”
  #   key: players # The name of the List. No impact if no GameServer found.
  #   order: Ascending # Default is "Ascending" so smaller available 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/agones-images/examples/simple-game-server:0.31

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%
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: Agones maximizes resource utilization by trying to populate nodes that are already in use before allocating GameServers to other nodes.
  - Distributed: Agones 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 available capacity is preferred. “Ascending” would be smaller available 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.

Docs: GameServerAllocation Specification

Sun, 07 Jul 2019 03:58:52 +0000

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:

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]
  # `Priorities` configuration alters the order in which `GameServers` are searched for matches to the configured `selectors`.
  #
  # Priority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first.
  #
  # For `Packed` strategy sorting, this priority list will be the tie-breaker within the least utilised infrastructure, to ensure optimal
  # infrastructure usage while also allowing some custom prioritisation of `GameServers`.
  #
  # For `Distributed` strategy sorting, the entire selection of `GameServers` will be sorted by this priority list to provide the
  # order that `GameServers` will be allocated by.
  # Optional.
  # priorities:
  # - type: Counter  # 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) alters the priority by which game GameServers are allocated by available capacity.
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.
Counters (Alpha, “CountsAndLists” feature flag) is a map of CounterStatus of the game server at allocation time.
Lists (Alpha, “CountsAndLists” feature flag) is a map of ListStatus of the game server at allocation time.

Info

For performance reasons, the query cache for a GameServerAllocation is eventually consistent.

Usually, the cache is populated practically immediately on GameServer change, but under high load of the Kubernetes control plane, it may take some time for updates to GameServer selectable features to be populated into the cache (although this doesn’t affect the atomicity of the Allocation operation).

While Agones will do a small series of retries when an allocatable GameServer is not available in its cache, depending on your game requirements, it may be worth implementing your own more extend retry mechanism for Allocation requests for high load scenarios.

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.

Docs: Fleet Autoscaler Specification

Thu, 03 Jan 2019 03:58:55 +0000

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 available 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: rooms
      # 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 available 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: players
      # 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.

Docs: Agones Kubernetes API

Mon, 01 Jan 0001 00:00:00 +0000

Packages:

multicluster.agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types:

GameServerAllocationPolicy

GameServerAllocationPolicy

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

Field Description

apiVersion
string multicluster.agones.dev/v1

kind
string GameServerAllocationPolicy

metadata
Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
GameServerAllocationPolicySpec

`priority` int32
`weight` int
`connectionInfo` ClusterConnectionInfo

ClusterConnectionInfo

(Appears on: GameServerAllocationPolicySpec)

ClusterConnectionInfo defines the connection information for a cluster

Field	Description
`clusterName` string	Optional: the name of the targeted cluster
`allocationEndpoints` []string	The endpoints for the allocator service in the targeted cluster. If the AllocationEndpoints is not set, the allocation happens on local cluster. If there are multiple endpoints any of the endpoints that can handle allocation request should suffice
`secretName` string	The name of the secret that contains TLS client certificates to connect the allocator server in the targeted cluster
`namespace` string	The cluster namespace from which to allocate gameservers
`serverCa` []byte	The PEM encoded server CA, used by the allocator client to authenticate the remote server.

ConnectionInfoIterator

ConnectionInfoIterator an iterator on ClusterConnectionInfo

Field	Description
`currPriority` int	currPriority Current priority index from the orderedPriorities
`orderedPriorities` []int32	orderedPriorities list of ordered priorities
`priorityToCluster` map[int32]map[string][]agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy*	priorityToCluster Map of priority to cluster-policies map
`clusterBlackList` map[string]bool	clusterBlackList the cluster blacklist for the clusters that has already returned

GameServerAllocationPolicySpec

(Appears on: GameServerAllocationPolicy)

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

Field	Description
`priority` int32
`weight` int
`connectionInfo` ClusterConnectionInfo

agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types:

Fleet

Fleet is the data structure for a Fleet resource

Field Description

apiVersion
string agones.dev/v1

kind
string Fleet

metadata
Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
FleetSpec

`replicas` int32	Replicas are the number of GameServers that should be in this set. Defaults to 0.
`allocationOverflow` AllocationOverflow	(Optional) [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`
`strategy` Kubernetes apps/v1.DeploymentStrategy	Deployment strategy
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”.
`priorities` []Priority	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] `Priorities` configuration alters scale down logic in Fleets based on the configured available capacity order under that key. Priority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first. For `Packed` strategy scale down, this priority list will be the tie-breaker within the node, to ensure optimal infrastructure usage while also allowing some custom prioritisation of `GameServers`. For `Distributed` strategy scale down, the entire `Fleet` will be sorted by this priority list to provide the order of `GameServers` to delete on scale down.
`template` GameServerTemplateSpec	Template the GameServer template to apply for this Fleet

status
FleetStatus

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 Agones 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.

Field Description

apiVersion
string agones.dev/v1

kind
string GameServer

metadata
Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
GameServerSpec

`container` string	Container specifies which Pod container is the game server. Only required if there is more than one container defined
`ports` []GameServerPort	Ports are the array of ports that can be exposed via the game server
`health` Health	Health configures health checking
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”
`sdkServer` SdkServer	SdkServer specifies parameters for the Agones SDK Server sidecar container
`template` Kubernetes core/v1.PodTemplateSpec	Template describes the Pod that will be created for the GameServer
`players` PlayersSpec	(Optional) (Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
`counters` map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus	(Optional) (Alpha, CountsAndLists feature flag) Counters provides the configuration for tracking of int64 values against a GameServer. Keys must be declared at GameServer creation time.
`lists` map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus	(Optional) (Alpha, CountsAndLists feature flag) Lists provides the configuration for tracking of lists of up to 1000 values against a GameServer. Keys must be declared at GameServer creation time.
`eviction` Eviction	(Optional) Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

status
GameServerStatus

GameServerSet

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

Field Description

apiVersion
string agones.dev/v1

kind
string GameServerSet

metadata
Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
GameServerSetSpec

`replicas` int32	Replicas are the number of GameServers that should be in this set
`allocationOverflow` AllocationOverflow	(Optional) [Stage: Beta] [FeatureFlag:FleetAllocationOverflow] Labels and Annotations to apply to GameServers when the number of Allocated GameServers drops below the desired replicas on the underlying `GameServerSet`
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”.
`priorities` []Priority	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] `Priorities` configuration alters scale down logic in Fleets based on the configured available capacity order under that key. Priority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first. For `Packed` strategy scale down, this priority list will be the tie-breaker within the node, to ensure optimal infrastructure usage while also allowing some custom prioritisation of `GameServers`. For `Distributed` strategy scale down, the entire `Fleet` will be sorted by this priority list to provide the order of `GameServers` to delete on scale down.
`template` GameServerTemplateSpec	Template the GameServer template to apply for this GameServerSet

status
GameServerSetStatus

AggregatedCounterStatus

(Appears on: FleetStatus, GameServerSetStatus)

AggregatedCounterStatus stores total and allocated Counter tracking values

Field	Description
`allocatedCount` int64
`allocatedCapacity` int64
`count` int64
`capacity` int64

AggregatedListStatus

(Appears on: FleetStatus, GameServerSetStatus)

AggregatedListStatus stores total and allocated List tracking values

Field	Description
`allocatedCount` int64
`allocatedCapacity` int64
`count` int64
`capacity` int64

AggregatedPlayerStatus

(Appears on: FleetStatus, GameServerSetStatus)

AggregatedPlayerStatus stores total player tracking values

Field	Description
`count` int64
`capacity` int64

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.

Field	Description
`labels` map[string]string	(Optional) Labels to be applied to the `GameServer`
`annotations` map[string]string	(Optional) Annotations to be applied to the `GameServer`

CounterStatus

(Appears on: GameServerSpec, GameServerStatus)

CounterStatus stores the current counter values and maximum capacity

Field	Description
`count` int64
`capacity` int64

Eviction

(Appears on: GameServerSpec, GameServerStatus)

Eviction specifies the eviction tolerance of the GameServer

Field	Description
`safe` EvictionSafe	Game server supports termination via SIGTERM: - Always: Allow eviction for both Cluster Autoscaler and node drain for upgrades - OnUpgrade: Allow eviction for upgrades alone - Never (default): Pod should run to completion

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

Field	Description
`replicas` int32	Replicas are the number of GameServers that should be in this set. Defaults to 0.
`allocationOverflow` AllocationOverflow	(Optional) [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`
`strategy` Kubernetes apps/v1.DeploymentStrategy	Deployment strategy
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”.
`priorities` []Priority	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] `Priorities` configuration alters scale down logic in Fleets based on the configured available capacity order under that key. Priority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first. For `Packed` strategy scale down, this priority list will be the tie-breaker within the node, to ensure optimal infrastructure usage while also allowing some custom prioritisation of `GameServers`. For `Distributed` strategy scale down, the entire `Fleet` will be sorted by this priority list to provide the order of `GameServers` to delete on scale down.
`template` GameServerTemplateSpec	Template the GameServer template to apply for this Fleet

FleetStatus

(Appears on: Fleet, FleetAutoscaleRequest)

FleetStatus is the status of a Fleet

Field	Description
`replicas` int32	Replicas the total number of current GameServer replicas
`readyReplicas` int32	ReadyReplicas are the number of Ready GameServer replicas
`reservedReplicas` int32	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.
`allocatedReplicas` int32	AllocatedReplicas are the number of Allocated GameServer replicas
`players` AggregatedPlayerStatus	(Optional) [Stage:Alpha] [FeatureFlag:PlayerTracking] Players are the current total player capacity and count for this Fleet
`counters` map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus	(Optional) (Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter count for this Fleet.
`lists` map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus	(Optional) (Alpha, CountsAndLists feature flag) Lists provides aggregated List capacityv and List values for this Fleet.

GameServerPort

(Appears on: GameServerSpec)

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

Field	Description
`name` string	Name is the descriptive name of the port
`portPolicy` PortPolicy	PortPolicy defines the policy for how the HostPort is populated. Dynamic port will allocate a HostPort within the selected MIN_PORT and MAX_PORT range passed to the controller at installation time. When `Static` portPolicy is specified, `HostPort` is required, to specify the port that game clients will connect to
`container` string	(Optional) Container is the name of the container on which to open the port. Defaults to the game server container.
`containerPort` int32	ContainerPort is the port that is being opened on the specified container’s process
`hostPort` int32	HostPort the port exposed on the host for clients to connect to
`protocol` Kubernetes core/v1.Protocol	Protocol is the network protocol being used. Defaults to UDP. TCP and TCPUDP are other options.

GameServerSetSpec

(Appears on: GameServerSet)

GameServerSetSpec the specification for GameServerSet

Field	Description
`replicas` int32	Replicas are the number of GameServers that should be in this set
`allocationOverflow` AllocationOverflow	(Optional) [Stage: Beta] [FeatureFlag:FleetAllocationOverflow] Labels and Annotations to apply to GameServers when the number of Allocated GameServers drops below the desired replicas on the underlying `GameServerSet`
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”.
`priorities` []Priority	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] `Priorities` configuration alters scale down logic in Fleets based on the configured available capacity order under that key. Priority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first. For `Packed` strategy scale down, this priority list will be the tie-breaker within the node, to ensure optimal infrastructure usage while also allowing some custom prioritisation of `GameServers`. For `Distributed` strategy scale down, the entire `Fleet` will be sorted by this priority list to provide the order of `GameServers` to delete on scale down.
`template` GameServerTemplateSpec	Template the GameServer template to apply for this GameServerSet

GameServerSetStatus

(Appears on: GameServerSet)

GameServerSetStatus is the status of a GameServerSet

Field	Description
`replicas` int32	Replicas is the total number of current GameServer replicas
`readyReplicas` int32	ReadyReplicas is the number of Ready GameServer replicas
`reservedReplicas` int32	ReservedReplicas is the number of Reserved GameServer replicas
`allocatedReplicas` int32	AllocatedReplicas is the number of Allocated GameServer replicas
`shutdownReplicas` int32	ShutdownReplicas is the number of Shutdown GameServers replicas
`players` AggregatedPlayerStatus	(Optional) [Stage:Alpha] [FeatureFlag:PlayerTracking] Players is the current total player capacity and count for this GameServerSet
`counters` map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus	(Optional) (Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter count for this GameServerSet.
`lists` map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus	(Optional) (Alpha, CountsAndLists feature flag) Lists provides aggregated List capacity and List values for this GameServerSet.

GameServerSpec

(Appears on: GameServer, GameServerTemplateSpec)

GameServerSpec is the spec for a GameServer resource

Field	Description
`container` string	Container specifies which Pod container is the game server. Only required if there is more than one container defined
`ports` []GameServerPort	Ports are the array of ports that can be exposed via the game server
`health` Health	Health configures health checking
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”
`sdkServer` SdkServer	SdkServer specifies parameters for the Agones SDK Server sidecar container
`template` Kubernetes core/v1.PodTemplateSpec	Template describes the Pod that will be created for the GameServer
`players` PlayersSpec	(Optional) (Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
`counters` map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus	(Optional) (Alpha, CountsAndLists feature flag) Counters provides the configuration for tracking of int64 values against a GameServer. Keys must be declared at GameServer creation time.
`lists` map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus	(Optional) (Alpha, CountsAndLists feature flag) Lists provides the configuration for tracking of lists of up to 1000 values against a GameServer. Keys must be declared at GameServer creation time.
`eviction` Eviction	(Optional) Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

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

Field	Description
`state` GameServerState	GameServerState is the current state of a GameServer, e.g. Creating, Starting, Ready, etc
`ports` []GameServerStatusPort
`address` string
`addresses` []Kubernetes core/v1.NodeAddress	(Optional) Addresses is the array of addresses at which the GameServer can be reached; copy of Node.Status.addresses.
`nodeName` string
`reservedUntil` Kubernetes meta/v1.Time
`players` PlayerStatus	(Optional) [Stage:Alpha] [FeatureFlag:PlayerTracking]
`counters` map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus	(Optional) (Alpha, CountsAndLists feature flag) Counters and Lists provides the configuration for generic tracking features.
`lists` map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus	(Optional)
`eviction` Eviction	(Optional) Eviction specifies the eviction tolerance of the GameServer.

GameServerStatusPort

(Appears on: GameServerAllocationStatus, GameServerStatus)

GameServerStatusPort shows the port that was allocated to a GameServer.

Field	Description
`name` string
`port` int32

GameServerTemplateSpec

(Appears on: FleetSpec, GameServerSetSpec)

GameServerTemplateSpec is a template for GameServers

Field Description

metadata
Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
GameServerSpec

`container` string	Container specifies which Pod container is the game server. Only required if there is more than one container defined
`ports` []GameServerPort	Ports are the array of ports that can be exposed via the game server
`health` Health	Health configures health checking
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”
`sdkServer` SdkServer	SdkServer specifies parameters for the Agones SDK Server sidecar container
`template` Kubernetes core/v1.PodTemplateSpec	Template describes the Pod that will be created for the GameServer
`players` PlayersSpec	(Optional) (Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
`counters` map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus	(Optional) (Alpha, CountsAndLists feature flag) Counters provides the configuration for tracking of int64 values against a GameServer. Keys must be declared at GameServer creation time.
`lists` map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus	(Optional) (Alpha, CountsAndLists feature flag) Lists provides the configuration for tracking of lists of up to 1000 values against a GameServer. Keys must be declared at GameServer creation time.
`eviction` Eviction	(Optional) Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

Health

(Appears on: GameServerSpec)

Health configures health checking on the GameServer

Field	Description
`disabled` bool	Disabled is whether health checking is disabled or not
`periodSeconds` int32	PeriodSeconds is the number of seconds each health ping has to occur in
`failureThreshold` int32	FailureThreshold how many failures in a row constitutes unhealthy
`initialDelaySeconds` int32	InitialDelaySeconds initial delay before checking health

ListStatus

(Appears on: GameServerSpec, GameServerStatus)

ListStatus stores the current list values and maximum capacity

Field	Description
`capacity` int64
`values` []string

PlayerStatus

(Appears on: GameServerStatus)

PlayerStatus stores the current player capacity values

Field	Description
`count` int64
`capacity` int64
`ids` []string

PlayersSpec

(Appears on: GameServerSpec)

PlayersSpec tracks the initial player capacity

Field	Description
`initialCapacity` int64

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 available capacity, i.e. the current Capacity value, minus either the Count value or List length.

Field	Description
`type` string	Type: Sort by a “Counter” or a “List”.
`key` string	Key: The name of the Counter or List. If not found on the GameServer, has no impact.
`order` string	Order: Sort by “Ascending” or “Descending”. “Descending” a bigger available capacity is preferred. “Ascending” would be smaller available capacity is preferred.

SdkServer

(Appears on: GameServerSpec)

SdkServer specifies parameters for the Agones SDK Server sidecar container

Field	Description
`logLevel` SdkServerLogLevel	LogLevel for SDK server (sidecar) logs. Defaults to “Info”
`grpcPort` int32	GRPCPort is the port on which the SDK Server binds the gRPC server to accept incoming connections
`httpPort` int32	HTTPPort is the port on which the SDK Server binds the HTTP gRPC gateway server to accept incoming connections

SdkServerLogLevel (`string` alias)

(Appears on: SdkServer)

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

allocation.agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types:

GameServerAllocation

GameServerAllocation

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

Field Description

apiVersion
string allocation.agones.dev/v1

kind
string GameServerAllocation

metadata
Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
GameServerAllocationSpec

`multiClusterSetting` MultiClusterSetting	MultiClusterPolicySelector if specified, multi-cluster policies are applied. Otherwise, allocation will happen locally.
`required` GameServerSelector	Deprecated: use field Selectors instead. If Selectors is set, this field is ignored. Required is the GameServer selector from which to choose GameServers from. Defaults to all GameServers.
`preferred` []GameServerSelector	Deprecated: use field Selectors instead. If Selectors is set, this field is ignored. Preferred is an ordered list of preferred GameServer 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.
`priorities` []Priority	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] `Priorities` configuration alters the order in which `GameServers` are searched for matches to the configured `selectors`. Priority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first. For `Packed` strategy sorting, this priority list will be the tie-breaker within the least utilised infrastructure, to ensure optimal infrastructure usage while also allowing some custom prioritisation of `GameServers`. For `Distributed` strategy sorting, the entire selection of `GameServers` will be sorted by this priority list to provide the order that `GameServers` will be allocated by.
`selectors` []GameServerSelector	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. Note: This field can only be set if neither Required or Preferred is set.
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”.
`metadata` MetaPatch	MetaPatch is optional custom metadata that is added to the game server at allocation You can use this to tell the server necessary session data
`counters` map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] Counter actions to perform during allocation.
`lists` map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] List actions to perform during allocation.

status
GameServerAllocationStatus

CounterAction

(Appears on: GameServerAllocationSpec)

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

Field	Description
`action` string	(Optional) Action must to either “Increment” or “Decrement” the Counter’s Count. Must also define the Amount.
`amount` int64	(Optional) Amount is the amount to increment or decrement the Count. Must be a positive integer.
`capacity` int64	(Optional) Capacity is the amount to update the maximum capacity of the Counter to this number. Min 0, Max int64.

CounterSelector

(Appears on: GameServerSelector)

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

Field	Description
`minCount` int64	(Optional) MinCount is the minimum current value. Defaults to 0.
`maxCount` int64	(Optional) MaxCount is the maximum current value. Defaults to 0, which translates as max(in64).
`minAvailable` int64	(Optional) MinAvailable specifies the minimum capacity (current capacity - current count) available on a GameServer. Defaults to 0.
`maxAvailable` int64	(Optional) MaxAvailable specifies the maximum capacity (current capacity - current count) available on a GameServer. Defaults to 0, which translates to max(int64).

GameServerAllocationSpec

(Appears on: GameServerAllocation)

GameServerAllocationSpec is the spec for a GameServerAllocation

Field	Description
`multiClusterSetting` MultiClusterSetting	MultiClusterPolicySelector if specified, multi-cluster policies are applied. Otherwise, allocation will happen locally.
`required` GameServerSelector	Deprecated: use field Selectors instead. If Selectors is set, this field is ignored. Required is the GameServer selector from which to choose GameServers from. Defaults to all GameServers.
`preferred` []GameServerSelector	Deprecated: use field Selectors instead. If Selectors is set, this field is ignored. Preferred is an ordered list of preferred GameServer 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.
`priorities` []Priority	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] `Priorities` configuration alters the order in which `GameServers` are searched for matches to the configured `selectors`. Priority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first. For `Packed` strategy sorting, this priority list will be the tie-breaker within the least utilised infrastructure, to ensure optimal infrastructure usage while also allowing some custom prioritisation of `GameServers`. For `Distributed` strategy sorting, the entire selection of `GameServers` will be sorted by this priority list to provide the order that `GameServers` will be allocated by.
`selectors` []GameServerSelector	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. Note: This field can only be set if neither Required or Preferred is set.
`scheduling` agones.dev/agones/pkg/apis.SchedulingStrategy	Scheduling strategy. Defaults to “Packed”.
`metadata` MetaPatch	MetaPatch is optional custom metadata that is added to the game server at allocation You can use this to tell the server necessary session data
`counters` map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] Counter actions to perform during allocation.
`lists` map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] List actions to perform during allocation.

GameServerAllocationState (`string` alias)

(Appears on: GameServerAllocationStatus)

GameServerAllocationState is the Allocation state

GameServerAllocationStatus

(Appears on: GameServerAllocation)

GameServerAllocationStatus is the status for an GameServerAllocation resource

Field	Description
`state` GameServerAllocationState	GameServerState is the current state of an GameServerAllocation, e.g. Allocated, or UnAllocated
`gameServerName` string
`ports` []GameServerStatusPort
`address` string
`addresses` []Kubernetes core/v1.NodeAddress
`nodeName` string
`source` string	If the allocation is from a remote cluster, Source is the endpoint of the remote agones-allocator. Otherwise, Source is “local”
`metadata` GameServerMetadata

GameServerMetadata

(Appears on: GameServerAllocationStatus)

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

Field	Description
`labels` map[string]string
`annotations` map[string]string

GameServerSelector

(Appears on: GameServerAllocationSpec)

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

Field	Description
`LabelSelector` Kubernetes meta/v1.LabelSelector	(Members of `LabelSelector` are embedded into this type.) See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
`gameServerState` 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.
`players` PlayerSelector	(Optional) [Stage:Alpha] [FeatureFlag:PlayerAllocationFilter] Players provides a filter on minimum and maximum values for player capacity when retrieving a GameServer through Allocation. Defaults to no limits.
`counters` map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterSelector	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] Counters provides filters on minimum and maximum values for a Counter’s count and available capacity when retrieving a GameServer through Allocation. Defaults to no limits.
`lists` map[string]agones.dev/agones/pkg/apis/allocation/v1.ListSelector	(Optional) [Stage: Alpha] [FeatureFlag:CountsAndLists] Lists provides filters on minimum and maximum values for List capacity, and for the existence of a value in a List, when retrieving a GameServer through Allocation. Defaults to no limits.

ListAction

(Appears on: GameServerAllocationSpec)

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

Field	Description
`addValues` []string	(Optional) AddValues appends values to a List’s Values array. Any duplicate values will be ignored.
`capacity` int64	(Optional) Capacity updates the maximum capacity of the Counter to this number. Min 0, Max 1000.

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.

Field	Description
`containsValue` string	(Optional) ContainsValue says to only match GameServers who has this value in the list. Defaults to “”, which is all.
`minAvailable` int64	(Optional) MinAvailable specifies the minimum capacity (current capacity - current count) available on a GameServer. Defaults to 0.
`maxAvailable` int64	(Optional) MaxAvailable specifies the maximum capacity (current capacity - current count) available on a GameServer. Defaults to 0, which is translated as max(int64).

MetaPatch

(Appears on: GameServerAllocationSpec)

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

Field	Description
`labels` map[string]string
`annotations` map[string]string

MultiClusterSetting

(Appears on: GameServerAllocationSpec)

MultiClusterSetting specifies settings for multi-cluster allocation.

Field	Description
`enabled` bool
`policySelector` Kubernetes meta/v1.LabelSelector

PlayerSelector

(Appears on: GameServerSelector)

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

Field	Description
`minAvailable` int64
`maxAvailable` int64

autoscaling.agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types:

FleetAutoscaler

FleetAutoscaler

FleetAutoscaler is the data structure for a FleetAutoscaler resource

Field Description

apiVersion
string autoscaling.agones.dev/v1

kind
string FleetAutoscaler

metadata
Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
FleetAutoscalerSpec

`fleetName` string
`policy` FleetAutoscalerPolicy	Autoscaling policy
`sync` FleetAutoscalerSync	(Optional) Sync defines when FleetAutoscalers runs autoscaling

status
FleetAutoscalerStatus

BufferPolicy

(Appears on: FleetAutoscalerPolicy)

BufferPolicy controls the desired behavior of the buffer policy.

Field	Description
`maxReplicas` int32	MaxReplicas is the maximum amount of replicas that the fleet may have. It must be bigger than both MinReplicas and BufferSize
`minReplicas` int32	MinReplicas is the minimum amount of replicas that the fleet must have If zero, it is ignored. If non zero, it must be smaller than MaxReplicas and bigger than BufferSize
`bufferSize` k8s.io/apimachinery/pkg/util/intstr.IntOrString	BufferSize defines how many replicas the autoscaler tries to have ready all the time Value can be an absolute number (ex: 5) or a percentage of desired gs instances (ex: 15%) Absolute number is calculated from percentage by rounding up. Example: when this is set to 20%, the autoscaler will make sure that 20% of the fleet’s game server replicas are ready. When this is set to 20, the autoscaler will make sure that there are 20 available game servers Must be bigger than 0 Note: by “ready” we understand in this case “non-allocated”; this is done to ensure robustness and computation stability in different edge case (fleet just created, not enough capacity in the cluster etc)

CounterPolicy

(Appears on: FleetAutoscalerPolicy)

CounterPolicy controls the desired behavior of the Counter autoscaler policy.

Field	Description
`key` string	Key is the name of the Counter. Required field.
`maxCapacity` int64	MaxCapacity is the maximum aggregate Counter total capacity across the fleet. MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
`minCapacity` int64	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.
`bufferSize` k8s.io/apimachinery/pkg/util/intstr.IntOrString	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 desired gs instances (ex: 5%). An absolute number is calculated from percentage by rounding up. Must be bigger than 0. Required field.

FixedIntervalSync

(Appears on: FleetAutoscalerSync)

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

Field	Description
`seconds` int32	Seconds defines how often we run fleet autoscaling in seconds

FleetAutoscaleRequest

(Appears on: FleetAutoscaleReview)

FleetAutoscaleRequest defines the request to webhook autoscaler endpoint

Field	Description
`uid` k8s.io/apimachinery/pkg/types.UID	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.
`name` string	Name is the name of the Fleet being scaled
`namespace` string	Namespace is the namespace associated with the request (if any).
`status` FleetStatus	The Fleet’s status values

FleetAutoscaleResponse

(Appears on: FleetAutoscaleReview)

FleetAutoscaleResponse defines the response of webhook autoscaler endpoint

Field	Description
`uid` k8s.io/apimachinery/pkg/types.UID	UID is an identifier for the individual request/response. This should be copied over from the corresponding FleetAutoscaleRequest.
`scale` bool	Set to false if no scaling should occur to the Fleet
`replicas` int32	The targeted replica count

FleetAutoscaleReview

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

Field	Description
`request` FleetAutoscaleRequest
`response` FleetAutoscaleResponse

FleetAutoscalerPolicy

(Appears on: FleetAutoscalerSpec)

FleetAutoscalerPolicy describes how to scale a fleet

Field	Description
`type` FleetAutoscalerPolicyType	Type of autoscaling policy.
`buffer` BufferPolicy	(Optional) Buffer policy config params. Present only if FleetAutoscalerPolicyType = Buffer.
`webhook` WebhookPolicy	(Optional) Webhook policy config params. Present only if FleetAutoscalerPolicyType = Webhook.
`counter` CounterPolicy	(Optional) [Stage:Alpha] [FeatureFlag:CountsAndLists] Counter policy config params. Present only if FleetAutoscalerPolicyType = Counter.
`list` ListPolicy	(Optional) [Stage:Alpha] [FeatureFlag:CountsAndLists] List policy config params. Present only if FleetAutoscalerPolicyType = List.

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

Field	Description
`fleetName` string
`policy` FleetAutoscalerPolicy	Autoscaling policy
`sync` FleetAutoscalerSync	(Optional) Sync defines when FleetAutoscalers runs autoscaling

FleetAutoscalerStatus

(Appears on: FleetAutoscaler)

FleetAutoscalerStatus defines the current status of a FleetAutoscaler

Field	Description
`currentReplicas` int32	CurrentReplicas is the current number of gameserver replicas of the fleet managed by this autoscaler, as last seen by the autoscaler
`desiredReplicas` int32	DesiredReplicas is the desired number of gameserver replicas of the fleet managed by this autoscaler, as last calculated by the autoscaler
`lastScaleTime` Kubernetes meta/v1.Time	(Optional) lastScaleTime is the last time the FleetAutoscaler scaled the attached fleet,
`ableToScale` bool	AbleToScale indicates that we can access the target fleet
`scalingLimited` bool	ScalingLimited indicates that the calculated scale would be above or below the range defined by MinReplicas and MaxReplicas, and has thus been capped.

FleetAutoscalerSync

(Appears on: FleetAutoscalerSpec)

FleetAutoscalerSync describes when to sync a fleet

Field	Description
`type` FleetAutoscalerSyncType	Type of autoscaling sync.
`fixedInterval` FixedIntervalSync	(Optional) FixedInterval config params. Present only if FleetAutoscalerSyncType = FixedInterval.

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.

Field	Description
`key` string	Key is the name of the List. Required field.
`maxCapacity` int64	MaxCapacity is the maximum aggregate List total capacity across the fleet. MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
`minCapacity` int64	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.
`bufferSize` k8s.io/apimachinery/pkg/util/intstr.IntOrString	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.

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

Field Description

url
string

(Optional)

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. The host might be resolved via external DNS in some apiservers (e.g., kube-apiserver cannot resolve in-cluster DNS as that would be a layering violation). host may also be an IP address.

Please note that using localhost or 127.0.0.1 as a host is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installs are likely to be non-portable, i.e., not easy to turn up in a new cluster.

The scheme must be “https”; the URL must begin with “https://”.

A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier.

Attempting to use a user or basic auth e.g. “user:password@” is not allowed. Fragments (“#…”) and query parameters (“?…”) are not allowed, either.

service
Kubernetes admissionregistration/v1.ServiceReference

(Optional)

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.

caBundle
[]byte

(Optional)

caBundle is a PEM encoded CA bundle which will be used to validate the webhook’s server certificate. If unspecified, system trust roots on the apiserver are used.

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

Agones – Reference

Docs: GameServer Specification

Note

Stable Network ID

GameServer State Diagram

Primary Address vs Addresses

Docs: Fleet Specification

Fleet Scale Subresource Specification

Docs: GameServerAllocation Specification

Info

Next Steps:

Docs: Fleet Autoscaler Specification

Ready Buffer Autoscaling

Counter and List Autoscaling

Webhook Autoscaling

Spec Field Reference

Webhook Endpoint Specification

Docs: Agones Kubernetes API

multicluster.agones.dev/v1

GameServerAllocationPolicy

ClusterConnectionInfo

ConnectionInfoIterator

GameServerAllocationPolicySpec

agones.dev/v1

Fleet

GameServer

GameServerSet

AggregatedCounterStatus

AggregatedListStatus

AggregatedPlayerStatus

AllocationOverflow

CounterStatus

Eviction

EvictionSafe (string alias)

FleetSpec

FleetStatus

GameServerPort

GameServerSetSpec

GameServerSetStatus

GameServerSpec

GameServerState (string alias)

GameServerStatus

GameServerStatusPort

GameServerTemplateSpec

Health

ListStatus

PlayerStatus

PlayersSpec

PortPolicy (string alias)

Priority

SdkServer

SdkServerLogLevel (string alias)

allocation.agones.dev/v1

GameServerAllocation

CounterAction

CounterSelector

GameServerAllocationSpec

GameServerAllocationState (string alias)

GameServerAllocationStatus

GameServerMetadata

GameServerSelector

ListAction

ListSelector

MetaPatch

MultiClusterSetting

PlayerSelector

autoscaling.agones.dev/v1

FleetAutoscaler

BufferPolicy

CounterPolicy

FixedIntervalSync

FleetAutoscaleRequest

FleetAutoscaleResponse

FleetAutoscaleReview

FleetAutoscalerPolicy

FleetAutoscalerPolicyType (string alias)

FleetAutoscalerSpec

FleetAutoscalerStatus

FleetAutoscalerSync

FleetAutoscalerSyncType (string alias)

EvictionSafe (`string` alias)

GameServerState (`string` alias)

PortPolicy (`string` alias)

SdkServerLogLevel (`string` alias)

GameServerAllocationState (`string` alias)

FleetAutoscalerPolicyType (`string` alias)

FleetAutoscalerSyncType (`string` alias)