docs: added game server state diagram

build/Makefile

@@ -59,6 +59,7 @@ GS_TEST_IMAGE ?= gcr.io/agones-images/udp-server:0.5
 mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))
 build_path := $(dir $(mkfile_path))
 agones_path := $(realpath $(build_path)/..)
+docs_path := $(agones_path)/docs
 
 kubeconfig_path := $(dir $(KUBECONFIG))
 kubeconfig_file := $(notdir $(KUBECONFIG))
@@ -296,6 +297,12 @@ gen-crd-client: $(ensure-build-image)
 	docker run --rm $(common_mounts) -w $(mount_path) $(build_tag) /root/gen-crd-client.sh
 	docker run --rm $(common_mounts) -w $(mount_path)/pkg $(build_tag) goimports -w .
 
+doc-images: $(docs_path)/gameserver-states.png
+
+%.png: %.dot
+	docker run -i --rm $(common_mounts) $(DOCKER_RUN_ARGS) $(build_tag) bash -c \
+	  'dot -Tpng /dev/stdin' < $< > [email protected] && mv [email protected] $@
+
 # Run a bash shell with the developer tools in it. (Creates the image if it doesn't exist)
 # Can use DOCKER_RUN_ARGS for extra arguments.
 shell: $(ensure-build-image)

docs/gameserver-states.dot

@@ -0,0 +1,71 @@
+digraph {
+    graph [fontname = "helvetica"];
+    node [fontname = "helvetica"];
+    edge [fontname = "helvetica", pad="0.2", penwidth="2"];
+
+    Created [ label = "game server created" ]
+    PortAllocation
+    Creating
+    Error
+    Starting
+    Scheduled
+    RequestReady
+    Ready
+    Allocated
+    Shutdown
+    Unhealthy
+    Allocated
+    Deleted [ label = "game server deleted" ]
+
+    Created -> PortAllocation [ label ="has any port\nwith dynamic policy", color="red" ]
+    Created -> Creating [ label="only static ports", color="red" ]
+
+    PortAllocation -> Creating [ label="allocated unused port", color="blue" ]
+    Creating -> Starting [ label="created pod", color="blue" ]
+    Starting -> Scheduled [ label="we have a pod, fetch its address", color="blue" ]
+    Scheduled -> RequestReady [ label="SDK.ready()", color="purple" ]
+    RequestReady -> Ready [ label="ready to be allocated", color="blue" ]
+    Ready -> Allocated [ label="allocated for use", color="orange" ]
+
+    Creating -> Error [ label="failed to create pod", color="blue" ]
+
+    Scheduled -> Shutdown [ label="SDK.shutdown()", color="purple" ]
+    RequestReady -> Shutdown [ color="purple" ]
+    Ready -> Shutdown [ color="purple" ]
+    Allocated -> Shutdown [ color="purple" ]
+
+    Scheduled -> Unhealthy [ label="failed to call SDK.healthy()\nin a timely manner" ]
+    RequestReady -> Unhealthy [ color="purple" ]
+    Ready -> Unhealthy [ color="purple" ]
+    Allocated -> Unhealthy [ color="purple" ]
+
+    Unhealthy -> Deleted [ label="delete unhealthy game server", color="blue" ]
+    Shutdown -> Deleted [ label="delete finished game server", color="blue" ]
+
+  subgraph cluster_01 {
+    style=invis;
+    {
+        s1 [style="invis"];
+        s2 [style="invis"];
+        s1 -> s2 [ color="red", label="API user" ]
+    }
+
+    {
+        s3 [style="invis"];
+        s4 [style="invis"];
+        s3 -> s4 [ color="purple", label="SDK" ]
+    }
+
+    {
+        s5 [style="invis"];
+        s6 [style="invis"];
+        s5 -> s6 [ color="orange", label="allocation\ncontroller" ]
+    }
+
+    {
+        s7 [style="invis"];
+        s8 [style="invis"];
+        s7 -> s8 [ color="blue", label="game server\ncontroller" ]
+    }
+  }
+}

docs/gameserver_spec.md

@@ -46,3 +46,15 @@ The `spec` field is the actual GameServer specification and it is composed as fo
   - `protocol` the protocol being used. Defaults to UDP. TCP is the only other option.
 - `health` to track the overall healthy state of the GameServer, more information available in the [health check documentation](./health_checking.md).
 - `template` the [pod spec template](https://v1-10.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#podtemplatespec-v1-core) to run your GameServer containers, [see](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/#pod-templates) for more information.
+
+## GameServer State Diagram
+
+The following diagram shows the lifecycle of a `GameServer`. 
+
+Game Servers are created through Kubernetes API (either directly or through a [Fleet](fleet_spec.md)) and their state transitions are orchestrated by:
+
+- GameServer controller, which allocates ports, launches Pods backing game servers and manages their lifetime
+- Allocation controller, which marks game servers as `Allocated` to handle a game session
+- SDK, which manages health checking and shutdown of a game server session
+
+![GameServer State Diagram](gameserver-states.png)