Add new GameServer lifecycle diagrams for Reserved

Shows how the workflow can exist for 1st party/distributed matchmakers.

Work on #660

build/Makefile

@@ -392,18 +392,6 @@ gen-crd-client: $(ensure-build-image)
 	docker run --rm $(common_mounts) -w $(workdir_path) $(build_tag) /root/gen-crd-client.sh
 	docker run --rm $(common_mounts) -w $(workdir_path)/pkg $(build_tag) goimports -w .
 
-site-images: $(site_path)/static/diagrams/gameserver-states.dot.png $(site_path)/static/diagrams/gameserver-lifecycle.puml.png
-
-# generate pngs from dot files
-%.dot.png: %.dot
-	docker run -i --rm $(common_mounts) $(DOCKER_RUN_ARGS) $(build_tag) bash -c \
-	  'dot -Tpng /dev/stdin' < $< > $@.tmp && mv $@.tmp $@
-
-# general pngs from puml files
-%.puml.png: %.puml
-	docker run -i --rm $(common_mounts) $(DOCKER_RUN_ARGS) $(build_tag) bash -c \
-		'plantuml -pipe' < $< > $@
-
 # 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)

build/README.md

@@ -439,6 +439,9 @@ Generate `https://agones.dev` website locally and host on `http://localhost:1313
 #### `make site-test`
 Check the links in website
 
+#### `make site-images`
+Create all the site images from dot and puml diagrams in /site/static/diagrams
+
 #### `make gen-api-docs`
 Generate Agones CRD reference documentation [Agones CRD API reference](../site/content/en/docs/Reference/agones_crd_api_reference.html). Set `feature` shortcode with proper version automatically
 

build/includes/website.mk

@@ -66,6 +66,19 @@ site-test:
 	docker run --rm -t -e "TERM=xterm-256color" $(common_mounts) $(DOCKER_RUN_ARGS) $(build_tag) bash -c \
 		"mkdir -p /tmp/website && cp -r $(mount_path)/site/public /tmp/website/site && htmltest -c $(mount_path)/site/htmltest.yaml /tmp/website"
 
+# generate site images, if they don't exist
+site-images: $(site_path)/static/diagrams/gameserver-states.dot.png $(site_path)/static/diagrams/gameserver-lifecycle.puml.png $(site_path)/static/diagrams/gameserver-reserved.puml.png
+
+# generate pngs from dot files
+%.dot.png: %.dot
+	docker run -i --rm $(common_mounts) $(DOCKER_RUN_ARGS) $(build_tag) bash -c \
+	  'dot -Tpng /dev/stdin' < $< > $@.tmp && mv $@.tmp $@
+
+# general pngs from puml files
+%.puml.png: %.puml
+	docker run -i --rm $(common_mounts) $(DOCKER_RUN_ARGS) $(build_tag) bash -c \
+		'plantuml -pipe' < $< > $@
+
 # Path to a file and docker command
 REL_PATH := content/en/docs/Reference/agones_crd_api_reference.html
 GEN_API_DOCS := docker run -e FILE="$(mount_path)/site/$(REL_PATH)" -e VERSION=${base_version} --rm -i $(common_mounts) $(build_tag) bash -c "/go/src/agones.dev/agones/site/gen-api-docs.sh"

site/content/en/docs/Contribute/_index.md

@@ -66,3 +66,8 @@ or to hide a section from 0.8.0 onward:
 > Due to [this hugo bug](https://github.com/gohugoio/hugo/issues/4695) headers wrapped in this shortcode will
   not be displayed in the Table of Contents. So we will need to actively remove the `feature` shortcode once
   the release versions have been passed for new content, for content that is affected.
+
+## Regenerate Diagrams
+
+To regenerate the [PlantUML](http://plantuml.com/) or [Dot](https://www.graphviz.org/doc/info/lang.html) diagrams,
+delete the .png version of the file in question from `/site/static/diagrams/`, and run `make site-images`.

site/content/en/docs/Guides/gameserver-lifecycle.md

@@ -4,11 +4,31 @@ linkTitle: "GameServer Lifecycle"
 date: 2019-02-01T02:15:18Z
 weight: 15
 description: >
-  Shows the most common life cycle of `GameServer` creation and integration with the SDK, 
+  Common patterns and life cycles of `GameServer` creation and integration with the SDK, 
   when being started and match made.
 ---
 
-![Lifecyle Sequence Diagram](../../../diagrams/gameserver-lifecycle.puml.png)
+## Matchmaker requests a GameServer from a Fleet
+
+This is the preferred workflow for a GameServer, in which an external matchmaker requests an allocation from one or more
+`Fleets` using a `GameServerAllocation`:
+
+![Allocated Lifecyle Sequence Diagram](../../../diagrams/gameserver-lifecycle.puml.png)
+
+{{% feature publishVersion="0.12.0" %}}
+
+## Matchmaker requires game server process registration
+
+Scenarios in which a Matchmaker requires a game server process to register themselves with the matchmaker, and the
+matchmaker decides which `GameServer` players are sent to, this flow is common:
+
+![Reserved Lifecyle Sequence Diagram](../../../diagrams/gameserver-reserved.puml.png)
+
+> This does relinquish control over how `GameServers` are packed across the cluster to the external matchmaker. It is likely
+  it will not do as good a job at packing and scaling as Agones. 
+
+
+{{% /feature %}}
 
 ## Next Steps:
 

site/static/diagrams/gameserver-reserved.puml

@@ -0,0 +1,74 @@
+@startuml
+participant Matchmaker
+participant Agones
+participant "Game Server\nProcess" as Binary
+participant "GameServer\nResource" as GameServer
+participant SDK
+box "Game Server Pod"
+  participant Binary
+  participant SDK
+end box
+
+== GameServer Start ==
+
+Agones -> GameServer: GameServer created through\na <i>Fleet</i> configuration
+activate GameServer
+GameServer -> Binary: Agones creates a Pod with the\nconfigured Game Server Container
+activate Binary
+activate SDK
+Binary -> SDK: SDK.Health()
+note right
+  <i>Health()</i> is a continuous
+  ping that occurs under
+  the configured threshold.
+end note
+GameServer <-- SDK: Maintains Healthy status
+
+== Match Maker Registration ==
+group loop
+Binary -> SDK: SDK.Reserve(duration)
+GameServer <-- SDK: Set state to <i>Reserved</i> for duration
+note right
+  <i>Duration</i> should be longer
+  than how long the matchmaker
+  requires <i>Register()</i> to be
+  available for, so it will not be
+  scaled down
+end note
+Binary -> Matchmaker: Register()
+note right
+  Register with the Matchmaker as
+  available to host a game session
+end note
+note left
+Matchmaker registration
+could occur on a timed loop
+to give each <i>GameServer</i>
+time to be scaled down
+while <i>Ready</i> if not allocated
+end note
+end
+
+
+== Matchmaker allocates GameServer ==
+Matchmaker -> Binary: StartGameSession()
+Binary -> SDK: Allocate()
+note right
+Disables timer to reset <i>Reserved</i> state
+back to <i>Ready</i>
+end note
+SDK --> GameServer: Set state to <i>Allocated</i>
+
+== Players Finish Game ==
+
+Binary -> GameServer: SDK.Shutdown()
+note left
+Once gameplay is complete, call
+<i>Shutdown()</i> to delete the
+<i>GameServer</i> resource and backing Pod.
+end note
+destroy Binary
+destroy SDK
+destroy GameServer
+
+@enduml