From 607d22f3af381972f4cd3f0520dd70874426f35e Mon Sep 17 00:00:00 2001 From: Mark Mandel Date: Wed, 14 Feb 2024 14:41:27 +1100 Subject: [PATCH] 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 --- examples/counterfleetautoscaler.yaml | 6 +- examples/fleet.yaml | 2 +- examples/gameserverallocation.yaml | 31 + examples/listfleetautoscaler.yaml | 6 +- install/helm/agones/templates/crds/fleet.yaml | 2 +- install/yaml/install.yaml | 2 +- pkg/allocation/go/allocation.pb.go | 19 +- pkg/allocation/go/allocation.swagger.json | 4 +- pkg/apis/agones/v1/common.go | 7 +- pkg/apis/agones/v1/fleet.go | 15 +- pkg/apis/agones/v1/gameserverset.go | 15 +- .../allocation/v1/gameserverallocation.go | 31 +- pkg/apis/autoscaling/v1/fleetautoscaler.go | 8 +- pkg/fleetautoscalers/fleetautoscalers.go | 4 +- proto/allocation/allocation.proto | 19 +- sdks/rust/proto/allocation/allocation.proto | 19 +- .../en/docs/Guides/Client SDKs/_index.md | 14 +- .../en/docs/Guides/counters-and-lists.md | 330 + site/content/en/docs/Guides/metrics.md | 2 + .../content/en/docs/Guides/player-tracking.md | 8 + .../Reference/agones_crd_api_reference.html | 7419 +++++++++-------- site/content/en/docs/Reference/fleet.md | 11 +- .../en/docs/Reference/fleetautoscaler.md | 24 +- .../en/docs/Reference/gameserverallocation.md | 59 +- test/e2e/fleetautoscaler_test.go | 2 +- 25 files changed, 4281 insertions(+), 3778 deletions(-) create mode 100644 site/content/en/docs/Guides/counters-and-lists.md diff --git a/examples/counterfleetautoscaler.yaml b/examples/counterfleetautoscaler.yaml index 6a301a151c..6daeacf9a8 100644 --- a/examples/counterfleetautoscaler.yaml +++ b/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 diff --git a/examples/fleet.yaml b/examples/fleet.yaml index c759ec2d7b..eb7ad3beac 100644 --- a/examples/fleet.yaml +++ b/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. # diff --git a/examples/gameserverallocation.yaml b/examples/gameserverallocation.yaml index 540bb6259a..0295865196 100644 --- a/examples/gameserverallocation.yaml +++ b/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. diff --git a/examples/listfleetautoscaler.yaml b/examples/listfleetautoscaler.yaml index f5d1a06aff..deef962ee5 100644 --- a/examples/listfleetautoscaler.yaml +++ b/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 diff --git a/install/helm/agones/templates/crds/fleet.yaml b/install/helm/agones/templates/crds/fleet.yaml index 2cd843f5ef..1c68f1a474 100644 --- a/install/helm/agones/templates/crds/fleet.yaml +++ b/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 diff --git a/install/yaml/install.yaml b/install/yaml/install.yaml index c5dac51e2f..593a1d32c5 100644 --- a/install/yaml/install.yaml +++ b/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 diff --git a/pkg/allocation/go/allocation.pb.go b/pkg/allocation/go/allocation.pb.go index e774b28d0a..f7944dede4 100644 --- a/pkg/allocation/go/allocation.pb.go +++ b/pkg/allocation/go/allocation.pb.go @@ -272,12 +272,21 @@ type AllocationRequest struct { // 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. GameServerSelectors []*GameServerSelector `protobuf:"bytes,8,rep,name=gameServerSelectors,proto3" json:"gameServerSelectors,omitempty"` - // (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. Priorities []*Priority `protobuf:"bytes,9,rep,name=priorities,proto3" json:"priorities,omitempty"` - // (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. Counters map[string]*CounterAction `protobuf:"bytes,10,rep,name=counters,proto3" json:"counters,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` Lists map[string]*ListAction `protobuf:"bytes,11,rep,name=lists,proto3" json:"lists,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` diff --git a/pkg/allocation/go/allocation.swagger.json b/pkg/allocation/go/allocation.swagger.json index 19124cca38..e9dea02596 100644 --- a/pkg/allocation/go/allocation.swagger.json +++ b/pkg/allocation/go/allocation.swagger.json @@ -162,14 +162,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", diff --git a/pkg/apis/agones/v1/common.go b/pkg/apis/agones/v1/common.go index 9e709e0b0b..c1bd11f9bc 100644 --- a/pkg/apis/agones/v1/common.go +++ b/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"` } diff --git a/pkg/apis/agones/v1/fleet.go b/pkg/apis/agones/v1/fleet.go index 876a397d50..8204465f38 100644 --- a/pkg/apis/agones/v1/fleet.go +++ b/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 diff --git a/pkg/apis/agones/v1/gameserverset.go b/pkg/apis/agones/v1/gameserverset.go index ec1cc89292..f1f6103ffb 100644 --- a/pkg/apis/agones/v1/gameserverset.go +++ b/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 diff --git a/pkg/apis/allocation/v1/gameserverallocation.go b/pkg/apis/allocation/v1/gameserverallocation.go index 02b91f7d63..a515eb4a29 100644 --- a/pkg/apis/allocation/v1/gameserverallocation.go +++ b/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 diff --git a/pkg/apis/autoscaling/v1/fleetautoscaler.go b/pkg/apis/autoscaling/v1/fleetautoscaler.go index c1ec15bfd3..f287a54c30 100644 --- a/pkg/apis/autoscaling/v1/fleetautoscaler.go +++ b/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"` diff --git a/pkg/fleetautoscalers/fleetautoscalers.go b/pkg/fleetautoscalers/fleetautoscalers.go index f1df1d8bbf..66c102feca 100644 --- a/pkg/fleetautoscalers/fleetautoscalers.go +++ b/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 diff --git a/proto/allocation/allocation.proto b/proto/allocation/allocation.proto index dee50f6599..9a63bd0736 100644 --- a/proto/allocation/allocation.proto +++ b/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 counters = 10; map lists = 11; diff --git a/sdks/rust/proto/allocation/allocation.proto b/sdks/rust/proto/allocation/allocation.proto index dee50f6599..9a63bd0736 100644 --- a/sdks/rust/proto/allocation/allocation.proto +++ b/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 counters = 10; map lists = 11; diff --git a/site/content/en/docs/Guides/Client SDKs/_index.md b/site/content/en/docs/Guides/Client SDKs/_index.md index 3a4ff378fe..20b88ce471 100644 --- a/site/content/en/docs/Guides/Client SDKs/_index.md +++ b/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) diff --git a/site/content/en/docs/Guides/counters-and-lists.md b/site/content/en/docs/Guides/counters-and-lists.md new file mode 100644 index 0000000000..cd1ab34fa7 --- /dev/null +++ b/site/content/en/docs/Guides/counters-and-lists.md @@ -0,0 +1,330 @@ +--- +title: "GameServer Counters and Lists" +linkTitle: "Counters and Lists" +date: 2024-01-08 +weight: 25 +description: > + Track, allocate and auto-scale based on user defined counters and lists stored on a `GameServer`. +--- + +{{< alpha title="Counters and Lists" gate="CountsAndLists" >}} + +Counters and Lists is provided as a way to track arbitrary integer counter values as well as +lists of values against a `GameServer` by a user provided key. + +Combined with the ability to set and manipulate max capacity values at runtime for each counter and list, allows +Agones to also provide Allocation, Fleet scheduling and Fleet autoscaling based on this functionality, such that it +supports a wide variety of use cases, including, but not limited to: + +* Connected player listing tracking, Allocation filtering and autoscaling based on available capacity. +* Multi-tenant server room counting, Allocation filtering and autoscaling based on available capacity. +* Game specific GameServer weighting on Allocation. +* ...any other use case that requires a list of values or a counter aligned with a GameServer for tracking purposes. + +## Declaration + +All keys for either Counters and Lists must be declared at creation time within the +[GameServerSpec]({{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerSpec" >}}) before being +utilised, and keys cannot be added or deleted from `GameServers` past their initial creation. + +For example, if we want to use a Counter of `rooms` to track the number of game session rooms that exist in +this `GameServer` instance, while also tracking a List of currently connected `players`, we could +implement the following: + +```yaml +apiVersion: agones.dev/v1 +kind: Fleet +metadata: + name: simple-game-server +spec: + replicas: 2 + template: + spec: + ports: + - name: default + containerPort: 7654 + counters: + rooms: # room counter + count: 0 + capacity: 10 + lists: + players: # players list + values: [] + template: + spec: + containers: + - name: simple-game-server + image: {{< example-image >}} +``` + +Both Counters and Lists can have a `capacity` value, which indicated the maximum counter value, or number of items that +can be stored in the list. + +In the above example, the `room` Counter has a capacity of 10, which means that the count cannot go past that value. + +See the [GameServer]({{< ref "/docs/Reference/gameserver.md" >}}) reference for all configurable options. + +## Retrieval + +We now have several ways to retrieve this Counter and List information from a GameServer, depending on your use case. + +### Kubernetes API + +If you wish to retrieve or view current Counter or List values from outside your `GameServer`, you are able to do this +through the Kubernetes API, or similarly through `kubectl`. + +Counter values and capacities for are stored on a `GameServer` resource instance +under [`GameServer.Status.Counters`][gameserverstatus] by key, and [`GameServer.Status.Lists`][gameserverstatus] stores +List value arrays and capacities by key as well. + +Therefore, in the above examples, the `GameServer.Status.Counters[rooms].Count` +and `GameServer.Status.Counters[rooms].Capacity` would have the current Counter value and capacity for the room +counters. + +Subsequently `GameServer.Status.Lists[players].Values` stores the array of values for the list +and `GameServer.Status.Lists[players].Capacity` is the current capacity for the player tracking List. + +Check the API reference for [`GameServerStatus`][gameserverstatus] for all the details on the data structure. + +### SDK + +Counter and Lists values can be accessed through the Agones SDK when that information is required within your game +server process. + +For example, to retrieve the above `room` counter, each language SDK has some implementation of the +[`SDK.Alpha().GetCounterCount("room")`]({{< ref "/docs/Guides/Client SDKs/_index.md#alphagetcountercountkey" >}}) +function +that returns +the current value of the counter. Similarly, to retrieve the `players` list, we can use the +[`SDK.Alpha().GetListValues("players")`]({{< ref "/docs/Guides/Client SDKs/_index.md#alphagetlistvalueskey" >}}) +function. + +The special ability of the SDK retrieval operations, is that is also tracks any modifications that have been made +through the SDK, that have yet to be persisted to the `GameServer`, and will return values with that data included. + +This means that any modifications made to Counters and Lists sent through the SDK can be immediately and atomically +retrieved from the SDK from the game server binary with accurate information without having to wait for it be persisted +to the `GameServer`. + +See the [SDK Guide]({{< ref "/docs/Guides/Client SDKs/_index.md" >}}) for the full set of data retrieval functions +that are available. + +## Manipulation + +We also have several ways to manipulate the Counter and List information stored on a `GameServer` instance, depending on your use case. + +### SDK + +Counter and Lists values can be modified through the Agones SDK when you wish to be able to edit that information +within your game server process. + +For example, to increment the above `room` counter by 1, each language SDK has some implementation of the +[`SDK.Alpha().IncrementCounter("room", 1)`]({{< ref "/docs/Guides/Client SDKs/_index.md#alphaincrementcounterkey-amount" >}}) +function thatincrements the counter by 1. Similarly, to add the value `player1` to the `players` list, we can use the +[`SDK.Alpha().AppendListValue("players", "player1")`]({{< ref "/docs/Guides/Client SDKs/_index.md#alphaappendlistvaluekey-value" >}}) +function. + +See the [SDK Guide]({{< ref "/docs/Guides/Client SDKs/_index.md" >}}) for the full set of modification functions +that are available. + +### Allocation + +When performing a `GameServer` allocation, you may want to manipulate the Counter and/or List information atomically +on a `GameServer` allocation operation. + +For example, you may wish to increment the `room` counter to indicate a new game session has started on the returned +`GameServer` instance, or provide the connecting player information to the `player` list to make that available to +the game server binary before the player connects. + +This can be done through [`GameServerAllocation.Spec.Counters`][gameserverallocation] and +[`GameServerAllocation.Spec.Lists`][gameserverallocation], which provide +[`CounterAction`]({{< ref "/docs/Reference/agones_crd_api_reference.html#allocation.agones.dev/v1.CounterAction" >}}) and +[`ListAction`]({{< ref "/docs/Reference/agones_crd_api_reference.html#allocation.agones.dev/v1.ListAction" >}}) +configuration respectively. + +For example, if on allocation we wished to increment the `room` counter by 1 and add `player1` to the `players` list, +this could be done with the following `GameServerAllocation` specification: + +```yaml +apiVersion: allocation.agones.dev/v1 +kind: GameServerAllocation +spec: + selectors: + - matchLabels: + agones.dev/fleet: simple-game-server + counters: + rooms: + action: Increment + amount: 1 + lists: + players: + addValues: + - player1 +``` + +Counter and List changes made through the `GameServerAllocation` functionality, will be eventually consistent in +their availability via the [SDK retrieval functions](#sdk) for performance reasons. + +Performing these data changes as part of the Allocation also **does not** guarantee that the +counter or list is past its capacity value. In the event that the capacity is exceeded, the allocation will succeed, but +the Counter or List values will not be updated. If you want to ensure there is capacity available for the Allocation +operation, see [Allocation Filtering and Prioritisation](#allocation-filtering-and-prioritisation) below. + +See the [Allocation Reference]({{< ref "/docs/Reference/gameserverallocation.md" >}}) for all the Allocation +configuration options. + +### Kubernetes API + +Counter values and capacities are stored on a `GameServer` resource instance +under [`GameServer.Status.Counters`][gameserverstatus] by key, and [`GameServer.Status.Lists`][gameserverstatus] stores +List value arrays and capacities by key as well. Therefore, they can be modified through the Kubernetes API either +through [Kubernetes client libraries](https://kubernetes.io/docs/reference/using-api/client-libraries/) or manually +through `kubectl edit`. + +Counter and List changes made through the `GameServerAllocation` functionality, will be eventually consistent in +their availability via the [SDK retrieval functions](#sdk) for performance reasons. + +Check out the [Access Agones via the Kubernetes API]({{% relref "access-api.md" %}}) guide for a more in depth guide +on how to interact with Agones resources through the Kubernetes API programmatically. + +## Allocation Filtering and Prioritisation + +Counters and Lists can also be used as filtering properties when performing an allocation through either the +[GameServerAllocation.Spec.Selectors.Counts][gameserverallocation] or +[GameServerAllocation.Spec.Selectors.Lists][gameserverallocation] properties. + +If we want to expand the above example to ensure there is always room for the `room` Counter increment and room +for the `player` List to add `player1`, we can add the following to the `GameServerAllocation` specification: + +```yaml +apiVersion: allocation.agones.dev/v1 +kind: GameServerAllocation +spec: + selectors: + - matchLabels: + agones.dev/fleet: simple-game-server + counters: + rooms: + minAvailable: 1 + lists: + players: + minAvailable: 1 + counters: + rooms: + action: Increment + amount: 1 + lists: + players: + addValues: + - player1 +``` + +Only `GameServer` instances that have a `capacity` value of at least one more than the Counter value, or List length +will be included in the potential allocation result - thereby ensuring that both `room` and `player` operations +will succeed, assuming a GameServer is found. + +This can be combined with the ability to define multiple `selectors` to create quite sophisticated `GameServer` +selection options that can attempt to find the most appropriate `GameServer`. + +See the [Allocation Reference]({{< ref "/docs/Reference/gameserverallocation.md" >}}) for more details. + +The `priorities` block also gives you options to prioritise specific `GameServers` over others when performing an +Allocation, depending on the Allocation Strategy. + +* Packed: The [usual infrastructure optimisation strategy]({{< ref "/docs/Advanced/scheduling-and-autoscaling.md#allocation-scheduling-strategy" >}}) + still applies, but the `priorities` block is used as a tie-breaker within the least utilised infrastructure, to ensure + optimal infrastructure usage while also allowing some custom prioritisation of `GameServers`. +* Distributed: The entire selection of `GameServers` will be sorted by this priority list to provide the + order that `GameServers` will be allocated by. + +For example, if we wanted to select a `GameServer` that had: + +1. At least one `room` available in the GameServer capacity. +2. First check Allocated `GameServers` and falling back to `Ready` `GameServers` if there aren't any. +3. Include general infrastructure optimisation for least usage. +4. And also ensure the `GameServers` that were most full are allocated first (after infrastructure optimisations + where applied). + +We could implement the following `GameServerAllocation`: + +```yaml +apiVersion: allocation.agones.dev/v1 +kind: GameServerAllocation +spec: + scheduling: Packed + # Choose most full `GameServers` first + priorities: + - type: Counter + key: rooms + order: Ascending + selectors: + # First check to see if we can back-fill an already allocated `GameServer` + - gameServerState: Allocated + matchLabels: + agones.dev/fleet: simple-game-server + counters: + rooms: + minAvailable: 1 + # If we can't, then go get a `Ready` `GameServer`. + - gameServerState: Ready + matchLabels: + agones.dev/fleet: simple-game-server + counters: + rooms: + minAvailable: 1 + counters: + rooms: + action: Increment + amount: 1 +``` + +For more details on how Agones implements infrastructure optimisation, see the documentation on +[Scheduling and Autoscaling]({{< ref "/docs/Advanced/scheduling-and-autoscaling.md" >}}). + +## Autoscaling + +Counters and Lists expands on Fleet Autoscaling capabilities, by allowing you to autoscale based on available capacity +across the `Fleet` as a unit, rather than the less granular unit of individual `GameServers` instances. + +This means, we can implement an Autoscaling strategy of "always make sure there are 5 free `rooms` available for new +players at all times" like so: + +```yaml +apiVersion: autoscaling.agones.dev/v1 +kind: FleetAutoscaler +metadata: + name: simple-game-server +spec: + fleetName: fleet-example + policy: + type: Counter + counter: + key: rooms + bufferSize: 5 + maxCapacity: 100 +``` + +See the [Fleet Autoscaling Reference]({{< ref "/docs/Reference/fleetautoscaler.md" >}}) for all the configuration +options. + +## Metrics + +Metrics are exported, using the `key` that the metric is stored under as a label on the metrics, in aggregate across +all `GameServers` within a `Fleet`, exporting aggregate numeric totals for Counters and Lists as gauge metrics. + +| Name | Description | Type | +|-----------------------|------------------------------------------------------------------------------------------|-------| +| agones_fleet_counters | Aggregate Metrics for Counters within a Fleet, including total capacity and count values | gauge | +| agones_fleet_lists | Aggregate Metrics for Lists within a Fleet, including total capacity and List lengths | gauge | + +See [Metrics available]({{< ref "/docs/Guides/metrics.md#metrics-available" >}}) for the full list of available metrics +and how to use them. + +## Next Steps + +* Check out how to access [Agones resource via the Kubernetes API]({{% relref "access-api.md" %}}). +* Have a look at the external [Allocator Service]({{< ref "/docs/Advanced/allocator-service.md" >}}) to make integrating + Allocation into your workflow easier. + +[gameserverstatus]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerStatus" >}} +[gameserverallocation]: {{< ref "/docs/Reference/agones_crd_api_reference.html#allocation.agones.dev/v1.GameServerAllocationSpec" >}} \ No newline at end of file diff --git a/site/content/en/docs/Guides/metrics.md b/site/content/en/docs/Guides/metrics.md index 0cee0350e9..00ceebede5 100644 --- a/site/content/en/docs/Guides/metrics.md +++ b/site/content/en/docs/Guides/metrics.md @@ -51,6 +51,8 @@ Follow the [Google Cloud Monitoring installation steps](#google-cloud-monitoring | agones_gameserver_player_connected_total | The total number of players connected to gameservers (Only available when [player tracking]({{< relref "player-tracking.md" >}}) is enabled) | gauge | | agones_gameserver_player_capacity_total | The available capacity for players on gameservers (Only available when [player tracking]({{< relref "player-tracking.md" >}}) is enabled) | gauge | | agones_fleets_replicas_count | The number of replicas per fleet (total, desired, ready, reserved, allocated) | gauge | +| agones_fleet_counters | Aggregate Metrics for Counters within a Fleet, including total capacity and count values (Only available when [Counters and Lists]({{< relref "counters-and-lists.md" >}})) are enabled) | gauge | +| agones_fleet_lists | Aggregate Metrics for Lists within a Fleet, including total capacity and List lengths (Only available when [Counters and Lists]({{< relref "counters-and-lists.md" >}})) are enabled) | gauge | | agones_fleet_autoscalers_able_to_scale | The fleet autoscaler can access the fleet to scale | gauge | | agones_fleet_autoscalers_buffer_limits | The limits of buffer based fleet autoscalers (min, max) | gauge | | agones_fleet_autoscalers_buffer_size | The buffer size of fleet autoscalers (count or percentage) | gauge | diff --git a/site/content/en/docs/Guides/player-tracking.md b/site/content/en/docs/Guides/player-tracking.md index fa7deafdff..26d38bb567 100644 --- a/site/content/en/docs/Guides/player-tracking.md +++ b/site/content/en/docs/Guides/player-tracking.md @@ -7,6 +7,14 @@ description: > Track player connections, disconnections, counts and capacities through the Agones SDK --- +{{% 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. + +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" >}} ## Managing GameServer Capacities diff --git a/site/content/en/docs/Reference/agones_crd_api_reference.html b/site/content/en/docs/Reference/agones_crd_api_reference.html index 7cb1841359..989b1b0a72 100644 --- a/site/content/en/docs/Reference/agones_crd_api_reference.html +++ b/site/content/en/docs/Reference/agones_crd_api_reference.html @@ -3,13 +3,10 @@ description="Detailed list of Agones Custom Resource Definitions available" +++ -{{% feature expiryVersion="1.37.0" %}} +{{% feature expiryVersion="1.39.0" %}}

