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 googleforgames#2716

examples/counterfleetautoscaler.yaml

@@ -33,15 +33,15 @@ 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.
       bufferSize: 5
-      # MinCapacity is the minimum aggregate Counter total capacity across the fleet.
+      # MinCapacity is the minimum aggregate Counter available 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 is the maximum aggregate Counter available capacity across the fleet.
       # MaxCapacity must be greater than or equal to both MinCapacity and BufferSize. Required field.
       maxCapacity: 100

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,16 +33,16 @@ 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%).
       # Must be bigger than 0. Required field.
       bufferSize: 5
-      # MinCapacity is the minimum aggregate List total capacity across the fleet.
+      # MinCapacity is the minimum aggregate List available 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 is the maximum aggregate List available capacity across the fleet.
       # MaxCapacity must be greater than or equal to both MinCapacity and BufferSize. Required field.
       maxCapacity: 100

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

pkg/apis/autoscaling/v1/fleetautoscaler.go

@@ -158,11 +158,11 @@ type CounterPolicy struct {
 	// Key is the name of the Counter. Required field.
 	Key string `json:"key"`
 
-	// MaxCapacity is the maximum aggregate Counter total capacity across the fleet.
+	// MaxCapacity is the maximum aggregate Counter available capacity across the fleet.
 	// MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
 	MaxCapacity int64 `json:"maxCapacity"`
 
-	// MinCapacity is the minimum aggregate Counter total capacity across the fleet.
+	// MinCapacity is the minimum aggregate Counter available capacity across the fleet.
 	// If zero, MinCapacity is ignored.
 	// If non zero, MinCapacity must be smaller than MaxCapacity and bigger than BufferSize.
 	MinCapacity int64 `json:"minCapacity"`
@@ -179,11 +179,11 @@ type ListPolicy struct {
 	// Key is the name of the List. Required field.
 	Key string `json:"key"`
 
-	// MaxCapacity is the maximum aggregate List total capacity across the fleet.
+	// MaxCapacity is the maximum aggregate List available capacity across the fleet.
 	// MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
 	MaxCapacity int64 `json:"maxCapacity"`
 
-	// MinCapacity is the minimum aggregate List total capacity across the fleet.
+	// MinCapacity is the minimum aggregate List available capacity across the fleet.
 	// If zero, it is ignored.
 	// If non zero, it must be smaller than MaxCapacity and bigger than BufferSize.
 	MinCapacity int64 `json:"minCapacity"`

pkg/fleetautoscalers/fleetautoscalers.go

@@ -300,7 +300,7 @@ func applyCounterOrListPolicy(c *autoscalingv1.CounterPolicy, l *autoscalingv1.L
 		bufferSize = l.BufferSize
 	}
 
-	// Checks if we've limited by TOTAL capacity
+	// Checks if we've limited by AVAILABLE capacity
 	limited, scale := isLimited(aggCapacity, minCapacity, maxCapacity)
 
 	// Total current number of Replicas
@@ -319,7 +319,7 @@ func applyCounterOrListPolicy(c *autoscalingv1.CounterPolicy, l *autoscalingv1.L
 		if err != nil {
 			return 0, false, err
 		}
-		// The desired TOTAL capacity based on the Aggregated Allocated Counts (see applyBufferPolicy for explanation)
+		// The desired AVAILABLE capacity based on the Aggregated Allocated Counts (see applyBufferPolicy for explanation)
 		desiredCapacity := int64(math.Ceil(float64(aggAllocatedCount*100) / float64(100-bufferPercent)))
 		// Convert into a desired AVAILABLE capacity aka the buffer
 		buffer = desiredCapacity - aggAllocatedCount