diff --git a/site/content/en/docs/Integration Patterns/high-density-gameservers.md b/site/content/en/docs/Integration Patterns/high-density-gameservers.md index 07fe4c0108..58884aa72c 100644 --- a/site/content/en/docs/Integration Patterns/high-density-gameservers.md +++ b/site/content/en/docs/Integration Patterns/high-density-gameservers.md @@ -29,25 +29,28 @@ game server process deems that is has room to host another game session. {{< alert title="Info" color="info">}} To watch for Allocation events, there is the initial `GameServer.status.state` change from `Ready` to `Allocated`, but it is also useful to know that the value of `GameServer.metadata.annotations["agones.dev/last-allocated"]` will -change with each allocation, regardless of if there is a state change or not. +change as it is set by Agones with each allocation with the current timestamp, regardless of if there +is a state change or not. {{< /alert >}} ## Example `GameServerAllocation` The below `Allocation` will first attempt to find a `GameServer` from the `Fleet` `simple-udp` that is already -Allocated and also has the label `agones.dev/sdk-available` with the value of `true`. +Allocated and also has the label `agones.dev/sdk-gs-session-ready` with the value of `true`. The above condition indicates that the matching game server process behind the matched `GameServer` record is able to accept another game session at this time. -If the above Allocated `GameServer` does not exist, then allocated a Ready `GameServer` from the `simple-udp` `Fleet`. +If an Allocated `GameServer` does not exist with the desired labels, then use the next selector to allocate a Ready +`GameServer` from the `simple-udp` `Fleet`. -Whichever condition is met, once allocation is made against a `GameServer`, its label of `agones.dev/sdk-available` -will be set to the value of `false`, thereby removing it from any future allocations with the below schema. +Whichever condition is met, once allocation is made against a `GameServer`, its label of `agones.dev/sdk-gs-session-ready` +will be set to the value of `false` and it will no longer match the first selector, thereby removing it from any +future allocations with the below schema. It will then be up to the game server process to decide on if and when it is appropriate to set the -`agones.dev/sdk-available` value back to `true`, thereby indicating that it can accept another concurrent -gameplay session. +`agones.dev/sdk-gs-session-ready` value back to `true`, thereby indicating that it can accept another concurrent +gameplay session. ```yaml apiVersion: "allocation.agones.dev/v1" @@ -56,14 +59,14 @@ spec: selectors: - matchLabels: agones.dev/fleet: simple-udp - agones.dev/sdk-available: "true" # this is important + agones.dev/sdk-gs-session-ready: "true" # this is important gameServerState: Allocated # new state filter: allocate from Allocated servers - matchLabels: agones.dev/fleet: simple-udp gameServerState: Ready # Allocate out of the Ready Pool (which would be default, so backward compatible) metadata: labels: - agones.dev/sdk-available: "false" # this removes it from the pool + agones.dev/sdk-gs-session-ready: "false" # this removes it from the pool ``` {{< alert title="Info" color="info">}} diff --git a/site/static/diagrams/high-density.puml b/site/static/diagrams/high-density.puml index f81094fa7f..89c2f32a42 100644 --- a/site/static/diagrams/high-density.puml +++ b/site/static/diagrams/high-density.puml @@ -38,21 +38,26 @@ Matchmaker -> Agones: Create: GameServerAllocation note left The GameServerAllocation is implemented to optionally select an already allocated GameServer - with metadata["agones.dev/sdk-available"] = "true" + with metadata.labels["agones.dev/sdk-gs-session-ready"] = "true" if one exists. At this stage, one does not, so Agones will allocate a Ready GameServer. end note -Agones -> GameServer: Finds a Ready GameServer,\nsets it to Allocated State\nand metadata["agones.dev/sdk-available"] = "false" +Agones -> GameServer: Finds a Ready GameServer.\n\nSets status.state to Allocated State\nand metadata.labels["agones.dev/sdk-gs-session-ready"] = "false"\nand metadata.annotations["agones.dev/last-allocated"] = current timestamp note left -By setting the label "agones.dev/last-allocated" to "false" +By setting the label "agones.dev/sdk-gs-session-ready" to "false" this remove the `GameServer` from possibly being -re-allocated until it knows it can handle -another session. +re-allocated until it knows it can handle another session. end note Matchmaker <-- Agones : GameServerAllocation is returned\nwith GameServer details\nincluding IP and port to connect to. SDK --> Binary: Sends SDK.WatchGameServer()\nevent for Allocation. -Binary -> SDK: SDK.SetLabel("available", "true") +note right +This initial allocation can be determined +as a change in GameServer.status.state +from Ready to Allocated +end note + +Binary -> SDK: SDK.SetLabel("gs-session-ready", "true") note right Since this game process can handle n concurrent sessions, set this label to match @@ -60,7 +65,7 @@ optional allocation label selectors, so it can be re-allocated. (See example below for more details) end note -SDK --> GameServer: Sets metadata["agones.dev/sdk-available"] = "true" +SDK --> GameServer: Sets metadata.labels["agones.dev/sdk-gs-session-ready"] = "true" == Allocated GameServers with room for more sessions == @@ -68,11 +73,11 @@ Matchmaker -> Agones: Create: GameServerAllocation note left The GameServerAllocation will this time find the Allocated GameServer with the label - metadata["agones.dev/sdk-available"] = "true", + metadata.labels["agones.dev/sdk-gs-session-ready"] = "true", indicating that it can accept more concurrent game sessions. end note -Agones -> GameServer: Finds the Allocated GameServer\nwith metadata["agones.dev/sdk-available"] = "true"\n and set metadata["agones.dev/sdk-available"] = "false". +Agones -> GameServer: Finds the Allocated GameServer with\nmetadata.labels["agones.dev/sdk-gs-session-ready"] = "true".\n\nSets metadata.labels["agones.dev/sdk-gs-session-ready"] = "false"\nand metadata.annotations["agones.dev/last-allocated"] = current timestamp. note right This is the a GameServer that has room for another concurrent game session. @@ -80,15 +85,20 @@ end note Matchmaker <-- Agones: returns Allocated GameServer record SDK --> Binary: Sends SDK.WatchGameServer()\nevent for Allocation. +note right +The game server process can watch for a change +in metadata.annotations["agones.dev/last-allocated"] +to determine there is an allocation event. +end note alt GameServer can accept more concurrent sessions - Binary -> SDK: SDK.SetLabel("available", "true") - SDK --> GameServer: Sets metadata["agones.dev/sdk-available"] = "true". + Binary -> SDK: SDK.SetLabel("gs-session-ready", "true") + SDK --> GameServer: Sets metadata.labels["agones.dev/sdk-gs-session-ready"] = "true". end alt note right If the GameServer can accept more concurrent sessions, reset the - "agones.dev/sdk-available" + "agones.dev/sdk-gs-session-ready" back to "true" end note @@ -101,7 +111,7 @@ that it hosts, and after n number, calls Shutdown() to delete the GameServer resource and backing Pod. end note SDK --> GameServer: Update to Shutdown state. -Agones -> GameServer: Deletes GameServer resource\n and backing Pod. +Agones -> GameServer: Deletes GameServer resource and backing Pod. destroy Binary destroy SDK destroy GameServer diff --git a/site/static/diagrams/high-density.puml.png b/site/static/diagrams/high-density.puml.png index d827f2a10d..96fb3ff913 100644 Binary files a/site/static/diagrams/high-density.puml.png and b/site/static/diagrams/high-density.puml.png differ