diff --git a/examples/counterfleetautoscaler.yaml b/examples/counterfleetautoscaler.yaml index 6a301a151c..f63e846c5c 100644 --- a/examples/counterfleetautoscaler.yaml +++ b/examples/counterfleetautoscaler.yaml @@ -33,7 +33,7 @@ spec: type: Counter # Counter based autoscaling counter: # Key is the name of the Counter. Required field. - key: players + key: rooms # BufferSize is the size of a buffer of counted items that are available in the Fleet (available capacity). # Value can be an absolute number (ex: 5) or a percentage of the Counter available capacity (ex: 5%). # An absolute number is calculated from percentage by rounding up. Must be bigger than 0. Required field. diff --git a/examples/fleet.yaml b/examples/fleet.yaml index 5ae6894d40..212b3cda26 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..0fd5004866 100644 --- a/examples/listfleetautoscaler.yaml +++ b/examples/listfleetautoscaler.yaml @@ -33,7 +33,7 @@ spec: type: List # List based autoscaling. list: # Key is the name of the List. Required field. - key: rooms + key: players # BufferSize is the size of a buffer based on the List capacity that is available over the current # aggregate List length in the Fleet (available capacity). # It can be specified either as an absolute value (i.e. 5) or percentage format (i.e. 5%). 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 85365cbde4..eb4f50b1f7 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 42aaf170b7..3d6683b1bb 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 ef0b5bc682..5df2807de0 100644 --- a/pkg/allocation/go/allocation.swagger.json +++ b/pkg/allocation/go/allocation.swagger.json @@ -190,14 +190,14 @@ "type": "object", "$ref": "#/definitions/allocationPriority" }, - "description": "(Alpha, CountsAndLists feature flag) The first Priority on the array of Priorities is the most\nimportant for sorting. The allocator will use the first priority for sorting GameServers in the\nSelector set, and will only use any following priority for tie-breaking during sort.\nImpacts which GameServer is checked first." + "description": "[Stage: Alpha]\n[FeatureFlag:CountsAndLists]\n`Priorities` configuration alters the order in which `GameServers` are searched for matches to the configured `selectors`.\n\nPriority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first.\n\nFor `Packed` strategy sorting, this priority list will be the tie-breaker within the least utilised infrastructure, to ensure optimal\ninfrastructure usage while also allowing some custom prioritisation of `GameServers`.\n\nFor `Distributed` strategy sorting, the entire selection of `GameServers` will be sorted by this priority list to provide the\norder that `GameServers` will be allocated by." }, "counters": { "type": "object", "additionalProperties": { "$ref": "#/definitions/allocationCounterAction" }, - "description": "(Alpha, CountsAndLists feature flag) Counters and Lists provide a set of actions to perform\non Counters and Lists during allocation." + "description": "[Stage: Alpha]\n[FeatureFlag:CountsAndLists]\nCounters and Lists provide a set of actions to perform\non Counters and Lists during allocation." }, "lists": { "type": "object", 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 ed17f5e296..6e76e32e3e 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/proto/allocation/allocation.proto b/proto/allocation/allocation.proto index 914177e631..fe886c9ba4 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 914177e631..fe886c9ba4 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..fecfca8a3d --- /dev/null +++ b/site/content/en/docs/Guides/counters-and-lists.md @@ -0,0 +1,388 @@ +--- +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" >}}). + +## Fleet Scale Down Prioritisation + +Another optimisation control you can apply with `Fleets` when Agones' scaled them down, is to also set `priorities` +to influence the order in which `GameServers` are shutdown and deleted. + +{{< feature expiryVersion="1.40.0" >}} + +{{% alert title="Warning" color="warning" %}} +In versions 1.39.0 and lower, Fleet prioritisation is calculated using _total capacity_, not _available capacity_. This +is being updated in the 1.40.0 release such that this and all uses of `priorities` operate using _available capacity_, +and unless otherwise noted, will be the default behaviour in future releases. + +Therefore, in this rare case, the documentation on this functionality is forward-looking. +{{% /alert %}} + +{{< /feature >}} + +While neither `players` or `rooms` are particularly good examples for this functionality, if we wanted to ensure +that `Ready` `GameServers` with the most available capacity `rooms` where a factor when scaling down a `Fleet` we could +implement the following: + +```yaml +apiVersion: agones.dev/v1 +kind: Fleet +metadata: + name: simple-game-server +spec: + replicas: 2 + priorities: + - type: Counter + key: rooms + order: Descending + template: + spec: + ports: + - name: default + containerPort: 7654 + counters: + rooms: # room counter + count: 0 + capacity: 10 + template: + spec: + containers: + - name: simple-game-server + image: {{< example-image >}} +``` + +Depending on the Fleet allocation strategy, the `priorities` block will influence scale down logic as follows: + +* Packed: The [usual infrastructure optimisation strategy]({{< ref "/docs/Advanced/scheduling-and-autoscaling.md#fleet-scheduling" >}}) + 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 scaled down by. + +See [Fleet Reference]({{< ref "/docs/Reference/fleet.md" >}}) for all the configuration options. + +## 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/Integration Patterns/player-capacity.md b/site/content/en/docs/Integration Patterns/player-capacity.md index e2c25c1752..3165c33036 100644 --- a/site/content/en/docs/Integration Patterns/player-capacity.md +++ b/site/content/en/docs/Integration Patterns/player-capacity.md @@ -7,6 +7,16 @@ description: > Find a `GameServer` that has room for a specific number of players. --- +{{% 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. + +This document will be updated to utilise Counters and Lists in the near future. +{{% /pageinfo %}} + {{< alpha title="Player Tracking and Allocation Player Filter" gate="PlayerTracking,PlayerAllocationFilter" >}} 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 7927eeeead..bdc5778527 100644 --- a/site/content/en/docs/Reference/agones_crd_api_reference.html +++ b/site/content/en/docs/Reference/agones_crd_api_reference.html @@ -7,6 +7,9 @@

Packages:

-

agones.dev/v1

+

multicluster.agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types: -

Fleet +

GameServerAllocationPolicy

-

Fleet is the data structure for a Fleet resource

+

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

@@ -50,7 +46,7 @@

Fleet string

@@ -59,7 +55,7 @@

Fleet kind
string -

+ @@ -90,111 +86,121 @@

Fleet

-agones.dev/v1 +multicluster.agones.dev/v1
FleetGameServerAllocationPolicy
@@ -79,8 +75,8 @@

Fleet

spec
- -FleetSpec + +GameServerAllocationPolicySpec
+
-replicas
+priority
int32 		-

Replicas are the number of GameServers that should be in this set. Defaults to 0.
-allocationOverflow
+weight
- -AllocationOverflow - +int 		-(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
+connectionInfo
- -Kubernetes apps/v1.DeploymentStrategy + +ClusterConnectionInfo 		-

Deployment strategy
+ + + + +

ClusterConnectionInfo +

+

+(Appears on: +GameServerAllocationPolicySpec) +

+

+

ClusterConnectionInfo defines the connection information for a cluster

+

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

Scheduling strategy. Defaults to “Packed”.

+

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

+

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
-template
+secretName
- -GameServerTemplateSpec - +string 		-

Template the GameServer template to apply for this Fleet

+

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

The cluster namespace from which to allocate gameservers

-status
+serverCa
- -FleetStatus - +[]byte +

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

-

GameServer +

ConnectionInfoIterator

-

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.

+

ConnectionInfoIterator an iterator on ClusterConnectionInfo

@@ -206,116 +212,403 @@

GameServer

+currPriority
+ +int + + + - + + +
-apiVersion
-string		 - -agones.dev/v1 - +

currPriority Current priority index from the orderedPriorities
-kind
-string +orderedPriorities
+ +[]int32 + +		 +

orderedPriorities list of ordered priorities

GameServer
-metadata
+priorityToCluster
- -Kubernetes meta/v1.ObjectMeta - +map[int32]map[string][]*agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +

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

clusterBlackList the cluster blacklist for the clusters that has already returned

+
+

GameServerAllocationPolicySpec +

+

+(Appears on: +GameServerAllocationPolicy) +

+

+

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

+

+ + + + + + + + +
FieldDescription
-container
+priority
-string +int32 		-

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

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

Health configures health checking
+
+

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
-scheduling
- -agones.dev/agones/pkg/apis.SchedulingStrategy - +apiVersion
+string		 + +agones.dev/v1 +
-

Scheduling strategy. Defaults to “Packed”

+kind
+string 		Fleet
-sdkServer
+metadata
- -SdkServer + +Kubernetes meta/v1.ObjectMeta 		-

SdkServer specifies parameters for the Agones SDK Server sidecar container

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-template
+spec
- -Kubernetes core/v1.PodTemplateSpec + +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.

+

+ + + + + + + + + + + + + + + + + + + + + + + @@ -2664,7 +2980,9 @@

GameServerAllocationS

@@ -2678,7 +2996,9 @@

GameServerAllocationS

@@ -2800,43 +3120,19 @@

GameServerAllocatio

- - - - - - - - - -
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 + + +		 +
+
+ + + + + + + + + + + + + + + + + + + + + + + @@ -507,10 +800,14 @@

GameServerSet

@@ -753,7 +1050,6 @@

CounterStatus

(Appears on: -GameServerAllocationStatus, GameServerSpec, GameServerStatus)

@@ -915,10 +1211,14 @@

FleetSpec

@@ -1209,10 +1509,14 @@

GameServerSetSpec

@@ -1950,7 +2254,6 @@

ListStatus

(Appears on: -GameServerAllocationStatus, GameServerSpec, GameServerStatus)

@@ -2083,7 +2386,8 @@

Priority GameServerSetSpec)

-

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.

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

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

(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.
@@ -2123,8 +2427,8 @@

Priority

@@ -2317,10 +2621,14 @@

GameServerAllocation

@@ -2375,7 +2683,9 @@

GameServerAllocation

@@ -2389,7 +2699,9 @@

GameServerAllocation

-

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

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

+

[Stage: Alpha] +[FeatureFlag:CountsAndLists] +Counter actions to perform during allocation.
(Optional) -

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

+

[Stage: Alpha] +[FeatureFlag:CountsAndLists] +List actions to perform during allocation.
@@ -2606,10 +2918,14 @@

GameServerAllocationS

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

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

+

[Stage: Alpha] +[FeatureFlag:CountsAndLists] +Counter actions to perform during allocation.
(Optional) -

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

+

[Stage: Alpha] +[FeatureFlag:CountsAndLists] +List actions to perform during allocation.
-counters
- - -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus - - -		 -
-lists
- - -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus - - -		 -
-

GameServerMetadata -

-

-(Appears on: -GameServerAllocationStatus) -

-

-

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

-

- - + +
+

GameServerMetadata +

+

+(Appears on: +GameServerAllocationStatus) +

+

+

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

+

+ + @@ -2942,7 +3238,9 @@

GameServerSelector

@@ -2958,7 +3256,9 @@

GameServerSelector

@@ -4071,18 +4371,42 @@

WebhookPolicy

Field Description (Optional) -

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

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

-

multicluster.agones.dev/v1

+

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

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

Packages:

+ +

agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types: -

GameServerAllocationPolicy +

Fleet

-

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

+

Fleet is the data structure for a Fleet resource

@@ -4098,7 +4422,7 @@

GameServerAllocat string

@@ -4107,13 +4431,13 @@

GameServerAllocat kind
string -

+ @@ -4138,121 +4462,115 @@

GameServerAllocat

-multicluster.agones.dev/v1 +agones.dev/v1
GameServerAllocationPolicyFleet
metadata
- + Kubernetes meta/v1.ObjectMeta @@ -4127,8 +4451,8 @@

GameServerAllocat

spec
- -GameServerAllocationPolicySpec + +FleetSpec
-
-priority
+replicas
int32 		+

Replicas are the number of GameServers that should be in this set. Defaults to 0.
-weight
+allocationOverflow
-int + +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
-connectionInfo
+strategy
- -ClusterConnectionInfo + +Kubernetes apps/v1.DeploymentStrategy 		+

Deployment strategy
- - - - -

ClusterConnectionInfo -

-

-(Appears on: -GameServerAllocationPolicySpec) -

-

-

ClusterConnectionInfo defines the connection information for a cluster

-

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

Optional: the name of the targeted cluster

+

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

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

[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.
-secretName
+template
-string + +GameServerTemplateSpec + 		-

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

+

Template the GameServer template to apply for this Fleet
-namespace
- -string - -		 -

The cluster namespace from which to allocate gameservers

+
-serverCa
+status
-[]byte + +FleetStatus + -

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

-

ConnectionInfoIterator +

GameServer

-

ConnectionInfoIterator an iterator on ClusterConnectionInfo

+

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.

@@ -4264,675 +4582,204 @@

ConnectionInfoIterato

+apiVersion
+string - + - - -
-currPriority
- -int - -		 -

currPriority Current priority index from the orderedPriorities

+ +agones.dev/v1 +
-orderedPriorities
- -[]int32 - -		 -

orderedPriorities list of ordered priorities

+kind
+string 		GameServer
-priorityToCluster
+metadata
-map[int32]map[string][]*agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy + +Kubernetes meta/v1.ObjectMeta + 		-

priorityToCluster Map of priority to cluster-policies map

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-clusterBlackList
+spec
-map[string]bool + +GameServerSpec + 		-

clusterBlackList the cluster blacklist for the clusters that has already returned

-
-

GameServerAllocationPolicySpec -

-

-(Appears on: -GameServerAllocationPolicy) -

-

-

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

-

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

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

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

Packages:

- -

autoscaling.agones.dev/v1

-

-

Package v1 is the v1 version of the API.

-

-Resource Types: - -

FleetAutoscaler -

-

-

FleetAutoscaler is the data structure for a FleetAutoscaler resource

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-apiVersion
-string		 - -autoscaling.agones.dev/v1 - -
-kind
-string -		FleetAutoscaler
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -FleetAutoscalerSpec - - -		 -
-
- - - - - - - - - - - - - -
-fleetName
- -string - -		 -
-policy
- - -FleetAutoscalerPolicy - - -		 -

Autoscaling policy

-
-sync
- - -FleetAutoscalerSync - - -		 -(Optional) -

Sync defines when FleetAutoscalers runs autoscaling

-
-
-status
- - -FleetAutoscalerStatus - - -		 -
-

BufferPolicy -

-

-(Appears on: -FleetAutoscalerPolicy) -

-

-

BufferPolicy controls the desired behavior of the buffer policy.

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-maxReplicas
- -int32 - -		 -

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

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

-
-bufferSize
- -k8s.io/apimachinery/pkg/util/intstr.IntOrString - -		 -

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.

-

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-key
- -string - -		 -

Key is the name of the Counter. Required field.

-
-maxCapacity
- -int64 - -		 -

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

-
-minCapacity
- -int64 - -		 -

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.

-
-bufferSize
- -k8s.io/apimachinery/pkg/util/intstr.IntOrString - -		 -

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
-seconds
- -int32 - -		 -

Seconds defines how often we run fleet autoscaling in seconds

-
-

FleetAutoscaleRequest -

-

-(Appears on: -FleetAutoscaleReview) -

-

-

FleetAutoscaleRequest defines the request to webhook autoscaler endpoint

-

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-uid
- -k8s.io/apimachinery/pkg/types.UID - -		 -

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.

-
-name
- -string - -		 -

Name is the name of the Fleet being scaled

-
-namespace
- -string - -		 -

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

-
-status
- - -FleetStatus - - -		 -

The Fleet’s status values

-
-

FleetAutoscaleResponse -

-

-(Appears on: -FleetAutoscaleReview) -

-

-

FleetAutoscaleResponse defines the response of webhook autoscaler endpoint

-

- - - - - - - - - - - - - - - - -
FieldDescription
-uid
- -k8s.io/apimachinery/pkg/types.UID - -		 -

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

-
-scale
- -bool - -		 -

Set to false if no scaling should occur to the Fleet

+

Health configures health checking
-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
+sdkServer
- -FleetAutoscaleRequest + +SdkServer 		+

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

Template describes the Pod that will be created for the GameServer
-

FleetAutoscalerPolicy -

-

-(Appears on: -FleetAutoscalerSpec) -

-

-

FleetAutoscalerPolicy describes how to scale a fleet

-

- - - - - - - - + +
FieldDescription
-type
+players
- -FleetAutoscalerPolicyType + +PlayersSpec 		-

Type of autoscaling policy.

+(Optional) +

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

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

+

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

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

+

(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.
-counter
+eviction
- -CounterPolicy + +Eviction 		(Optional) -

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

+

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

+
-list
+status
- -ListPolicy + +GameServerStatus -(Optional) -

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

-

FleetAutoscalerPolicyType -(string alias)

-

-(Appears on: -FleetAutoscalerPolicy) -

-

-

FleetAutoscalerPolicyType is the policy for autoscaling -for a given Fleet

-

-

FleetAutoscalerSpec +

GameServerSet

-(Appears on: -FleetAutoscaler) -

-

-

FleetAutoscalerSpec is the spec for a Fleet Scaler

+

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

@@ -4944,131 +4791,147 @@

FleetAutoscalerSpec

+ + + + - - -
-fleetName
- -string - +apiVersion
+string		 + +agones.dev/v1 +
+kind
+string 		GameServerSet
-policy
+metadata
- -FleetAutoscalerPolicy + +Kubernetes meta/v1.ObjectMeta 		-

Autoscaling policy

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-sync
+spec
- -FleetAutoscalerSync + +GameServerSetSpec 		-(Optional) -

Sync defines when FleetAutoscalers runs autoscaling

-
-

FleetAutoscalerStatus -

-

-(Appears on: -FleetAutoscaler) -

-

-

FleetAutoscalerStatus defines the current status of a FleetAutoscaler

-

+
+
- - - + + - - + +
FieldDescription +replicas
+ +int32 + +		 +

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

+
-currentReplicas
+allocationOverflow
-int32 + +AllocationOverflow + 		-

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

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

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

+

Scheduling strategy. Defaults to “Packed”.
-lastScaleTime
+priorities
- -Kubernetes meta/v1.Time + +[]Priority 		(Optional) -

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

+

[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.
-ableToScale
+template
-bool + +GameServerTemplateSpec + 		-

AbleToScale indicates that we can access the target fleet

+

Template the GameServer template to apply for this GameServerSet

+
-scalingLimited
+status
-bool + +GameServerSetStatus + -

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

-

FleetAutoscalerSync +

AggregatedCounterStatus

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

-

FleetAutoscalerSync describes when to sync a fleet

+

AggregatedCounterStatus stores total and allocated Counter tracking values

@@ -5080,50 +4943,55 @@

FleetAutoscalerSync

+ + + + + + + +
-type
+allocatedCount
- -FleetAutoscalerSyncType - +int64 		-

Type of autoscaling sync.
-fixedInterval
+allocatedCapacity
- -FixedIntervalSync - +int64 + +		 +
+count
+ +int64 + +		 +
+capacity
+ +int64 		-(Optional) -

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

FleetAutoscalerSyncType -(string alias)

-

-(Appears on: -FleetAutoscalerSync) -

-

-

FleetAutoscalerSyncType is the sync strategy for a given Fleet

-

-

ListPolicy +

AggregatedListStatus

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

-

ListPolicy controls the desired behavior of the List autoscaler policy.

+

AggregatedListStatus stores total and allocated List tracking values

@@ -5135,66 +5003,55 @@

ListPolicy

-key
+allocatedCount
-string +int64 		-

Key is the name of the List. Required field.
-maxCapacity
+allocatedCapacity
int64 		-

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

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
+capacity
-k8s.io/apimachinery/pkg/util/intstr.IntOrString +int64 		-

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 +

AggregatedPlayerStatus

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

-

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

+

AggregatedPlayerStatus stores total player tracking values

@@ -5206,79 +5063,37 @@

WebhookPolicy

- - - -
-url
- -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
+count
- -Kubernetes admissionregistration/v1.ServiceReference - +int64 		-(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.
-caBundle
+capacity
-[]byte +int64 		-(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.
-
-

multicluster.agones.dev/v1

+

AllocationOverflow +

-

Package v1 is the v1 version of the API.

+(Appears on: +FleetSpec, +GameServerSetSpec)

-Resource Types: - -

GameServerAllocationPolicy -

-

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

+

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.

@@ -5290,63 +5105,54 @@

GameServerAllocat

- - - - - - - - + + +
-apiVersion
-string		 - -multicluster.agones.dev/v1 - -
-kind
-string -		GameServerAllocationPolicy
-metadata
+labels
- -Kubernetes meta/v1.ObjectMeta - +map[string]string 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +(Optional) +

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

Annotations to be applied to the GameServer

+
+

CounterStatus +

+

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

+

+

CounterStatus stores the current counter values and maximum capacity

+

+ - - + + + + -
-priority
- -int32 - -		 -FieldDescription
-weight
+count
-int +int64 		@@ -5354,29 +5160,25 @@

GameServerAllocat

-connectionInfo
+capacity
- -ClusterConnectionInfo - +int64
- - -

ClusterConnectionInfo +

Eviction

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

-

ClusterConnectionInfo defines the connection information for a cluster

+

Eviction specifies the eviction tolerance of the GameServer

@@ -5388,130 +5190,145 @@

ClusterConnectionInfo

- - - - + +
-clusterName
- -string - -		 -

Optional: the name of the targeted cluster

-
-allocationEndpoints
+safe
-[]string + +EvictionSafe + 		-

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

+

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

+

+ + - - + + + + - -
-secretName
- -string - -		 -

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

-		FieldDescription
-namespace
+replicas
-string +int32 		-

The cluster namespace from which to allocate gameservers

+

Replicas are the number of GameServers that should be in this set. Defaults to 0.
-serverCa
+allocationOverflow
-[]byte + +AllocationOverflow + 		-

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

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

ConnectionInfoIterator -

-

-

ConnectionInfoIterator an iterator on ClusterConnectionInfo

-

- - - - - - - -
FieldDescription
-currPriority
+strategy
-int + +Kubernetes apps/v1.DeploymentStrategy + 		-

currPriority Current priority index from the orderedPriorities

+

Deployment strategy
-orderedPriorities
+scheduling
-[]int32 +agones.dev/agones/pkg/apis.SchedulingStrategy 		-

orderedPriorities list of ordered priorities

+

Scheduling strategy. Defaults to “Packed”.
-priorityToCluster
+priorities
-map[int32]map[string][]*agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy + +[]Priority + 		-

priorityToCluster Map of priority to cluster-policies map

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

clusterBlackList the cluster blacklist for the clusters that has already returned

+

Template the GameServer template to apply for this Fleet
-

GameServerAllocationPolicySpec +

FleetStatus

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

-

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

+

FleetStatus is the status of a Fleet

@@ -5523,215 +5340,200 @@

GameServerAll

- -
-priority
+replicas
int32 		+

Replicas the total number of current GameServer replicas
-weight
+readyReplicas
-int +int32 		+

ReadyReplicas are the number of Ready GameServer replicas
-connectionInfo
+reservedReplicas
- -ClusterConnectionInfo - +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.
-
-

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 - +allocatedReplicas
+ +int32 +
-kind
-string +

AllocatedReplicas are the number of Allocated GameServer replicas

Fleet
-metadata
+players
- -Kubernetes meta/v1.ObjectMeta + +AggregatedPlayerStatus 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +(Optional) +

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

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

+ + + +
-replicas
+lists
-int32 + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedListStatus + 		-

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

+(Optional) +

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

GameServerPort +

+

+(Appears on: +GameServerSpec) +

+

+

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

+

+ + + + + + + + - -
FieldDescription
-allocationOverflow
+name
- -AllocationOverflow - +string 		-(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

+

Name is the descriptive name of the port
-strategy
+portPolicy
- -Kubernetes apps/v1.DeploymentStrategy + +PortPolicy 		-

Deployment strategy

+

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
-scheduling
+container
-agones.dev/agones/pkg/apis.SchedulingStrategy +string 		-

Scheduling strategy. Defaults to “Packed”.

+(Optional) +

Container is the name of the container on which to open the port. Defaults to the game server container.
-priorities
+containerPort
- -[]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.

+

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

Template the GameServer template to apply for this Fleet

-
+

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

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

GameServer +

GameServerSetSpec

-

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: +GameServerSet) +

+

+

GameServerSetSpec the specification for GameServerSet

@@ -5743,283 +5545,253 @@

GameServer

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

Replicas are the number of GameServers that should be in this set
-spec
+allocationOverflow
- -GameServerSpec + +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

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

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

+

Scheduling strategy. Defaults to “Packed”.
-ports
+priorities
- -[]GameServerPort + +[]Priority 		-

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

+(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.
-health
+template
- -Health + +GameServerTemplateSpec 		-

Health configures health checking

+

Template the GameServer template to apply for this GameServerSet
+

GameServerSetStatus +

+

+(Appears on: +GameServerSet) +

+

+

GameServerSetStatus is the status of a GameServerSet

+

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

Scheduling strategy. Defaults to “Packed”

+

Replicas is the total number of current GameServer replicas
-sdkServer
+readyReplicas
- -SdkServer - +int32 		-

SdkServer specifies parameters for the Agones SDK Server sidecar container

+

ReadyReplicas is the number of Ready GameServer replicas
-template
+reservedReplicas
- -Kubernetes core/v1.PodTemplateSpec - +int32 		-

Template describes the Pod that will be created for the GameServer

+

ReservedReplicas is the number of Reserved GameServer replicas
-players
+allocatedReplicas
- -PlayersSpec - +int32 		-(Optional) -

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

+

AllocatedReplicas is the number of Allocated GameServer replicas
-counters
+shutdownReplicas
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus - +int32 		-(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.

+

ShutdownReplicas is the number of Shutdown GameServers replicas
-lists
+players
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus + +AggregatedPlayerStatus 		(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:PlayerTracking] +Players is the current total player capacity and count for this GameServerSet
-eviction
+counters
- -Eviction + +map[string]agones.dev/agones/pkg/apis/agones/v1.AggregatedCounterStatus 		(Optional) -

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

-
+

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

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

GameServerSet +

GameServerSpec

-

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

+(Appears on: +GameServer, +GameServerTemplateSpec)

- - - - - - - - - - - - +

+

GameServerSpec is the spec for a GameServer resource

+

+
FieldDescription
-apiVersion
-string		 - -agones.dev/v1 - -
+ - - + + + + - - -
-kind
-string -		GameServerSetFieldDescription
-metadata
+container
- -Kubernetes meta/v1.ObjectMeta - +string 		-Refer to the Kubernetes API documentation for the fields of the -metadata field. +

Container specifies which Pod container is the game server. Only required if there is more than one +container defined
-spec
+ports
- -GameServerSetSpec + +[]GameServerPort 		-
-
- - - - @@ -6030,125 +5802,113 @@

GameServerSet

- -
-replicas
- -int32 - -		 -

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

+

Ports are the array of ports that can be exposed via the game server
-allocationOverflow
+health
- -AllocationOverflow + +Health 		-(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

+

Health configures health checking
-

Scheduling strategy. Defaults to “Packed”.

+

Scheduling strategy. Defaults to “Packed”
-priorities
+sdkServer
- -[]Priority + +SdkServer 		-(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.

+

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

Template the GameServer template to apply for this GameServerSet

-
+

Template describes the Pod that will be created for the GameServer
-status
+players
- -GameServerSetStatus + +PlayersSpec 		-
-

AggregatedCounterStatus -

-

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

-

-

AggregatedCounterStatus stores total and allocated Counter tracking values

-

- - - - - - - - - - -
FieldDescription
-allocatedCount
- -int64 - -		 +(Optional) +

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
-allocatedCapacity
+counters
-int64 + +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.
-count
+lists
-int64 + +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.
-capacity
+eviction
-int64 + +Eviction + 		+(Optional) +

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

AggregatedListStatus +

GameServerState +(string alias)

+

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

+

+

GameServerState is the state for the GameServer

+

+

GameServerStatus

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

-

AggregatedListStatus stores total and allocated List tracking values

+

GameServerStatus is the status for a GameServer resource

@@ -6160,19 +5920,24 @@

AggregatedListStatus

- -
-allocatedCount
+state
-int64 + +GameServerState + 		+

GameServerState is the current state of a GameServer, e.g. Creating, Starting, Ready, etc
-allocatedCapacity
+ports
-int64 + +[]GameServerStatusPort + 		@@ -6180,9 +5945,9 @@

AggregatedListStatus

-count
+address
-int64 +string 		@@ -6190,39 +5955,35 @@

AggregatedListStatus

-capacity
+addresses
-int64 + +[]Kubernetes core/v1.NodeAddress + 		+(Optional) +

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

AggregatedPlayerStatus -

-

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

-

-

AggregatedPlayerStatus stores total player tracking values

-

- - - - + + - - - -
FieldDescription +nodeName
+ +string + +		 +
-count
+reservedUntil
-int64 + +Kubernetes meta/v1.Time + 		@@ -6230,72 +5991,72 @@

AggregatedPlayerStatus

-capacity
+players
-int64 + +PlayerStatus + 		+(Optional) +

[Stage:Alpha] +[FeatureFlag:PlayerTracking]
-

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.

-

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

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

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

Annotations to be applied to the GameServer

+

Eviction specifies the eviction tolerance of the GameServer.
-

CounterStatus +

GameServerStatusPort

(Appears on: GameServerAllocationStatus, -GameServerSpec, GameServerStatus)

-

CounterStatus stores the current counter values and maximum capacity

+

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

@@ -6307,9 +6068,9 @@

CounterStatus

-count
+name
-int64 +string 		@@ -6317,9 +6078,9 @@

CounterStatus

-capacity
+port
-int64 +int32 		@@ -6327,15 +6088,15 @@

CounterStatus

-

Eviction +

GameServerTemplateSpec

(Appears on: -GameServerSpec, -GameServerStatus) +FleetSpec, +GameServerSetSpec)

-

Eviction specifies the eviction tolerance of the GameServer

+

GameServerTemplateSpec is a template for GameServers

@@ -6347,87 +6108,67 @@

Eviction

- -
-safe
+metadata
- -EvictionSafe + +Kubernetes meta/v1.ObjectMeta 		-

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

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-

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

-

- - - - - - - + +
FieldDescription
+spec
+ + +GameServerSpec + + +		 +
+
+ @@ -6438,50 +6179,106 @@

FleetSpec

+ + + + + + + + + + + + + + + + + +
-replicas
+container
-int32 +string 		-

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

+

Container specifies which Pod container is the game server. Only required if there is more than one +container defined
-allocationOverflow
+ports
- -AllocationOverflow + +[]GameServerPort 		-(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

+

Ports are the array of ports that can be exposed via the game server
-strategy
+health
- -Kubernetes apps/v1.DeploymentStrategy + +Health 		-

Deployment strategy

+

Health configures health checking
-

Scheduling strategy. Defaults to “Packed”.

+

Scheduling strategy. Defaults to “Packed”
-priorities
+sdkServer
- -[]Priority + +SdkServer 		-(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.

+

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

Template the GameServer template to apply for this Fleet

+

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

+
-

FleetStatus +

Health

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

-

FleetStatus is the status of a Fleet

+

Health configures health checking on the GameServer

@@ -6493,106 +6290,189 @@

FleetStatus

+ + + + + + + +
-replicas
+disabled
+ +bool + +		 +

Disabled is whether health checking is disabled or not

+
+periodSeconds
int32 		-

Replicas the total number of current GameServer replicas

+

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

ReadyReplicas are the number of Ready GameServer replicas

+

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

InitialDelaySeconds initial delay before checking health

+
+

ListStatus +

+

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

+

+

ListStatus stores the current list values and maximum capacity

+

+ + + + + + + + + + + + + + + +
FieldDescription
+capacity
+ +int64 + +		 +
+values
-int32 +[]string 		-

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

PlayerStatus +

+

+(Appears on: +GameServerStatus) +

+

+

PlayerStatus stores the current player capacity values

+

+ + + + + + + + + +
FieldDescription
-allocatedReplicas
+count
-int32 +int64 		-

AllocatedReplicas are the number of Allocated GameServer replicas
-players
+capacity
- -AggregatedPlayerStatus - +int64 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:PlayerTracking] -Players are the current total player capacity and count for this Fleet
-counters
+ids
- -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 Fleet.
+

PlayersSpec +

+

+(Appears on: +GameServerSpec) +

+

+

PlayersSpec tracks the initial player capacity

+

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

PortPolicy +(string alias)

+

+(Appears on: +GameServerPort) +

+

+

PortPolicy is the port policy for the GameServer

+

+

Priority

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

-

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

+

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.

@@ -6604,89 +6484,117 @@

GameServerPort

+ +
-name
+type
string 		-

Name is the descriptive name of the port

+

Type: Sort by a “Counter” or a “List”.
-portPolicy
+key
- -PortPolicy - +string 		-

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

+

Key: The name of the Counter or List. If not found on the GameServer, has no impact.
-container
+order
string 		-(Optional) -

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

+

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

SdkServer +

+

+(Appears on: +GameServerSpec) +

+

+

SdkServer specifies parameters for the Agones SDK Server sidecar container

+

+ + + + + + + +
FieldDescription
-containerPort
+logLevel
-int32 + +SdkServerLogLevel + 		-

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

+

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

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

+

GRPCPort is the port on which the SDK Server binds the gRPC server to accept incoming connections
-protocol
+httpPort
- -Kubernetes core/v1.Protocol - +int32 		-

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

+

HTTPPort is the port on which the SDK Server binds the HTTP gRPC gateway server to accept incoming connections
-

GameServerSetSpec -

+

SdkServerLogLevel +(string alias)

(Appears on: -GameServerSet) +SdkServer)

-

GameServerSetSpec the specification for GameServerSet

+

SdkServerLogLevel is the log level for SDK server (sidecar) logs

+

+
+

allocation.agones.dev/v1

+

+

Package v1 is the v1 version of the API.

+

+Resource Types: + +

GameServerAllocation +

+

+

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

@@ -6698,204 +6606,214 @@

GameServerSetSpec

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

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

+kind
+string 		GameServerAllocation
-allocationOverflow
+metadata
- -AllocationOverflow + +Kubernetes meta/v1.ObjectMeta 		-(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

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-scheduling
+spec
-agones.dev/agones/pkg/apis.SchedulingStrategy + +GameServerAllocationSpec + 		-

Scheduling strategy. Defaults to “Packed”.

-
- -
-priorities
+multiClusterSetting
- -[]Priority + +MultiClusterSetting 		-(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.

+

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

Template the GameServer template to apply for this GameServerSet

+

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

GameServerSetStatus -

-

-(Appears on: -GameServerSet) -

-

-

GameServerSetStatus is the status of a GameServerSet

-

- - - - - - - - + +
FieldDescription
-replicas
+preferred
-int32 + +[]GameServerSelector + 		-

Replicas is the total number of current GameServer replicas

+

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.
-readyReplicas
+priorities
-int32 + +[]Priority + 		-

ReadyReplicas is the number of Ready GameServer replicas

+(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.
-reservedReplicas
+selectors
-int32 + +[]GameServerSelector + 		-

ReservedReplicas is the number of Reserved GameServer replicas

+

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

AllocatedReplicas is the number of Allocated GameServer replicas

+

Scheduling strategy. Defaults to “Packed”.
-shutdownReplicas
+metadata
-int32 + +MetaPatch + 		-

ShutdownReplicas is the number of Shutdown GameServers replicas

+

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

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

+

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

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

+

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

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

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

-

GameServerSpec +

CounterAction

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

-

GameServerSpec is the spec for a GameServer resource

+

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

@@ -6907,157 +6825,117 @@

GameServerSpec

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

+(Optional) +

Action must to either “Increment” or “Decrement” the Counter’s Count. Must also define the Amount.
-scheduling
+amount
-agones.dev/agones/pkg/apis.SchedulingStrategy +int64 		-

Scheduling strategy. Defaults to “Packed”

+(Optional) +

Amount is the amount to increment or decrement the Count. Must be a positive integer.
-sdkServer
+capacity
- -SdkServer - +int64 		-

SdkServer specifies parameters for the Agones SDK Server sidecar container

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

+

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

Template describes the Pod that will be created for the GameServer

-		FieldDescription
-players
+minCount
- -PlayersSpec - +int64 		(Optional) -

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

+

MinCount is the minimum current value. Defaults to 0.
-counters
+maxCount
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus - +int64 		(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.

+

MaxCount is the maximum current value. Defaults to 0, which translates as max(in64).
-lists
+minAvailable
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus - +int64 		(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.

+

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

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

+

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

GameServerState -(string alias)

-

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

-

-

GameServerState is the state for the GameServer

-

-

GameServerStatus +

GameServerAllocationSpec

(Appears on: -GameServer) +GameServerAllocation)

-

GameServerStatus is the status for a GameServer resource

+

GameServerAllocationSpec is the spec for a GameServerAllocation

@@ -7069,183 +6947,164 @@

GameServerStatus

- - - -
-state
+multiClusterSetting
- -GameServerState + +MultiClusterSetting 		-

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

+

MultiClusterPolicySelector if specified, multi-cluster policies are applied. +Otherwise, allocation will happen locally.
-ports
+required
- -[]GameServerStatusPort + +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.
-address
- -string - -		 -
-addresses
+preferred
- -[]Kubernetes core/v1.NodeAddress + +[]GameServerSelector 		-(Optional) -

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

+

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.
-nodeName
+priorities
-string + +[]Priority + 		+(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.
-reservedUntil
+selectors
- -Kubernetes meta/v1.Time + +[]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.
-players
+scheduling
- -PlayerStatus - +agones.dev/agones/pkg/apis.SchedulingStrategy 		-(Optional) -

[Stage:Alpha] -[FeatureFlag:PlayerTracking]

+

Scheduling strategy. Defaults to “Packed”.
-counters
+metadata
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus + +MetaPatch 		-(Optional) -

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

+

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

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

Eviction specifies the eviction tolerance of the GameServer.

+

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

GameServerStatusPort -

+

GameServerAllocationState +(string alias)

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

-

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

+

GameServerAllocationState is the Allocation state

- - - - - - - - - - - - - - - - - -
FieldDescription
-name
- -string - -		 -
-port
- -int32 - -		 -
-

GameServerTemplateSpec +

GameServerAllocationStatus

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

-

GameServerTemplateSpec is a template for GameServers

+

GameServerAllocationStatus is the status for an GameServerAllocation resource

@@ -7257,118 +7116,93 @@

GameServerTemplateSpec

- + +
-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
- - -GameServerSpec - - -		 -
-
- - - @@ -7381,9 +7215,6 @@

GameServerTemplateSpec

@@ -7396,38 +7227,58 @@

GameServerTemplateSpec

+ +
-container
+gameServerName
string 		-

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

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

Health configures health checking
-scheduling
+addresses
-agones.dev/agones/pkg/apis.SchedulingStrategy + +[]Kubernetes core/v1.NodeAddress + 		-

Scheduling strategy. Defaults to “Packed”
-sdkServer
+nodeName
- -SdkServer - +string 		-

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

Template describes the Pod that will be created for the GameServer

+

If the allocation is from a remote cluster, Source is the endpoint of the remote agones-allocator. +Otherwise, Source is “local”
-players
+metadata
- -PlayersSpec + +GameServerMetadata 		-(Optional) -

(Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
-(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.
-(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.
+

GameServerMetadata +

+

+(Appears on: +GameServerAllocationStatus) +

+

+

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

+

+ + + + + + + + -
FieldDescription
-eviction
+labels
- -Eviction - +map[string]string 		-(Optional) -

Eviction specifies the eviction tolerance of the GameServer. Defaults to “Never”.
+
+annotations
+ +map[string]string + +
-

Health +

GameServerSelector

(Appears on: -GameServerSpec) +GameServerAllocationSpec)

-

Health configures health checking on the GameServer

+

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

@@ -7439,60 +7290,98 @@

Health

+ + + +
-disabled
+LabelSelector
-bool + +Kubernetes meta/v1.LabelSelector + 		-

Disabled is whether health checking is disabled or not

+

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

+

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

PeriodSeconds is the number of seconds each health ping has to occur in

+

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.
-failureThreshold
+players
-int32 + +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 + 		-

FailureThreshold how many failures in a row constitutes unhealthy

+(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.
-initialDelaySeconds
+lists
-int32 + +map[string]agones.dev/agones/pkg/apis/allocation/v1.ListSelector + 		-

InitialDelaySeconds initial delay before checking health

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

ListStatus +

ListAction

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

-

ListStatus stores the current list values and maximum capacity

+

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

@@ -7504,34 +7393,39 @@

ListStatus

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

AddValues appends values to a List’s Values array. Any duplicate values will be ignored.
-values
+capacity
-[]string +int64 		+(Optional) +

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

PlayerStatus +

ListSelector

(Appears on: -GameServerStatus) +GameServerSelector)

-

PlayerStatus stores the current player capacity values

+

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

@@ -7543,44 +7437,50 @@

PlayerStatus

-count
+containsValue
-int64 +string 		+(Optional) +

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

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

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

PlayersSpec +

MetaPatch

(Appears on: -GameServerSpec) +GameServerAllocationSpec)

-

PlayersSpec tracks the initial player capacity

+

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

@@ -7592,9 +7492,19 @@

PlayersSpec

+ + + +
-initialCapacity
+labels
-int64 +map[string]string + +		 +
+annotations
+ +map[string]string 		@@ -7602,25 +7512,14 @@

PlayersSpec

-

PortPolicy -(string alias)

-

-(Appears on: -GameServerPort) -

-

-

PortPolicy is the port policy for the GameServer

-

-

Priority +

MultiClusterSetting

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

-

Priority is a sorting option for GameServers with Counters or Lists based on the Capacity.

+

MultiClusterSetting specifies settings for multi-cluster allocation.

@@ -7632,48 +7531,36 @@

Priority

- - - -
-type
- -string - -		 -

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

-
-key
+enabled
-string +bool 		-

Key: The name of the Counter or List. If not found on the GameServer, has no impact.
-order
+policySelector
-string + +Kubernetes meta/v1.LabelSelector + 		-

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

SdkServer +

PlayerSelector

(Appears on: -GameServerSpec) +GameServerSelector)

-

SdkServer specifies parameters for the Agones SDK Server sidecar container

+

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

@@ -7685,64 +7572,39 @@

SdkServer

- - - -
-logLevel
- - -SdkServerLogLevel - - -		 -

LogLevel for SDK server (sidecar) logs. Defaults to “Info”

-
-grpcPort
+minAvailable
-int32 +int64 		-

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

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

+

autoscaling.agones.dev/v1

Package v1 is the v1 version of the API.

Resource Types: -

GameServerAllocation +

FleetAutoscaler

-

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

+

FleetAutoscaler is the data structure for a FleetAutoscaler resource

@@ -7758,7 +7620,7 @@

GameServerAllocation string

@@ -7767,7 +7629,7 @@

GameServerAllocation kind
string -

+ @@ -7798,162 +7660,229 @@

GameServerAllocation

-allocation.agones.dev/v1 +autoscaling.agones.dev/v1
GameServerAllocationFleetAutoscaler
@@ -7787,8 +7649,8 @@

GameServerAllocation

spec
- -GameServerAllocationSpec + +FleetAutoscalerSpec
+ +
-multiClusterSetting
+fleetName
- -MultiClusterSetting - +string 		-

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

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.

+

Autoscaling policy
-preferred
+sync
- -[]GameServerSelector + +FleetAutoscalerSync 		-

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

Sync defines when FleetAutoscalers runs autoscaling

+
-priorities
+status
- -[]Priority + +FleetAutoscalerStatus -(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.

+ + + + +

BufferPolicy +

+

+(Appears on: +FleetAutoscalerPolicy) +

+

+

BufferPolicy controls the desired behavior of the buffer policy.

+

+ + + + + + + + + + + + + + + + +
FieldDescription
+maxReplicas
+ +int32 + +		 +

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

+
+minReplicas
+ +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
-selectors
+bufferSize
- -[]GameServerSelector - +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		-

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.

+

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.

+

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

Scheduling strategy. Defaults to “Packed”.

+

Key is the name of the Counter. Required field.
-metadata
+maxCapacity
- -MetaPatch - +int64 		-

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

+

MaxCapacity is the maximum aggregate Counter total capacity across the fleet. +MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
-counters
+minCapacity
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterAction - +int64 		-(Optional) -

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

+

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.
-lists
+bufferSize
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.ListAction - +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		-(Optional) -

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

+

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
-status
+seconds
- -GameServerAllocationStatus - +int32 		+

Seconds defines how often we run fleet autoscaling in seconds
-

CounterAction +

FleetAutoscaleRequest

(Appears on: -GameServerAllocationSpec) +FleetAutoscaleReview)

-

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

+

FleetAutoscaleRequest defines the request to webhook autoscaler endpoint

@@ -7965,50 +7894,63 @@

CounterAction

+ + + +
-action
+uid
+ +k8s.io/apimachinery/pkg/types.UID + +		 +

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.

+
+name
string 		-(Optional) -

Action must to either “Increment” or “Decrement” the Counter’s Count. Must also define the Amount.

+

Name is the name of the Fleet being scaled
-amount
+namespace
-int64 +string 		-(Optional) -

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

+

Namespace is the namespace associated with the request (if any).
-capacity
+status
-int64 + +FleetStatus + 		-(Optional) -

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

+

The Fleet’s status values
-

CounterSelector +

FleetAutoscaleResponse

(Appears on: -GameServerSelector) +FleetAutoscaleReview)

-

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

+

FleetAutoscaleResponse defines the response of webhook autoscaler endpoint

@@ -8020,62 +7962,88 @@

CounterSelector

+ +
-minCount
+uid
-int64 +k8s.io/apimachinery/pkg/types.UID 		-(Optional) -

MinCount is the minimum current value. Defaults to 0.

+

UID is an identifier for the individual request/response. +This should be copied over from the corresponding FleetAutoscaleRequest.
-maxCount
+scale
-int64 +bool 		-(Optional) -

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

+

Set to false if no scaling should occur to the Fleet
-minAvailable
+replicas
-int64 +int32 		-(Optional) -

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

+

The targeted replica count
+

FleetAutoscaleReview +

+

+

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

+

+ + + + + + + + + + + +
FieldDescription
-maxAvailable
+request
-int64 + +FleetAutoscaleRequest + + +		 +
+response
+ + +FleetAutoscaleResponse + 		-(Optional) -

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

GameServerAllocationSpec +

FleetAutoscalerPolicy

(Appears on: -GameServerAllocation) +FleetAutoscalerSpec)

-

GameServerAllocationSpec is the spec for a GameServerAllocation

+

FleetAutoscalerPolicy describes how to scale a fleet

@@ -8087,156 +8055,153 @@

GameServerAllocationS

+ +
-multiClusterSetting
+type
- -MultiClusterSetting + +FleetAutoscalerPolicyType 		-

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

+

Type of autoscaling policy.
-required
+buffer
- -GameServerSelector + +BufferPolicy 		-

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.

+(Optional) +

Buffer policy config params. Present only if FleetAutoscalerPolicyType = Buffer.
-preferred
+webhook
- -[]GameServerSelector + +WebhookPolicy 		-

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

Webhook policy config params. Present only if FleetAutoscalerPolicyType = Webhook.
-priorities
+counter
- -[]Priority + +CounterPolicy 		(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:Alpha] +[FeatureFlag:CountsAndLists] +Counter policy config params. Present only if FleetAutoscalerPolicyType = Counter.
-selectors
+list
- -[]GameServerSelector + +ListPolicy 		-

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.

+(Optional) +

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

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

+

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

Scheduling strategy. Defaults to “Packed”.

-		FieldDescription
-metadata
+fleetName
- -MetaPatch - +string 		-

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

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

+

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

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

+

Sync defines when FleetAutoscalers runs autoscaling
-

GameServerAllocationState -(string alias)

-

-(Appears on: -GameServerAllocationStatus) -

-

-

GameServerAllocationState is the Allocation state

-

-

GameServerAllocationStatus +

FleetAutoscalerStatus

(Appears on: -GameServerAllocation) +FleetAutoscaler)

-

GameServerAllocationStatus is the status for an GameServerAllocation resource

+

FleetAutoscalerStatus defines the current status of a FleetAutoscaler

@@ -8248,129 +8213,201 @@

GameServerAllocatio

+ + + +
-state
+currentReplicas
- -GameServerAllocationState - +int32 		-

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

+

CurrentReplicas is the current number of gameserver replicas +of the fleet managed by this autoscaler, as last seen by the autoscaler
-gameServerName
+desiredReplicas
-string +int32 		+

DesiredReplicas is the desired number of gameserver replicas +of the fleet managed by this autoscaler, as last calculated by the autoscaler
-ports
+lastScaleTime
- -[]GameServerStatusPort + +Kubernetes meta/v1.Time 		+(Optional) +

lastScaleTime is the last time the FleetAutoscaler scaled the attached fleet,
-address
+ableToScale
-string +bool 		+

AbleToScale indicates that we can access the target fleet
-addresses
+scalingLimited
- -[]Kubernetes core/v1.NodeAddress +bool + +		 +

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

+
+

FleetAutoscalerSync +

+

+(Appears on: +FleetAutoscalerSpec) +

+

+

FleetAutoscalerSync describes when to sync a fleet

+

+ + + + + + + + + + + +
FieldDescription
+type
+ + +FleetAutoscalerSyncType 		+

Type of autoscaling sync.
-nodeName
+fixedInterval
-string + +FixedIntervalSync + 		+(Optional) +

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

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
-source
+key
string 		-

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

+

Key is the name of the List. Required field.
-metadata
+maxCapacity
- -GameServerMetadata - +int64 		+

MaxCapacity is the maximum aggregate List total capacity across the fleet. +MaxCapacity must be bigger than both MinCapacity and BufferSize. Required field.
-counters
+minCapacity
- -map[string]agones.dev/agones/pkg/apis/agones/v1.CounterStatus - +int64 		+

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.
-lists
+bufferSize
- -map[string]agones.dev/agones/pkg/apis/agones/v1.ListStatus - +k8s.io/apimachinery/pkg/util/intstr.IntOrString 		+

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

GameServerMetadata +

WebhookPolicy

(Appears on: -GameServerAllocationStatus) +FleetAutoscalerPolicy)

-

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

+

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

@@ -8378,39 +8415,83 @@

GameServerMetadata

- - + + + + + +
Field Description
+url
+ +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.

+
-labels
+service
-map[string]string + +Kubernetes admissionregistration/v1.ServiceReference + 		+(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.
-annotations
+caBundle
-map[string]string +[]byte 		+(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.
-

GameServerSelector -

+
+

multicluster.agones.dev/v1

-(Appears on: -GameServerAllocationSpec) +

Package v1 is the v1 version of the API.

+Resource Types: + +

GameServerAllocationPolicy +

-

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

+

GameServerAllocationPolicy is the Schema for the gameserverallocationpolicies API

@@ -8422,94 +8503,93 @@

GameServerSelector

+ + + +
-LabelSelector
- - -Kubernetes meta/v1.LabelSelector - - +apiVersion
+string		 + +multicluster.agones.dev/v1 +
-

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

-

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

+kind
+string 		GameServerAllocationPolicy
-gameServerState
+metadata
- -GameServerState + +Kubernetes meta/v1.ObjectMeta 		-

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.

+Refer to the Kubernetes API documentation for the fields of the +metadata field.
-players
+spec
- -PlayerSelector + +GameServerAllocationPolicySpec 		-(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.

+
+
+ + + + + +
+priority
+ +int32 + +
-counters
+weight
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.CounterSelector - +int 		-(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
+connectionInfo
- -map[string]agones.dev/agones/pkg/apis/allocation/v1.ListSelector + +ClusterConnectionInfo 		-(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 +

ClusterConnectionInfo

(Appears on: -GameServerAllocationSpec) +GameServerAllocationPolicySpec)

-

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

+

ClusterConnectionInfo defines the connection information for a cluster

@@ -8521,94 +8601,67 @@

ListAction

- -
-addValues
+clusterName
-[]string +string 		-(Optional) -

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

+

Optional: the name of the targeted cluster
-capacity
+allocationEndpoints
-int64 +[]string 		-(Optional) -

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

+

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
-

ListSelector -

-

-(Appears on: -GameServerSelector) -

-

-

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

-

- - - - - - - -
FieldDescription
-containsValue
+secretName
string 		-(Optional) -

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

+

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

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

+

The cluster namespace from which to allocate gameservers
-maxAvailable
+serverCa
-int64 +[]byte 		-(Optional) -

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

+

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

MetaPatch +

ConnectionInfoIterator

-(Appears on: -GameServerAllocationSpec) -

-

-

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

+

ConnectionInfoIterator an iterator on ClusterConnectionInfo

@@ -8620,75 +8673,58 @@

MetaPatch

- -
-labels
+currPriority
-map[string]string +int 		+

currPriority Current priority index from the orderedPriorities
-annotations
+orderedPriorities
-map[string]string +[]int32 		+

orderedPriorities list of ordered priorities
-

MultiClusterSetting -

-

-(Appears on: -GameServerAllocationSpec) -

-

-

MultiClusterSetting specifies settings for multi-cluster allocation.

-

- - - - - - - -
FieldDescription
-enabled
+priorityToCluster
-bool +map[int32]map[string][]*agones.dev/agones/pkg/apis/multicluster/v1.GameServerAllocationPolicy 		+

priorityToCluster Map of priority to cluster-policies map
-policySelector
+clusterBlackList
- -Kubernetes meta/v1.LabelSelector - +map[string]bool 		+

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

PlayerSelector +

GameServerAllocationPolicySpec

(Appears on: -GameServerSelector) +GameServerAllocationPolicy)

-

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

+

GameServerAllocationPolicySpec defines the desired state of GameServerAllocationPolicy

@@ -8700,9 +8736,9 @@

PlayerSelector

+ + + +
-minAvailable
+priority
-int64 +int32 		@@ -8710,9 +8746,21 @@

PlayerSelector

-maxAvailable
+weight
-int64 +int + +		 +
+connectionInfo
+ + +ClusterConnectionInfo + 		diff --git a/site/content/en/docs/Reference/fleet.md b/site/content/en/docs/Reference/fleet.md index 87c0cd9601..4d7e095723 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. + # key: rooms # The name of the Counter. No impact if no GameServer found. + # 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. + # key: players # The name of the List. No impact if no GameServer found. + # 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..d0e06d82a7 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,7 +77,7 @@ spec: type: Counter # Counter based autoscaling counter: # Key is the name of the Counter. Required field. - key: players + key: rooms # BufferSize is the size of a buffer of counted items that are available in the Fleet (available capacity). # Value can be an absolute number (ex: 5) or a percentage of the Counter available capacity (ex: 5%). # An absolute number is calculated from percentage by rounding up. Must be bigger than 0. Required field. @@ -92,7 +92,7 @@ spec: ``` 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,7 +112,7 @@ spec: type: List # List based autoscaling. list: # Key is the name of the List. Required field. - key: rooms + key: players # BufferSize is the size of a buffer based on the List capacity that is available over the current # aggregate List length in the Fleet (available capacity). # It can be specified either as an absolute value (i.e. 5) or percentage format (i.e. 5%). diff --git a/site/content/en/docs/Reference/gameserverallocation.md b/site/content/en/docs/Reference/gameserverallocation.md index fa037e35a2..173b69e6c0 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.