diff --git a/examples/rust-simple/Makefile b/examples/rust-simple/Makefile index 9808965704..518e8e6c42 100644 --- a/examples/rust-simple/Makefile +++ b/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 # _____ _ # |_ _|_ _ _ __ __ _ ___| |_ ___ diff --git a/examples/rust-simple/README.md b/examples/rust-simple/README.md index 6f57dd785b..505d62b1f2 100644 --- a/examples/rust-simple/README.md +++ b/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 ``` diff --git a/examples/rust-simple/gameserver.yaml b/examples/rust-simple/gameserver.yaml index ca99e7d713..2986392091 100644 --- a/examples/rust-simple/gameserver.yaml +++ b/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 diff --git a/site/content/en/docs/Tutorials/simple-gameserver-cpp.md b/site/content/en/docs/Tutorials/simple-gameserver-cpp.md index 77a8c04fc0..e82cc778ac 100644 --- a/site/content/en/docs/Tutorials/simple-gameserver-cpp.md +++ b/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 diff --git a/site/content/en/docs/Tutorials/simple-gameserver-nodejs.md b/site/content/en/docs/Tutorials/simple-gameserver-nodejs.md index b84f09fe14..15bd48c18a 100644 --- a/site/content/en/docs/Tutorials/simple-gameserver-nodejs.md +++ b/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 diff --git a/site/content/en/docs/Tutorials/simple-gameserver-rust.md b/site/content/en/docs/Tutorials/simple-gameserver-rust.md new file mode 100644 index 0000000000..4743a42331 --- /dev/null +++ b/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= # 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} +```