Counters & Lists landing page and doc improvements (#3649)

* Counters & Lists landing page and doc improvements

The primary detail of this PR is to implement a Guide > Counters and
Lists documentation landing page to give end users documentation on how
to use all the variety of touch points of Counters and Lists.

This does sprawl out a little, as in part of this process, this also
touched on:
* Links and warnings from other pages that should link to this landing
page.
* Found a bunch of minor fixes that needed doing, with both
documentation and example bugs and updates just for consistency.
* Implemented some small changes in terminology (primarily total
capacity -> available capacity), which aligns the implementations and
the documentation.
* Fixes and updates to CRD and Go data structure documentation that
goes along with the above.
* Found some example content that was missing.

Work on #2716

* Add in Fleet prioritisation section.

* Review updates.

* Add warning for Fleet priorities, until next release.

examples/counterfleetautoscaler.yaml

@@ -33,7 +33,7 @@ spec:
     type: Counter  # Counter based autoscaling
     counter:
       # Key is the name of the Counter. Required field.
-      key: players
+      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.

examples/fleet.yaml

@@ -66,7 +66,7 @@ spec:
   # [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.
+  # - type: Counter  # 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.
   #

examples/gameserverallocation.yaml

@@ -85,3 +85,34 @@ spec:
       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.

examples/listfleetautoscaler.yaml

@@ -33,7 +33,7 @@ spec:
     type: List  # List based autoscaling.
     list:
       # Key is the name of the List. Required field.
-      key: rooms
+      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%).

install/helm/agones/templates/crds/fleet.yaml

@@ -128,7 +128,7 @@ spec:
                         description: The name of the Counter or List. If not found on the GameServer, those GameServer with the key will have priority over those that do not.
                       order:
                         type: string
-                        description: Ascending or Descending sort order. Default is "Ascending" so remove smaller total capacity first. "Descending" would remove larger total capacity first.
+                        description: Ascending or Descending sort order. Default is "Ascending" so remove smaller available capacity first. "Descending" would remove larger available capacity first.
                         enum:
                           - Ascending
                           - Descending

install/yaml/install.yaml

@@ -298,7 +298,7 @@ spec:
                         description: The name of the Counter or List. If not found on the GameServer, those GameServer with the key will have priority over those that do not.
                       order:
                         type: string
-                        description: Ascending or Descending sort order. Default is "Ascending" so remove smaller total capacity first. "Descending" would remove larger total capacity first.
+                        description: Ascending or Descending sort order. Default is "Ascending" so remove smaller available capacity first. "Descending" would remove larger available capacity first.
                         enum:
                           - Ascending
                           - Descending

pkg/allocation/go/allocation.swagger.json

@@ -190,14 +190,14 @@
             "type": "object",
             "$ref": "#/definitions/allocationPriority"
           },
-          "description": "(Alpha, CountsAndLists feature flag) The first Priority on the array of Priorities is the most\nimportant for sorting. The allocator will use the first priority for sorting GameServers in the\nSelector set, and will only use any following priority for tie-breaking during sort.\nImpacts which GameServer is checked first."
+          "description": "[Stage: Alpha]\n[FeatureFlag:CountsAndLists]\n`Priorities` configuration alters the order in which `GameServers` are searched for matches to the configured `selectors`.\n\nPriority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first.\n\nFor `Packed` strategy sorting, this priority list will be the tie-breaker within the least utilised infrastructure, to ensure optimal\ninfrastructure usage while also allowing some custom prioritisation of `GameServers`.\n\nFor `Distributed` strategy sorting, the entire selection of `GameServers` will be sorted by this priority list to provide the\norder that `GameServers` will be allocated by."
         },
         "counters": {
           "type": "object",
           "additionalProperties": {
             "$ref": "#/definitions/allocationCounterAction"
           },
-          "description": "(Alpha, CountsAndLists feature flag) Counters and Lists provide a set of actions to perform\non Counters and Lists during allocation."
+          "description": "[Stage: Alpha]\n[FeatureFlag:CountsAndLists]\nCounters and Lists provide a set of actions to perform\non Counters and Lists during allocation."
         },
         "lists": {
           "type": "object",

pkg/apis/agones/v1/common.go

@@ -175,14 +175,15 @@ func (ao *AllocationOverflow) Apply(gs *GameServer) {
 	}
 }
 
