CountersAndLists in Reference Documentation

site/content/en/docs/Reference/fleet.md

@@ -163,6 +163,15 @@ spec:
       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: List  # Whether a Counter or a List.
+  #   key: rooms  # The name of the Counter or List.
+  #   order: Ascending  # Default is "Ascending" so smaller capacity will be removed first on down scaling.
+  #      
   template:
     # GameServer metadata
     metadata:

site/content/en/docs/Reference/fleetautoscaler.md

@@ -47,6 +47,65 @@ spec:
       seconds: 30
 ```
 
+{{% feature publishVersion="1.37.0" %}}
+Counter-based `FleetAutoscaler` specification below and in the {{< ghlink href="examples/counterfleetautoscaler.yaml" >}}example folder{{< /ghlink >}}:
+
+```yaml
+apiVersion: autoscaling.agones.dev/v1
+kind: FleetAutoscaler
+metadata:
+  name: fleet-autoscaler-counter
+spec:
+  fleetName: fleet-example
+  policy:
+    type: Counter  # Counter based autoscaling
+    counter:
+      # The name of the Counter.
+      # Required.
+      key: players
+      # Size of a buffer of counted items that are available in the Fleet (available capacity).
+      # bufferSize can be specified either in absolute (i.e. 5) or percentage format (i.e. 5%).
+      # Required.
+      bufferSize: 5
+      # Minimum aggregate counter capacity that can be provided by this FleetAutoscaler.
+      # If minCapacity is not specified, the effective minimum capacity will be bufferSize.
+      # When bufferSize in percentage format is used, minCapacity should be set and more than 0.
+      minCapacity: 10
+      # Maximum aggregate counter capacity that can be provided by this FleetAutoscaler.
+      # Required.
+      maxCapacity: 100
+```
+
+List-based `FleetAutoscaler` specification below and in the {{< ghlink href="examples/listfleetautoscaler.yaml" >}}example folder{{< /ghlink >}}:
+
+```yaml
+apiVersion: autoscaling.agones.dev/v1
+kind: FleetAutoscaler
+metadata:
+  name: fleet-autoscaler-list
+spec:
+  fleetName: fleet-example
+  policy:
+    type: List  # List based autoscaling.
+    list:
+      # The name of the List.
+      # Required.
+      key: rooms
+      # Size of a buffer based on the list capacity that is available over the current aggregate
+      # list length in the Fleet (available capacity).
+      # bufferSize can be specified either in absolute (i.e. 5) or percentage format (i.e. 5%)
+      # Required.
+      bufferSize: 5
+      # Minimum aggregate list capacity that can be provided by this FleetAutoscaler.
+      # If minCapacity is not specified, the effective minimum capacity will be bufferSize.
+      # When bufferSize in percentage format is used, minCapacity should be set and more than 0.
+      minCapacity: 10
+      # Maximum aggregate list capacity that can be provided by this FleetAutoscaler.
+      # Required.
+      maxCapacity: 100
+```
+{{% /feature %}}
+
 Or for Webhook FleetAutoscaler below and in {{< ghlink href="examples/webhookfleetautoscaler.yaml" >}}example folder{{< /ghlink >}}:
 
 ```yaml

site/content/en/docs/Reference/gameserver.md

 - `players` (Alpha, behind "PlayerTracking" feature gate), sets this GameServer's initial player capacity 
 - `players` (Alpha, behind "PlayerTracking" feature gate), sets this GameServer's initial player capacity 
@@ -9,6 +9,7 @@ description: >
 
 A full GameServer specification is available below and in the {{< ghlink href="examples/gameserver.yaml" >}}example folder{{< /ghlink >}} for reference :
 
+{{% feature expiryVersion="1.37.0" %}}
 ```yaml
 apiVersion: "agones.dev/v1"
 kind: GameServer
@@ -96,7 +97,118 @@ spec:
       # nodeSelector:
       #   kubernetes.io/os: windows
 ```
+{{% /feature %}}
 
+{{% feature publishVersion="1.37.0" %}}
+```yaml
+apiVersion: "agones.dev/v1"
+kind: GameServer
+# GameServer Metadata
+# {{< k8s-api-version href="#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:
+  #   games:
+  #     count: 1
+  #     capacity: 100
+  #   sessions:
+  #     count:  # Count and/or capacity must be listed (but may be nil) otherwise the counter will by dropped by the CRD schema.
+  # lists:
+  #   players:
+  #     capacity:  # Capacity and/or values must be listed (but may be nil) otherwise the list will be dropped by the CRD schema.
+  #   rooms:
+  #     capacity: 333
+  #     values:
+  #       - room1
+  #       - room2
+  #       - room3
+  #  
+  # Pod template configuration
+  # {{< k8s-api-version href="#podtemplate-v1-core" >}}
+  template:
+    # pod metadata. Name & Namespace is overwritten
+    metadata:
+      labels:
+        myspeciallabel: myspecialvalue
+    # Pod Specification
+    spec:
+      containers:
+      - name: simple-game-server
+        image:  {{< example-image >}}
+        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
+```
+{{% /feature %}}
 Since Agones defines a new [Custom Resources Definition (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources/) 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](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)

site/content/en/docs/Reference/gameserverallocation.md

@@ -10,6 +10,121 @@ weight: 30
 A full `GameServerAllocation` specification is available below and in the
 {{< ghlink href="/examples/gameserverallocation.yaml" >}}example folder{{< /ghlink >}} for reference:
 
+{{% feature expiryVersion="1.37.0" %}}
+{{< tabpane >}}
+  {{< tab header="selectors" lang="yaml" >}}
+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: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
+  {{< /tab >}}
+  {{< tab header="required & preferred (deprecated)" lang="yaml" >}}
+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
+  {{< /tab >}}
+{{< /tabpane >}}  
+{{% /feature %}}
+
+{{% feature publishVersion="1.37.0" %}}
 {{< tabpane >}}
   {{< tab header="selectors" lang="yaml" >}}
 apiVersion: "allocation.agones.dev/v1"
@@ -41,6 +156,14 @@ spec:
       # label/annotation/player selectors to retrieve an already Allocated GameServer.
       gameServerState: Ready
       # [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:
+      #   players:
+      #     minAvailable: 1
+      #     maxAvailable: 10
+      # [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.
@@ -121,6 +244,7 @@ spec:
       map:  garden22
   {{< /tab >}}
 {{< /tabpane >}}  
+{{% /feature %}}
 
 The `spec` field is the actual `GameServerAllocation` specification, and it is composed as follows: