Add a System Diagram and overview page

build/includes/website.mk

@@ -78,6 +78,7 @@ site-test:
 # generate site images, if they don't exist
 site-images: $(site_path)/static/diagrams/gameserver-states.dot.png
 site-images: $(site_path)/static/diagrams/eviction-decision.dot.png
+site-images: ${site_path}/static/diagrams/system-diagram.dot.png
 site-images: $(site_path)/static/diagrams/gameserver-lifecycle.puml.png
 site-images: $(site_path)/static/diagrams/gameserver-reserved.puml.png
 site-images: $(site_path)/static/diagrams/canary-testing.puml.png

site/content/en/docs/Advanced/system-diagram.md

@@ -0,0 +1,49 @@
+---
+title: "System Diagram"
+date: 2024-04-18
+weight: -100
+description: >
+  A pictoral overview of the Agones component relationships.
+---
+
+![System Diagram](../../../diagrams/system-diagram.dot.png)
+
+# Agones Control Plane 
+
+The Agones Control Plane consists of 4 `Deployments`:
+```
+NAME                READY   UP-TO-DATE   AVAILABLE   AGE
+agones-allocator    3/3     3            3           40d
+agones-controller   2/2     2            2           40d
+agones-extensions   2/2     2            2           40d
+agones-ping         2/2     2            2           40d
+```
+
+## `agones-allocator`
+
+`agones-allocator` provides a gRPC/REST service that translates allocation requests into `GameServerAllocations`. See [Allocator Service]({{< relref "allocator-service.md">}}) for more information.
+
+## `agones-controller`
+
+`agones-controller` maintains various control loops for all Agones CRDs (`GameServer`, `Fleet`, etc.). A single leader-elected `Pod` of the `Deployment`
+is active at any given time (see [High Availability]({{< relref "high-availability-agones.md">}})).
+
+## `agones-extensions`
+
+`agones-extensions` is the endpoint for:
+* Agones-installed Kubernetes webhooks, which handle defaulting and validation for Agones CRs,
+* and the `GameServerAllocation` `APIService`, which handles `GameServer` allocations (either from the Allocator Service or the Kubernetes API).
+
+## `agones-ping` (not pictured)
+
+`agones-ping` is a simple ping service for latency testing from your game client - see [Latency Testing]({{< relref "ping-service.md">}})).
+
+# Agones CRDs
+
+See [Create a Game Server]({{< relref "create-gameserver.md">}})), [Create a Game Server]({{< relref "create-fleet.md">}})) for examples of Agones CRDs in action, or the [API Reference]({{< ref "/docs/Reference" >}}) for more detail.
+
+All of the Agones CRDs are controlled and updated by `agones-controller`. `GameServer` is additionally updated by the SDK Sidecar and `agones-extensions` (moving a `GameServer` from [`Ready` to `Allocated`]({{< ref "/docs/Reference/gameserver.md#gameserver-state-diagram" >}}))
+
+# Game Server Pod
+
+Also pictured is an example `Pod` owned by a `GameServer`. Game clients typically connect to the Dedicated Game Server directly, or via a proxy like [Quilkin](https://googleforgames.github.io/quilkin/main/book/introduction.html). The game server server interfaces with Agones using the [Client SDK]({{< relref "Client SDKs">}}), which is a thin wrapper around the [SDK gRPC protocol](https://github.com/googleforgames/agones/blob/main/proto/sdk/sdk.proto). The SDK connects to the SDK Sidecar (`sdk-server`) in the same Pod, which handles the SDK business logic for e.g. [health checks]({{< relref "health-checking.md">}}), [Counters and Lists]({{< relref "counters-and-lists.md">}}), etc.

site/static/diagrams/system-diagram.dot

@@ -0,0 +1,165 @@
+digraph {
+    compound=true
+    graph [fontname = "helvetica", style="rounded", nodesep=0.2, newrank="true"]
+    node [fontname = "helvetica", shape="box3d"]
+    edge [fontname = "helvetica", pad="0.2", penwidth="2"]
+
+    subgraph cluster_invisible_margin0 {
+        style="invis"
+        graph[margin=20]
+        rank="source"
+
+        GameFrontEnd [ label= "game front end" ]
+    }
+
+    subgraph cluster_invisible_margin1 {
+        style="invis"
+        graph[margin=20]
+        rank="same"
+        // rank="source"
+
+        subgraph cluster_acp {
+            label="Agones Control Plane"
+            graph[margin=4, style="rounded"]
+
+            subgraph cluster_allocator {
+                label="agones-allocator Deployment";
+                rank="same"
+
+                AllocatorN [ label = "agones-allocator\nreplica N", style="filled" ]
+                Allocator1 [ label = "agones-allocator\nreplica 1", style="filled" ]
+            }
+            subgraph cluster_controller {
+                label="agones-controller Deployment";
+                rank="same"
+
+                ControllerSpare [ label = "agones-controller\nspare", style="filled" ]
+                Controller [ label = "agones-controller\nleader", style="filled" ]
+            }
+            subgraph cluster_extensions {
+                label="agones-extensions Deployment";
+                rank="same"
+
+                ExtensionsN [ label = "agones-extensions\nreplica N", style="filled" ]
+                Extensions1 [ label = "agones-extensions\nreplica 1", style="filled" ]
+            }
+        }
+    }
+
+    GameFrontEnd -> AllocatorN
+    GameFrontEnd -> Allocator1
+
+    subgraph cluster_invisible_margin2 {
+        style="invis"
+        graph[margin=20]
+
+        subgraph cluster_kcp {
+            label="Kubernetes Control Plane"
+            graph[margin=4, style="rounded"]
+            node[shape="note"]
+
+            subgraph cluster_agones_crds {
+                label="Agones CRDs"
+                rank="same"
+
+                subgraph cluster_fleet {
+                    label="Fleet"
+
+                    subgraph cluster_gss_2 {
+                        label="GameServerSet 2"
+                        graph[style=rounded]
+
+                        GameServer3 [ label = "GameServer\ngame-server-3" ]
+                    }
+
+                    subgraph cluster_gss_1 {
+                        label="GameServerSet 1"
+                        graph[style=rounded]
+
+                        GameServer2 [ label = "GameServer\ngame-server-2" ]
+                        GameServer1 [ label = "GameServer\ngame-server-1" ]
+                    }
+                }
+            }
+            subgraph cluster_pods {
+                label="Pods"
+                rank="same"
+
+                Pod1 [ label = "game-server-1" ]
+                Pod2 [ label = "game-server-2" ]
+                Pod3 [ label = "game-server-3" ]
+            }
+            GameServer1 -> Pod1 [ style="dotted" ]
+            GameServer2 -> Pod2 [ style="dotted" ]
+            GameServer3 -> Pod3 [ style="dotted" ]
+        }
+    }
+
+    subgraph cluster_invisible_key {
+        style="invis"
+        graph[margin=20, nodesep=1]
+
+        subgraph cluster_key_top {
+            style="invis"
+
+            k8s_top [ label="", style="invis" ]
+            gsa_top [ label="", style="invis" ]
+            sdk_top [ label="", style="invis" ]
+            control_top [ label="", style="invis" ]
+
+            KubeResource [label="kubernetes\nresource", shape="note" ]
+        }
+
+        subgraph cluster_key_bottom {
+            k8s_bottom [label="", style="invis"]
+            gsa_bottom [ label="", style="invis" ]
+            sdk_bottom [label="", style="invis"]
+            control_bottom [label="", style="invis"]
+
+            Container [style="filled"]
+        }
+
+        KubeResource -> Container [ style="invis" ]
+        k8s_top -> k8s_bottom [ color="blue", label="K8s"  ]
+        gsa_top -> gsa_bottom [ color="green", label="Allocations"  ]
+        sdk_top -> sdk_bottom [ color="red", label="SDK\ngRPC" ]
+        control_top -> control_bottom [ style="dotted", label="controls" ]
+
+    }
+
+    subgraph cluster_invisible_margin3 {
+        style="invis"
+        graph[margin=0]
+        rank="sink"
+
+        subgraph cluster_pod {
+            label="Pod game-server-1 runtime"
+            graph[margin=4, style="rounded"]
+
+            SDKServer [ label = "sdk-server\nSDK Sidecar", style="filled" ]
+            GameServerContainer [ label = "dedicated\ngame server", style="filled" ]
+            GameServerContainer -> SDKServer [ color="red" ]
+        }
+
+        GameClient [ label="game client" ]
+        GameClient -> GameServerContainer
+
+        // force position using invisible edges
+        k8s_bottom -> SDKServer [ style="invis" ]
+        gsa_bottom -> SDKServer [ style="invis" ]
+        sdk_bottom -> SDKServer [ style="invis" ]
+        control_bottom -> SDKServer [ style="invis" ]
+        Container -> SDKServer[ style="invis" ]
+    }
+
+    GameServer1 -> Extensions1 [ ltail="cluster_kcp", color="blue" ]
+    GameServer1 -> ExtensionsN [ ltail="cluster_kcp", color="blue" ]
+    GameServer1 -> Extensions1 [ ltail="cluster_kcp", color="green", constraint=false ]
+    GameServer1 -> ExtensionsN [ ltail="cluster_kcp", color="green", constraint=false ]
+    Controller -> GameServer1 [ lhead="cluster_kcp", color="blue" ]
+    Allocator1 -> GameServer1 [ lhead="cluster_kcp", color="green" ]
+    AllocatorN -> GameServer1 [ lhead="cluster_kcp", color="green" ]
+    SDKServer -> GameServer1 [ color="blue" ]
+
+    Pod1 -> GameServerContainer [ lhead="cluster_pod", style="dotted" ]
+}