Packages:

-

agones.dev/v1

+

allocation.agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types: -

Fleet +

GameServerAllocation

-

Fleet is the data structure for a Fleet resource

+

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

@@ -50,7 +47,7 @@

Fleet string

@@ -59,7 +56,7 @@

Fleet kind
string -

+ @@ -90,43 +87,82 @@

Fleet

-agones.dev/v1 +allocation.agones.dev/v1
FleetGameServerAllocation
@@ -79,8 +76,8 @@

Fleet

spec
- -FleetSpec + +GameServerAllocationSpec
+ + + + + + + + @@ -142,32 +178,44 @@

Fleet

+ + + +
-replicas
+multiClusterSetting
-int32 + +MultiClusterSetting + 		-

Replicas are the number of GameServers that should be in this set. Defaults to 0.

+

MultiClusterPolicySelector if specified, multi-cluster policies are applied. +Otherwise, allocation will happen locally.
-allocationOverflow
+required
- -AllocationOverflow + +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: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

+

(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.
-strategy
+selectors
- -Kubernetes apps/v1.DeploymentStrategy + +[]GameServerSelector 		-

Deployment strategy

+

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.
-priorities
+metadata
- -[]Priority + +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) -

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

+

(Alpha, CountsAndLists feature flag) Counter actions to perform during allocation.
-template
+lists
- -GameServerTemplateSpec + +map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction 		-

Template the GameServer template to apply for this Fleet

+(Optional) +

(Alpha, CountsAndLists feature flag) List actions to perform during allocation.
@@ -177,8 +225,8 @@

Fleet status
- -FleetStatus + +GameServerAllocationStatus @@ -187,14 +235,14 @@

Fleet -

GameServer +

CounterAction

-

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.

+(Appears on: +GameServerAllocationSpec) +

+

+

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

@@ -206,200 +254,117 @@

GameServer

- - - - - - - - - - - -
-apiVersion
-string		 - -agones.dev/v1 - -
-kind
-string -		GameServer
-metadata
+action
- -Kubernetes meta/v1.ObjectMeta - +string 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +(Optional) +

Action must to either “Increment” or “Decrement” the Counter’s Count. Must also define the Amount.
-spec
- - -GameServerSpec - - -		 -
-
- - - + +
-container
+amount
-string +int64 		-

Container specifies which Pod container is the game server. Only required if there is more than one -container defined

+(Optional) +

Amount is the amount to increment or decrement the Count. Must be a positive integer.
-ports
+capacity
- -[]GameServerPort - +int64 		-

Ports are the array of ports that can be exposed via the game server

+(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.

+

+ + + + + + + + - - - - - - - - - - - - - - - - - - -
FieldDescription
-health
+minCount
- -Health - +int64 		-

Health configures health checking

+(Optional) +

MinCount is the minimum current value. Defaults to 0.
-scheduling
+maxCount
-agones.dev/agones/pkg/apis.SchedulingStrategy +int64 		-

Scheduling strategy. Defaults to “Packed”

+(Optional) +

MaxCount is the maximum current value. Defaults to 0, which translates as max(in64).
-sdkServer
+minAvailable
- -SdkServer - +int64 		-

SdkServer specifies parameters for the Agones SDK Server sidecar container

+(Optional) +

MinAvailable specifies the minimum capacity (current capacity - current count) available on a GameServer. Defaults to 0.
-template
+maxAvailable
- -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 and Lists provides the configuration for generic tracking features.

-
-lists
- - -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus - - -		 -
-eviction
- - -Eviction - - -		 -(Optional) -

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

-
-
-status
- - -GameServerStatus - +int64 		+(Optional) +

MaxAvailable specifies the maximum capacity (current capacity - current count) available on a GameServer. Defaults to 0, which translates to max(int64).
-

GameServerSet +

GameServerAllocationSpec

-

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

+(Appears on: +GameServerAllocation) +

+

+

GameServerAllocationSpec is the spec for a GameServerAllocation

@@ -411,74 +376,82 @@

GameServerSet

- - - -
-apiVersion
-string		 - -agones.dev/v1 - +multiClusterSetting
+ + +MultiClusterSetting + +
-kind
-string +

MultiClusterPolicySelector if specified, multi-cluster policies are applied. +Otherwise, allocation will happen locally.

GameServerSet
-metadata
+required
- -Kubernetes meta/v1.ObjectMeta + +GameServerSelector 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +

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.
-spec
+preferred
- -GameServerSetSpec + +[]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.

+ + @@ -494,60 +467,65 @@

GameServerSet

- -
-replicas
+priorities
-int32 + +[]Priority + 		-

Replicas are the number of GameServers that should be in this set

+(Optional) +

(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.
-allocationOverflow
+selectors
- -AllocationOverflow + +[]GameServerSelector 		-(Optional) -

[Stage: Alpha] -[FeatureFlag:FleetAllocationOverflow] -Labels and Annotations to apply to GameServers when the number of Allocated GameServers drops below -the desired replicas on the underlying GameServerSet

+

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.
-priorities
+metadata
- -[]Priority + +MetaPatch 		-(Optional) -

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

+

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
-template
+counters
- -GameServerTemplateSpec + +map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction 		-

Template the GameServer template to apply for this GameServerSet

-
+(Optional) +

(Alpha, CountsAndLists feature flag) Counter actions to perform during allocation.
-status
+lists
- -GameServerSetStatus + +map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction 		+(Optional) +

(Alpha, CountsAndLists feature flag) List actions to perform during allocation.
-

AggregatedCounterStatus +

GameServerAllocationState +(string alias)

+

+(Appears on: +GameServerAllocationStatus) +

+

+

GameServerAllocationState is the Allocation state

+

+

GameServerAllocationStatus

(Appears on: -FleetStatus, -GameServerSetStatus) +GameServerAllocation)

-

AggregatedCounterStatus stores total and allocated Counter tracking values

+

GameServerAllocationStatus is the status for an GameServerAllocation resource

@@ -559,19 +537,22 @@

AggregatedCounterStatus

- -
-allocatedCount
+state
-int64 + +GameServerAllocationState + 		+

GameServerState is the current state of an GameServerAllocation, e.g. Allocated, or UnAllocated
-allocatedCapacity
+gameServerName
-int64 +string 		@@ -579,9 +560,11 @@

AggregatedCounterStatus

-count
+ports
-int64 + +[]GameServerStatusPort + 		@@ -589,39 +572,21 @@

AggregatedCounterStatus

-capacity
+address
-int64 +string
-

AggregatedListStatus -

-

-(Appears on: -FleetStatus, -GameServerSetStatus) -

-

-

AggregatedListStatus stores total and allocated List tracking values

-

- - - - - - - - +

If the allocation is from a remote cluster, Source is the endpoint of the remote agones-allocator. +Otherwise, Source is “local”

+
FieldDescription
-allocatedCount
+addresses
-int64 + +[]Kubernetes core/v1.NodeAddress + 		@@ -629,9 +594,9 @@

AggregatedListStatus

-allocatedCapacity
+nodeName
-int64 +string 		@@ -639,19 +604,23 @@

AggregatedListStatus

-count
+source
-int64 +string 		-
-capacity
+metadata
-int64 + +GameServerMetadata + 		@@ -659,15 +628,14 @@

AggregatedListStatus

-

AggregatedPlayerStatus +

GameServerMetadata

(Appears on: -FleetStatus, -GameServerSetStatus) +GameServerAllocationStatus)

-

AggregatedPlayerStatus stores total player tracking values

+

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

@@ -679,9 +647,9 @@

AggregatedPlayerStatus

-count
+labels
-int64 +map[string]string 		@@ -689,9 +657,9 @@

AggregatedPlayerStatus

-capacity
+annotations
-int64 +map[string]string 		@@ -699,17 +667,15 @@

AggregatedPlayerStatus

-

AllocationOverflow +

GameServerSelector

(Appears on: -FleetSpec, -GameServerSetSpec) +GameServerAllocationSpec)

-

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.

+

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

@@ -721,79 +687,94 @@

AllocationOverflow

- -
-labels
+LabelSelector
-map[string]string + +Kubernetes meta/v1.LabelSelector + 		-(Optional) -

Labels to be applied to the GameServer

+

+(Members of LabelSelector are embedded into this type.) +

+

See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
-annotations
+gameServerState
-map[string]string + +GameServerState + 		-(Optional) -

Annotations to be applied to the GameServer

+

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

CounterStatus -

-

-(Appears on: -GameServerSpec, -GameServerStatus) -

-

-

CounterStatus stores the current counter values

-

- - - - + + - -
FieldDescription +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.

+
-count
+counters
-int64 + +map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterSelector + 		+(Optional) +

(Alpha, CountsAndLists feature flag) 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.
-capacity
+lists
-int64 + +map[string]agones.dev/agones/pkg/apis/allocation/v1.ListSelector + 		+(Optional) +

(Alpha, CountsAndLists feature flag) 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.
-

Eviction +

ListAction

(Appears on: -GameServerSpec, -GameServerStatus) +GameServerAllocationSpec)

-

Eviction specifies the eviction tolerance of the GameServer

+

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

@@ -805,39 +786,39 @@

Eviction

+ + + +
-safe
+addValues
- -EvictionSafe - +[]string 		-

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

+(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.
-

EvictionSafe -(string alias)

-

-(Appears on: -Eviction) -

-

-

EvictionSafe specified whether the game server supports termination via SIGTERM

-

-

FleetSpec +

ListSelector

(Appears on: -Fleet) +GameServerSelector)

-

FleetSpec is the spec for a Fleet

+

ListSelector is the filter options for a GameServer based on List available capacity and/or the +existence of a value in a List.

@@ -849,97 +830,89 @@

FleetSpec

+ +
-replicas
+containsValue
-int32 +string 		-

Replicas are the number of GameServers that should be in this set. Defaults to 0.

+(Optional) +

ContainsValue says to only match GameServers who has this value in the list. Defaults to “”, which is all.
-allocationOverflow
+minAvailable
- -AllocationOverflow - +int64 		(Optional) -

[Stage: Alpha] -[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

+

MinAvailable specifies the minimum capacity (current capacity - current count) available on a GameServer. Defaults to 0.
-strategy
+maxAvailable
- -Kubernetes apps/v1.DeploymentStrategy - +int64 		-

Deployment strategy

+(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

+

+ + - - + + + +
-scheduling
- -agones.dev/agones/pkg/apis.SchedulingStrategy - -		 -

Scheduling strategy. Defaults to “Packed”.

-		FieldDescription
-priorities
+labels
- -[]Priority - +map[string]string 		-(Optional) -

(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.
-template
+annotations
- -GameServerTemplateSpec - +map[string]string 		-

Template the GameServer template to apply for this Fleet
-

FleetStatus +

MultiClusterSetting

(Appears on: -Fleet, -FleetAutoscaleRequest) +GameServerAllocationSpec)

-

FleetStatus is the status of a Fleet

+

MultiClusterSetting specifies settings for multi-cluster allocation.

@@ -951,106 +924,80 @@

FleetStatus

- - - - - - - - + +
-replicas
+enabled
-int32 +bool 		-

Replicas the total number of current GameServer replicas
-readyReplicas
+policySelector
-int32 + +Kubernetes meta/v1.LabelSelector + 		-

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
+

PlayerSelector +

+

+(Appears on: +GameServerSelector) +

+

+

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

+

+ + - - + + + +
-players
- - -AggregatedPlayerStatus - - -		 -(Optional) -

[Stage:Alpha] -[FeatureFlag:PlayerTracking] -Players are the current total player capacity and count for this Fleet

-		FieldDescription
-counters
+minAvailable
- -map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus - +int64 		-(Optional) -

(Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter -count for this Fleet.
-lists
+maxAvailable
- -map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus - +int64 		-(Optional) -

(Alpha, CountsAndLists feature flag) Lists provides aggregated List capacityv and List values -for this Fleet.
-

GameServerPort -

+
+

autoscaling.agones.dev/v1

-(Appears on: -GameServerSpec) +

Package v1 is the v1 version of the API.

+Resource Types: + +

FleetAutoscaler +

-

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

+

FleetAutoscaler is the data structure for a FleetAutoscaler resource

@@ -1062,89 +1009,110 @@

GameServerPort

+ + + + +
-name
- -string - +apiVersion
+string		 + +autoscaling.agones.dev/v1 +
-

Name is the descriptive name of the port

+kind
+string 		FleetAutoscaler
-portPolicy
+metadata
- -PortPolicy + +Kubernetes meta/v1.ObjectMeta 		-

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

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-container
+spec
+ + +FleetAutoscalerSpec + + +		 +
+
+ + + + +
+fleetName
string 		-(Optional) -

Container is the name of the container on which to open the port. Defaults to the game server container.
-containerPort
+policy
-int32 + +FleetAutoscalerPolicy + 		-

ContainerPort is the port that is being opened on the specified container’s process

+

Autoscaling policy
-hostPort
+sync
-int32 + +FleetAutoscalerSync + 		-

HostPort the port exposed on the host for clients to connect to

+(Optional) +

Sync defines when FleetAutoscalers runs autoscaling

+
-protocol
+status
- -Kubernetes core/v1.Protocol + +FleetAutoscalerStatus 		-

Protocol is the network protocol being used. Defaults to UDP. TCP and TCPUDP are other options.
-

GameServerSetSpec +

BufferPolicy

(Appears on: -GameServerSet) +FleetAutoscalerPolicy)

-

GameServerSetSpec the specification for GameServerSet

+

BufferPolicy controls the desired behavior of the buffer policy.

@@ -1156,83 +1124,59 @@

GameServerSetSpec

- - - - - - - -
-replicas
+maxReplicas
int32 		-

Replicas are the number of GameServers that should be in this set

-
-allocationOverflow
- - -AllocationOverflow - - -		 -(Optional) -

[Stage: Alpha] -[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”.

+

MaxReplicas is the maximum amount of replicas that the fleet may have. +It must be bigger than both MinReplicas and BufferSize
-priorities
+minReplicas
- -[]Priority - +int32 		-(Optional) -

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

+

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
-template
+bufferSize
- -GameServerTemplateSpec - +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		-

Template the GameServer template to apply for this GameServerSet

+

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)
-

GameServerSetStatus +

CounterPolicy

(Appears on: -GameServerSet) +FleetAutoscalerPolicy)

-

GameServerSetStatus is the status of a GameServerSet

+

CounterPolicy controls the desired behavior of the Counter autoscaler policy.

@@ -1244,116 +1188,162 @@

GameServerSetStatus

- - +

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.

+ + + +
-replicas
+key
-int32 +string 		-

Replicas is the total number of current GameServer replicas

+

Key is the name of the Counter. Required field.
-readyReplicas
+maxCapacity
-int32 +int64 		-

ReadyReplicas is the number of Ready GameServer replicas

+

MaxCapacity is the maximum aggregate Counter total capacity across the fleet. +MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
-reservedReplicas
+minCapacity
-int32 +int64 		-

ReservedReplicas is the number of Reserved GameServer replicas

+

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.
-allocatedReplicas
+bufferSize
-int32 +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		-

AllocatedReplicas is the number of Allocated GameServer replicas

-
+

FixedIntervalSync +

+

+(Appears on: +FleetAutoscalerSync) +

+

+

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

+

+ + + + + + + + + + +
FieldDescription
-shutdownReplicas
+seconds
int32 		-

ShutdownReplicas is the number of Shutdown GameServers replicas

+

Seconds defines how often we run fleet autoscaling in seconds
+

FleetAutoscaleRequest +

+

+(Appears on: +FleetAutoscaleReview) +

+

+

FleetAutoscaleRequest defines the request to webhook autoscaler endpoint

+

+ + + + + + + + + + + +
FieldDescription
-players
+uid
- -AggregatedPlayerStatus - +k8s.io/apimachinery/pkg/types.UID 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:PlayerTracking] -Players is the current total player capacity and count for this GameServerSet

+

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.
-counters
+name
- -map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus - +string 		-(Optional) -

(Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter -count for this GameServerSet.

+

Name is the name of the Fleet being scaled
-lists
+namespace
- -map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus +string + +		 +

Namespace is the namespace associated with the request (if any).

+
+status
+ + +FleetStatus 		-(Optional) -

(Alpha, CountsAndLists feature flag) Lists provides aggregated List capacity and List values -for this GameServerSet.

+

The Fleet’s status values
-

GameServerSpec +

FleetAutoscaleResponse

(Appears on: -GameServer, -GameServerTemplateSpec) +FleetAutoscaleReview)

-

GameServerSpec is the spec for a GameServer resource

+

FleetAutoscaleResponse defines the response of webhook autoscaler endpoint

@@ -1365,153 +1355,190 @@

GameServerSpec

+ +
-container
+uid
-string +k8s.io/apimachinery/pkg/types.UID 		-

Container specifies which Pod container is the game server. Only required if there is more than one -container defined

+

UID is an identifier for the individual request/response. +This should be copied over from the corresponding FleetAutoscaleRequest.
-ports
+scale
- -[]GameServerPort - +bool 		-

Ports are the array of ports that can be exposed via the game server

+

Set to false if no scaling should occur to the Fleet
-health
+replicas
- -Health - +int32 		-

Health configures health checking

+

The targeted replica count
+

FleetAutoscaleReview +

+

+

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

+

+ + + + + + + + + +
FieldDescription
-scheduling
+request
-agones.dev/agones/pkg/apis.SchedulingStrategy + +FleetAutoscaleRequest + 		-

Scheduling strategy. Defaults to “Packed”
-sdkServer
+response
- -SdkServer + +FleetAutoscaleResponse 		-

SdkServer specifies parameters for the Agones SDK Server sidecar container
+

FleetAutoscalerPolicy +

+

+(Appears on: +FleetAutoscalerSpec) +

+

+

FleetAutoscalerPolicy describes how to scale a fleet

+

+ + + + + + + +
FieldDescription
-template
+type
- -Kubernetes core/v1.PodTemplateSpec + +FleetAutoscalerPolicyType 		-

Template describes the Pod that will be created for the GameServer

+

Type of autoscaling policy.
-players
+buffer
- -PlayersSpec + +BufferPolicy 		(Optional) -

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.

+

Buffer policy config params. Present only if FleetAutoscalerPolicyType = Buffer.
-counters
+webhook
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + +WebhookPolicy 		(Optional) -

(Alpha, CountsAndLists feature flag) Counters and Lists provides the configuration for generic tracking features.

+

Webhook policy config params. Present only if FleetAutoscalerPolicyType = Webhook.
-lists
+counter
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus + +CounterPolicy 		+(Optional) +

[Stage:Alpha] +[FeatureFlag:CountsAndLists] +Counter policy config params. Present only if FleetAutoscalerPolicyType = Counter.
-eviction
+list
- -Eviction + +ListPolicy 		(Optional) -

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

+

[Stage:Alpha] +[FeatureFlag:CountsAndLists] +List policy config params. Present only if FleetAutoscalerPolicyType = List.
-

GameServerState +

FleetAutoscalerPolicyType (string alias)

(Appears on: -GameServerSelector, -GameServerStatus) +FleetAutoscalerPolicy)

-

GameServerState is the state for the GameServer

+

FleetAutoscalerPolicyType is the policy for autoscaling +for a given Fleet

-

GameServerStatus +

FleetAutoscalerSpec

(Appears on: -GameServer) +FleetAutoscaler)

-

GameServerStatus is the status for a GameServer resource

+

FleetAutoscalerSpec is the spec for a Fleet Scaler

@@ -1523,143 +1550,131 @@

GameServerStatus

+ +
-state
+fleetName
- -GameServerState - +string 		-

GameServerState is the current state of a GameServer, e.g. Creating, Starting, Ready, etc
-ports
+policy
- -[]GameServerStatusPort + +FleetAutoscalerPolicy 		+

Autoscaling policy
-address
+sync
-string + +FleetAutoscalerSync + 		+(Optional) +

Sync defines when FleetAutoscalers runs autoscaling
+

FleetAutoscalerStatus +

+

+(Appears on: +FleetAutoscaler) +

+

+

FleetAutoscalerStatus defines the current status of a FleetAutoscaler

+

+ + - - - - - - + + + +
-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 - -		 -FieldDescription
-reservedUntil
+currentReplicas
- -Kubernetes meta/v1.Time - +int32 		+

CurrentReplicas is the current number of gameserver replicas +of the fleet managed by this autoscaler, as last seen by the autoscaler
-players
+desiredReplicas
- -PlayerStatus - +int32 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:PlayerTracking]

+

DesiredReplicas is the desired number of gameserver replicas +of the fleet managed by this autoscaler, as last calculated by the autoscaler
-counters
+lastScaleTime
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + +Kubernetes meta/v1.Time 		(Optional) -

(Alpha, CountsAndLists feature flag) Counters and Lists provides the configuration for generic tracking features.

+

lastScaleTime is the last time the FleetAutoscaler scaled the attached fleet,
-lists
+ableToScale
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus - +bool 		-(Optional) +

AbleToScale indicates that we can access the target fleet
-eviction
+scalingLimited
- -Eviction - +bool 		-(Optional) -

Eviction specifies the eviction tolerance of the GameServer.

+

ScalingLimited indicates that the calculated scale would be above or below the range +defined by MinReplicas and MaxReplicas, and has thus been capped.
-

GameServerStatusPort +

FleetAutoscalerSync

(Appears on: -GameServerAllocationStatus, -GameServerStatus) +FleetAutoscalerSpec)

-

GameServerStatusPort shows the port that was allocated to a -GameServer.

+

FleetAutoscalerSync describes when to sync a fleet

@@ -1671,35 +1686,50 @@

GameServerStatusPort

-name
+type
-string + +FleetAutoscalerSyncType + 		+

Type of autoscaling sync.
-port
+fixedInterval
-int32 + +FixedIntervalSync + 		+(Optional) +

FixedInterval config params. Present only if FleetAutoscalerSyncType = FixedInterval.
-

GameServerTemplateSpec +

FleetAutoscalerSyncType +(string alias)

+

+(Appears on: +FleetAutoscalerSync) +

+

+

FleetAutoscalerSyncType is the sync strategy for a given Fleet

+

+

ListPolicy

(Appears on: -FleetSpec, -GameServerSetSpec) +FleetAutoscalerPolicy)

-

GameServerTemplateSpec is a template for GameServers

+

ListPolicy controls the desired behavior of the List autoscaler policy.

@@ -1711,173 +1741,150 @@

GameServerTemplateSpec

- - - - -
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -GameServerSpec - - -		 -
-
- - - + +
-container
+key
string 		-

Container specifies which Pod container is the game server. Only required if there is more than one -container defined

+

Key is the name of the List. Required field.
-ports
+maxCapacity
- -[]GameServerPort - +int64 		-

Ports are the array of ports that can be exposed via the game server

+

MaxCapacity is the maximum aggregate List total capacity across the fleet. +MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
-health
+minCapacity
- -Health - +int64 		-

Health configures health checking

+

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.
-scheduling
+bufferSize
-agones.dev/agones/pkg/apis.SchedulingStrategy +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		-

Scheduling strategy. Defaults to “Packed”

+

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

+

+ + - - + + + + - - - - - - - - - -
-sdkServer
- - -SdkServer - - -		 -

SdkServer specifies parameters for the Agones SDK Server sidecar container

-		FieldDescription
-template
+url
- -Kubernetes core/v1.PodTemplateSpec - +string 		-

Template describes the Pod that will be created for the GameServer

+(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.
-players
+service
- -PlayersSpec + +Kubernetes admissionregistration/v1.ServiceReference 		(Optional) -

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.

+

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.
-counters
+caBundle
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus - +[]byte 		(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 - - -		 -
-eviction
- - -Eviction - - -		 -(Optional) -

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

-
+

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

Health -

+
+

multicluster.agones.dev/v1

-(Appears on: -GameServerSpec) +

Package v1 is the v1 version of the API.

+Resource Types: + +

GameServerAllocationPolicy +

-

Health configures health checking on the GameServer

+

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

@@ -1889,59 +1896,93 @@

Health

+ + + + + + + + +
-disabled
+apiVersion
+string		 + +multicluster.agones.dev/v1 + +
+kind
+string +		GameServerAllocationPolicy
+metadata
-bool + +Kubernetes meta/v1.ObjectMeta + 		-

Disabled is whether health checking is disabled or not

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-periodSeconds
+spec
+ + +GameServerAllocationPolicySpec + + +		 +
+
+ + + + +
+priority
int32 		-

PeriodSeconds is the number of seconds each health ping has to occur in
-failureThreshold
+weight
-int32 +int 		-

FailureThreshold how many failures in a row constitutes unhealthy
-initialDelaySeconds
+connectionInfo
-int32 + +ClusterConnectionInfo + 		-

InitialDelaySeconds initial delay before checking health

+
-

ListStatus +

ClusterConnectionInfo

(Appears on: -GameServerSpec, -GameServerStatus) +GameServerAllocationPolicySpec)

-

ListStatus stores the current list values

+

ClusterConnectionInfo defines the connection information for a cluster

@@ -1953,83 +1994,67 @@

ListStatus

- -
-capacity
+clusterName
-int64 +string 		+

Optional: the name of the targeted cluster
-values
+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
-

PlayerStatus -

-

-(Appears on: -GameServerStatus) -

-

-

PlayerStatus stores the current player capacity values

-

- - - - - - - -
FieldDescription
-count
+secretName
-int64 +string 		+

The name of the secret that contains TLS client certificates to connect the allocator server in the targeted cluster
-capacity
+namespace
-int64 +string 		+

The cluster namespace from which to allocate gameservers
-ids
+serverCa
-[]string +[]byte 		+

The PEM encoded server CA, used by the allocator client to authenticate the remote server.
-

PlayersSpec +

ConnectionInfoIterator

-(Appears on: -GameServerSpec) -

-

-

PlayersSpec tracks the initial player capacity

+

ConnectionInfoIterator an iterator on ClusterConnectionInfo

@@ -2041,88 +2066,58 @@

PlayersSpec

- -
-initialCapacity
+currPriority
-int64 +int 		+

currPriority Current priority index from the orderedPriorities
-

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 Capacity. -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: Sort by “Ascending” or “Descending”. “Descending” a bigger Capacity is preferred. -“Ascending” would be smaller Capacity is preferred.

-

- - - - - - - -
FieldDescription
-type
+orderedPriorities
-string +[]int32 		+

orderedPriorities list of ordered priorities
-key
+priorityToCluster
-string +map[int32]map[string][]*agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy 		+

priorityToCluster Map of priority to cluster-policies map
-order
+clusterBlackList
-string +map[string]bool 		+

clusterBlackList the cluster blacklist for the clusters that has already returned
-

SdkServer +

GameServerAllocationPolicySpec

(Appears on: -GameServerSpec) +GameServerAllocationPolicy)

-

SdkServer specifies parameters for the Agones SDK Server sidecar container

+

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

@@ -2134,64 +2129,55 @@

SdkServer

-logLevel
+priority
- -SdkServerLogLevel - +int32 		-

LogLevel for SDK server (sidecar) logs. Defaults to “Info”
-grpcPort
+weight
-int32 +int 		-

GRPCPort is the port on which the SDK Server binds the gRPC server to accept incoming connections
-httpPort
+connectionInfo
-int32 + +ClusterConnectionInfo + 		-

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

+

agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types: -

GameServerAllocation +

Fleet

-

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

+

Fleet is the data structure for a Fleet resource

@@ -2207,7 +2193,7 @@

GameServerAllocation string

@@ -2216,7 +2202,7 @@

GameServerAllocation kind
string -

+ @@ -2247,82 +2233,43 @@

GameServerAllocation

-allocation.agones.dev/v1 +agones.dev/v1
GameServerAllocationFleet
@@ -2236,8 +2222,8 @@

GameServerAllocation

spec
- -GameServerAllocationSpec + +FleetSpec
- - - - - - - - @@ -2338,43 +2285,32 @@

GameServerAllocation

- - - -
-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
+replicas
- -[]GameServerSelector - +int32 		-

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.

+

Replicas are the number of GameServers that should be in this set. Defaults to 0.
-priorities
+allocationOverflow
- -[]Priority + +AllocationOverflow 		(Optional) -

(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: 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
-selectors
+strategy
- -[]GameServerSelector + +Kubernetes apps/v1.DeploymentStrategy 		-

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.

+

Deployment strategy
-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
+priorities
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction + +[]Priority 		(Optional) -

(Alpha, CountsAndLists feature flag) Counters and Lists provide a set of actions to perform -on Counters and Lists during allocation.

+

(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.
-lists
+template
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction + +GameServerTemplateSpec 		+

Template the GameServer template to apply for this Fleet
@@ -2384,8 +2320,8 @@

GameServerAllocation status
- -GameServerAllocationStatus + +FleetStatus @@ -2394,17 +2330,14 @@

GameServerAllocation -

CounterAction +

GameServer

-(Appears on: -GameServerAllocationSpec) -

-

-

CounterAction is an optional action that can be performed on a Counter at allocation. -Action: “Increment” or “Decrement” the Counter’s Count (optional). Must also define the Amount. -Amount: The amount to increment or decrement the Count (optional). Must be a positive integer. -Capacity: Update the maximum capacity of the Counter to this number (optional). Min 0, Max int64.

+

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.

@@ -2416,239 +2349,190 @@

CounterAction

+ + + + - - -
-action
- -string - +apiVersion
+string		 + +agones.dev/v1 +
+kind
+string 		GameServer
-amount
+metadata
-int64 + +Kubernetes meta/v1.ObjectMeta + 		+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-capacity
+spec
-int64 + +GameServerSpec + 		-
-

CounterSelector -

-

-(Appears on: -GameServerSelector) -

-

-

CounterSelector is the filter options for a GameServer based on the count and/or available capacity. -0 for MaxCount or MaxAvailable means unlimited maximum. Default for all fields: 0

-

+
+
- - - - - - - - -
FieldDescription
-minCount
+container
-int64 +string 		+

Container specifies which Pod container is the game server. Only required if there is more than one +container defined
-maxCount
+ports
-int64 + +[]GameServerPort + 		+

Ports are the array of ports that can be exposed via the game server
-minAvailable
+health
-int64 + +Health + 		+

Health configures health checking
-maxAvailable
+scheduling
-int64 +agones.dev/agones/pkg/apis.SchedulingStrategy 		+

Scheduling strategy. Defaults to “Packed”
-

GameServerAllocationSpec -

-

-(Appears on: -GameServerAllocation) -

-

-

GameServerAllocationSpec is the spec for a GameServerAllocation

-

- - - - - - - - - - - - - - -
FieldDescription
-multiClusterSetting
+sdkServer
- -MultiClusterSetting + +SdkServer 		-

MultiClusterPolicySelector if specified, multi-cluster policies are applied. -Otherwise, allocation will happen locally.

+

SdkServer specifies parameters for the Agones SDK Server sidecar container
-required
+template
- -GameServerSelector + +Kubernetes core/v1.PodTemplateSpec 		-

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.

+

Template describes the Pod that will be created for the GameServer
-preferred
+players
- -[]GameServerSelector + +PlayersSpec 		-

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.

+(Optional) +

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
-priorities
+counters
- -[]Priority + +map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus 		(Optional) -

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

+

(Alpha, CountsAndLists feature flag) Counters provides the configuration for tracking of int64 values against a GameServer. +Keys must be declared at GameServer creation time.
-selectors
+lists
- -[]GameServerSelector + +map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus 		-

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

+(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.
-metadata
+eviction
- -MetaPatch + +Eviction 		-

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

+(Optional) +

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.
-counters
- - -map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction - - -		 -(Optional) -

(Alpha, CountsAndLists feature flag) Counters and Lists provide a set of actions to perform -on Counters and Lists during allocation.

+
-lists
+status
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction + +GameServerStatus @@ -2657,23 +2541,12 @@

GameServerAllocationS -

GameServerAllocationState -(string alias)

-

-(Appears on: -GameServerAllocationStatus) -

-

-

GameServerAllocationState is the Allocation state

-

-

GameServerAllocationStatus +

GameServerSet

-(Appears on: -GameServerAllocation) -

-

-

GameServerAllocationStatus is the status for an GameServerAllocation resource

+

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

@@ -2685,89 +2558,126 @@

GameServerAllocatio

+ + + + @@ -2776,14 +2686,15 @@

GameServerAllocatio

-state
- - -GameServerAllocationState - - +apiVersion
+string		 + +agones.dev/v1 +
-

GameServerState is the current state of an GameServerAllocation, e.g. Allocated, or UnAllocated

+kind
+string 		GameServerSet
-gameServerName
+metadata
-string + +Kubernetes meta/v1.ObjectMeta + 		+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-ports
+spec
- -[]GameServerStatusPort + +GameServerSetSpec 		+
+
+ + + + + +
+replicas
+ +int32 + +		 +

Replicas are the number of GameServers that should be in this set
-address
+allocationOverflow
-string + +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
-addresses
+scheduling
- -[]Kubernetes core/v1.NodeAddress - +agones.dev/agones/pkg/apis.SchedulingStrategy 		+

Scheduling strategy. Defaults to “Packed”.
-nodeName
+priorities
-string + +[]Priority + 		+(Optional) +

(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.
-source
+template
-string + +GameServerTemplateSpec + 		-

If the allocation is from a remote cluster, Source is the endpoint of the remote agones-allocator. -Otherwise, Source is “local”

+

Template the GameServer template to apply for this GameServerSet

+
-metadata
+status
- -GameServerMetadata + +GameServerSetStatus
-

GameServerMetadata +

AggregatedCounterStatus

(Appears on: -GameServerAllocationStatus) +FleetStatus, +GameServerSetStatus)

-

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

+

AggregatedCounterStatus stores total and allocated Counter tracking values

@@ -2795,9 +2706,9 @@

GameServerMetadata

+ + + + + + + +
-labels
+allocatedCount
-map[string]string +int64 		@@ -2805,9 +2716,29 @@

GameServerMetadata

-annotations
+allocatedCapacity
-map[string]string +int64 + +		 +
+count
+ +int64 + +		 +
+capacity
+ +int64 		@@ -2815,15 +2746,15 @@

GameServerMetadata

-

GameServerSelector +

AggregatedListStatus

(Appears on: -GameServerAllocationSpec) +FleetStatus, +GameServerSetStatus)

-

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

+

AggregatedListStatus stores total and allocated List tracking values

@@ -2835,96 +2766,55 @@

GameServerSelector

- - - -
-LabelSelector
+allocatedCount
- -Kubernetes meta/v1.LabelSelector - +int64 		-

-(Members of LabelSelector are embedded into this type.) -

-

See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
-gameServerState
+allocatedCapacity
- -GameServerState - +int64 		-

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
+count
- -PlayerSelector - +int64 		-(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
+capacity
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterSelector - +int64 		-(Optional) -

(Alpha, CountsAndLists feature flag) 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) -

(Alpha, CountsAndLists feature flag) 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 +

AggregatedPlayerStatus

(Appears on: -GameServerAllocationSpec) +FleetStatus, +GameServerSetStatus)

-

ListAction is an optional action that can be performed on a List at allocation. -AddValues: Append values to a List’s Values array (optional). Any duplicate values will be ignored. -Capacity: Update the maximum capacity of the Counter to this number (optional). Min 0, Max 1000.

+

AggregatedPlayerStatus stores total player tracking values

@@ -2936,9 +2826,9 @@

ListAction

-addValues
+count
-[]string +int64 		@@ -2956,17 +2846,17 @@

ListAction

-

ListSelector +

AllocationOverflow

(Appears on: -GameServerSelector) +FleetSpec, +GameServerSetSpec)

-

ListSelector is the filter options for a GameServer based on List available capacity and/or the -existence of a value in a List. -0 for MaxAvailable means unlimited maximum. Default for integer fields: 0 -“” for ContainsValue means ignore field. Default for string field: “”

+

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.

@@ -2978,44 +2868,39 @@

ListSelector

- - - -
-containsValue
- -string - -		 -
-minAvailable
+labels
-int64 +map[string]string 		+(Optional) +

Labels to be applied to the GameServer
-maxAvailable
+annotations
-int64 +map[string]string 		+(Optional) +

Annotations to be applied to the GameServer
-

MetaPatch +

CounterStatus

(Appears on: -GameServerAllocationSpec) +GameServerSpec, +GameServerStatus)

-

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

+

CounterStatus stores the current counter values and maximum capacity

@@ -3027,9 +2912,9 @@

MetaPatch

-labels
+count
-map[string]string +int64 		@@ -3037,9 +2922,9 @@

MetaPatch

-annotations
+capacity
-map[string]string +int64 		@@ -3047,14 +2932,15 @@

MetaPatch

-

MultiClusterSetting +

Eviction

(Appears on: -GameServerAllocationSpec) +GameServerSpec, +GameServerStatus)

-

MultiClusterSetting specifies settings for multi-cluster allocation.

+

Eviction specifies the eviction tolerance of the GameServer

@@ -3066,80 +2952,39 @@

MultiClusterSetting

- - - -
-enabled
- -bool - -		 -
-policySelector
+safe
- -Kubernetes meta/v1.LabelSelector + +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
-

PlayerSelector -

+

EvictionSafe +(string alias)

(Appears on: -GameServerSelector) +Eviction)

-

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

+

EvictionSafe specified whether the game server supports termination via SIGTERM

- - - - - - - - - - - - - - - - - -
FieldDescription
-minAvailable
- -int64 - -		 -
-maxAvailable
- -int64 - -		 -
-
-

autoscaling.agones.dev/v1

+

FleetSpec +

-

Package v1 is the v1 version of the API.

+(Appears on: +Fleet)

-Resource Types: - -

FleetAutoscaler -

-

FleetAutoscaler is the data structure for a FleetAutoscaler resource

+

FleetSpec is the spec for a Fleet

@@ -3151,110 +2996,97 @@

FleetAutoscaler

- - - -
-apiVersion
-string		 - -autoscaling.agones.dev/v1 - +replicas
+ +int32 +
-kind
-string +

Replicas are the number of GameServers that should be in this set. Defaults to 0.

FleetAutoscaler
-metadata
+allocationOverflow
- -Kubernetes meta/v1.ObjectMeta + +AllocationOverflow 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +(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
-spec
+strategy
- -FleetAutoscalerSpec + +Kubernetes apps/v1.DeploymentStrategy 		-
-
- - - - - -
-fleetName
- -string - -		 +

Deployment strategy
-policy
+scheduling
- -FleetAutoscalerPolicy - +agones.dev/agones/pkg/apis.SchedulingStrategy 		-

Autoscaling policy

+

Scheduling strategy. Defaults to “Packed”.
-sync
+priorities
- -FleetAutoscalerSync + +[]Priority 		(Optional) -

Sync defines when FleetAutoscalers runs autoscaling

-
+

(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.
-status
+template
- -FleetAutoscalerStatus + +GameServerTemplateSpec 		+

Template the GameServer template to apply for this Fleet
-

BufferPolicy +

FleetStatus

(Appears on: -FleetAutoscalerPolicy) +Fleet, +FleetAutoscaleRequest)

-

BufferPolicy controls the desired behavior of the buffer policy.

+

FleetStatus is the status of a Fleet

@@ -3266,128 +3098,106 @@

BufferPolicy

- - -
-maxReplicas
+replicas
int32 		-

MaxReplicas is the maximum amount of replicas that the fleet may have. -It must be bigger than both MinReplicas and BufferSize

+

Replicas the total number of current GameServer replicas
-minReplicas
+readyReplicas
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

+

ReadyReplicas are the number of Ready GameServer replicas
-bufferSize
+reservedReplicas
-k8s.io/apimachinery/pkg/util/intstr.IntOrString +int32 		-

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.

-

- - - - - +

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.

+ - -
FieldDescription
-key
+allocatedReplicas
-string +int32 		-

Key is the name of the Counter. Required field.

+

AllocatedReplicas are the number of Allocated GameServer replicas
-maxCapacity
+players
-int64 + +AggregatedPlayerStatus + 		-

MaxCapacity is the maximum aggregate Counter total capacity across the fleet. -MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.

+(Optional) +

[Stage:Alpha] +[FeatureFlag:PlayerTracking] +Players are the current total player capacity and count for this Fleet
-minCapacity
+counters
-int64 + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus + 		-

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.

+(Optional) +

(Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter +count for this Fleet.
-bufferSize
+lists
-k8s.io/apimachinery/pkg/util/intstr.IntOrString + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus + 		-

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.

+(Optional) +

(Alpha, CountsAndLists feature flag) Lists provides aggregated List capacityv and List values +for this Fleet.
-

FixedIntervalSync +

GameServerPort

(Appears on: -FleetAutoscalerSync) +GameServerSpec)

-

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

+

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

@@ -3399,93 +3209,89 @@

FixedIntervalSync

- -
-seconds
+name
-int32 +string 		-

Seconds defines how often we run fleet autoscaling in seconds

+

Name is the descriptive name of the port
-

FleetAutoscaleRequest -

-

-(Appears on: -FleetAutoscaleReview) -

-

-

FleetAutoscaleRequest defines the request to webhook autoscaler endpoint

-

- - - - + + - -
FieldDescription +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

+
-uid
+container
-k8s.io/apimachinery/pkg/types.UID +string 		-

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.

+(Optional) +

Container is the name of the container on which to open the port. Defaults to the game server container.
-name
+containerPort
-string +int32 		-

Name is the name of the Fleet being scaled

+

ContainerPort is the port that is being opened on the specified container’s process
-namespace
+hostPort
-string +int32 		-

Namespace is the namespace associated with the request (if any).

+

HostPort the port exposed on the host for clients to connect to
-status
+protocol
- -FleetStatus + +Kubernetes core/v1.Protocol 		-

The Fleet’s status values

+

Protocol is the network protocol being used. Defaults to UDP. TCP and TCPUDP are other options.
-

FleetAutoscaleResponse +

GameServerSetSpec

(Appears on: -FleetAutoscaleReview) +GameServerSet)

-

FleetAutoscaleResponse defines the response of webhook autoscaler endpoint

+

GameServerSetSpec the specification for GameServerSet

@@ -3497,88 +3303,83 @@

FleetAutoscaleResponse

- -
-uid
+replicas
-k8s.io/apimachinery/pkg/types.UID +int32 		-

UID is an identifier for the individual request/response. -This should be copied over from the corresponding FleetAutoscaleRequest.

+

Replicas are the number of GameServers that should be in this set
-scale
+allocationOverflow
-bool + +AllocationOverflow + 		-

Set to false if no scaling should occur to the Fleet

+(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
-replicas
+scheduling
-int32 +agones.dev/agones/pkg/apis.SchedulingStrategy 		-

The targeted replica count

+

Scheduling strategy. Defaults to “Packed”.
-

FleetAutoscaleReview -

-

-

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

-

- - - - - - - -
FieldDescription
-request
+priorities
- -FleetAutoscaleRequest + +[]Priority 		+(Optional) +

(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.
-response
+template
- -FleetAutoscaleResponse + +GameServerTemplateSpec 		+

Template the GameServer template to apply for this GameServerSet
-

FleetAutoscalerPolicy +

GameServerSetStatus

(Appears on: -FleetAutoscalerSpec) +GameServerSet)

-

FleetAutoscalerPolicy describes how to scale a fleet

+

GameServerSetStatus is the status of a GameServerSet

@@ -3590,153 +3391,116 @@

FleetAutoscalerPolicy

- -
-type
+replicas
- -FleetAutoscalerPolicyType - +int32 		-

Type of autoscaling policy.

+

Replicas is the total number of current GameServer replicas
-buffer
+readyReplicas
- -BufferPolicy - +int32 		-(Optional) -

Buffer policy config params. Present only if FleetAutoscalerPolicyType = Buffer.

+

ReadyReplicas is the number of Ready GameServer replicas
-webhook
+reservedReplicas
- -WebhookPolicy - +int32 		-(Optional) -

Webhook policy config params. Present only if FleetAutoscalerPolicyType = Webhook.

+

ReservedReplicas is the number of Reserved GameServer replicas
-counter
+allocatedReplicas
- -CounterPolicy - +int32 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:CountsAndLists] -Counter policy config params. Present only if FleetAutoscalerPolicyType = Counter.

+

AllocatedReplicas is the number of Allocated GameServer replicas
-list
+shutdownReplicas
- -ListPolicy - +int32 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:CountsAndLists] -List policy config params. Present only if FleetAutoscalerPolicyType = List.

+

ShutdownReplicas is the number of Shutdown GameServers replicas
-

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

-

- - - - - - - -
FieldDescription
-fleetName
+players
-string + +AggregatedPlayerStatus + 		+(Optional) +

[Stage:Alpha] +[FeatureFlag:PlayerTracking] +Players is the current total player capacity and count for this GameServerSet
-policy
+counters
- -FleetAutoscalerPolicy + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus 		-

Autoscaling policy

+(Optional) +

(Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter +count for this GameServerSet.
-sync
+lists
- -FleetAutoscalerSync + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus 		(Optional) -

Sync defines when FleetAutoscalers runs autoscaling

+

(Alpha, CountsAndLists feature flag) Lists provides aggregated List capacity and List values +for this GameServerSet.
-

FleetAutoscalerStatus +

GameServerSpec

(Appears on: -FleetAutoscaler) +GameServer, +GameServerTemplateSpec)

-

FleetAutoscalerStatus defines the current status of a FleetAutoscaler

+

GameServerSpec is the spec for a GameServer resource

@@ -3748,130 +3512,157 @@

FleetAutoscalerStatus

- -
-currentReplicas
+container
-int32 +string 		-

CurrentReplicas is the current number of gameserver replicas -of the fleet managed by this autoscaler, as last seen by the autoscaler

+

Container specifies which Pod container is the game server. Only required if there is more than one +container defined
-desiredReplicas
+ports
-int32 + +[]GameServerPort + 		-

DesiredReplicas is the desired number of gameserver replicas -of the fleet managed by this autoscaler, as last calculated by the autoscaler

+

Ports are the array of ports that can be exposed via the game server
-lastScaleTime
+health
- -Kubernetes meta/v1.Time + +Health 		-(Optional) -

lastScaleTime is the last time the FleetAutoscaler scaled the attached fleet,

+

Health configures health checking
-ableToScale
+scheduling
-bool +agones.dev/agones/pkg/apis.SchedulingStrategy 		-

AbleToScale indicates that we can access the target fleet

+

Scheduling strategy. Defaults to “Packed”
-scalingLimited
+sdkServer
-bool + +SdkServer + 		-

ScalingLimited indicates that the calculated scale would be above or below the range -defined by MinReplicas and MaxReplicas, and has thus been capped.

+

SdkServer specifies parameters for the Agones SDK Server sidecar container
-

FleetAutoscalerSync -

-

-(Appears on: -FleetAutoscalerSpec) -

-

-

FleetAutoscalerSync describes when to sync a fleet

-

- - - - + + - - + + + + + + + +
FieldDescription +template
+ + +Kubernetes core/v1.PodTemplateSpec + + +		 +

Template describes the Pod that will be created for the GameServer

+
-type
+players
- -FleetAutoscalerSyncType + +PlayersSpec 		-

Type of autoscaling sync.

+(Optional) +

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
-fixedInterval
+counters
- -FixedIntervalSync + +map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus 		(Optional) -

FixedInterval config params. Present only if FleetAutoscalerSyncType = FixedInterval.

+

(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”.
-

FleetAutoscalerSyncType +

GameServerState (string alias)

(Appears on: -FleetAutoscalerSync) +GameServerSelector, +GameServerStatus)

-

FleetAutoscalerSyncType is the sync strategy for a given Fleet

+

GameServerState is the state for the GameServer

-

ListPolicy +

GameServerStatus

(Appears on: -FleetAutoscalerPolicy) +GameServer)

-

ListPolicy controls the desired behavior of the List autoscaler policy.

+

GameServerStatus is the status for a GameServer resource

@@ -3883,150 +3674,143 @@

ListPolicy

- -
-key
+state
-string + +GameServerState + 		-

Key is the name of the List. Required field.

+

GameServerState is the current state of a GameServer, e.g. Creating, Starting, Ready, etc
-maxCapacity
+ports
-int64 + +[]GameServerStatusPort + 		-

MaxCapacity is the maximum aggregate List total capacity across the fleet. -MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
-minCapacity
+address
-int64 +string 		-

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
+addresses
-k8s.io/apimachinery/pkg/util/intstr.IntOrString + +[]Kubernetes core/v1.NodeAddress + 		-

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.

+(Optional) +

Addresses is the array of addresses at which the GameServer can be reached; copy of Node.Status.addresses.
-

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

-

- - - - - - - - + + + + + + + + + + + +
FieldDescription
-url
+nodeName
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
+reservedUntil
- -Kubernetes admissionregistration/v1.ServiceReference + +Kubernetes meta/v1.Time + + +		 +
+players
+ + +PlayerStatus 		(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.

+

[Stage:Alpha] +[FeatureFlag:PlayerTracking]
-caBundle
+counters
-[]byte + +map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + 		(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.

+

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

multicluster.agones.dev/v1

+

GameServerStatusPort +

-

Package v1 is the v1 version of the API.

+(Appears on: +GameServerAllocationStatus, +GameServerStatus)

-Resource Types: - -

GameServerAllocationPolicy -

-

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

+

GameServerStatusPort shows the port that was allocated to a +GameServer.

@@ -4038,21 +3822,44 @@

GameServerAllocat

+name
+ +string + + - + + + +
-apiVersion
-string		 - -multicluster.agones.dev/v1 -
-kind
-string +port
+ +int32 + 		GameServerAllocationPolicy +
+

GameServerTemplateSpec +

+

+(Appears on: +FleetSpec, +GameServerSetSpec) +

+

+

GameServerTemplateSpec is a template for GameServers

+

+ + + + + + + @@ -4082,121 +3889,150 @@

GameServerAllocat

FieldDescription
metadata
@@ -4071,8 +3878,8 @@

GameServerAllocat

spec
- -GameServerAllocationPolicySpec + +GameServerSpec
-
-priority
+container
-int32 +string 		+

Container specifies which Pod container is the game server. Only required if there is more than one +container defined
-weight
+ports
-int + +[]GameServerPort + 		+

Ports are the array of ports that can be exposed via the game server
-connectionInfo
+health
- -ClusterConnectionInfo + +Health 		+

Health configures health checking
+ + +scheduling
+ +agones.dev/agones/pkg/apis.SchedulingStrategy + + + +

Scheduling strategy. Defaults to “Packed”

- - -

ClusterConnectionInfo -

-

-(Appears on: -GameServerAllocationPolicySpec) -

-

-

ClusterConnectionInfo defines the connection information for a cluster

-

- - - - + + - - + +
FieldDescription +sdkServer
+ + +SdkServer + + +		 +

SdkServer specifies parameters for the Agones SDK Server sidecar container

+
-clusterName
+template
-string + +Kubernetes core/v1.PodTemplateSpec + 		-

Optional: the name of the targeted cluster

+

Template describes the Pod that will be created for the GameServer
-allocationEndpoints
+players
-[]string + +PlayersSpec + 		-

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

+(Optional) +

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
-secretName
+counters
-string + +map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + 		-

The name of the secret that contains TLS client certificates to connect the allocator server in the targeted cluster

+(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.
-namespace
+lists
-string + +map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus + 		-

The cluster namespace from which to allocate gameservers

+(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.
-serverCa
+eviction
-[]byte + +Eviction + 		-

The PEM encoded server CA, used by the allocator client to authenticate the remote server.

+(Optional) +

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

+
-

ConnectionInfoIterator +

Health

-

ConnectionInfoIterator an iterator on ClusterConnectionInfo

+(Appears on: +GameServerSpec) +

+

+

Health configures health checking on the GameServer

@@ -4208,58 +4044,59 @@

ConnectionInfoIterato

-currPriority
+disabled
-int +bool 		-

currPriority Current priority index from the orderedPriorities

+

Disabled is whether health checking is disabled or not
-orderedPriorities
+periodSeconds
-[]int32 +int32 		-

orderedPriorities list of ordered priorities

+

PeriodSeconds is the number of seconds each health ping has to occur in
-priorityToCluster
+failureThreshold
-map[int32]map[string][]*agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy +int32 		-

priorityToCluster Map of priority to cluster-policies map

+

FailureThreshold how many failures in a row constitutes unhealthy
-clusterBlackList
+initialDelaySeconds
-map[string]bool +int32 		-

clusterBlackList the cluster blacklist for the clusters that has already returned

+

InitialDelaySeconds initial delay before checking health
-

GameServerAllocationPolicySpec +

ListStatus

(Appears on: -GameServerAllocationPolicy) +GameServerSpec, +GameServerStatus)

-

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

+

ListStatus stores the current list values and maximum capacity

@@ -4271,9 +4108,9 @@

GameServerAll

+ +
-priority
+capacity
-int32 +int64 		@@ -4281,21 +4118,58 @@

GameServerAll

-weight
+values
-int +[]string
+

PlayerStatus +

+

+(Appears on: +GameServerStatus) +

+

+

PlayerStatus stores the current player capacity values

+

+ + + + + + + + + + + + + + + +
FieldDescription
-connectionInfo
+count
- -ClusterConnectionInfo - +int64 + +		 +
+capacity
+ +int64 + +		 +
+ids
+ +[]string 		@@ -4303,40 +4177,14 @@

GameServerAll

-
-

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

-{{% /feature %}} -{{% feature publishVersion="1.37.0" %}} -

Packages:

- -

allocation.agones.dev/v1

+

PlayersSpec +

-

Package v1 is the v1 version of the API.

+(Appears on: +GameServerSpec)

-Resource Types: - -

GameServerAllocation -

-

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

+

PlayersSpec tracks the initial player capacity

@@ -4348,179 +4196,677 @@

GameServerAllocation

+initialCapacity
+ +int64 + + + +
-apiVersion
-string		 - -allocation.agones.dev/v1 -
+

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

+

+ + + + + + + + + - + + +
FieldDescription
-kind
+type
+ string + +		 +

Type: Sort by a “Counter” or a “List”.

GameServerAllocation
-metadata
+key
- -Kubernetes meta/v1.ObjectMeta - +string 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +

Key: The name of the Counter or List. If not found on the GameServer, has no impact.
-spec
+order
- -GameServerAllocationSpec - +string 		-
-
+

Order: Sort by “Ascending” or “Descending”. “Descending” a bigger Capacity is preferred. +“Ascending” would be smaller Capacity is preferred.

+
+

SdkServer +

+

+(Appears on: +GameServerSpec) +

+

+

SdkServer specifies parameters for the Agones SDK Server sidecar container

+

+ + + + + + + + + +
FieldDescription
-multiClusterSetting
+logLevel
- -MultiClusterSetting + +SdkServerLogLevel 		-

MultiClusterPolicySelector if specified, multi-cluster policies are applied. -Otherwise, allocation will happen locally.

+

LogLevel for SDK server (sidecar) logs. Defaults to “Info”
-required
+grpcPort
- -GameServerSelector - +int32 		-

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.

+

GRPCPort is the port on which the SDK Server binds the gRPC server to accept incoming connections
-preferred
+httpPort
- -[]GameServerSelector - +int32 		-

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.

+

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

+

+
+

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

+{{% /feature %}} +{{% feature publishVersion="1.39.0" %}} +

Packages:

+ +

agones.dev/v1

+

+

Package v1 is the v1 version of the API.

+

+Resource Types: + +

Fleet +

+

+

Fleet is the data structure for a Fleet resource

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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

+

+ + + + + + + + + + + + + + + + + + + - +
+
+
FieldDescription
+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.
-priorities
+spec
- -[]Priority + +GameServerSetSpec 		-(Optional) -

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

-
-selectors
+replicas
- -[]GameServerSelector - +int32 		-

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.

+

Replicas are the number of GameServers that should be in this set
-scheduling
+allocationOverflow
-agones.dev/agones/pkg/apis.SchedulingStrategy + +AllocationOverflow + 		-

Scheduling strategy. Defaults to “Packed”.

+(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
-metadata
+scheduling
- -MetaPatch - +agones.dev/agones/pkg/apis.SchedulingStrategy 		-

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

+

Scheduling strategy. Defaults to “Packed”.
-counters
+priorities
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction + +[]Priority 		(Optional) -

(Alpha, CountsAndLists feature flag) Counter actions to perform during allocation.

+

[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.
-lists
+template
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction + +GameServerTemplateSpec 		-(Optional) -

(Alpha, CountsAndLists feature flag) List actions to perform during allocation.

+

Template the GameServer template to apply for this GameServerSet
@@ -4530,8 +4876,8 @@

GameServerAllocation status
- -GameServerAllocationStatus + +GameServerSetStatus @@ -4540,14 +4886,15 @@

GameServerAllocation -

CounterAction +

AggregatedCounterStatus

(Appears on: -GameServerAllocationSpec) +FleetStatus, +GameServerSetStatus)

-

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

+

AggregatedCounterStatus stores total and allocated Counter tracking values

@@ -4559,26 +4906,32 @@

CounterAction

+ + + + @@ -4589,20 +4942,19 @@

CounterAction

-action
+allocatedCount
-string +int64 		-(Optional) -

Action must to either “Increment” or “Decrement” the Counter’s Count. Must also define the Amount.
-amount
+allocatedCapacity
+ +int64 + +		 +
+count
int64 		-(Optional) -

Amount is the amount to increment or decrement the Count. Must be a positive integer.
-(Optional) -

Capacity is the amount to update the maximum capacity of the Counter to this number. Min 0, Max int64.
-

CounterSelector +

AggregatedListStatus

(Appears on: -GameServerSelector) +FleetStatus, +GameServerSetStatus)

-

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

+

AggregatedListStatus stores total and allocated List tracking values

@@ -4614,62 +4966,55 @@

CounterSelector

-minCount
+allocatedCount
int64 		-(Optional) -

MinCount is the minimum current value. Defaults to 0.
-maxCount
+allocatedCapacity
int64 		-(Optional) -

MaxCount is the maximum current value. Defaults to 0, which translates as max(in64).
-minAvailable
+count
int64 		-(Optional) -

MinAvailable specifies the minimum capacity (current capacity - current count) available on a GameServer. Defaults to 0.
-maxAvailable
+capacity
int64 		-(Optional) -

MaxAvailable specifies the maximum capacity (current capacity - current count) available on a GameServer. Defaults to 0, which translates to max(int64).
-

GameServerAllocationSpec +

AggregatedPlayerStatus

(Appears on: -GameServerAllocation) +FleetStatus, +GameServerSetStatus)

-

GameServerAllocationSpec is the spec for a GameServerAllocation

+

AggregatedPlayerStatus stores total player tracking values

@@ -4681,156 +5026,121 @@

GameServerAllocationS

+ +
-multiClusterSetting
+count
- -MultiClusterSetting - +int64 		-

MultiClusterPolicySelector if specified, multi-cluster policies are applied. -Otherwise, allocation will happen locally.
-required
+capacity
- -GameServerSelector - +int64 		-

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

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.

+

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

-		FieldDescription
-priorities
+labels
- -[]Priority - +map[string]string 		(Optional) -

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

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

+

Labels to be applied to the GameServer
-scheduling
+annotations
-agones.dev/agones/pkg/apis.SchedulingStrategy +map[string]string 		-

Scheduling strategy. Defaults to “Packed”.

+(Optional) +

Annotations to be applied to the GameServer
+

CounterStatus +

+

+(Appears on: +GameServerSpec, +GameServerStatus) +

+

+

CounterStatus stores the current counter values and maximum capacity

+

+ + - - + + + +
-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

-		FieldDescription
-counters
+count
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction - +int64 		-(Optional) -

(Alpha, CountsAndLists feature flag) Counter actions to perform during allocation.
-lists
+capacity
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction - +int64 		-(Optional) -

(Alpha, CountsAndLists feature flag) List actions to perform during allocation.
-

GameServerAllocationState -(string alias)

-

-(Appears on: -GameServerAllocationStatus) -

-

-

GameServerAllocationState is the Allocation state

-

-

GameServerAllocationStatus +

Eviction

(Appears on: -GameServerAllocation) +GameServerSpec, +GameServerStatus)

-

GameServerAllocationStatus is the status for an GameServerAllocation resource

+

Eviction specifies the eviction tolerance of the GameServer

@@ -4842,105 +5152,145 @@

GameServerAllocatio

+ +
-state
+safe
- -GameServerAllocationState + +EvictionSafe 		-

GameServerState is the current state of an GameServerAllocation, e.g. Allocated, or UnAllocated

+

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

+

+ + - - + + + +
-gameServerName
- -string - -		 -FieldDescription
-ports
+replicas
- -[]GameServerStatusPort - +int32 		+

Replicas are the number of GameServers that should be in this set. Defaults to 0.
-address
+allocationOverflow
-string + +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
-addresses
+strategy
- -[]Kubernetes core/v1.NodeAddress + +Kubernetes apps/v1.DeploymentStrategy 		+

Deployment strategy
-nodeName
+scheduling
-string +agones.dev/agones/pkg/apis.SchedulingStrategy 		+

Scheduling strategy. Defaults to “Packed”.
-source
+priorities
-string + +[]Priority + 		-

If the allocation is from a remote cluster, Source is the endpoint of the remote agones-allocator. -Otherwise, Source is “local”

+(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.
-metadata
+template
- -GameServerMetadata + +GameServerTemplateSpec 		+

Template the GameServer template to apply for this Fleet
-

GameServerMetadata +

FleetStatus

(Appears on: -GameServerAllocationStatus) +Fleet, +FleetAutoscaleRequest)

-

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

+

FleetStatus is the status of a Fleet

@@ -4952,178 +5302,106 @@

GameServerMetadata

- -
-labels
+replicas
-map[string]string +int32 		+

Replicas the total number of current GameServer replicas
-annotations
+readyReplicas
-map[string]string +int32 		+

ReadyReplicas are the number of Ready GameServer replicas
-

GameServerSelector -

-

-(Appears on: -GameServerAllocationSpec) -

-

-

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

-

- - - - - - - - - - -
FieldDescription
-LabelSelector
+reservedReplicas
- -Kubernetes meta/v1.LabelSelector - +int32 		-

-(Members of LabelSelector are embedded into this type.) -

-

See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/

+

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.
-gameServerState
+allocatedReplicas
- -GameServerState - +int32 		-

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.

+

AllocatedReplicas are the number of Allocated GameServer replicas
players
- -PlayerSelector + +AggregatedPlayerStatus 		(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.

+[FeatureFlag:PlayerTracking] +Players are the current total player capacity and count for this Fleet
counters
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterSelector + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus 		(Optional) -

(Alpha, CountsAndLists feature flag) 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.

+

(Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter +count for this Fleet.
lists
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.ListSelector + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus 		(Optional) -

(Alpha, CountsAndLists feature flag) 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.

-

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

+

(Alpha, CountsAndLists feature flag) Lists provides aggregated List capacityv and List values +for this Fleet.
-

ListSelector +

GameServerPort

(Appears on: -GameServerSelector) +GameServerSpec)

-

-

ListSelector is the filter options for a GameServer based on List available capacity and/or the -existence of a value in a List.

+

+

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

@@ -5135,89 +5413,89 @@

ListSelector

- -
-containsValue
+name
string 		-(Optional) -

ContainsValue says to only match GameServers who has this value in the list. Defaults to “”, which is all.

+

Name is the descriptive name of the port
-minAvailable
+portPolicy
-int64 + +PortPolicy + 		-(Optional) -

MinAvailable specifies the minimum capacity (current capacity - current count) available on a GameServer. Defaults to 0.

+

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
-maxAvailable
+container
-int64 +string 		(Optional) -

MaxAvailable specifies the maximum capacity (current capacity - current count) available on a GameServer. Defaults to 0, which is translated as max(int64).

+

Container is the name of the container on which to open the port. Defaults to the game server container.
-

MetaPatch -

-

-(Appears on: -GameServerAllocationSpec) -

-

-

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

-

- - - - + + - -
FieldDescription +containerPort
+ +int32 + +		 +

ContainerPort is the port that is being opened on the specified container’s process

+
-labels
+hostPort
-map[string]string +int32 		+

HostPort the port exposed on the host for clients to connect to
-annotations
+protocol
-map[string]string + +Kubernetes core/v1.Protocol + 		+

Protocol is the network protocol being used. Defaults to UDP. TCP and TCPUDP are other options.
-

MultiClusterSetting +

GameServerSetSpec

(Appears on: -GameServerAllocationSpec) +GameServerSet)

-

MultiClusterSetting specifies settings for multi-cluster allocation.

+

GameServerSetSpec the specification for GameServerSet

@@ -5229,80 +5507,87 @@

MultiClusterSetting

- -
-enabled
+replicas
-bool +int32 		+

Replicas are the number of GameServers that should be in this set
-policySelector
+allocationOverflow
- -Kubernetes meta/v1.LabelSelector + +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
-

PlayerSelector -

-

-(Appears on: -GameServerSelector) -

-

-

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

-

- - - - + + - -
FieldDescription +scheduling
+ +agones.dev/agones/pkg/apis.SchedulingStrategy + +		 +

Scheduling strategy. Defaults to “Packed”.

+
-minAvailable
+priorities
-int64 + +[]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.
-maxAvailable
+template
-int64 + +GameServerTemplateSpec + 		+

Template the GameServer template to apply for this GameServerSet
-
-

autoscaling.agones.dev/v1

+

GameServerSetStatus +

-

Package v1 is the v1 version of the API.

+(Appears on: +GameServerSet)

-Resource Types: - -

FleetAutoscaler -

-

FleetAutoscaler is the data structure for a FleetAutoscaler resource

+

GameServerSetStatus is the status of a GameServerSet

@@ -5314,174 +5599,116 @@

FleetAutoscaler

- - - - - - - - - - -
-apiVersion
-string		 - -autoscaling.agones.dev/v1 - -
-kind
-string -		FleetAutoscaler
-metadata
+replicas
- -Kubernetes meta/v1.ObjectMeta - +int32 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +

Replicas is the total number of current GameServer replicas
-spec
- - -FleetAutoscalerSpec - - -		 -
-
- - - - -
-fleetName
+readyReplicas
-string +int32 		+

ReadyReplicas is the number of Ready GameServer replicas
-policy
+reservedReplicas
- -FleetAutoscalerPolicy - +int32 		-

Autoscaling policy

+

ReservedReplicas is the number of Reserved GameServer replicas
-sync
+allocatedReplicas
- -FleetAutoscalerSync - +int32 		-(Optional) -

Sync defines when FleetAutoscalers runs autoscaling

-
+

AllocatedReplicas is the number of Allocated GameServer replicas
-status
+shutdownReplicas
- -FleetAutoscalerStatus - +int32 		+

ShutdownReplicas is the number of Shutdown GameServers replicas
-

BufferPolicy -

-

-(Appears on: -FleetAutoscalerPolicy) -

-

-

BufferPolicy controls the desired behavior of the buffer policy.

-

- - - - - - - -
FieldDescription
-maxReplicas
+players
-int32 + +AggregatedPlayerStatus + 		-

MaxReplicas is the maximum amount of replicas that the fleet may have. -It must be bigger than both MinReplicas and BufferSize

+(Optional) +

[Stage:Alpha] +[FeatureFlag:PlayerTracking] +Players is the current total player capacity and count for this GameServerSet
-minReplicas
+counters
-int32 + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus + 		-

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

+(Optional) +

(Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter +count for this GameServerSet.
-bufferSize
+lists
-k8s.io/apimachinery/pkg/util/intstr.IntOrString + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus + 		-

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)

+(Optional) +

(Alpha, CountsAndLists feature flag) Lists provides aggregated List capacity and List values +for this GameServerSet.
-

CounterPolicy +

GameServerSpec

(Appears on: -FleetAutoscalerPolicy) +GameServer, +GameServerTemplateSpec)

-

CounterPolicy controls the desired behavior of the Counter autoscaler policy.

+

GameServerSpec is the spec for a GameServer resource

@@ -5493,162 +5720,157 @@

CounterPolicy

- -
-key
+container
string 		-

Key is the name of the Counter. Required field.

+

Container specifies which Pod container is the game server. Only required if there is more than one +container defined
-maxCapacity
+ports
-int64 + +[]GameServerPort + 		-

MaxCapacity is the maximum aggregate Counter total capacity across the fleet. -MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.

+

Ports are the array of ports that can be exposed via the game server
-minCapacity
+health
-int64 + +Health + 		-

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.

+

Health configures health checking
-bufferSize
+scheduling
-k8s.io/apimachinery/pkg/util/intstr.IntOrString +agones.dev/agones/pkg/apis.SchedulingStrategy 		-

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.

+

Scheduling strategy. Defaults to “Packed”
-

FixedIntervalSync -

-

-(Appears on: -FleetAutoscalerSync) -

-

-

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

-

- - - - - - - - - -
FieldDescription
-seconds
+sdkServer
-int32 + +SdkServer + 		-

Seconds defines how often we run fleet autoscaling in seconds

+

SdkServer specifies parameters for the Agones SDK Server sidecar container
-

FleetAutoscaleRequest -

-

-(Appears on: -FleetAutoscaleReview) -

-

-

FleetAutoscaleRequest defines the request to webhook autoscaler endpoint

-

- - - - + + - -
FieldDescription +template
+ + +Kubernetes core/v1.PodTemplateSpec + + +		 +

Template describes the Pod that will be created for the GameServer

+
-uid
+players
-k8s.io/apimachinery/pkg/types.UID + +PlayersSpec + 		-

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.

+(Optional) +

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
-name
+counters
-string + +map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + 		-

Name is the name of the Fleet being scaled

+(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.
-namespace
+lists
-string + +map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus + 		-

Namespace is the namespace associated with the request (if any).

+(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.
-status
+eviction
- -FleetStatus + +Eviction 		-

The Fleet’s status values

+(Optional) +

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.
-

FleetAutoscaleResponse +

GameServerState +(string alias)

+

+(Appears on: +GameServerSelector, +GameServerStatus) +

+

+

GameServerState is the state for the GameServer

+

+

GameServerStatus

(Appears on: -FleetAutoscaleReview) +GameServer)

-

FleetAutoscaleResponse defines the response of webhook autoscaler endpoint

+

GameServerStatus is the status for a GameServer resource

@@ -5660,190 +5882,143 @@

FleetAutoscaleResponse

- -
-uid
+state
-k8s.io/apimachinery/pkg/types.UID + +GameServerState + 		-

UID is an identifier for the individual request/response. -This should be copied over from the corresponding FleetAutoscaleRequest.

+

GameServerState is the current state of a GameServer, e.g. Creating, Starting, Ready, etc
-scale
+ports
-bool + +[]GameServerStatusPort + 		-

Set to false if no scaling should occur to the Fleet
-replicas
+address
-int32 +string 		-

The targeted replica count
-

FleetAutoscaleReview -

-

-

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

-

- - - - - - - - - -
FieldDescription
-request
+addresses
- -FleetAutoscaleRequest + +[]Kubernetes core/v1.NodeAddress 		+(Optional) +

Addresses is the array of addresses at which the GameServer can be reached; copy of Node.Status.addresses.
-response
+nodeName
- -FleetAutoscaleResponse - +string
-

FleetAutoscalerPolicy -

-

-(Appears on: -FleetAutoscalerSpec) -

-

-

FleetAutoscalerPolicy describes how to scale a fleet

-

- - - - - - - -
FieldDescription
-type
+reservedUntil
- -FleetAutoscalerPolicyType + +Kubernetes meta/v1.Time 		-

Type of autoscaling policy.
-buffer
+players
- -BufferPolicy + +PlayerStatus 		(Optional) -

Buffer policy config params. Present only if FleetAutoscalerPolicyType = Buffer.

+

[Stage:Alpha] +[FeatureFlag:PlayerTracking]
-webhook
+counters
- -WebhookPolicy + +map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus 		(Optional) -

Webhook policy config params. Present only if FleetAutoscalerPolicyType = Webhook.

+

(Alpha, CountsAndLists feature flag) Counters and Lists provides the configuration for generic tracking features.
-counter
+lists
- -CounterPolicy + +map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus 		(Optional) -

[Stage:Alpha] -[FeatureFlag:CountsAndLists] -Counter policy config params. Present only if FleetAutoscalerPolicyType = Counter.
-list
+eviction
- -ListPolicy + +Eviction 		(Optional) -

[Stage:Alpha] -[FeatureFlag:CountsAndLists] -List policy config params. Present only if FleetAutoscalerPolicyType = List.

+

Eviction specifies the eviction tolerance of the GameServer.
-

FleetAutoscalerPolicyType -(string alias)

-

-(Appears on: -FleetAutoscalerPolicy) -

-

-

FleetAutoscalerPolicyType is the policy for autoscaling -for a given Fleet

-

-

FleetAutoscalerSpec +

GameServerStatusPort

(Appears on: -FleetAutoscaler) +GameServerAllocationStatus, +GameServerStatus)

-

FleetAutoscalerSpec is the spec for a Fleet Scaler

+

GameServerStatusPort shows the port that was allocated to a +GameServer.

@@ -5855,7 +6030,7 @@

FleetAutoscalerSpec

- - - -
-fleetName
+name
string @@ -5865,41 +6040,25 @@

FleetAutoscalerSpec

-policy
- - -FleetAutoscalerPolicy - - -		 -

Autoscaling policy

-
-sync
+port
- -FleetAutoscalerSync - +int32 		-(Optional) -

Sync defines when FleetAutoscalers runs autoscaling
-

FleetAutoscalerStatus +

GameServerTemplateSpec

(Appears on: -FleetAutoscaler) +FleetSpec, +GameServerSetSpec)

-

FleetAutoscalerStatus defines the current status of a FleetAutoscaler

+

GameServerTemplateSpec is a template for GameServers

@@ -5911,285 +6070,177 @@

FleetAutoscalerStatus

- - - - - - - - - +
+
+
-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
+metadata
- -Kubernetes meta/v1.Time + +Kubernetes meta/v1.ObjectMeta 		-(Optional) -

lastScaleTime is the last time the FleetAutoscaler scaled the attached fleet,

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-ableToScale
+spec
-bool + +GameServerSpec + 		-

AbleToScale indicates that we can access the target fleet

-
- -
-scalingLimited
+container
-bool +string 		-

ScalingLimited indicates that the calculated scale would be above or below the range -defined by MinReplicas and MaxReplicas, and has thus been capped.

+

Container specifies which Pod container is the game server. Only required if there is more than one +container defined
-

FleetAutoscalerSync -

-

-(Appears on: -FleetAutoscalerSpec) -

-

-

FleetAutoscalerSync describes when to sync a fleet

-

- - - - - - - - - -
FieldDescription
-type
+ports
- -FleetAutoscalerSyncType + +[]GameServerPort 		-

Type of autoscaling sync.

+

Ports are the array of ports that can be exposed via the game server
-fixedInterval
+health
- -FixedIntervalSync + +Health 		-(Optional) -

FixedInterval config params. Present only if FleetAutoscalerSyncType = FixedInterval.

+

Health configures health checking
-

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.

-

- - - - - - - - - -
FieldDescription
-key
+scheduling
-string +agones.dev/agones/pkg/apis.SchedulingStrategy 		-

Key is the name of the List. Required field.

+

Scheduling strategy. Defaults to “Packed”
-maxCapacity
+sdkServer
-int64 + +SdkServer + 		-

MaxCapacity is the maximum aggregate List total capacity across the fleet. -MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.

+

SdkServer specifies parameters for the Agones SDK Server sidecar container
-minCapacity
+template
-int64 + +Kubernetes core/v1.PodTemplateSpec + 		-

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.

+

Template describes the Pod that will be created for the GameServer
-bufferSize
+players
-k8s.io/apimachinery/pkg/util/intstr.IntOrString + +PlayersSpec + 		-

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.

+(Optional) +

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
-

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

-

