From b2e5354cb34875a44853b47be986697345194fe4 Mon Sep 17 00:00:00 2001 From: Robert Bailey Date: Mon, 19 Apr 2021 21:11:08 +0000 Subject: [PATCH 1/2] Copy of #2047. --- examples/gameserver.yaml | 6 ++++ .../gameserver-windows.yaml | 2 +- site/content/en/docs/Examples/_index.md | 11 +++---- .../docs/Installation/Creating Cluster/gke.md | 32 ++++++++++++++++--- 4 files changed, 39 insertions(+), 12 deletions(-) diff --git a/examples/gameserver.yaml b/examples/gameserver.yaml index fe6cf57318..cbf159ad4d 100644 --- a/examples/gameserver.yaml +++ b/examples/gameserver.yaml @@ -98,3 +98,9 @@ spec: - name: simple-game-server image: gcr.io/agones-images/simple-game-server:0.3 imagePullPolicy: Always + # nodeSelector is a label that can be used to tell Kubernetes which host + # OS to use. For Windows game servers uncomment the nodeSelector + # definition below. + # Details: https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/#ensuring-os-specific-workloads-land-on-the-appropriate-container-host + # nodeSelector: + # kubernetes.io/os: windows diff --git a/examples/simple-game-server/gameserver-windows.yaml b/examples/simple-game-server/gameserver-windows.yaml index 422d6bfc32..4872c59eab 100644 --- a/examples/simple-game-server/gameserver-windows.yaml +++ b/examples/simple-game-server/gameserver-windows.yaml @@ -15,7 +15,7 @@ apiVersion: "agones.dev/v1" kind: GameServer metadata: - generateName: "simple-game-server-" + generateName: "simple-game-server-windows-" spec: ports: - name: default diff --git a/site/content/en/docs/Examples/_index.md b/site/content/en/docs/Examples/_index.md index c2cf50b1c9..89657b55c7 100644 --- a/site/content/en/docs/Examples/_index.md +++ b/site/content/en/docs/Examples/_index.md @@ -10,7 +10,6 @@ weight: 120 These are full examples for each of the resource types of Agones - {{< ghlink href="examples/gameserver.yaml" >}}Full GameServer Configuration{{< /ghlink >}} -- {{< ghlink href="examples/gameserver-windows.yaml" >}}Full GameServer Configuration (for Windows){{< /ghlink >}} - {{< ghlink href="examples/fleet.yaml" >}}Full Fleet Configuration{{< /ghlink >}} - {{< ghlink href="examples/gameserverallocation.yaml" >}}Full GameServer Allocation Configuration{{< /ghlink >}} - {{< ghlink href="examples/fleetautoscaler.yaml" >}}Full Autoscaler Configuration with Buffer Strategy{{< /ghlink >}} @@ -19,11 +18,11 @@ These are full examples for each of the resource types of Agones ## Game server implementations -These are all examples of simple game server implementations, that integrate the Agones game server SDK. +These are all examples of simple game server implementations, that integrate the Agones game server SDK. -* {{< ghlink href="examples/simple-game-server" >}}Simple gameserver{{< /ghlink >}} (Go) - simple server that +* {{< ghlink href="examples/simple-game-server" >}}Simple gameserver{{< /ghlink >}} (Go) - simple server that responds to TCP connections or UDP packets on the same port. -* {{< ghlink href="examples/cpp-simple" >}}CPP Simple{{< /ghlink >}} (C++) - C++ example that starts up, stays +* {{< ghlink href="examples/cpp-simple" >}}CPP Simple{{< /ghlink >}} (C++) - C++ example that starts up, stays healthy and then shuts down after 60 seconds. * {{< ghlink href="examples/nodejs-simple" >}}Node.js Simple{{< /ghlink >}} (Node.js) - A simple Node.js example that marks itself as ready, sets some labels and then shutsdown. @@ -31,13 +30,13 @@ These are all examples of simple game server implementations, that integrate the A simple Rust example that marks itself as ready, sets some labels and then shutsdown. * {{< ghlink href="examples/unity-simple" >}}Unity Simple{{< /ghlink >}} (Unity3d) - This is a very simple "unity server" that doesn't do much other than show how the SDK works in Unity. -* {{< ghlink href="examples/xonotic" >}}Xonotic{{< /ghlink >}} - Wraps the SDK around the open source FPS game +* {{< ghlink href="examples/xonotic" >}}Xonotic{{< /ghlink >}} - Wraps the SDK around the open source FPS game [Xonotic](http://www.xonotic.org) and hosts it on Agones. * {{< ghlink href="examples/supertuxkart" >}}SuperTuxKart{{< /ghlink >}} \- Wraps the SDK around the open source racing game [SuperTuxKart](https://supertuxkart.net/), and hosts it on Agones. ## Building on top of Agones -- {{< ghlink href="examples/crd-client" >}}Agones API Usage Example{{< /ghlink >}} (Go) - +- {{< ghlink href="examples/crd-client" >}}Agones API Usage Example{{< /ghlink >}} (Go) - This service provides an example of using the [Agones API](https://pkg.go.dev/agones.dev/agones/pkg/client/clientset/versioned/typed/agones/v1) to create a GameServer. diff --git a/site/content/en/docs/Installation/Creating Cluster/gke.md b/site/content/en/docs/Installation/Creating Cluster/gke.md index c837d24c25..43ff83552e 100644 --- a/site/content/en/docs/Installation/Creating Cluster/gke.md +++ b/site/content/en/docs/Installation/Creating Cluster/gke.md @@ -38,7 +38,7 @@ If you prefer using your local shell, you must install the gcloud and kubectl co To launch Cloud Shell, perform the following steps: 1. Go to [Google Cloud Platform Console][cloud] -1. From the top-right corner of the console, click the +1. From the top-right corner of the console, click the **Activate Google Cloud Shell** button: ![cloud shell](../../../../images/cloud-shell.png) 1. A Cloud Shell session opens inside a frame at the bottom of the console. Use this shell to run `gcloud` and `kubectl` commands. 1. Set a compute zone in your geographical region with the following command. The compute zone will be something like `us-west1-a`. A full list can be found [here][zones]. @@ -89,6 +89,10 @@ gcloud container clusters create [CLUSTER_NAME] --cluster-version={{% k8s-versio --no-enable-autoupgrade \ --machine-type=e2-standard-4 ``` + +{{< alert title="Note" color="info">}} +If you're creating a cluster to run Windows game servers you'll also need to add `--enable-ip-alias`. +{{< /alert >}} {{% /feature %}} Flag explanations: @@ -99,6 +103,9 @@ Flag explanations: * num-nodes: The number of nodes to be created in each of the cluster's zones. Default: 4. Depending on the needs of your game, this parameter should be adjusted. * no-enable-autoupgrade: Disable automatic upgrades for nodes to reduce the likelihood of in-use games being disrupted. * machine-type: The type of machine to use for nodes. Default: e2-standard-4. Depending on the needs of your game, you may wish to [have smaller or larger machines](https://cloud.google.com/compute/docs/machine-types). +{{% feature publishVersion="1.14.0" %}} +* enable-ip-alias: Use [Alias IP ranges](https://cloud.google.com/vpc/docs/alias-ip) instead of routes based networking. This is required to create windows node pools. +{{% /feature %}} _Optional_: Create a dedicated node pool for the Agones controllers. If you choose to skip this step, the Agones controllers will share the default node pool with your game servers which is fine for kicking the tires but is not @@ -133,6 +140,21 @@ Flag explanations: * node-labels: The Kubernetes labels to automatically apply to nodes in this node pool. * num-nodes: The Agones system controllers only require a single node of capacity to run. For faster recovery time in the event of a node failure, you can increase the size to 2. +{{% feature publishVersion="1.14.0" %}} +_Optional_: Create a dedicated Windows node pool for game servers. If you need to run game servers on Windows you'll +need to create a dedicated node pool for it. Windows Server 2019 (`WINDOWS_LTSC`) is the recommended image for Windows +game servers. + +```bash +gcloud container node-pools create windows \ + --cluster=[CLUSTER_NAME] \ + --no-enable-autoupgrade \ + --image-type WINDOWS_LTSC \ + --machine-type e2-standard-4 \ + --num-nodes=4 +``` +{{% /feature %}} + Finally, let's tell `gcloud` that we are speaking with this cluster, and get auth credentials for `kubectl` to use. ```bash @@ -155,14 +177,14 @@ gcloud compute firewall-rules create game-server-firewall \ ``` {{< alert title="Note" color="info">}} -Before planning your production GKE infrastructure, it is worth reviewing the +Before planning your production GKE infrastructure, it is worth reviewing the [different types of GKE clusters that can be created](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters), such as Zonal or Regional, as each has different reliability and cost values, and ensuring this aligns with your -Service Level Objectives or Agreements. +Service Level Objectives or Agreements. -This is particularly true for GKE masters, which can go down temporarily to adjust for cluster resizing, +This is particularly true for a zonal GKE control plane, which can go down temporarily to adjust for cluster resizing, [automatic upgrades](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-upgrades) and -[repairs](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions#repairs). +[repairs](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions#repairs). {{< /alert >}} ## Next Steps From cd8d01f42859b192c38bb2cee9ea51971fc483f4 Mon Sep 17 00:00:00 2001 From: Robert Bailey Date: Tue, 20 Apr 2021 07:27:56 +0000 Subject: [PATCH 2/2] Add a Guide for running windows game servers. Refactor some common prerequisites into a shortcode. --- .../en/docs/Getting Started/create-fleet.md | 11 +- .../docs/Getting Started/create-gameserver.md | 18 +--- .../en/docs/Guides/windows-gameservers.md | 102 ++++++++++++++++++ .../docs/Installation/Creating Cluster/gke.md | 16 ++- site/content/en/docs/Reference/gameserver.md | 6 ++ site/layouts/shortcodes/gs-prerequisites.html | 14 +++ 6 files changed, 143 insertions(+), 24 deletions(-) create mode 100644 site/content/en/docs/Guides/windows-gameservers.md create mode 100644 site/layouts/shortcodes/gs-prerequisites.html diff --git a/site/content/en/docs/Getting Started/create-fleet.md b/site/content/en/docs/Getting Started/create-fleet.md index 6a3601ae02..35f893e36b 100644 --- a/site/content/en/docs/Getting Started/create-fleet.md +++ b/site/content/en/docs/Getting Started/create-fleet.md @@ -9,16 +9,7 @@ description: > ## Prerequisites -The following prerequisites are required to create a GameServer: - -1. A Kubernetes cluster with the UDP port range 7000-8000 open on each node. -2. Agones controller installed in the targeted cluster -3. kubectl properly configured -4. Netcat which is already installed on most Linux/macOS distributions, for windows you can use [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10). - -If you don't have a Kubernetes cluster you can follow [these instructions]({{< ref "/docs/Installation/_index.md" >}}) to create a cluster on Google Kubernetes Engine (GKE), Minikube or Azure Kubernetes Service (AKS), and install Agones. - -For the purpose of this guide we're going to use the {{< ghlink href="examples/simple-game-server/" >}}simple-game-server{{< /ghlink >}} example as the GameServer container. This example is a very simple UDP server written in Go. Don't hesitate to look at the code of this example for more information. +{{< gs-prerequisites >}} While not required, you may wish to go through the [Create a Game Server]({{< relref "create-gameserver.md" >}}) quickstart before this one. diff --git a/site/content/en/docs/Getting Started/create-gameserver.md b/site/content/en/docs/Getting Started/create-gameserver.md index ff718a4bbe..b4ff9f1002 100644 --- a/site/content/en/docs/Getting Started/create-gameserver.md +++ b/site/content/en/docs/Getting Started/create-gameserver.md @@ -4,27 +4,19 @@ linkTitle: "Create a Game Server" date: 2019-01-02T06:35:31Z weight: 10 description: > - This guide covers how you can quickly get started using Agones to create GameServers. + This guide covers how you can quickly get started using Agones to create GameServers. --- +## Prerequisites + +{{< gs-prerequisites >}} + ## Objectives - Create a GameServer in Kubernetes using Agones custom resource. - Get information about the GameServer such as IP address, port and state. - Connect to the GameServer. -## Prerequisites - -The following prerequisites are required to create a GameServer : - -1. A Kubernetes cluster with the UDP port range 7000-8000 open on each node. -2. Agones controller installed in the targeted cluster -3. kubectl properly configured -4. Netcat which is already installed on most Linux/macOS distributions, for windows you can use [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10). - -If you don't have a Kubernetes cluster you can follow [these instructions]({{< ref "/docs/Installation/_index.md" >}}) to create a cluster on Google Kubernetes Engine (GKE), Minikube or Azure Kubernetes Service (AKS), and install Agones. - -For the purpose of this guide we're going to use the {{< ghlink href="examples/simple-game-server/" >}}simple-game-server{{< /ghlink >}} example as the GameServer container. This example is a very simple UDP server written in Go. Don't hesitate to look at the code of this example for more information. ### 1. Create a GameServer diff --git a/site/content/en/docs/Guides/windows-gameservers.md b/site/content/en/docs/Guides/windows-gameservers.md new file mode 100644 index 0000000000..f839040d6d --- /dev/null +++ b/site/content/en/docs/Guides/windows-gameservers.md @@ -0,0 +1,102 @@ +--- +title: "Windows Gameservers" +date: 2021-04-19T21:14:19Z +publishDate: 2021-04-27T23:00:00Z +weight: 20 +description: > + Run `GameServers` on Kubernetes nodes with the Windows operating system. +--- + +{{< alert title="Warning" color="warning">}} +Running `GameServers` on Windows nodes is currently Alpha, and any feedback +would be appreciated. +{{< /alert >}} + +## Prerequisites + +{{< gs-prerequisites >}} + +Ensure that you have some nodes to your cluster that are running Windows. + +## Objectives + +- Create a GameServer on a Windows node. +- Connect to the GameServer. + +### 1. Create a GameServer + +{{< alert title="Note" color="info">}} +Starting with version 0.3, the {{< ghlink href="examples/simple-game-server/" >}}simple-game-server{{< /ghlink >}} example is compiled as a multi-arch docker image that will run on both Linux and Windows. To ensure that the game server runs on a Windows node, a nodeSelector of `"kubernetes.io/os": windows` must be added to the game server specification. +{{< /alert >}} + +Create a GameServer using the following command: + +``` +kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/{{< release-branch >}}/examples/simple-game-server/gameserver-windows.yaml +``` + +You should see a successful output similar to this: + +``` +gameserver.agones.dev/simple-game-server-4ss4j created +``` + +Verify that the GameServer becomes Ready by running: + +``` +kubectl get gameservers +``` +It should look something like this: + +``` +NAME STATE ADDRESS PORT NODE AGE +simple-game-server-7pjrq Ready 35.233.183.43 7190 agones 3m +``` + +Take a note of the Game Server IP address and ports. + +For the full details of the YAML file head to the [GameServer Specification Guide]({{< ref "/docs/Reference/gameserver.md" >}}) + + +### 2. Connect to the GameServer + +{{< alert title="Note" color="info">}} +If you have Agones installed on Google Kubernetes Engine, and are using + Cloud Shell for your terminal, UDP is blocked. For this step, we recommend + SSH'ing into a running VM in your project, such as a Kubernetes node. + You can click the 'SSH' button on the [Google Compute Engine Instances](https://console.cloud.google.com/compute/instances) + page to do this. + Run `toolbox` on GKE Node to run docker container with tools and then `nc` command would be available. +{{< /alert >}} + +You can now communicate with the Game Server: + +{{< alert title="Note" color="info">}} +If you do not have netcat installed + (i.e. you get a response of `nc: command not found`), + you can install netcat by running `sudo apt install netcat`. + +If you are on Windows, you can alternatively install netcat on +[WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), +or download a version of netcat for Windows from [nmap.org](https://nmap.org/ncat/). +{{< /alert >}} + +``` +nc -u {IP} {PORT} +Hello World ! +ACK: Hello World ! +EXIT +``` + +You can finally type `EXIT` which tells the SDK to run the [Shutdown command]({{< ref "/docs/Guides/Client SDKs/_index.md#shutdown" >}}), and therefore shuts down the `GameServer`. + +If you run `kubectl describe gameserver` again - either the GameServer will be gone completely, or it will be in `Shutdown` state, on the way to being deleted. + + +## Next Steps + +- Make a local copy of the simple-game-server {{< ghlink href="examples/simple-game-server/fleet.yaml" >}}fleet configuration{{< /ghlink >}}, +modify it to include a node selector, and use it to go through the [Quickstart: Create a Game Server Fleet]({{< ref "/docs/Getting Started/create-fleet.md" >}}). +- If you want to use your own GameServer container make sure you have properly integrated the [Agones SDK]({{< ref "/docs/Guides/Client SDKs/_index.md" >}}). + + diff --git a/site/content/en/docs/Installation/Creating Cluster/gke.md b/site/content/en/docs/Installation/Creating Cluster/gke.md index 43ff83552e..b848716601 100644 --- a/site/content/en/docs/Installation/Creating Cluster/gke.md +++ b/site/content/en/docs/Installation/Creating Cluster/gke.md @@ -68,7 +68,7 @@ To install `gcloud` and `kubectl`, perform the following steps: ## Creating the cluster -A [cluster][cluster] consists of at least one *cluster master* machine and multiple worker machines called *nodes*: [Compute Engine virtual machine][vms] instances that run the Kubernetes processes necessary to make them part of the cluster. +A [cluster][cluster] consists of at least one *control plane* machine and multiple worker machines called *nodes*: [Compute Engine virtual machine][vms] instances that run the Kubernetes processes necessary to make them part of the cluster. {{% feature expiryVersion="0.14.0" %}} ```bash @@ -97,13 +97,22 @@ If you're creating a cluster to run Windows game servers you'll also need to add Flag explanations: +{{% feature expiryVersion="0.14.0" %}} * cluster-version: Agones requires Kubernetes version {{% k8s-version %}}. * tags: Defines the tags that will be attached to new nodes in the cluster. This is to grant access through ports via the firewall created in the next step. * scopes: Defines the Oauth scopes required by the nodes. * num-nodes: The number of nodes to be created in each of the cluster's zones. Default: 4. Depending on the needs of your game, this parameter should be adjusted. * no-enable-autoupgrade: Disable automatic upgrades for nodes to reduce the likelihood of in-use games being disrupted. * machine-type: The type of machine to use for nodes. Default: e2-standard-4. Depending on the needs of your game, you may wish to [have smaller or larger machines](https://cloud.google.com/compute/docs/machine-types). +{{% /feature %}} + {{% feature publishVersion="1.14.0" %}} +* cluster-version: Agones requires Kubernetes version {{% k8s-version %}}. +* tags: Defines the tags that will be attached to new nodes in the cluster. This is to grant access through ports via the firewall created in the next step. +* scopes: Defines the Oauth scopes required by the nodes. +* num-nodes: The number of nodes to be created in each of the cluster's zones. Default: 4. Depending on the needs of your game, this parameter should be adjusted. +* no-enable-autoupgrade: Disable automatic upgrades for nodes to reduce the likelihood of in-use games being disrupted. +* machine-type: The type of machine to use for nodes. Default: e2-standard-4. Depending on the needs of your game, you may wish to [have smaller or larger machines](https://cloud.google.com/compute/docs/machine-types). * enable-ip-alias: Use [Alias IP ranges](https://cloud.google.com/vpc/docs/alias-ip) instead of routes based networking. This is required to create windows node pools. {{% /feature %}} @@ -145,6 +154,11 @@ _Optional_: Create a dedicated Windows node pool for game servers. If you need t need to create a dedicated node pool for it. Windows Server 2019 (`WINDOWS_LTSC`) is the recommended image for Windows game servers. +{{< alert title="Warning" color="warning">}} +Running `GameServers` on Windows nodes is currently Alpha, and any feedback +would be appreciated. +{{< /alert >}} + ```bash gcloud container node-pools create windows \ --cluster=[CLUSTER_NAME] \ diff --git a/site/content/en/docs/Reference/gameserver.md b/site/content/en/docs/Reference/gameserver.md index 672aee7e06..a54cb92970 100644 --- a/site/content/en/docs/Reference/gameserver.md +++ b/site/content/en/docs/Reference/gameserver.md @@ -89,6 +89,12 @@ spec: - name: simple-game-server image: {{< example-image >}} imagePullPolicy: Always + # nodeSelector is a label that can be used to tell Kubernetes which host + # OS to use. For Windows game servers uncomment the nodeSelector + # definition below. + # Details: https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/#ensuring-os-specific-workloads-land-on-the-appropriate-container-host + # nodeSelector: + # kubernetes.io/os: windows ``` Since Agones defines a new [Custom Resources Definition (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources/) we can define a new resource using the kind `GameServer` with the custom group `agones.dev` and API version `v1`. diff --git a/site/layouts/shortcodes/gs-prerequisites.html b/site/layouts/shortcodes/gs-prerequisites.html new file mode 100644 index 0000000000..b7207ae871 --- /dev/null +++ b/site/layouts/shortcodes/gs-prerequisites.html @@ -0,0 +1,14 @@ +{{- $branch := .Get "branch" | default (getenv "RELEASE_BRANCH") | default $.Page.Site.Params.release_branch }} +{{- $test := eq (.Get "link_test") "true" | default true }} +

The following prerequisites are required to create a GameServer:

+
    +
  1. A Kubernetes cluster with the UDP port range 7000-8000 open on each node.
    2. +
  2. Agones controller installed in the targeted cluster
    3. +
  3. kubectl properly configured
    4. +
  4. Netcat which is already installed on most Linux/macOS distributions, for windows you can use WSL.
    5. +
+

If you don’t have a Kubernetes cluster you can follow these instructions to create a cluster on Google Kubernetes Engine (GKE), Minikube or Azure Kubernetes Service (AKS), and install Agones.

+

For the purpose of this guide we’re going to use the +simple-game-server + example as the GameServer container. This example is a very simple UDP server written in Go. Don’t hesitate to look at the code of this example for more information.

+