diff --git a/examples/fleet.yaml b/examples/fleet.yaml index 4de5425425..57132fd2e3 100644 --- a/examples/fleet.yaml +++ b/examples/fleet.yaml @@ -89,25 +89,25 @@ spec: # - "Error" The SDK server will only output error messages logLevel: Info # - # [Stage:Alpha] + # [Stage:Beta] # [FeatureFlag:CountsAndLists] # Counts and Lists provides the configuration for generic (player, room, session, etc.) tracking features. - # Commented out since Alpha, and disabled by default - # counters: - # players: - # count: 9 - # capacity: 10 - # sessions: - # count: # Count and/or capacity must be listed (but may be nil) otherwise the counter will by dropped by the CRD schema. - # lists: - # players: - # capacity: # Capacity and/or values must be listed (but may be nil) otherwise the list will be dropped by the CRD schema. - # rooms: - # capacity: 5 - # values: - # - room1 - # - room2 - # - room3 + # Now in Beta, and enabled by default + counters: + players: + count: 9 + capacity: 10 + sessions: + count: # Count and/or capacity must be listed (but may be nil) otherwise the counter will by dropped by the CRD schema. + lists: + players: + capacity: # Capacity and/or values must be listed (but may be nil) otherwise the list will be dropped by the CRD schema. + rooms: + capacity: 5 + values: + - room1 + - room2 + - room3 # # The GameServer's Pod template template: diff --git a/examples/gameserver.yaml b/examples/gameserver.yaml index a65e4c0283..55ee51fc55 100644 --- a/examples/gameserver.yaml +++ b/examples/gameserver.yaml @@ -91,25 +91,25 @@ spec: # # set this GameServer's initial player capacity # initialCapacity: 10 # - # [Stage:Alpha] + # [Stage:Beta] # [FeatureFlag:CountsAndLists] # Counts and Lists provides the configuration for generic (player, room, session, etc.) tracking features. - # Commented out since Alpha, and disabled by default - # counters: # counters are int64 counters that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time. - # games: # arbitrary key. - # count: 1 # initial value. - # capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details. - # sessions: - # count: 1 - # lists: # lists are lists of values stored against this GameServer that can be added and deleted from. Keys must be declared at GameServer creation time. - # players: # an empty list, with a capacity set to 10. - # capacity: 10 # capacity value, defaults to 1000. - # rooms: - # capacity: 333 - # values: # initial set of values in a list. - # - room1 - # - room2 - # - room3 + # Now in Beta, and enabled by default + counters: # counters are int64 counters that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time. + games: # arbitrary key. + count: 1 # initial value. + capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details. + sessions: + count: 1 + lists: # lists are lists of values stored against this GameServer that can be added and deleted from. Keys must be declared at GameServer creation time. + players: # an empty list, with a capacity set to 10. + capacity: 10 # capacity value, defaults to 1000. + rooms: + capacity: 333 + values: # initial set of values in a list. + - room1 + - room2 + - room3 # # Pod template configuration template: diff --git a/examples/gameserverallocation.yaml b/examples/gameserverallocation.yaml index acbb025354..61594591b9 100644 --- a/examples/gameserverallocation.yaml +++ b/examples/gameserverallocation.yaml @@ -28,15 +28,14 @@ metadata: name: allocation-example spec: # GameServer selector from which to choose GameServers from. - # GameServers still have the hard requirement to be `Ready` to be allocated from - # however we can also make available `matchExpressions` for even greater - # flexibility. + # GameServers still have the hard requirement to be `Ready` to be allocated from. + # However, we can also make available `matchExpressions` for even greater flexibility. # Below is an example of a GameServer allocated against a given fleet. # See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details # The selectors is an ordered list of allocations set. # 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. - # This also support `matchExpressions` + # This also supports `matchExpressions` selectors: - matchLabels: agones.dev/fleet: green-fleet @@ -50,19 +49,19 @@ spec: # 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. gameServerState: Ready - # [Stage:Alpha] + # [Stage:Beta] # [FeatureFlag:CountsAndLists] - # counters: # selector for counter current values of a GameServer count - # rooms: - # minCount: 1 # minimum value. Defaults to 0. - # maxCount: 5 # maximum value. Defaults to max(int64) - # minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0. - # maxAvailable: 10 # maximum available (current capacity - current count) Defaults to max(int64) - # lists: - # players: - # containsValue: "x6k8z" # only match GameServers who has this value in the list. Defaults to "", which is all. - # minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0. - # maxAvailable: 10 # maximum available (current capacity - current count) Defaults to 0, which translates to max(int64) + counters: # selector for counter current values of a GameServer count + rooms: + minCount: 1 # minimum value. Defaults to 0. + maxCount: 5 # maximum value. Defaults to max(int64) + minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0. + maxAvailable: 10 # maximum available (current capacity - current count) Defaults to max(int64) + lists: + players: + containsValue: "x6k8z" # only match GameServers who has this value in the list. Defaults to "", which is all. + minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0. + maxAvailable: 10 # maximum available (current capacity - current count) Defaults to 0, which translates to max(int64) # # [Stage:Alpha] # [FeatureFlag:PlayerAllocationFilter] @@ -86,7 +85,7 @@ spec: annotations: map: garden22 # yamllint disable rule:comments-indentation rule:line-length - # [Stage: Alpha] + # [Stage: Beta] # [FeatureFlag:CountsAndLists] # `Priorities` configuration alters the order in which `GameServers` are searched for matches to the configured `selectors`. # @@ -98,22 +97,22 @@ spec: # 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] + 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:Beta] # [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. + 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. + 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/site/content/en/docs/Guides/Client SDKs/_index.md b/site/content/en/docs/Guides/Client SDKs/_index.md index 20b88ce471..4bd83dcc28 100644 --- a/site/content/en/docs/Guides/Client SDKs/_index.md +++ b/site/content/en/docs/Guides/Client SDKs/_index.md @@ -52,6 +52,7 @@ The SDKs will automatically discover and connect to the gRPC port specified in t If your game server requires using a REST client, it is advised to use the port from the environment variable, otherwise your game server will not be able to contact the SDK server if it is configured to use a non-default port. +{{% feature expiryVersion="1.41.0" %}} ## Function Reference While each of the SDKs are canonical to their languages, they all have the following @@ -80,6 +81,37 @@ Functions which changes GameServer state or settings are: 14. Alpha().AppendListValue() 15. Alpha().DeleteListValue() 16. Alpha().SetListCapacity() +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +## Function Reference + +While each of the SDKs are canonical to their languages, they all have the following +functions that implement the core responsibilities of the SDK. + +For language specific documentation, have a look at the respective source (linked above), +and the {{< ghlink href="examples" >}}examples{{< /ghlink >}}. + +Calling any of state changing functions mentioned below does not guarantee that GameServer Custom Resource object would actually change its state right after the call. For instance, it could be moved to the `Shutdown` state elsewhere (for example, when a fleet scales down), which leads to no changes in `GameServer` object. You can verify the result of this call by waiting for the desired state in a callback to WatchGameServer() function. + +Functions which changes GameServer state or settings are: + +1. Ready() +2. Shutdown() +3. SetLabel() +4. SetAnnotation() +5. Allocate() +6. Reserve() +7. Alpha().SetCapacity() +8. Alpha().PlayerConnect() +9. Alpha().PlayerDisconnect() +10. Beta().SetCounterCount() +11. Beta().IncrementCounter() +12. Beta().DecrementCounter() +13. Beta().SetCounterCapacity() +14. Beta().AppendListValue() +15. Beta().DeleteListValue() +16. Beta().SetListCapacity() +{{% /feature %}} ### Lifecycle Management @@ -230,7 +262,12 @@ observable through the Kubernetes API. ### Counters And Lists +{{% feature expiryVersion="1.41.0" %}} {{< alpha title="Counters And Lists" gate="CountsAndLists" >}} +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +{{< beta title="Counters And Lists" gate="CountsAndLists" >}} +{{% /feature %}} The `Counters` and `Lists` features in the SDK offer a flexible configuration for tracking various entities like players, rooms, and sessions. @@ -259,6 +296,7 @@ to the capacity of that Counter or List. {{% /alert %}} +{{% feature expiryVersion="1.41.0" %}} #### Counters All functions will return an error if the specified `key` is not predefined in the @@ -343,6 +381,93 @@ Convenience function, which retrieves the length of the results of [`Alpha().Get [gameserverspec]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerSpec" >}} [gameserverstatus]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerStatus" >}} +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +#### Counters + +All functions will return an error if the specified `key` is not predefined in the +[`GameServer.Spec.Counters`][gameserverspec] resource configuration. + +**Note:** For Counters, the default setting for the capacity is preset to 1000. It is recommended to avoid configuring the capacity to max(int64), as doing so could cause problems with [JSON Patch operations](https://github.com/googleforgames/agones/issues/3636). + +##### Beta().GetCounterCount(key) + +This function retrieves either the [`GameServer.Status.Counters[key].Count`][gameserverstatus] or the SDK awaiting-batch +value for a given key, whichever is most up to date. + +##### Beta().SetCounterCount(key, amount) + +This function sets the value of [`GameServer.Status.Counters[key].Count`][gameserverstatus] for the given key to the +passed in amount. This operation overwrites any previous values and the new value cannot exceed the Counter's capacity. + +##### Beta().IncrementCounter(key, amount) + +This function increments [`GameServer.Status.Counters[key].Count`][gameserverstatus] for the given key by the passed in +non-negative amount. The function returns an error if the Counter is already at capacity (at time of operation), +indicating no increment will occur. + +##### Beta().DecrementCounter(key, amount) + +This function decreases [`GameServer.Status.Counters[key].Count`][gameserverstatus] for the given key by the passed in +non-negative amount. It returns an error if the Counter's count is already at zero. + +##### Beta().SetCounterCapacity(key, amount) + +This function sets the maximum [`GameServer.Status.Counters[key].Capacity`][gameserverstatus] for the given key by the +passed in non-negative amount. A capacity value of 0 indicates no capacity limit. + +##### Beta().GetCounterCapacity(key) + +This function retrieves either the [`GameServer.Status.Counters[key].Capacity`][gameserverstatus] or the SDK +awaiting-batch value for the given key, whichever is most up to date. + +#### Lists + +All functions will return an error if the specified `key` is not predefined in the +[`GameServer.Spec.Lists`][gameserverspec] resource configuration. + +##### Beta().AppendListValue(key, value) + +This function appends the specified string value to the List +in [`GameServer.Status.Lists[key].Values`][gameserverstatus]. + +An error is returned if the string already exists in the list or if the list is at capacity. + +##### Beta().DeleteListValue(key, value) + +This function removes the specified string value from the List +in [`GameServer.Status.Lists[key].Values`][gameserverstatus]. + +An error is returned if the string does not exist in the list. + +##### Beta().SetListCapacity(key, amount) + +This function sets the maximum capacity for the List at [`GameServer.Status.Lists[key].Capacity`][gameserverstatus]. + +The capacity value is required to be between 0 and 1000. + +##### Beta().GetListCapacity(key) + +This function retrieves either the [`GameServer.Status.Lists[key].Capacity`][gameserverstatus] or the SDK +awaiting-batch value for the given key, whichever is most up to date. + +##### Beta().GetListValues(key) + +This function retrieves either the [`GameServer.Status.Lists[key].Values`][gameserverstatus] or the SDK +awaiting-batch values array for the given key, whichever is most up to date. + +##### Beta().ListContains(key, value) + +Convenience function, which returns if the specific string value exists in the results +of [`Beta().GetListValues(key)`](#betagetlistvalueskey). + +##### Beta().GetListLength(key) + +Convenience function, which retrieves the length of the results of [`Beta().GetListValues(key)`](#betagetlistvalueskey). + +[gameserverspec]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerSpec" >}} +[gameserverstatus]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerStatus" >}} +{{% /feature %}} ### Player Tracking diff --git a/site/content/en/docs/Guides/Client SDKs/csharp.md b/site/content/en/docs/Guides/Client SDKs/csharp.md index 53b0b09485..656b746a09 100644 --- a/site/content/en/docs/Guides/Client SDKs/csharp.md +++ b/site/content/en/docs/Guides/Client SDKs/csharp.md @@ -146,6 +146,7 @@ agonesSDK.WatchGameServer((gameServer) => { Console.WriteLine($"Server - Watch { ``` +{{% feature expiryVersion="1.41.0" %}} ### Counters And Lists {{< alpha title="Counters And Lists" gate="CountsAndLists" >}} @@ -221,9 +222,9 @@ predefined in the GameServer resource on creation. string key = "rooms"; long count = await agones.Alpha().GetCounterCapacityAsync(key); ``` -#$## Lists +#### Lists -##$## Alpha: AppendListValue +##### Alpha: AppendListValue Appends a string to a List's values list, given the List's key (name) and the string value. Will error if the string already exists in the list. Will error if the key was not predefined in the @@ -235,7 +236,7 @@ string value = "player1"; await agones.Alpha().AppendListValueAsync(key, value); ``` -##$## Alpha: DeleteListValue +##### Alpha: DeleteListValue DeleteListValue removes a string from a List's values list, given the List's key (name) and the string value. Will error if the string does not exist in the list. Will error if the key was not @@ -247,7 +248,7 @@ string value = "player2"; await agones.Alpha().DeleteListValueAsync(key, value); ``` -###$# Alpha: SetListCapacity +##### Alpha: SetListCapacity Sets the capacity for a given list. Capacity must be between 0 and 1000. Will error if the key was not predefined in the GameServer resource on creation. @@ -258,7 +259,7 @@ long amount = 1000; await agones.Alpha().SetListCapacityAsync(key, amount); ``` -##$## Alpha: GetListCapacity +##### Alpha: GetListCapacity Returns the Capacity for a List, given the List's key (name). Will error if the key was not predefined in the GameServer resource on creation. @@ -268,7 +269,7 @@ string key = "players"; long amount = await agones.Alpha().GetListCapacityAsync(key); ``` -##$## Alpha: ListContains +##### Alpha: ListContains Returns if a string exists in a List's values list, given the List's key (name) and the string value. Search is case-sensitive. Will error if the key was not predefined in the GameServer resource on creation. @@ -279,7 +280,7 @@ string value = "player3"; bool contains = await agones.Alpha().ListContainsAsync(key, value); ``` -##$## Alpha: GetListLength +##### Alpha: GetListLength GetListLength returns the length of the Values list for a List, given the List's key (name). Will error if the key was not predefined in the GameServer resource on creation. @@ -289,7 +290,7 @@ string key = "players"; int listLength = await agones.Alpha().GetListLengthAsync(key); ``` -##$## Alpha: GetListValues +##### Alpha: GetListValues Returns the > Values for a List, given the List's key (name). Will error if the key was not predefined in the GameServer resource on creation. @@ -298,6 +299,161 @@ was not predefined in the GameServer resource on creation. string key = "players"; List values = await agones.Alpha().GetListValuesAsync(key); ``` +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +### Counters And Lists + +{{< beta title="Counters And Lists" gate="CountsAndLists" >}} + +#### Counters + +##### Beta: GetCounterCount + +Returns the Count for a Counter, given the Counter's key (name). Will error if the key was not +predefined in the GameServer resource on creation. + +```csharp +string key = "rooms"; +long count = await agones.Beta().GetCounterCountAsync(key); +``` + +##### Beta: SetCounterCount + +Sets a count to the given value. Use with care, as this will overwrite any previous invocations’ value. +Cannot be greater than Capacity. + +```csharp +string key = "rooms"; +long amount = 0; +await agones.Beta().SetCounterCountAsync(key, amount); +``` + +##### Beta: IncrementCounter + +Increases a counter by the given nonnegative integer amount. Will execute the increment operation +against the current CRD value. Will max at max(int64). Will error if the key was not predefined in +the GameServer resource on creation. Errors if the count is at the current capacity (to the latest +knowledge of the SDK), and no increment will occur. + +Note: A potential race condition here is that if count values are set from both the SDK and through +the K8s API (Allocation or otherwise), since the SDK append operation back to the CRD value is +batched asynchronous any value incremented past the capacity will be silently truncated. + +```csharp +string key = "rooms"; +long amount = 1; +await agones.Beta().IncrementCounterAsync(key, amount); +``` + +##### Beta: DecrementCounter + +Decreases the current count by the given nonnegative integer amount. The Counter Will not go below 0. +Will execute the decrement operation against the current CRD value. Errors if the count is at 0 (to +the latest knowledge of the SDK), and no decrement will occur. + +```csharp +string key = "rooms"; +long amount = 2; +await agones.Beta().DecrementCounterAsync(key, amount); +``` + +##### Beta: SetCounterCapacity + +Sets the capacity for the given Counter. A capacity of 0 is no capacity. + +```csharp +string key = "rooms"; +long amount = 0; +await agones.Beta().SetCounterCapacityAsync(key, amount); +``` + +##### Beta: GetCounterCapacity + +Returns the Capacity for a Counter, given the Counter's key (name). Will error if the key was not +predefined in the GameServer resource on creation. + +```csharp +string key = "rooms"; +long count = await agones.Beta().GetCounterCapacityAsync(key); +``` +#### Lists + +##### Beta: AppendListValue + +Appends a string to a List's values list, given the List's key (name) and the string value. Will +error if the string already exists in the list. Will error if the key was not predefined in the +GameServer resource on creation. Will error if the list is already at capacity. + +```csharp +string key = "players"; +string value = "player1"; +await agones.Beta().AppendListValueAsync(key, value); +``` + +##### Beta: DeleteListValue + +DeleteListValue removes a string from a List's values list, given the List's key (name) and the +string value. Will error if the string does not exist in the list. Will error if the key was not +predefined in the GameServer resource on creation. + +```csharp +string key = "players"; +string value = "player2"; +await agones.Beta().DeleteListValueAsync(key, value); +``` + +##### Beta: SetListCapacity + +Sets the capacity for a given list. Capacity must be between 0 and 1000. Will error if the key was +not predefined in the GameServer resource on creation. + +```csharp +string key = "players"; +long amount = 1000; +await agones.Beta().SetListCapacityAsync(key, amount); +``` + +##### Beta: GetListCapacity + +Returns the Capacity for a List, given the List's key (name). Will error if the key was not +predefined in the GameServer resource on creation. + +```csharp +string key = "players"; +long amount = await agones.Beta().GetListCapacityAsync(key); +``` + +##### Beta: ListContains + +Returns if a string exists in a List's values list, given the List's key (name) and the string value. +Search is case-sensitive. Will error if the key was not predefined in the GameServer resource on creation. + +```csharp +string key = "players"; +string value = "player3"; +bool contains = await agones.Beta().ListContainsAsync(key, value); +``` + +##### Beta: GetListLength + +GetListLength returns the length of the Values list for a List, given the List's key (name). Will +error if the key was not predefined in the GameServer resource on creation. + +```csharp +string key = "players"; +int listLength = await agones.Beta().GetListLengthAsync(key); +``` + +##### Beta: GetListValues + +Returns the > Values for a List, given the List's key (name). Will error if the key +was not predefined in the GameServer resource on creation. + +```csharp +string key = "players"; +List values = await agones.Beta().GetListValuesAsync(key); +``` +{{% /feature %}} ### Player Tracking diff --git a/site/content/en/docs/Guides/Client SDKs/rest.md b/site/content/en/docs/Guides/Client SDKs/rest.md index 31d6bcfba9..013fd20d2d 100644 --- a/site/content/en/docs/Guides/Client SDKs/rest.md +++ b/site/content/en/docs/Guides/Client SDKs/rest.md @@ -238,6 +238,7 @@ Apply an Annotation with the prefix "agones.dev/sdk-" to the backing `GameServer curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/annotation ``` +{{% feature expiryVersion="1.41.0" %}} ### Counters and Lists {{< alpha title="Counters and Lists" gate="CountsAndLists" >}} @@ -336,6 +337,107 @@ Response: ```json {"name":"players", "capacity":"120", "values":["player4", "player9"]} ``` +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +### Counters and Lists + +{{< beta title="Counters and Lists" gate="CountsAndLists" >}} + +#### Counters + +In all the Counter examples, we retrieve the counter under the key `rooms` as if it was previously defined in [`GameServer.Spec.counters[room]`]({{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerSpec" >}}). + +For your own Counter REST requests, replace the value `rooms` with your own key in the path. + +##### Beta: GetCounter +This function retrieves a specified counter by its key, `rooms`, and returns its information. + +###### Example + +```bash +curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/v1beta1/counters/rooms +``` + +Response: +```json +{"name":"rooms", "count":"1", "capacity":"10"} +``` + +##### Beta: UpdateCounter +This function updates the properties of the counter with the key `rooms`, such as its count and capacity, and returns the updated counter details. + +###### Example + +```bash +curl -d '{"count": "5", "capacity": "11"}' -H "Content-Type: application/json" -X PATCH http://localhost:${AGONES_SDK_HTTP_PORT}/v1beta1/counters/rooms +``` + +Response: +```json +{"name":"rooms", "count":"5", "capacity":"11"} +``` + +#### Lists + +In all the List examples, we retrieve the list under the key `players` as if it was previously defined in [`GameServer.Spec.lists[players]`]({{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerSpec" >}}). + +For your own List REST based requests, replace the value `players` with your own key in the path. + +##### Beta: GetList +This function retrieves the list's properties with the key `players`, returns the list's information. + +###### Example +```bash +curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/v1beta1/lists/players +``` + +Response: +```json +{"name":"players", "capacity":"100", "values":["player0", "player1", "player2"]} +``` + +##### Beta: UpdateList +This function updates the list's properties with the key `players`, such as its capacity and values, returns the updated list details. This will overwrite all existing List.Values with the update list request values. Use addValue or removeValue for modifying the List.Values field. + +###### Example + +```bash +curl -d '{"capacity": "120", "values": ["player3", "player4"]}' -H "Content-Type: application/json" -X PATCH http://localhost:${AGONES_SDK_HTTP_PORT}/v1beta1/lists/players +``` + +Response: +```json +{"name":"players", "capacity":"120", "values":["player3", "player4"]} +``` + +##### Beta: AddListValue +This function adds a new value to a list with the key `players` and returns the list with this addition. + +###### Example + +```bash +curl -d '{"value": "player9"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/v1beta1/lists/players:addValue +``` + +Response: +```json +{"name":"players", "capacity":"120", "values":["player3", "player4", "player9"]} +``` + +##### Beta: RemoveListValue +This function removes a value from the list with the key `players` and returns updated list. + +###### Example + +```bash +curl -d '{"value": "player3"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/v1beta1/lists/players:removeValue +``` + +Response: +```json +{"name":"players", "capacity":"120", "values":["player4", "player9"]} +``` +{{% /feature %}} ### Player Tracking diff --git a/site/content/en/docs/Guides/counters-and-lists.md b/site/content/en/docs/Guides/counters-and-lists.md index df6c1c45fd..ec5677d0a4 100644 --- a/site/content/en/docs/Guides/counters-and-lists.md +++ b/site/content/en/docs/Guides/counters-and-lists.md @@ -7,7 +7,12 @@ description: > Track, allocate and auto-scale based on user defined counters and lists stored on a `GameServer`. --- +{{% feature expiryVersion="1.41.0" %}} {{< alpha title="Counters and Lists" gate="CountsAndLists" >}} +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +{{< beta title="Counters and Lists" gate="CountsAndLists" >}} +{{% /feature %}} 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. @@ -86,6 +91,7 @@ and `GameServer.Status.Lists[players].Capacity` is the current capacity for the Check the API reference for [`GameServerStatus`][gameserverstatus] for all the details on the data structure. +{{% feature expiryVersion="1.41.0" %}} ### SDK Counter and Lists values can be accessed through the Agones SDK when that information is required within your game @@ -108,11 +114,37 @@ 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. +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +### 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.Beta().GetCounterCount("room")`]({{< ref "/docs/Guides/Client SDKs/_index.md#betagetcountercountkey" >}}) +function +that returns +the current value of the counter. Similarly, to retrieve the `players` list, we can use the +[`SDK.Beta().GetListValues("players")`]({{< ref "/docs/Guides/Client SDKs/_index.md#betagetlistvalueskey" >}}) +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. +{{% /feature %}} ## Manipulation We also have several ways to manipulate the Counter and List information stored on a `GameServer` instance, depending on your use case. +{{% feature expiryVersion="1.41.0" %}} ### SDK Counter and Lists values can be modified through the Agones SDK when you wish to be able to edit that information @@ -126,7 +158,22 @@ function. See the [SDK Guide]({{< ref "/docs/Guides/Client SDKs/_index.md" >}}) for the full set of modification functions that are available. +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +### 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.Beta().IncrementCounter("room", 1)`]({{< ref "/docs/Guides/Client SDKs/_index.md#betaincrementcounterkey-amount" >}}) +function thatincrements the counter by 1. Similarly, to add the value `player1` to the `players` list, we can use the +[`SDK.Beta().AppendListValue("players", "player1")`]({{< ref "/docs/Guides/Client SDKs/_index.md#betaappendlistvaluekey-value" >}}) +function. + +See the [SDK Guide]({{< ref "/docs/Guides/Client SDKs/_index.md" >}}) for the full set of modification functions +that are available. +{{% /feature %}} ### Allocation When performing a `GameServer` allocation, you may want to manipulate the Counter and/or List information atomically diff --git a/site/content/en/docs/Guides/player-tracking.md b/site/content/en/docs/Guides/player-tracking.md index 26d38bb567..3258726a15 100644 --- a/site/content/en/docs/Guides/player-tracking.md +++ b/site/content/en/docs/Guides/player-tracking.md @@ -7,6 +7,7 @@ description: > Track player connections, disconnections, counts and capacities through the Agones SDK --- +{{% feature expiryVersion="1.41.0" %}} {{% 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. @@ -14,6 +15,16 @@ 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 %}} +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +{{% pageinfo color="info" %}} +[Counters and Lists]({{< ref "/docs/Guides/counters-and-lists.md" >}}) will eventually replace the Beta functionality +of Player Tracking, which will subsequently be removed from Agones. + +If you are currently using this Beta 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 %}} +{{% /feature %}} {{< alpha title="Player Tracking" gate="PlayerTracking" >}} diff --git a/site/content/en/docs/Integration Patterns/player-capacity.md b/site/content/en/docs/Integration Patterns/player-capacity.md index 3165c33036..f73ea68ecb 100644 --- a/site/content/en/docs/Integration Patterns/player-capacity.md +++ b/site/content/en/docs/Integration Patterns/player-capacity.md @@ -7,6 +7,7 @@ description: > Find a `GameServer` that has room for a specific number of players. --- +{{% feature expiryVersion="1.41.0" %}} {{% 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. @@ -16,6 +17,18 @@ 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 %}} +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +{{% pageinfo color="info" %}} +[Counters and Lists]({{< ref "/docs/Guides/counters-and-lists.md" >}}) will eventually replace the Beta functionality +of Player Tracking, which will subsequently be removed from Agones. + +If you are currently using this Beta 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 %}} +{{% /feature %}} {{< alpha title="Player Tracking and Allocation Player Filter" diff --git a/site/content/en/docs/Reference/gameserver.md b/site/content/en/docs/Reference/gameserver.md index ead3821df7..8c616c9ad2 100644 --- a/site/content/en/docs/Reference/gameserver.md +++ b/site/content/en/docs/Reference/gameserver.md @@ -192,26 +192,25 @@ spec: # # set this GameServer's initial player capacity # initialCapacity: 10 # - # [Stage:Alpha] + # [Stage:Beta] # [FeatureFlag:CountsAndLists] # Counts and Lists provides the configuration for generic (player, room, session, etc.) tracking features. - # Commented out since Alpha, and disabled by default - # counters: # counters are int64 counters that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time. - # games: # arbitrary key. - # count: 1 # initial value. - # capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details. - # sessions: - # count: 1 - # lists: # lists are lists of values stored against this GameServer that can be added and deleted from. Keys must be declared at GameServer creation time. - # players: # an empty list, with a capacity set to 10. - # capacity: 10 # capacity value, defaults to 1000. - # rooms: - # capacity: 333 - # values: # initial set of values in a list. - # - room1 - # - room2 - # - room3 - # + # Now in Beta, and enabled by default + counters: # counters are int64 counters that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time. + games: # arbitrary key. + count: 1 # initial value. + capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details. + sessions: + count: 1 + lists: # lists are lists of values stored against this GameServer that can be added and deleted from. Keys must be declared at GameServer creation time. + players: # an empty list, with a capacity set to 10. + capacity: 10 # capacity value, defaults to 1000. + rooms: + capacity: 333 + values: # initial set of values in a list. + - room1 + - room2 + - room3 # Pod template configuration # {{< k8s-api-version href="#podtemplate-v1-core" >}} template: @@ -240,12 +239,12 @@ but also attach specific [annotations](https://kubernetes.io/docs/concepts/overv The length of the `name` field of the Gameserver should not exceed 63 characters. +{{% feature expiryVersion="1.41.0" %}} The `spec` field is the actual GameServer specification and it is composed as follow: - `container` is the name of container running the GameServer in case you have more than one container defined in the [pod](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/). If you do, this is a mandatory field. For instance this is useful if you want to run a sidecar to ship logs. - `ports` are an array of ports that can be exposed as direct connections to the game server container - `name` is an optional descriptive name for a port - - `range` (Alpha, behind "PortRanges" feature gate) is the optional port range name from which to select a port when using a 'Dynamic' or 'Passthrough' port policy. - `portPolicy` has three options: - `Dynamic` (default) the system allocates a random free hostPort for the gameserver, for game clients to connect to. - `Static`, user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the port is available. When static is the policy specified, `hostPort` is required to be populated. @@ -269,6 +268,38 @@ The `spec` field is the actual GameServer specification and it is composed as fo {{< alert title="Note" color="info">}} The GameServer resource does not support updates. If you need to make regular updates to the GameServer spec, consider using a [Fleet]({{< ref "/docs/Reference/fleet.md" >}}). {{< /alert >}} +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +The `spec` field is the actual GameServer specification and it is composed as follow: + +- `container` is the name of container running the GameServer in case you have more than one container defined in the [pod](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/). If you do, this is a mandatory field. For instance this is useful if you want to run a sidecar to ship logs. +- `ports` are an array of ports that can be exposed as direct connections to the game server container + - `name` is an optional descriptive name for a port + - `range` (Alpha, behind "PortRanges" feature gate) is the optional port range name from which to select a port when using a 'Dynamic' or 'Passthrough' port policy. + - `portPolicy` has three options: + - `Dynamic` (default) the system allocates a random free hostPort for the gameserver, for game clients to connect to. + - `Static`, user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the port is available. When static is the policy specified, `hostPort` is required to be populated. + - `Passthrough` dynamically sets the `containerPort` to the same value as the dynamically selected hostPort. This will mean that users will need to lookup what port to open through the server side SDK before starting communications. + - `container` (Alpha) the name of the container to open the port on. Defaults to the game server container if omitted or empty. + - `containerPort` the port that is being opened on the game server process, this is a required field for `Dynamic` and `Static` port policies, and should not be included in Passthrough configuration. + - `protocol` the protocol being used. Defaults to UDP. TCP and TCPUDP are other options. +- `health` to track the overall healthy state of the GameServer, more information available in the [health check documentation]({{< relref "../Guides/health-checking.md" >}}). +- `sdkServer` defines parameters for the game server sidecar + - `logging` field defines log level for SDK server. Defaults to "Info". It has three options: + - "Info" (default) The SDK server will output all messages except for debug messages + - "Debug" The SDK server will output all messages including debug messages + - "Error" The SDK server will only output error messages + - `grpcPort` the port that the SDK Server binds to for gRPC connections + - `httpPort` the port that the SDK Server binds to for HTTP gRPC gateway connections +- `players` (Alpha, behind "PlayerTracking" feature gate), sets this GameServer's initial player capacity +- `counters` (Beta, requires "CountsAndLists" feature flag) are int64 counters with a default capacity of 1000 that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time. Note that setting the capacity to max(int64) may lead to issues. +- `lists` (Beta, requires "CountsAndLists" feature flag) are lists of values stored against this GameServer that can be added and deleted from. Key must be declared at GameServer creation time. +- `template` the [pod spec template]({{% k8s-api-version href="#podtemplatespec-v1-core" %}}) to run your GameServer containers, [see](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/#pod-templates) for more information. + +{{< alert title="Note" color="info">}} +The GameServer resource does not support updates. If you need to make regular updates to the GameServer spec, consider using a [Fleet]({{< ref "/docs/Reference/fleet.md" >}}). +{{< /alert >}} +{{% /feature %}} ## Stable Network ID diff --git a/site/content/en/docs/Reference/gameserverallocation.md b/site/content/en/docs/Reference/gameserverallocation.md index 173b69e6c0..456951c6bd 100644 --- a/site/content/en/docs/Reference/gameserverallocation.md +++ b/site/content/en/docs/Reference/gameserverallocation.md @@ -16,6 +16,7 @@ A full `GameServerAllocation` specification is available below and in the {{< ghlink href="/examples/gameserverallocation.yaml" >}}example folder{{< /ghlink >}} for reference: +{{% feature expiryVersion="1.41.0" %}} {{< tabpane >}} {{< tab header="selectors" lang="yaml" >}} apiVersion: "allocation.agones.dev/v1" @@ -171,7 +172,166 @@ spec: map: garden22 {{< /tab >}} {{< /tabpane >}} +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +{{< tabpane >}} + {{< tab header="selectors" lang="yaml" >}} +apiVersion: "allocation.agones.dev/v1" +kind: GameServerAllocation +spec: + # GameServer selector from which to choose GameServers from. + # Defaults to all GameServers. + # matchLabels, matchExpressions, gameServerState and player filters can be used for filtering. + # See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details on label selectors. + # An 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. + selectors: + - matchLabels: + agones.dev/fleet: green-fleet + # [Stage:Alpha] + # [FeatureFlag:PlayerAllocationFilter] + players: + minAvailable: 0 + maxAvailable: 99 + - matchLabels: + agones.dev/fleet: blue-fleet + - matchLabels: + game: my-game + matchExpressions: + - {key: tier, operator: In, values: [cache]} + # 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. + gameServerState: Ready + # [Stage:Beta] + # [FeatureFlag:CountsAndLists] + counters: # selector for counter current values of a GameServer count + rooms: + minCount: 1 # minimum value. Defaults to 0. + maxCount: 5 # maximum value. Defaults to max(int64) + minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0. + maxAvailable: 10 # maximum available (current capacity - current count) Defaults to max(int64) + lists: + players: + containsValue: "x6k8z" # only match GameServers who has this value in the list. Defaults to "", which is all. + minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0. + maxAvailable: 10 # maximum available (current capacity - current count) Defaults to 0, which translates to max(int64) + # [Stage:Alpha] + # [FeatureFlag:PlayerAllocationFilter] + # Provides a filter on minimum and maximum values for player capacity when retrieving a GameServer + # through Allocation. Defaults to no limits. + players: + minAvailable: 0 + maxAvailable: 99 + # defines how GameServers are organised across the cluster. + # Options include: + # "Packed" (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack + # resources + # "Distributed" is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire + # cluster + scheduling: Packed + # Optional custom metadata that is added to the game server at allocation + # You can use this to tell the server necessary session data + metadata: + labels: + mode: deathmatch + annotations: + map: garden22 + # [Stage: Beta] + # [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: Beta] + # [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" +kind: GameServerAllocation +spec: + # Deprecated, use field selectors instead. + # GameServer selector from which to choose GameServers from. + # Defaults to all GameServers. + # matchLabels, matchExpressions, gameServerState and player filters can be used for filtering. + # See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details on label selectors. + # Deprecated, use field selectors instead. + required: + matchLabels: + game: my-game + matchExpressions: + - {key: tier, operator: In, values: [cache]} + # 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. + gameServerState: Ready + # [Stage:Alpha] + # [FeatureFlag:PlayerAllocationFilter] + # Provides a filter on minimum and maximum values for player capacity when retrieving a GameServer + # through Allocation. Defaults to no limits. + players: + minAvailable: 0 + maxAvailable: 99 + # Deprecated, use field selectors instead. + # An ordered list of preferred GameServer label 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. + # This also support matchExpressions, gameServerState and player filters. + preferred: + - matchLabels: + agones.dev/fleet: green-fleet + # [Stage:Alpha] + # [FeatureFlag:PlayerAllocationFilter] + players: + minAvailable: 0 + maxAvailable: 99 + - matchLabels: + agones.dev/fleet: blue-fleet + # defines how GameServers are organised across the cluster. + # Options include: + # "Packed" (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack + # resources + # "Distributed" is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire + # cluster + scheduling: Packed + # Optional custom metadata that is added to the game server at allocation + # You can use this to tell the server necessary session data + metadata: + labels: + mode: deathmatch + annotations: + map: garden22 + {{< /tab >}} +{{< /tabpane >}} +{{% /feature %}} +{{% feature expiryVersion="1.41.0" %}} The `spec` field is the actual `GameServerAllocation` specification, and it is composed as follows: - Deprecated, use `selectors` instead. If `selectors` is set, this field will be ignored. @@ -248,6 +408,85 @@ when using an API call. If not specified when using the command line, the [names [addresses]: https://v1-26.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#nodeaddress-v1-core [counterstatus]: {{% ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.CounterStatus" %}} [liststatus]: {{% ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.ListStatus" %}} +{{% /feature %}} +{{% feature publishVersion="1.41.0" %}} +The `spec` field is the actual `GameServerAllocation` specification, and it is composed as follows: + +- Deprecated, use `selectors` instead. If `selectors` is set, this field will be ignored. + `required` is a [GameServerSelector][gameserverselector] + (matchLabels. matchExpressions, gameServerState and player filters) from which to choose GameServers from. +- Deprecated, use `selectors` instead. If `selectors` is set, this field will be ignored. + `preferred` is an ordered list of preferred [GameServerSelector][gameserverselector] + 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. +- `selectors` is an ordered list of [GameServerSelector][gameserverselector]. + 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. +- `matchLabels` is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element + of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". + The requirements are ANDed. Optional. +- `matchExpressions` is a list of label selector requirements. The requirements are ANDed. Optional. +- `gameServerState` GameServerState specifies which State is the filter to be used when attempting to retrieve a + GameServer via Allocation. Defaults to "Ready". The only other option is "Allocated", which can be used in + conjunction with label/annotation/player selectors to retrieve an already Allocated GameServer. +- `counters` (Beta, "CountsAndLists" feature flag) enables filtering based on game server Counter status, such as + the minimum and maximum number of active rooms. This helps in selecting game servers based on their current activity + or capacity. Optional. +- `lists` (Beta, "CountsAndLists" feature flag) enables filtering based on game server List status, such as allowing + for inclusion or exclusion of specific players. Optional. +- `scheduling` defines how GameServers are organised across the cluster, in this case specifically when allocating + `GameServers` for usage. + "Packed" (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack + resources. "Distributed" is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire + 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` (Beta, requires `CountsAndLists` feature flag) alters the priority by which game `GameServers` are allocated by available capacity. +- `counters` (Beta, "CountsAndLists" feature flag) Counter actions to perform during allocation. +- `lists` (Beta, "CountsAndLists" feature flag) List actions to perform during allocation. + +Once created the `GameServerAllocation` will have a `status` field consisting of the following: + +- `State` is the current state of a GameServerAllocation, e.g. `Allocated`, or `UnAllocated` +- `GameServerName` is the name of the game server attached to this allocation, once the `state` is `Allocated` +- `Ports` is a list of the ports that the game server makes available. See [the GameServer Reference]({{< ref "/docs/Reference/gameserver.md" >}}) for more details. +- `Address` is the primary network address where the game server can be reached. +- `Addresses` is an array of all network addresses where the game server can be reached. It is a copy of the [`Node.Status.addresses`][addresses] field for the node the `GameServer` is scheduled on. +- `NodeName` is the name of the node that the gameserver is running on. +- `Source` is "local" unless this allocation is from a remote cluster, in which case `Source` is the endpoint of the remote agones-allocator. See [Multi-cluster Allocation]({{< ref "/docs/Advanced/multi-cluster-allocation.md" >}}) for more details. +- `Metadata` conststs of: + - `Labels` containing the labels of the game server at allocation time. + - `Annotations` containing the annotations of the underlying game server at allocation time. +- `Counters` (Beta, "CountsAndLists" feature flag) is a map of [CounterStatus][counterstatus] of the game server at allocation time. +- `Lists` (Beta, "CountsAndLists" feature flag) is a map of [ListStatus][liststatus] of the game server at allocation time. +{{< alert title="Info" color="info" >}} + +For performance reasons, the query cache for a `GameServerAllocation` is _eventually consistent_. + +Usually, the cache is populated practically immediately on `GameServer` change, but under high load of the Kubernetes +control plane, it may take some time for updates to `GameServer` selectable features to be populated into the cache +(although this doesn't affect the atomicity of the Allocation operation). + +While Agones will do a small series of retries when an allocatable `GameServer` is not available in its cache, +depending on your game requirements, it may be worth implementing your own more extend retry mechanism for +Allocation requests for high load scenarios. + +{{< /alert >}} + +Each `GameServerAllocation` will allocate from a single [namespace][namespace]. The namespace can be specified outside of +the spec, either with the `--namespace` flag when using the command line / `kubectl` or +[in the url]({{% ref "/docs/Guides/access-api.md#allocate-a-gameserver-from-a-fleet-named-simple-game-server-with-gameserverallocation" %}}) +when using an API call. If not specified when using the command line, the [namespace][namespace] will be automatically set to `default`. + + +[gameserverselector]: {{% ref "/docs/Reference/agones_crd_api_reference.html#allocation.agones.dev/v1.GameServerSelector" %}} +[namespace]: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces +[addresses]: https://v1-26.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#nodeaddress-v1-core +[counterstatus]: {{% ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.CounterStatus" %}} +[liststatus]: {{% ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.ListStatus" %}} +{{% /feature %}} ## Next Steps: