Updates to the rust simple example. (#937)

examples/rust-simple/Makefile

@@ -23,9 +23,11 @@
 #     \_/ \__,_|_|  |_|\__,_|_.__/|_|\___|___/
 #
 
+REPOSITORY ?= gcr.io/agones-images
+
 mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))
 project_path := $(dir $(mkfile_path))
-server_tag = rust-simple-server:0.2
+server_tag = $(REPOSITORY)/rust-simple-server:0.4
 
 #   _____                    _
 #  |_   _|_ _ _ __ __ _  ___| |_ ___

examples/rust-simple/README.md

@@ -8,62 +8,36 @@ It will
 - Every 10 seconds, write a log saying "Hi! I'm a Game Server"
 - After 60 seconds, call `SDK::Shutdown()` to shut the server down.
 
-## Running locally (without Docker)
+To learn how to deploy this example service to GKE, please see the tutorial [Build and Run a Simple Gameserver (Rust)](https://agones.dev/site/docs/tutorials/simple-gameserver-rust/).
 
-This will build example server which will run for 100 seconds:
-```
-make build
-```
+## Building
 
-In a separate terminal run next command:
-```
-cd ../../build; make run-sdk-conformance-local TIMEOUT=120 TESTS=ready,watch,health,gameserver
-```
-This will start an SDK-server in a docker, which will be running for 120 seconds.
+If you have a local rust developer environment installed locally, you can run `make build` to compile the code and
+`make run` to execute the resulting binary.
 
-Run the Rust Simple Gameserver binary:
-```
-make run
-```
+If you want to build an updated container image or want to build the source code without installing the rust developer
+tools locally, run `make build-image` to run the `docker build` command with the correct context.
 
-You will see the following output:
-```
-Rust Game Server has started!
-Creating SDK instance
-Setting a label
-Starting to watch GameServer updates...
-Health ping sent
-Setting an annotation
-...
-```
+This example uses the [Docker builder pattern](https://docs.docker.com/develop/develop-images/multistage-build/) to
+build the SDK, example and host it inside a container.
 
-Clean the resulting `sdk` directory and `target` folder:
-```
-make clean
-```
-
-
-## Running locally with Docker
-
-Build the container locally:
-```
-make build-image
-```
+## Testing locally with Docker
 
-In a separate terminal run next command:
-```
-cd ../../build; make run-sdk-conformance-local TIMEOUT=120 TESTS=ready,watch,health,gameserver
+If you want to run the example locally, you need to start an instance of the SDK-server. To run an SDK-server for
+120 seconds, run
+```bash
+$ cd ../../build; make run-sdk-conformance-local TIMEOUT=120 TESTS=ready,watch,health,gameserver
 ```
-This will start an SDK-server in a docker, which will be running for 120 seconds.
 
-Run next make targets:
-```
-make run-image
+In a separate terminal, while the SDK-server is still running, build and start a container with the example gameserver:
+```bash
+$ make build-image
+$ make run-image
 ```
 
 You will see the following output:
 ```
-docker run --network=host rust-simple-server:0.2
+docker run --network=host gcr.io/agones-images/rust-simple-server:0.4
 Rust Game Server has started!
 Creating SDK instance
 Setting a label
@@ -83,32 +57,38 @@ Health ping sent
 Health ping sent
 Running for 10 seconds
 ```
-Clean the resulting `sdk` directory:
+
+When you are finished, clean up the `sdk` directory:
 ```
 make clean-docker
 ```
 
-## Running by minikube
-
-First of all, you have to configure Agones on minikube. Check out [these instructions](https://agones.dev/site/docs/installation/#setting-up-a-minikube-cluster).
+## Testing locally (without Docker)
 
-```
-$ eval $(minikube docker-env)
-$ make build-image
-$ kubectl create -f gameserver.yaml
+If you want to run the example locally, you need to start an instance of the SDK-server. To run an SDK-server for
+120 seconds, run
+```bash
+$ cd ../../build; make run-sdk-conformance-local TIMEOUT=120 TESTS=ready,watch,health,gameserver
 ```
 
-You can see output of the example by the following.
+In a separate terminal, while the SDK-server is still running, build and execute the example gameserver:
+```bash
+$ make build
+$ make run
+```
 
+You will see the following output:
 ```
-$ POD_NAME=`kubectl get pods -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}'`
-$ kubectl logs $POD_NAME -c rust-simple
 Rust Game Server has started!
 Creating SDK instance
-Marking server as ready...
-Running for 0 seconds
-Health ping sent
-Health ping sent
-Health ping sent
+Setting a label
+Starting to watch GameServer updates...
 Health ping sent
+Setting an annotation
+...
+```
+
+When you are finished, clean up the `sdk` directory and `target` folder:
+```
+make clean
 ```

examples/rust-simple/gameserver.yaml

@@ -26,5 +26,5 @@ spec:
     spec:
       containers:
       - name: rust-simple
-        image: gcr.io/agones-images/rust-simple-server:0.2
-        imagePullPolicy: IfNotPresent
+        image: gcr.io/agones-images/rust-simple-server:0.4
+        imagePullPolicy: Always

site/content/en/docs/Tutorials/simple-gameserver-cpp.md

@@ -37,7 +37,7 @@ $ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{
 ```
 
 The game server sets up the Agones SDK, calls `SDK::Ready()` to inform Agones that it is ready to serve traffic,
-prints a message every 10 seconds, and then calls `SDK::Shutdown()` after a minute indicate that the gameserver
+prints a message every 10 seconds, and then calls `SDK::Shutdown()` after a minute to indicate that the gameserver
 is going to exit.
 
 You can follow along with the lifecycle of the gameserver by running

site/content/en/docs/Tutorials/simple-gameserver-nodejs.md

@@ -37,7 +37,7 @@ $ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{
 ```
 
 The game server sets up the Agones SDK, calls `sdk.ready()` to inform Agones that it is ready to serve traffic,
-prints a message every 10 seconds, and then calls `sdk.shutdown()` after a minute indicate that the gameserver
+prints a message every 10 seconds, and then calls `sdk.shutdown()` after a minute to indicate that the gameserver
 is going to exit.
 
 You can follow along with the lifecycle of the gameserver by running

site/content/en/docs/Tutorials/simple-gameserver-rust.md

@@ -0,0 +1,203 @@
+---
+title: "Tutorial Build and Run a Simple Gameserver (Rust)"
+linkTitle: "Build and Run a Simple Gameserver (Rust)"
+date: 2019-07-30T07:47:45Z
+publishDate: 2019-08-01T10:00:00Z
+description: >
+  This tutorial describes how to use the Agones Rust SDK in a simple Rust gameserver.
+---
+
+## Objectives
+- Run a simple gameserver
+- Understand how the simple gameserver uses the Agones Rust SDK
+- Build a customized version of the simple gameserver
+- Run your customized simple gameserver
+
+## Prerequisites
+1. [Docker](https://www.docker.com/get-started/)
+2. Agones installed on GKE
+3. kubectl properly configured
+4. A local copy of the [Agones repository](https://github.com/googleforgames/agones/tree/{{< release-branch >}})
+5. A repository for Docker images, such as [Docker Hub](https://hub.docker.com/) or [GC Container Registry](https://cloud.google.com/container-registry/)
+
+To install on GKE, follow the install instructions (if you haven't already) at
+[Setting up a Google Kubernetes Engine (GKE) cluster]({{< relref "../Installation/_index.md#setting-up-a-google-kubernetes-engine-gke-cluster" >}}).
+Also complete the "Installing Agones" instructions on the same page.
+
+While not required, you may wish to review the [Create a Game Server]({{< relref "../Getting Started/create-gameserver.md" >}}),
+[Create a Game Server Fleet]({{< relref "../Getting Started/create-fleet.md" >}}), and/or [Edit a Game Server]({{< relref "../Getting Started/edit-first-gameserver-go.md" >}}) quickstarts.
+
+### 1. Run the simple gameserver
+
+First, run the pre-built version of the simple gameserver and take note of the name that was created:
+
+```bash
+$ kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/{{< release-branch >}}/examples/rust-simple/gameserver.yaml
+$ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')
+```
+
+The game server sets up the Agones SDK, calls `sdk.ready()` to inform Agones that it is ready to serve traffic,
+prints a message every 10 seconds, and then calls `sdk.shutdown()` after a minute to indicate that the gameserver
+is going to exit.
+
+You can follow along with the lifecycle of the gameserver by running
+
+```bash
+$ kubectl logs ${GAMESERVER_NAME} rust-simple -f
+```
+
+which should produce output similar to
+```
+Rust Game Server has started!
+Creating SDK instance
+Setting a label
+Starting to watch GameServer updates...
+Health ping sent
+Setting an annotation
+Marking server as ready...
+...marked Ready
+Getting GameServer details...
+GameServer name: rust-simple-txsc6
+Running for 0 seconds
+GameServer Update, name: rust-simple-txsc6
+GameServer Update, state: Scheduled
+GameServer Update, name: rust-simple-txsc6
+GameServer Update, state: Scheduled
+GameServer Update, name: rust-simple-txsc6
+GameServer Update, state: RequestReady
+GameServer Update, name: rust-simple-txsc6
+GameServer Update, state: Ready
+Health ping sent
+Health ping sent
+Health ping sent
+Health ping sent
+Health ping sent
+Running for 10 seconds
+GameServer Update, name: rust-simple-txsc6
+GameServer Update, state: Ready
+...
+Shutting down after 60 seconds...
+...marked for Shutdown
+Running for 60 seconds
+Health ping sent
+GameServer Update, name: rust-simple-txsc6
+GameServer Update, state: Shutdown
+GameServer Update, name: rust-simple-txsc6
+GameServer Update, state: Shutdown
+...
+```
+
+If everything goes as expected, the gameserver will exit automatically after about a minute. 
+
+In some cases, the gameserver goes into an unhealthy state, in which case it will be restarted indefinitely. 
+If this happens, you can manually remove it by running
+```bash
+$ kubectl delete gs ${GAMESERVER_NAME}
+```
+
+### 2. Build a simple gameserver
+
+Change directories to your local agones/examples/rust-simple directory. To experiment with the SDK, open up `main.rs`
+in your favorite editor and change the interval at which the gameserver calls `sdk.health()` from 2 seconds to 20
+seconds by modifying the line in the thread assigned to `let _health` to be
+
+```rust
+thread::sleep(Duration::from_secs(20));
+```
+
+Next build a new docker image by running
+```bash
+$ cd examples/rust-simple
+$ REPOSITORY=<your-repository> # e.g. gcr.io/agones-images
+$ make build-image REPOSITORY=${REPOSITORY}
+```
+
+The multi-stage Dockerfile will pull down all of the dependencies needed to build the image. Note that it is normal
+for this to take several minutes to complete.
+
+Once the container has been built, push it to your repository
+```bash
+$ docker push ${REPOSITORY}/rust-simple-server:0.4
+```
+
+### 3. Run the customized gameserver
+
+Now it is time to deploy your newly created gameserver container into your Agones cluster. 
+
+First, you need to edit `examples/rust-simple/gameserver.yaml` to point to your new image:
+
+```
+containers:
+- name: rust-simple
+  image: $(REPOSITORY)/rust-simple-server:0.4
+  imagePullPolicy: Always
+```
+
+Then, deploy your gameserver
+
+```bash
+$ kubectl create -f gameserver.yaml
+$ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')
+```
+
+Again, follow along with the lifecycle of the gameserver by running
+
+```bash
+$ kubectl logs ${GAMESERVER_NAME} rust-simple -f
+```
+
+which should produce output similar to
+
+```
+Rust Game Server has started!
+Creating SDK instance
+Setting a label
+Starting to watch GameServer updates...
+Health ping sent
+Setting an annotation
+Marking server as ready...
+...marked Ready
+Getting GameServer details...
+GameServer name: rust-simple-z6lz8
+Running for 0 seconds
+GameServer Update, name: rust-simple-z6lz8
+GameServer Update, state: Scheduled
+GameServer Update, name: rust-simple-z6lz8
+GameServer Update, state: RequestReady
+GameServer Update, name: rust-simple-z6lz8
+GameServer Update, state: RequestReady
+GameServer Update, name: rust-simple-z6lz8
+GameServer Update, state: Ready
+Running for 10 seconds
+GameServer Update, name: rust-simple-z6lz8
+GameServer Update, state: Ready
+GameServer Update, name: rust-simple-z6lz8
+GameServer Update, state: Unhealthy
+Health ping sent
+Running for 20 seconds
+Running for 30 seconds
+Health ping sent
+Running for 40 seconds
+GameServer Update, name: rust-simple-z6lz8
+GameServer Update, state: Unhealthy
+Running for 50 seconds
+Health ping sent
+Shutting down after 60 seconds...
+...marked for Shutdown
+Running for 60 seconds
+Running for 70 seconds
+GameServer Update, name: rust-simple-z6lz8
+GameServer Update, state: Unhealthy
+Health ping sent
+Running for 80 seconds
+Running for 90 seconds
+Health ping sent
+Rust Game Server finished.
+```
+
+with the slower healthcheck interval, the gameserver gets automatically marked an `Unhealthy` by Agones. 
+
+To finish, clean up the gameserver by manually removing it
+```bash
+$ kubectl delete gs ${GAMESERVER_NAME}
+```