Add a System Diagram and overview page (#3792)

* Add a System Diagram and overview page Adds a System Diagram and a whirlwind tour of the pieces of Agones. * Add licenses to diagram source * Update site/content/en/docs/Advanced/system-diagram.md Co-authored-by: Mark Mandel <[email protected]> * Update site/content/en/docs/Advanced/system-diagram.md Co-authored-by: Mark Mandel <[email protected]> * Update site/content/en/docs/Advanced/system-diagram.md Co-authored-by: Mark Mandel <[email protected]> --------- Co-authored-by: Mark Mandel <[email protected]>
googleforgames · Apr 25, 2024 · 55e7bab · 55e7bab
1 parent 2e34147
commit 55e7bab
Show file tree

Hide file tree

Showing 19 changed files with 353 additions and 0 deletions.
diff --git a/build/includes/website.mk b/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

diff --git a/site/content/en/docs/Advanced/system-diagram.md b/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.
diff --git a/site/static/diagrams/allocation-player-capacity.puml b/site/static/diagrams/allocation-player-capacity.puml
@@ -1,4 +1,20 @@
 @startuml
+/'
+Copyright 2024 Google LLC All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'/
+
 'https://plantuml.com/sequence-diagram
 
 actor "Player One" as Player1

diff --git a/site/static/diagrams/allocation-player-capacity.puml.png b/site/static/diagrams/allocation-player-capacity.puml.png
diff --git a/site/static/diagrams/canary-testing.puml b/site/static/diagrams/canary-testing.puml
@@ -1,4 +1,20 @@
 @startuml
+/'
+Copyright 2024 Google LLC All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'/
+
 'https://plantuml.com/sequence-diagram
 
 participant Matchmaker

diff --git a/site/static/diagrams/canary-testing.puml.png b/site/static/diagrams/canary-testing.puml.png
diff --git a/site/static/diagrams/eviction-decision.dot b/site/static/diagrams/eviction-decision.dot
@@ -1,3 +1,17 @@
+// Copyright 2024 Google LLC All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 digraph {
  graph [fontname = "helvetica", ordering="out"];
  node [fontname = "helvetica"];

diff --git a/site/static/diagrams/gameserver-lifecycle.puml b/site/static/diagrams/gameserver-lifecycle.puml
@@ -1,4 +1,20 @@
 @startuml
+/'
+Copyright 2024 Google LLC All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'/
+
 participant Matchmaker
 participant "Kubernetes API" as K8sAPI
 participant Agones

diff --git a/site/static/diagrams/gameserver-lifecycle.puml.png b/site/static/diagrams/gameserver-lifecycle.puml.png
diff --git a/site/static/diagrams/gameserver-reserved.puml b/site/static/diagrams/gameserver-reserved.puml
@@ -1,4 +1,20 @@
 @startuml
+/'
+Copyright 2024 Google LLC All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'/
+
 participant Matchmaker
 participant Agones
 participant "Game Server\nProcess" as Binary

diff --git a/site/static/diagrams/gameserver-reserved.puml.png b/site/static/diagrams/gameserver-reserved.puml.png
diff --git a/site/static/diagrams/gameserver-states.dot b/site/static/diagrams/gameserver-states.dot
@@ -1,3 +1,17 @@
+// Copyright 2024 Google LLC All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 digraph {
  graph [fontname = "helvetica"];
  node [fontname = "helvetica"];

diff --git a/site/static/diagrams/gameserver-states.dot.png b/site/static/diagrams/gameserver-states.dot.png
diff --git a/site/static/diagrams/high-density.puml b/site/static/diagrams/high-density.puml
@@ -1,4 +1,20 @@
 @startuml
+/'
+Copyright 2024 Google LLC All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'/
+
 participant Matchmaker
 participant Agones
 participant "Game Server\nProcess" as Binary

diff --git a/site/static/diagrams/high-density.puml.png b/site/static/diagrams/high-density.puml.png
diff --git a/site/static/diagrams/reusing-gameservers.puml b/site/static/diagrams/reusing-gameservers.puml
@@ -1,4 +1,20 @@
 @startuml
+/'
+Copyright 2024 Google LLC All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'/
+
 participant Matchmaker
 participant Agones
 participant "Game Server\nProcess" as Binary

diff --git a/site/static/diagrams/reusing-gameservers.puml.png b/site/static/diagrams/reusing-gameservers.puml.png