Review updates.

site/content/en/docs/Integration Patterns/high-density-gameservers.md

@@ -16,7 +16,7 @@ The tradeoff here is that this requires more management on behalf of the integra
 systems, since it works around the common Kubernetes and/or Agones container lifecycle.
 
 Utilising the new allocation `gameServerState` filter as well as the existing ability to edit the 
-`GameServer` Labels at both [allocation time]({{% ref "/docs/Reference/gameserverallocation.md" %}}), and from 
+`GameServer` labels at both [allocation time]({{% ref "/docs/Reference/gameserverallocation.md" %}}), and from 
 within the game server process, [via the SDK]({{% ref "/docs/Guides/Client SDKs/_index.md#setlabelkey-value" %}}), 
 means Agones is able to atomically remove a `GameServer` from the list of potentially allocatable 
 `GameServers` at allocation time, and then return it back into the pool of allocatable `GameServers` if and when the 
@@ -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">}}

site/static/diagrams/high-density.puml

@@ -38,57 +38,67 @@ Matchmaker -> Agones: Create: <i>GameServerAllocation</i>
 note left
   The <i>GameServerAllocation</i> is implemented to
   optionally select an already allocated <i>GameServer</i>
-  with <i>metadata["agones.dev/sdk-available"] = "true"</i>
+  with <i>metadata.labels["agones.dev/sdk-gs-session-ready"] = "true"</i>
   if one exists. At this stage, one does not, so
   Agones will allocate a <i>Ready</i> <i>GameServer</i>.
 end note
-Agones -> GameServer: Finds a <i>Ready</i> <i>GameServer</i>,\nsets it to <i>Allocated</i> State\nand <i>metadata["agones.dev/sdk-available"] = "false"</i>
+Agones -> GameServer: Finds a <i>Ready</i> <i>GameServer</i>.\n\nSets <i>status.state</i> to <i>Allocated</i> State\nand <i>metadata.labels["agones.dev/sdk-gs-session-ready"] = "false"</i>\nand <i>metadata.annotations["agones.dev/last-allocated"] = current timestamp</i>
 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 : <i>GameServerAllocation</i> is returned\nwith <i>GameServer</i> 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 <i>GameServer.status.state</i>
+from <i>Ready</i> to <i>Allocated</i>
+end note
+
+Binary -> SDK: SDK.SetLabel("gs-session-ready", "true")
 note right
 Since this game process can handle <i>n</i>
 concurrent sessions, set this label to match
 optional allocation label selectors, so it can be
 re-allocated.
 (See example below for more details)
 end note
-SDK --> GameServer: Sets <i>metadata["agones.dev/sdk-available"] = "true"</i>
+SDK --> GameServer: Sets <i>metadata.labels["agones.dev/sdk-gs-session-ready"] = "true"</i>
 
 == Allocated <i>GameServers</i> with room for more sessions ==
 
 Matchmaker -> Agones: Create: <i>GameServerAllocation</i>
 note left
   The <i>GameServerAllocation</i> will this time
   find the Allocated <i>GameServer</i> with the label
-  <i>metadata["agones.dev/sdk-available"] = "true"</i>,
+  <i>metadata.labels["agones.dev/sdk-gs-session-ready"] = "true"</i>,
   indicating that it can accept more
   concurrent game sessions.
 end note
-Agones -> GameServer: Finds the Allocated <i>GameServer</i>\nwith <i>metadata["agones.dev/sdk-available"] = "true"</i>\n and set <i>metadata["agones.dev/sdk-available"] = "false"</i>.
+Agones -> GameServer: Finds the Allocated <i>GameServer</i> with\n<i>metadata.labels["agones.dev/sdk-gs-session-ready"] = "true"</i>.\n\nSets <i>metadata.labels["agones.dev/sdk-gs-session-ready"] = "false"</i>\nand <i>metadata.annotations["agones.dev/last-allocated"] = current timestamp</i>.
 note right
   This is the a <i>GameServer</i> that has room
   for another concurrent game session.
 end note
 Matchmaker <-- Agones: returns <i>Allocated GameServer</i> record
 
 SDK --> Binary: Sends SDK.WatchGameServer()\nevent for Allocation.
+note right
+The game server process can watch for a change
+in <i>metadata.annotations["agones.dev/last-allocated"]</i>
+to determine there is an allocation event.
+end note
 
 alt <i>GameServer</i> can accept more concurrent sessions
-  Binary -> SDK: SDK.SetLabel("available", "true")
-  SDK --> GameServer: Sets <i>metadata["agones.dev/sdk-available"] = "true"</i>.
+  Binary -> SDK: SDK.SetLabel("gs-session-ready", "true")
+  SDK --> GameServer: Sets <i>metadata.labels["agones.dev/sdk-gs-session-ready"] = "true"</i>.
 end alt
 note right
-  If the <i>GameServer</i> can accept
-  more concurrent sessions, reset the
-  <i>"agones.dev/sdk-available"</i>
+  If the <i>GameServer</i> can accept more
+  concurrent sessions, reset the label
+  <i>"agones.dev/sdk-gs-session-ready"</i>
   back to "true"
 end note
 
@@ -101,7 +111,7 @@ that it hosts, and after <i>n</i> number, calls <i>Shutdown()</i>
 to delete the <i>GameServer</i> resource and backing Pod.
 end note
 SDK --> GameServer: Update to <i>Shutdown</i> state.
-Agones -> GameServer: Deletes GameServer resource\n and backing Pod.
+Agones -> GameServer: Deletes GameServer resource and backing Pod.
 destroy Binary
 destroy SDK
 destroy GameServer