Merge branch 'main' into sdk-matrixes

examples/counterfleetautoscaler.yaml

@@ -32,17 +32,16 @@ spec:
   policy:
     type: Counter  # Counter based autoscaling
     counter:
-      # The name of the Counter.
-      # Required.
+      # Key is the name of the Counter. Required field.
       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 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
-      # 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 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
-      # Maximum aggregate counter capacity that can be provided by this FleetAutoscaler.
-      # Required.
+      # 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

examples/gameserver.yaml

@@ -90,18 +90,18 @@ spec:
   # [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
+  # 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) Maximum value for the counter. 0 is max(int64).
   #   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.
+  #     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:
+  #     values: # initial set of values in a list.
   #       - room1
   #       - room2
   #       - room3

examples/gameserverallocation.yaml

@@ -52,12 +52,18 @@ spec:
       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:
+      # 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:
-      #     minAvailable: 1
-      #     maxAvailable: 10
+      #     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

examples/listfleetautoscaler.yaml

@@ -32,18 +32,17 @@ spec:
   policy:
     type: List  # List based autoscaling.
     list:
-      # The name of the List.
-      # Required.
+      # Key is the name of the List. Required field.
       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 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
-      # 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 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
-      # Maximum aggregate list capacity that can be provided by this FleetAutoscaler.
-      # Required.
+      # 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

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

@@ -163,6 +163,18 @@ 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: Counter # Sort by a “Counter”
+  #   key: player # The name of the Counter. No impact if no GameServer found.
+  #   order: Descending # Default is "Ascending" so smaller capacity will be removed first on down scaling.
+  # - type: List # Sort by a “List”
+  #   key: room # The name of the List. No impact if no GameServer found.
+  #   order: Ascending # Default is "Ascending" so smaller capacity will be removed first on down scaling.
+  #      
   template:
     # GameServer metadata
     metadata:
@@ -226,6 +238,10 @@ The `spec` field is the actual `Fleet` specification and it is composed as follo
   - `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 Capacity is preferred. “Ascending” would be smaller Capacity is preferred.
 - `template` a full `GameServer` configuration template.
    See the [GameServer]({{< relref "gameserver.md" >}}) reference for all available fields.
 {{% /feature %}}

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

@@ -79,11 +79,69 @@ 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:
+      # Key is the name of the Counter. Required field.
+      key: players
+      # BufferSize is the size of a buffer of counted items that are available in the Fleet (available capacity).
+      # Value can be an absolute number (ex: 5) or a percentage of the Counter available capacity (ex: 5%).
+      # An absolute number is calculated from percentage by rounding up. Must be bigger than 0. Required field.
+      bufferSize: 5
+      # MinCapacity is the minimum aggregate Counter total capacity across the fleet.
+      # If BufferSize is specified as a percentage, MinCapacity is required and cannot be 0.
+      # If non zero, MinCapacity must be smaller than MaxCapacity and must be greater than or equal to BufferSize.
+      minCapacity: 10
+      # MaxCapacity is the maximum aggregate Counter total capacity across the fleet.
+      # MaxCapacity must be greater than or equal to both MinCapacity and BufferSize. Required field.
+      maxCapacity: 100
+```
+
+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:
+      # Key is the name of the List. Required field.
+      key: rooms
+      # BufferSize is the size of a buffer based on the List capacity that is available over the current
+      # aggregate List length in the Fleet (available capacity).
+      # It can be specified either as an absolute value (i.e. 5) or percentage format (i.e. 5%).
+      # Must be bigger than 0. Required field.
+      bufferSize: 5
+      # MinCapacity is the minimum aggregate List total capacity across the fleet.
+      # If BufferSize is specified as a percentage, MinCapacity is required must be greater than 0.
+      # If non zero, MinCapacity must be smaller than MaxCapacity and must be greater than or equal to BufferSize.
+      minCapacity: 10
+      # MaxCapacity is the maximum aggregate List total capacity across the fleet.
+      # MaxCapacity must be greater than or equal to both MinCapacity and BufferSize. Required field.
+      maxCapacity: 100
+```
+{{% /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 `FleetAutoscaler` with the custom group `autoscaling.agones.dev` 
 and API version `v1`
 
+{{% feature expiryVersion="1.37.0" %}}
 The `spec` field is the actual `FleetAutoscaler` specification and it is composed as follows:
 
 - `fleetName` is name of the fleet to attach to and control. Must be an existing `Fleet` in the same namespace
@@ -115,7 +173,53 @@ The `spec` field is the actual `FleetAutoscaler` specification and it is compose
   - `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 auto scaling
+{{% /feature %}}
 
+{{% feature publishVersion="1.37.0" %}}
+The `spec` field is the actual `FleetAutoscaler` specification and it 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 {{< ghlink href="examples/autoscaler-webhook/autoscaler-service.yaml" >}}(see example){{< /ghlink >}}
+                      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 auto scaling
+{{% /feature %}}
 # Webhook Endpoint Specification
 
 Webhook endpoint is used to delegate the scaling logic to a separate pod or server.