- - - - - - - - + +
FieldDescription
-url
+counters
-string + +map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + 		(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.

+

(Alpha, CountsAndLists feature flag) Counters provides the configuration for tracking of int64 values against a GameServer. +Keys must be declared at GameServer creation time.
-service
+lists
- -Kubernetes admissionregistration/v1.ServiceReference + +map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus 		(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.

+

(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.
-caBundle
+eviction
-[]byte + +Eviction + 		(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.

+

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

+
-
-

multicluster.agones.dev/v1

+

Health +

-

Package v1 is the v1 version of the API.

+(Appears on: +GameServerSpec)

-Resource Types: - -

GameServerAllocationPolicy -

-

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

+

Health configures health checking on the GameServer

@@ -6201,93 +6252,59 @@

GameServerAllocat

- - - - - - - - -
-apiVersion
-string		 - -multicluster.agones.dev/v1 - -
-kind
-string -		GameServerAllocationPolicy
-metadata
+disabled
- -Kubernetes meta/v1.ObjectMeta - +bool 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +

Disabled is whether health checking is disabled or not
-spec
- - -GameServerAllocationPolicySpec - - -		 -
-
- - - - -
-priority
+periodSeconds
int32 		+

PeriodSeconds is the number of seconds each health ping has to occur in
-weight
+failureThreshold
-int +int32 		+

FailureThreshold how many failures in a row constitutes unhealthy
-connectionInfo
+initialDelaySeconds
- -ClusterConnectionInfo - +int32 		-
+

InitialDelaySeconds initial delay before checking health
-

ClusterConnectionInfo +

ListStatus

(Appears on: -GameServerAllocationPolicySpec) +GameServerSpec, +GameServerStatus)

-

ClusterConnectionInfo defines the connection information for a cluster

+

ListStatus stores the current list values and maximum capacity

@@ -6299,67 +6316,83 @@

ClusterConnectionInfo

+ +
-clusterName
+capacity
-string +int64 		-

Optional: the name of the targeted cluster
-allocationEndpoints
+values
[]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
+

PlayerStatus +

+

+(Appears on: +GameServerStatus) +

+

+

PlayerStatus stores the current player capacity values

+

+ + + + + + + +
FieldDescription
-secretName
+count
-string +int64 		-

The name of the secret that contains TLS client certificates to connect the allocator server in the targeted cluster
-namespace
+capacity
-string +int64 		-

The cluster namespace from which to allocate gameservers
-serverCa
+ids
-[]byte +[]string 		-

The PEM encoded server CA, used by the allocator client to authenticate the remote server.
-

ConnectionInfoIterator +

PlayersSpec

-

ConnectionInfoIterator an iterator on ClusterConnectionInfo

+(Appears on: +GameServerSpec) +

+

+

PlayersSpec tracks the initial player capacity

@@ -6371,58 +6404,89 @@

ConnectionInfoIterato

+ +
-currPriority
+initialCapacity
-int +int64 		-

currPriority Current priority index from the orderedPriorities
+

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.

+

+ + + + + + + +
FieldDescription
-orderedPriorities
+type
-[]int32 +string 		-

orderedPriorities list of ordered priorities

+

Type: Sort by a “Counter” or a “List”.
-priorityToCluster
+key
-map[int32]map[string][]*agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy +string 		-

priorityToCluster Map of priority to cluster-policies map

+

Key: The name of the Counter or List. If not found on the GameServer, has no impact.
-clusterBlackList
+order
-map[string]bool +string 		-

clusterBlackList the cluster blacklist for the clusters that has already returned

+

Order: Sort by “Ascending” or “Descending”. “Descending” a bigger available capacity is preferred. +“Ascending” would be smaller available capacity is preferred.
-

GameServerAllocationPolicySpec +

SdkServer

(Appears on: -GameServerAllocationPolicy) +GameServerSpec)

-

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

+

SdkServer specifies parameters for the Agones SDK Server sidecar container

@@ -6434,55 +6498,64 @@

GameServerAll

-priority
+logLevel
-int32 + +SdkServerLogLevel + 		+

LogLevel for SDK server (sidecar) logs. Defaults to “Info”
-weight
+grpcPort
-int +int32 		+

GRPCPort is the port on which the SDK Server binds the gRPC server to accept incoming connections
-connectionInfo
+httpPort
- -ClusterConnectionInfo - +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

+

-

agones.dev/v1

+

allocation.agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types: -

Fleet +

GameServerAllocation

-

Fleet is the data structure for a Fleet resource

+

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

@@ -6498,7 +6571,7 @@

Fleet string

@@ -6507,7 +6580,7 @@

Fleet kind
string -

+ @@ -6538,43 +6611,86 @@

Fleet

-agones.dev/v1 +allocation.agones.dev/v1
FleetGameServerAllocation
@@ -6527,8 +6600,8 @@

Fleet

spec
- -FleetSpec + +GameServerAllocationSpec
+ + + + + + + + @@ -6590,32 +6706,48 @@

Fleet

+ + + +
-replicas
+multiClusterSetting
-int32 + +MultiClusterSetting + 		-

Replicas are the number of GameServers that should be in this set. Defaults to 0.

+

MultiClusterPolicySelector if specified, multi-cluster policies are applied. +Otherwise, allocation will happen locally.
-allocationOverflow
+required
- -AllocationOverflow + +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: 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

+

[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.
-strategy
+selectors
- -Kubernetes apps/v1.DeploymentStrategy + +[]GameServerSelector 		-

Deployment strategy

+

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.
-priorities
+metadata
- -[]Priority + +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) -

(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] +Counter actions to perform during allocation.
-template
+lists
- -GameServerTemplateSpec + +map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction 		-

Template the GameServer template to apply for this Fleet

+(Optional) +

[Stage: Alpha] +[FeatureFlag:CountsAndLists] +List actions to perform during allocation.
@@ -6625,8 +6757,8 @@

Fleet status
- -FleetStatus + +GameServerAllocationStatus @@ -6635,14 +6767,14 @@

Fleet -

GameServer +

CounterAction

-

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.

+(Appears on: +GameServerAllocationSpec) +

+

+

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

@@ -6654,204 +6786,286 @@

GameServer

+action
+ +string + + + - + + +
-apiVersion
-string		 - -agones.dev/v1 - +(Optional) +

Action must to either “Increment” or “Decrement” the Counter’s Count. Must also define the Amount.
-kind
-string +amount
+ +int64 + +		 +(Optional) +

Amount is the amount to increment or decrement the Count. Must be a positive integer.

GameServer
-metadata
+capacity
- -Kubernetes meta/v1.ObjectMeta - +int64 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +(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.

+

+ + + + + + + + + + +
FieldDescription
+minCount
+ +int64 + +		 +(Optional) +

MinCount is the minimum current value. Defaults to 0.
-spec
+maxCount
- -GameServerSpec - +int64 		-
-
- +(Optional) +

MaxCount is the maximum current value. Defaults to 0, which translates as max(in64).

+ + + + + + + +
-container
+minAvailable
-string +int64 		-

Container specifies which Pod container is the game server. Only required if there is more than one -container defined

+(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

+

+ + - - + + + + - -
-ports
- - -[]GameServerPort - - -		 -

Ports are the array of ports that can be exposed via the game server

-		FieldDescription
-health
+multiClusterSetting
- -Health + +MultiClusterSetting 		-

Health configures health checking

+

MultiClusterPolicySelector if specified, multi-cluster policies are applied. +Otherwise, allocation will happen locally.
-scheduling
+required
-agones.dev/agones/pkg/apis.SchedulingStrategy + +GameServerSelector + 		-

Scheduling strategy. Defaults to “Packed”

+

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.
-sdkServer
+preferred
- -SdkServer + +[]GameServerSelector 		-

SdkServer specifies parameters for the Agones SDK Server sidecar container

+

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.
-template
+priorities
- -Kubernetes core/v1.PodTemplateSpec + +[]Priority 		-

Template describes the Pod that will be created for the GameServer

+(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.
-players
+selectors
- -PlayersSpec + +[]GameServerSelector 		-(Optional) -

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.

+

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.
-counters
+scheduling
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus - +agones.dev/agones/pkg/apis.SchedulingStrategy 		-(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.

+

Scheduling strategy. Defaults to “Packed”.
-lists
+metadata
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus + +MetaPatch 		-(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.

+

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
-eviction
+counters
- -Eviction + +map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction 		(Optional) -

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

-
+

[Stage: Alpha] +[FeatureFlag:CountsAndLists] +Counter actions to perform during allocation.
-status
+lists
- -GameServerStatus + +map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction 		+(Optional) +

[Stage: Alpha] +[FeatureFlag:CountsAndLists] +List actions to perform during allocation.
-

GameServerSet +

GameServerAllocationState +(string alias)

+

+(Appears on: +GameServerAllocationStatus) +

+

+

GameServerAllocationState is the Allocation state

+

+

GameServerAllocationStatus

-

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

+(Appears on: +GameServerAllocation) +

+

+

GameServerAllocationStatus is the status for an GameServerAllocation resource

@@ -6863,177 +7077,119 @@

GameServerSet

- - - - - - - - - - -
-apiVersion
-string		 - -agones.dev/v1 - -
-kind
-string -		GameServerSet
-metadata
+state
- -Kubernetes meta/v1.ObjectMeta + +GameServerAllocationState 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +

GameServerState is the current state of an GameServerAllocation, e.g. Allocated, or UnAllocated
-spec
- - -GameServerSetSpec - - -		 -
-
- - - - - - - - -
-replicas
+gameServerName
-int32 +string 		-

Replicas are the number of GameServers that should be in this set
-allocationOverflow
+ports
- -AllocationOverflow + +[]GameServerStatusPort 		-(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
+address
- -[]Priority - +string 		-(Optional) -

(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.
-template
+addresses
- -GameServerTemplateSpec + +[]Kubernetes core/v1.NodeAddress 		-

Template the GameServer template to apply for this GameServerSet

-
-status
+nodeName
- -GameServerSetStatus - +string
-

AggregatedCounterStatus -

-

-(Appears on: -FleetStatus, -GameServerSetStatus) -

-

-

AggregatedCounterStatus stores total and allocated Counter tracking values

-

- - - - - - - - + +
FieldDescription
-allocatedCount
+source
-int64 +string 		+

If the allocation is from a remote cluster, Source is the endpoint of the remote agones-allocator. +Otherwise, Source is “local”
-allocatedCapacity
+metadata
-int64 + +GameServerMetadata +
+

GameServerMetadata +

+

+(Appears on: +GameServerAllocationStatus) +

+

+

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

+

+ + + + + + + +
FieldDescription
-count
+labels
-int64 +map[string]string 		@@ -7041,9 +7197,9 @@

AggregatedCounterStatus

-capacity
+annotations
-int64 +map[string]string 		@@ -7051,15 +7207,15 @@

AggregatedCounterStatus

-

AggregatedListStatus +

GameServerSelector

(Appears on: -FleetStatus, -GameServerSetStatus) +GameServerAllocationSpec)

-

AggregatedListStatus stores total and allocated List tracking values

+

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

@@ -7071,55 +7227,98 @@

AggregatedListStatus

+ + + +
-allocatedCount
+LabelSelector
-int64 + +Kubernetes meta/v1.LabelSelector + 		+

+(Members of LabelSelector are embedded into this type.) +

+

See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
-allocatedCapacity
+gameServerState
-int64 + +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.
-count
+players
-int64 + +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.
-capacity
+lists
-int64 + +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.
-

AggregatedPlayerStatus +

ListAction

(Appears on: -FleetStatus, -GameServerSetStatus) +GameServerAllocationSpec)

-

AggregatedPlayerStatus stores total player tracking values

+

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

@@ -7131,12 +7330,14 @@

AggregatedPlayerStatus

@@ -7147,21 +7348,21 @@

AggregatedPlayerStatus

-count
+addValues
-int64 +[]string 		+(Optional) +

AddValues appends values to a List’s Values array. Any duplicate values will be ignored.
+(Optional) +

Capacity updates the maximum capacity of the Counter to this number. Min 0, Max 1000.
-

AllocationOverflow +

ListSelector

(Appears on: -FleetSpec, -GameServerSetSpec) +GameServerSelector)

-

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.

+

ListSelector is the filter options for a GameServer based on List available capacity and/or the +existence of a value in a List.

@@ -7173,39 +7374,50 @@

AllocationOverflow

+ + + +
-labels
+containsValue
-map[string]string +string 		(Optional) -

Labels to be applied to the GameServer

+

ContainsValue says to only match GameServers who has this value in the list. Defaults to “”, which is all.
-annotations
+minAvailable
-map[string]string +int64 		(Optional) -

Annotations to be applied to the GameServer

+

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

CounterStatus +

MetaPatch

(Appears on: -GameServerSpec, -GameServerStatus) +GameServerAllocationSpec)

-

CounterStatus stores the current counter values and maximum capacity

+

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

@@ -7217,9 +7429,9 @@

CounterStatus

-count
+labels
-int64 +map[string]string 		@@ -7227,9 +7439,9 @@

CounterStatus

-capacity
+annotations
-int64 +map[string]string 		@@ -7237,15 +7449,14 @@

CounterStatus

-

Eviction +

MultiClusterSetting

(Appears on: -GameServerSpec, -GameServerStatus) +GameServerAllocationSpec)

-

Eviction specifies the eviction tolerance of the GameServer

+

MultiClusterSetting specifies settings for multi-cluster allocation.

@@ -7257,39 +7468,36 @@

Eviction

+ + + +
-safe
+enabled
- -EvictionSafe +bool + +		 +
+policySelector
+ + +Kubernetes meta/v1.LabelSelector 		-

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 +

PlayerSelector

(Appears on: -Fleet) +GameServerSelector)

-

FleetSpec is the spec for a Fleet

+

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

@@ -7301,97 +7509,39 @@

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 - +minAvailable
+ +int64 		-(Optional) -

(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.
-template
+maxAvailable
- -GameServerTemplateSpec - +int64 		-

Template the GameServer template to apply for this Fleet
-

FleetStatus -

+
+

autoscaling.agones.dev/v1

-(Appears on: -Fleet, -FleetAutoscaleRequest) +

Package v1 is the v1 version of the API.

+Resource Types: + +

FleetAutoscaler +

-

FleetStatus is the status of a Fleet

+

FleetAutoscaler is the data structure for a FleetAutoscaler resource

@@ -7403,106 +7553,110 @@

FleetStatus

+ + + + - +
+
+
-replicas
- -int32 - +apiVersion
+string		 + +autoscaling.agones.dev/v1 +
-

Replicas the total number of current GameServer replicas

+kind
+string 		FleetAutoscaler
-readyReplicas
+metadata
-int32 + +Kubernetes meta/v1.ObjectMeta + 		-

ReadyReplicas are the number of Ready GameServer replicas

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-reservedReplicas
+spec
-int32 + +FleetAutoscalerSpec + 		-

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
+fleetName
-int32 +string 		-

AllocatedReplicas are the number of Allocated GameServer replicas
-players
+policy
- -AggregatedPlayerStatus + +FleetAutoscalerPolicy 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:PlayerTracking] -Players are the current total player capacity and count for this Fleet

+

Autoscaling policy
-counters
+sync
- -map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus + +FleetAutoscalerSync 		(Optional) -

(Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter -count for this Fleet.

+

Sync defines when FleetAutoscalers runs autoscaling

+
-lists
+status
- -map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus + +FleetAutoscalerStatus -(Optional) -

(Alpha, CountsAndLists feature flag) Lists provides aggregated List capacityv and List values -for this Fleet.

-

GameServerPort +

BufferPolicy

(Appears on: -GameServerSpec) +FleetAutoscalerPolicy)

-

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

+

BufferPolicy controls the desired behavior of the buffer policy.

@@ -7514,89 +7668,59 @@

GameServerPort

- - - - - - - - - - - -
-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
+maxReplicas
int32 		-

ContainerPort is the port that is being opened on the specified container’s process

+

MaxReplicas is the maximum amount of replicas that the fleet may have. +It must be bigger than both MinReplicas and BufferSize
-hostPort
+minReplicas
int32 		-

HostPort the port exposed on the host for clients to connect to

+

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
-protocol
+bufferSize
- -Kubernetes core/v1.Protocol - +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		-

Protocol is the network protocol being used. Defaults to UDP. TCP and TCPUDP are other options.

+

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)
-

GameServerSetSpec +

CounterPolicy

(Appears on: -GameServerSet) +FleetAutoscalerPolicy)

-

GameServerSetSpec the specification for GameServerSet

+

CounterPolicy controls the desired behavior of the Counter autoscaler policy.

@@ -7608,83 +7732,94 @@

GameServerSetSpec

+ +
-replicas
+key
-int32 +string 		-

Replicas are the number of GameServers that should be in this set

+

Key is the name of the Counter. Required field.
-allocationOverflow
+maxCapacity
- -AllocationOverflow - +int64 		-(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

+

MaxCapacity is the maximum aggregate Counter available capacity across the fleet. +MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
-scheduling
+minCapacity
-agones.dev/agones/pkg/apis.SchedulingStrategy +int64 		-

Scheduling strategy. Defaults to “Packed”.

+

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.
-priorities
+bufferSize
- -[]Priority - +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		-(Optional) -

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

+

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.

+

+ + + + + + + +
FieldDescription
-template
+seconds
- -GameServerTemplateSpec - +int32 		-

Template the GameServer template to apply for this GameServerSet

+

Seconds defines how often we run fleet autoscaling in seconds
-

GameServerSetStatus +

FleetAutoscaleRequest

(Appears on: -GameServerSet) +FleetAutoscaleReview)

-

GameServerSetStatus is the status of a GameServerSet

+

FleetAutoscaleRequest defines the request to webhook autoscaler endpoint

@@ -7696,116 +7831,113 @@

GameServerSetStatus

+ +
-replicas
+uid
-int32 +k8s.io/apimachinery/pkg/types.UID 		-

Replicas is the total number of current GameServer replicas

+

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.
-readyReplicas
+name
-int32 +string 		-

ReadyReplicas is the number of Ready GameServer replicas

+

Name is the name of the Fleet being scaled
-reservedReplicas
+namespace
-int32 +string 		-

ReservedReplicas is the number of Reserved GameServer replicas

+

Namespace is the namespace associated with the request (if any).
-allocatedReplicas
+status
-int32 + +FleetStatus + 		-

AllocatedReplicas is the number of Allocated GameServer replicas

+

The Fleet’s status values
+

FleetAutoscaleResponse +

+

+(Appears on: +FleetAutoscaleReview) +

+

+

FleetAutoscaleResponse defines the response of webhook autoscaler endpoint

+

+ + - - + + + +
-shutdownReplicas
- -int32 - -		 -

ShutdownReplicas is the number of Shutdown GameServers replicas

-		FieldDescription
-players
+uid
- -AggregatedPlayerStatus - +k8s.io/apimachinery/pkg/types.UID 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:PlayerTracking] -Players is the current total player capacity and count for this GameServerSet

+

UID is an identifier for the individual request/response. +This should be copied over from the corresponding FleetAutoscaleRequest.
-counters
+scale
- -map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus - +bool 		-(Optional) -

(Alpha, CountsAndLists feature flag) Counters provides aggregated Counter capacity and Counter -count for this GameServerSet.

+

Set to false if no scaling should occur to the Fleet
-lists
+replicas
- -map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus - +int32 		-(Optional) -

(Alpha, CountsAndLists feature flag) Lists provides aggregated List capacity and List values -for this GameServerSet.

+

The targeted replica count
-

GameServerSpec +

FleetAutoscaleReview

-(Appears on: -GameServer, -GameServerTemplateSpec) -

-

-

GameServerSpec is the spec for a GameServer resource

+

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

@@ -7817,194 +7949,152 @@

GameServerSpec

- - - - - - - - + +
-container
- -string - -		 -

Container specifies which Pod container is the game server. Only required if there is more than one -container defined

-
-ports
+request
- -[]GameServerPort + +FleetAutoscaleRequest 		-

Ports are the array of ports that can be exposed via the game server
-health
+response
- -Health + +FleetAutoscaleResponse 		-

Health configures health checking

-
-scheduling
- -agones.dev/agones/pkg/apis.SchedulingStrategy - -		 -

Scheduling strategy. Defaults to “Packed”
+

FleetAutoscalerPolicy +

+

+(Appears on: +FleetAutoscalerSpec) +

+

+

FleetAutoscalerPolicy describes how to scale a fleet

+

+ + - - + + + +
-sdkServer
- - -SdkServer - - -		 -

SdkServer specifies parameters for the Agones SDK Server sidecar container

-		FieldDescription
-template
+type
- -Kubernetes core/v1.PodTemplateSpec + +FleetAutoscalerPolicyType 		-

Template describes the Pod that will be created for the GameServer

+

Type of autoscaling policy.
-players
+buffer
- -PlayersSpec + +BufferPolicy 		(Optional) -

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.

+

Buffer policy config params. Present only if FleetAutoscalerPolicyType = Buffer.
-counters
+webhook
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + +WebhookPolicy 		(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.

+

Webhook policy config params. Present only if FleetAutoscalerPolicyType = Webhook.
-lists
+counter
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus + +CounterPolicy 		(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.

+

[Stage:Alpha] +[FeatureFlag:CountsAndLists] +Counter policy config params. Present only if FleetAutoscalerPolicyType = Counter.
-eviction
+list
- -Eviction + +ListPolicy 		(Optional) -

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

+

[Stage:Alpha] +[FeatureFlag:CountsAndLists] +List policy config params. Present only if FleetAutoscalerPolicyType = List.
-

GameServerState +

FleetAutoscalerPolicyType (string alias)

(Appears on: -GameServerSelector, -GameServerStatus) +FleetAutoscalerPolicy)

-

GameServerState is the state for the GameServer

+

FleetAutoscalerPolicyType is the policy for autoscaling +for a given Fleet

-

GameServerStatus +

FleetAutoscalerSpec

(Appears on: -GameServer) +FleetAutoscaler)

-

GameServerStatus is the status for a GameServer resource

+

FleetAutoscalerSpec is the spec for a Fleet Scaler

- - - - - - - - - - - - - + + + + + + +
FieldDescription
-state
- - -GameServerState - - -		 -

GameServerState is the current state of a GameServer, e.g. Creating, Starting, Ready, etc

-
-ports
- - -[]GameServerStatusPort - - -		 -
FieldDescription
-address
+fleetName
string @@ -8014,108 +8104,121 @@

GameServerStatus

-addresses
+policy
- -[]Kubernetes core/v1.NodeAddress + +FleetAutoscalerPolicy 		-(Optional) -

Addresses is the array of addresses at which the GameServer can be reached; copy of Node.Status.addresses.

+

Autoscaling policy
-nodeName
+sync
-string + +FleetAutoscalerSync + 		+(Optional) +

Sync defines when FleetAutoscalers runs autoscaling
+

FleetAutoscalerStatus +

+

+(Appears on: +FleetAutoscaler) +

+

+

FleetAutoscalerStatus defines the current status of a FleetAutoscaler

+

+ + + + + + + +
FieldDescription
-reservedUntil
+currentReplicas
- -Kubernetes meta/v1.Time - +int32 		+

CurrentReplicas is the current number of gameserver replicas +of the fleet managed by this autoscaler, as last seen by the autoscaler
-players
+desiredReplicas
- -PlayerStatus - +int32 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:PlayerTracking]

+

DesiredReplicas is the desired number of gameserver replicas +of the fleet managed by this autoscaler, as last calculated by the autoscaler
-counters
+lastScaleTime
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + +Kubernetes meta/v1.Time 		(Optional) -

(Alpha, CountsAndLists feature flag) Counters and Lists provides the configuration for generic tracking features.

+

lastScaleTime is the last time the FleetAutoscaler scaled the attached fleet,
-lists
+ableToScale
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus - +bool 		-(Optional) +

AbleToScale indicates that we can access the target fleet
-eviction
+scalingLimited
- -Eviction - +bool 		-(Optional) -

Eviction specifies the eviction tolerance of the GameServer.

+

ScalingLimited indicates that the calculated scale would be above or below the range +defined by MinReplicas and MaxReplicas, and has thus been capped.
-

GameServerStatusPort +

FleetAutoscalerSync

(Appears on: -GameServerAllocationStatus, -GameServerStatus) +FleetAutoscalerSpec)

-

GameServerStatusPort shows the port that was allocated to a -GameServer.

+

FleetAutoscalerSync describes when to sync a fleet

@@ -8127,35 +8230,50 @@

GameServerStatusPort

-name
+type
-string + +FleetAutoscalerSyncType + 		+

Type of autoscaling sync.
-port
+fixedInterval
-int32 + +FixedIntervalSync + 		+(Optional) +

FixedInterval config params. Present only if FleetAutoscalerSyncType = FixedInterval.
-

GameServerTemplateSpec +

FleetAutoscalerSyncType +(string alias)

+

+(Appears on: +FleetAutoscalerSync) +

+

+

FleetAutoscalerSyncType is the sync strategy for a given Fleet

+

+

ListPolicy

(Appears on: -FleetSpec, -GameServerSetSpec) +FleetAutoscalerPolicy)

-

GameServerTemplateSpec is a template for GameServers

+

ListPolicy controls the desired behavior of the List autoscaler policy.

@@ -8167,177 +8285,150 @@

GameServerTemplateSpec

- - - - -
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -GameServerSpec - - -		 -
-
- - - - - - - - - - - + +
-container
+key
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

+

Key is the name of the List. Required field.
-scheduling
+maxCapacity
-agones.dev/agones/pkg/apis.SchedulingStrategy +int64 		-

Scheduling strategy. Defaults to “Packed”

+

MaxCapacity is the maximum aggregate List available capacity across the fleet. +MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
-sdkServer
+minCapacity
- -SdkServer - +int64 		-

SdkServer specifies parameters for the Agones SDK Server sidecar container

+

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.
-template
+bufferSize
- -Kubernetes core/v1.PodTemplateSpec - +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		-

Template describes the Pod that will be created for the GameServer

+

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

+

+ + - - + + + + - -
-players
- - -PlayersSpec - - -		 -(Optional) -

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.

-		FieldDescription
-counters
+url
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus - +string 		(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.

+

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.
-lists
+service
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus + +Kubernetes admissionregistration/v1.ServiceReference 		(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.

+

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.
-eviction
+caBundle
- -Eviction - +[]byte 		(Optional) -

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.

-
+

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

Health -

+
+

multicluster.agones.dev/v1

-(Appears on: -GameServerSpec) +

Package v1 is the v1 version of the API.

+Resource Types: + +

GameServerAllocationPolicy +

-

Health configures health checking on the GameServer

+

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

@@ -8349,59 +8440,93 @@

Health

+ + + + + + + + +
-disabled
+apiVersion
+string		 + +multicluster.agones.dev/v1 + +
+kind
+string +		GameServerAllocationPolicy
+metadata
-bool + +Kubernetes meta/v1.ObjectMeta + 		-

Disabled is whether health checking is disabled or not

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-periodSeconds
+spec
+ + +GameServerAllocationPolicySpec + + +		 +
+
+ + + + +
+priority
int32 		-

PeriodSeconds is the number of seconds each health ping has to occur in
-failureThreshold
+weight
-int32 +int 		-

FailureThreshold how many failures in a row constitutes unhealthy
-initialDelaySeconds
+connectionInfo
-int32 + +ClusterConnectionInfo + 		-

InitialDelaySeconds initial delay before checking health

+
-

ListStatus +

ClusterConnectionInfo

(Appears on: -GameServerSpec, -GameServerStatus) +GameServerAllocationPolicySpec)

-

ListStatus stores the current list values and maximum capacity

+

ClusterConnectionInfo defines the connection information for a cluster

@@ -8413,83 +8538,67 @@

ListStatus

- -
-capacity
+clusterName
-int64 +string 		+

Optional: the name of the targeted cluster
-values
+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
-

PlayerStatus -

-

-(Appears on: -GameServerStatus) -

-

-

PlayerStatus stores the current player capacity values

-

- - - - - - - -
FieldDescription
-count
+secretName
-int64 +string 		+

The name of the secret that contains TLS client certificates to connect the allocator server in the targeted cluster
-capacity
+namespace
-int64 +string 		+

The cluster namespace from which to allocate gameservers
-ids
+serverCa
-[]string +[]byte 		+

The PEM encoded server CA, used by the allocator client to authenticate the remote server.
-

PlayersSpec +

ConnectionInfoIterator

-(Appears on: -GameServerSpec) -

-

-

PlayersSpec tracks the initial player capacity

+

ConnectionInfoIterator an iterator on ClusterConnectionInfo

@@ -8501,88 +8610,58 @@

PlayersSpec

- -
-initialCapacity
+currPriority
-int64 +int 		+

currPriority Current priority index from the orderedPriorities
-

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

-

- - - - - - - -
FieldDescription
-type
+orderedPriorities
-string +[]int32 		-

Type: Sort by a “Counter” or a “List”.

+

orderedPriorities list of ordered priorities
-key
+priorityToCluster
-string +map[int32]map[string][]*agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy 		-

Key: The name of the Counter or List. If not found on the GameServer, has no impact.

+

priorityToCluster Map of priority to cluster-policies map
-order
+clusterBlackList
-string +map[string]bool 		-

Order: Sort by “Ascending” or “Descending”. “Descending” a bigger Capacity is preferred. -“Ascending” would be smaller Capacity is preferred.

+

clusterBlackList the cluster blacklist for the clusters that has already returned
-

SdkServer +

GameServerAllocationPolicySpec

(Appears on: -GameServerSpec) +GameServerAllocationPolicy)

-

SdkServer specifies parameters for the Agones SDK Server sidecar container

+

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

@@ -8594,50 +8673,38 @@

SdkServer

-logLevel
+priority
- -SdkServerLogLevel - +int32 		-

LogLevel for SDK server (sidecar) logs. Defaults to “Info”
-grpcPort
+weight
-int32 +int 		-

GRPCPort is the port on which the SDK Server binds the gRPC server to accept incoming connections
-httpPort
+connectionInfo
-int32 + +ClusterConnectionInfo + 		-

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

-

Generated with gen-crd-api-reference-docs. diff --git a/site/content/en/docs/Reference/fleet.md b/site/content/en/docs/Reference/fleet.md index 87c0cd9601..08edf93419 100644 --- a/site/content/en/docs/Reference/fleet.md +++ b/site/content/en/docs/Reference/fleet.md @@ -57,14 +57,14 @@ spec: # # [Stage:Alpha] # [FeatureFlag:CountsAndLists] - # Which gameservers in the Fleet are most important to keep around - impacts scale down logic. + # 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. + # order: Descending # Default is "Ascending" so smaller available 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. + # order: Ascending # Default is "Ascending" so smaller available capacity will be removed first on down scaling. # template: # GameServer metadata @@ -129,10 +129,11 @@ 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. +- `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. + - `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]({{< relref "gameserver.md" >}}) reference for all available fields. diff --git a/site/content/en/docs/Reference/fleetautoscaler.md b/site/content/en/docs/Reference/fleetautoscaler.md index 8bec87e42e..1cded0af82 100644 --- a/site/content/en/docs/Reference/fleetautoscaler.md +++ b/site/content/en/docs/Reference/fleetautoscaler.md @@ -57,7 +57,7 @@ spec: ## 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 total capacity available. +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 @@ -77,22 +77,22 @@ 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 ``` 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 total capacity available. +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 @@ -112,17 +112,17 @@ 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 ``` @@ -210,14 +210,14 @@ The `spec` field of the `FleetAutoscaler` is composed as follows: - `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. + - `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. + - `maxCapacity` is the maximum aggregate Counter available 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. + - `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. + - `maxCapacity` is the maximum aggregate List available 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 diff --git a/site/content/en/docs/Reference/gameserverallocation.md b/site/content/en/docs/Reference/gameserverallocation.md index 1142edd48e..c453dc7afa 100644 --- a/site/content/en/docs/Reference/gameserverallocation.md +++ b/site/content/en/docs/Reference/gameserverallocation.md @@ -80,31 +80,37 @@ spec: mode: deathmatch annotations: map: garden22 - # [Stage:Alpha] - # [FeatureFlag:CountsAndLists] - # 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. Optional. - # priorities: - # - type: List # 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. + # [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. {{< /tab >}} {{< tab header="required & preferred (deprecated)" lang="yaml" >}} apiVersion: "allocation.agones.dev/v1" @@ -199,8 +205,7 @@ The `spec` field is the actual `GameServerAllocation` specification, and it is c cluster. See [Scheduling and Autoscaling]({{< ref "/docs/Advanced/scheduling-and-autoscaling.md" >}}) 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) manages counters and lists for game servers, setting limits on - room counts and player inclusion/exclusion. +- `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. diff --git a/test/e2e/fleetautoscaler_test.go b/test/e2e/fleetautoscaler_test.go index 04b383f54f..c57a9152c6 100644 --- a/test/e2e/fleetautoscaler_test.go +++ b/test/e2e/fleetautoscaler_test.go @@ -845,7 +845,7 @@ func TestCounterAutoscaler(t *testing.T) { fap.Counter = &autoscalingv1.CounterPolicy{ Key: "players", BufferSize: intstr.FromInt(5), // Buffer refers to the available capacity (AggregateCapacity - AggregateCount) - MinCapacity: 10, // Min and MaxCapacity refer to the total capacity aggregated across the fleet, NOT the available capacity + MinCapacity: 10, // Min and MaxCapacity refer to the available capacity aggregated across the fleet, NOT the available capacity MaxCapacity: 100, } }),