-// Priority is a sorting option for GameServers with Counters or Lists based on the Capacity.
+// 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.
 type Priority struct {
 	// Type: Sort by a "Counter" or a "List".
 	Type string `json:"type"`
 	// Key: The name of the Counter or List. If not found on the GameServer, has no impact.
 	Key string `json:"key"`
-	// Order: Sort by "Ascending" or "Descending". "Descending" a bigger Capacity is preferred.
-	// "Ascending" would be smaller Capacity is preferred.
+	// Order: Sort by "Ascending" or "Descending". "Descending" a bigger available capacity is preferred.
+	// "Ascending" would be smaller available capacity is preferred.
 	Order string `json:"order"`
 }
 

pkg/apis/agones/v1/fleet.go

@@ -69,10 +69,17 @@ type FleetSpec struct {
 	Strategy appsv1.DeploymentStrategy `json:"strategy"`
 	// Scheduling strategy. Defaults to "Packed".
 	Scheduling apis.SchedulingStrategy `json:"scheduling"`
-	// (Alpha, CountsAndLists feature flag) The first Priority on the array of Priorities is the most
-	// important for sorting. The Fleetautoscaler will use the first priority for sorting GameServers
-	// by total Capacity in the Fleet and acts as a tie-breaker after sorting the game servers by
-	// State and Strategy. Impacts scale down logic.
+	// [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.
 	// +optional
 	Priorities []Priority `json:"priorities,omitempty"`
 	// Template the GameServer template to apply for this Fleet

pkg/apis/agones/v1/gameserverset.go

@@ -67,10 +67,17 @@ type GameServerSetSpec struct {
 	AllocationOverflow *AllocationOverflow `json:"allocationOverflow,omitempty"`
 	// Scheduling strategy. Defaults to "Packed".
 	Scheduling apis.SchedulingStrategy `json:"scheduling,omitempty"`
-	// (Alpha, CountsAndLists feature flag) The first Priority on the array of Priorities is the most
-	// important for sorting. The Fleetautoscaler will use the first priority for sorting GameServers
-	// by total Capacity in the Fleet and acts as a tie-breaker after sorting the game servers by
-	// State and Strategy. Impacts scale down logic.
+	// [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.
 	// +optional
 	Priorities []Priority `json:"priorities,omitempty"`
 	// Template the GameServer template to apply for this GameServerSet

pkg/apis/allocation/v1/gameserverallocation.go

@@ -85,10 +85,17 @@ type GameServerAllocationSpec struct {
 	// This is useful for things like smoke testing of new game servers.
 	Preferred []GameServerSelector `json:"preferred,omitempty" hash:"ignore"`
 
-	// (Alpha, CountsAndLists feature flag) The first Priority on the array of Priorities is the most
-	// important for sorting. The allocator will use the first priority for sorting GameServers by
-	// available Capacity in the Selector set. Acts as a tie-breaker after sorting the game servers
-	// by State and Strategy Packed. Impacts which GameServer is checked first.
+	// [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 []agonesv1.Priority `json:"priorities,omitempty"`
 
@@ -105,10 +112,14 @@ type GameServerAllocationSpec struct {
 	// You can use this to tell the server necessary session data
 	MetaPatch MetaPatch `json:"metadata,omitempty" hash:"ignore"`
 
-	// (Alpha, CountsAndLists feature flag) Counter actions to perform during allocation.
+	// [Stage: Alpha]
+	// [FeatureFlag:CountsAndLists]
+	// Counter actions to perform during allocation.
 	// +optional
 	Counters map[string]CounterAction `json:"counters,omitempty" hash:"ignore"`
-	// (Alpha, CountsAndLists feature flag) List actions to perform during allocation.
+	// [Stage: Alpha]
+	// [FeatureFlag:CountsAndLists]
+	// List actions to perform during allocation.
 	// +optional
 	Lists map[string]ListAction `json:"lists,omitempty" hash:"ignore"`
 }
@@ -128,12 +139,16 @@ type GameServerSelector struct {
 	// Players provides a filter on minimum and maximum values for player capacity when retrieving a GameServer
 	// through Allocation. Defaults to no limits.
 	Players *PlayerSelector `json:"players,omitempty"`
-	// (Alpha, CountsAndLists feature flag) Counters provides filters on minimum and maximum values
+	// [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.
 	// +optional
 	Counters map[string]CounterSelector `json:"counters,omitempty"`
-	// (Alpha, CountsAndLists feature flag) Lists provides filters on minimum and maximum values
+	// [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.
 	// +optional

proto/allocation/allocation.proto

@@ -79,13 +79,22 @@ message AllocationRequest {
   // Note: This field can only be set if neither Required or Preferred is set.
   repeated GameServerSelector gameServerSelectors = 8;
 
-  // (Alpha, CountsAndLists feature flag) The first Priority on the array of Priorities is the most
-	// important for sorting. The allocator will use the first priority for sorting GameServers in the
-	// Selector set, and will only use any following priority for tie-breaking during sort.
-	// Impacts which GameServer is checked first.
+  // [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.
 	repeated Priority priorities = 9;
 
-  // (Alpha, CountsAndLists feature flag) Counters and Lists provide a set of actions to perform
+  // [Stage: Alpha]
+  // [FeatureFlag:CountsAndLists]
+  // Counters and Lists provide a set of actions to perform
 	// on Counters and Lists during allocation.
   map<string, CounterAction> counters = 10;
   map<string, ListAction> lists = 11;

sdks/rust/proto/allocation/allocation.proto

@@ -79,13 +79,22 @@ message AllocationRequest {
   // Note: This field can only be set if neither Required or Preferred is set.
   repeated GameServerSelector gameServerSelectors = 8;
 
-  // (Alpha, CountsAndLists feature flag) The first Priority on the array of Priorities is the most
-	// important for sorting. The allocator will use the first priority for sorting GameServers in the
-	// Selector set, and will only use any following priority for tie-breaking during sort.
-	// Impacts which GameServer is checked first.
+  // [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.
 	repeated Priority priorities = 9;
 
-  // (Alpha, CountsAndLists feature flag) Counters and Lists provide a set of actions to perform
+  // [Stage: Alpha]
+  // [FeatureFlag:CountsAndLists]
+  // Counters and Lists provide a set of actions to perform
 	// on Counters and Lists during allocation.
   map<string, CounterAction> counters = 10;
   map<string, ListAction> lists = 11;

site/content/en/docs/Guides/Client SDKs/_index.md

@@ -346,13 +346,15 @@ Convenience function, which retrieves the length of the results of [`Alpha().Get
 
 ### Player Tracking
 
-{{< alpha title="Player Tracking" gate="PlayerTracking" >}}
+{{% pageinfo color="info" %}}
+[Counters and Lists]({{< ref "/docs/Guides/counters-and-lists.md" >}}) will eventually replace the Alpha functionality
+of Player Tracking, which will subsequently be removed from Agones.
 
-{{< alert title="Warning" color="warning">}}
-[Counters and Lists](#counters-and-lists) will eventually replace the Alpha functionality of Player Tracking, which will subsequently be
-removed from Agones. If you are currently using this Alpha feature, we would love for you to test (and ideally migrate
-to!) this new functionality to ensure it will meet all your needs.
-{{< /alert >}}
+If you are currently using this Alpha feature, we would love for you to test (and ideally migrate to!) this new
+functionality to Counters and Lists to ensure it meet all your needs.
+{{% /pageinfo %}}
+
+{{< alpha title="Player Tracking" gate="PlayerTracking" >}}
 
 #### Alpha().PlayerConnect(playerID)