Permalink
Browse files

docs: added game server state diagram

  • Loading branch information...
jkowalski authored and markmandel committed Jan 8, 2019
1 parent 1651726 commit c39f6935fd33a6b58852f24007bde771177bb832
Showing with 90 additions and 0 deletions.
  1. +7 −0 build/Makefile
  2. +71 −0 docs/gameserver-states.dot
  3. BIN docs/gameserver-states.png
  4. +12 −0 docs/gameserver_spec.md
@@ -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' < $< > $@.tmp && mv $@.tmp $@

# 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)
@@ -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" ]
}
}
}
Binary file not shown.
@@ -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)

0 comments on commit c39f693

Please sign in to comment.