Merge pull request #122 from GoogleCloudPlatform/cluster-quickstart

Add cluster creation Quickstart.
googleforgames · Mar 5, 2018 · 51efcc2 · 51efcc2
2 parents 291825b + df40107
commit 51efcc2
Show file tree

Hide file tree

Showing 3 changed files with 218 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -15,23 +15,18 @@ This software is currently alpha, and subject to change. Not to be used in produ
 
 ## Requirements
 - Kubernetes cluster version 1.9+
-    - [Minikube](https://github.com/kubernetes/minikube) and [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) have been tested  
-    - If you are creating and managing your own Kubernetes cluster, the 
-    [MutatingAdmissionWebhook](https://kubernetes.io/docs/admin/admission-controllers/#mutatingadmissionwebhook-beta-in-19) 
-    admission controller is required.  
+    - [Minikube](https://github.com/kubernetes/minikube) and [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) have been tested
+    - If you are creating and managing your own Kubernetes cluster, the
+    [MutatingAdmissionWebhook](https://kubernetes.io/docs/admin/admission-controllers/#mutatingadmissionwebhook-beta-in-19)
+    admission controller is required.
     We also recommend following the
     [recommended set of admission controllers](https://kubernetes.io/docs/admin/admission-controllers/#is-there-a-recommended-set-of-admission-controllers-to-use).
 - Firewall access for the range of ports that Game Servers can be connected to in the cluster.
 - Game Servers must have the [project SDK](sdks) integrated, to manage Game Server state, health checking, etc.
 
 ## Installation
-`kubectl apply -f install.yaml`
 
-If you are running your own Docker repository or want to install a specific version, make a local copy of install.yaml
-and edit to match your settings.
-
-_Note:_ There has yet to be a release of Agones, so you will need to edit the `install.yaml` to specify a 
-development release or [build from source](build/README.md) 
+Follow [these instructions](./docs/installing_agones.md) to create a cluster on Google Kubernetes Engine (GKE) or Minikube, and install Agones.
 
 ## Usage
 
@@ -52,13 +47,13 @@ Documentation and usage guides on how to develop and host dedicated game servers
 - [Full GameServer Configuration](./examples/gameserver.yaml)
 - [Simple UDP](./examples/simple-udp) (Go) - simple server and client that send UDP packets back and forth.
 - [CPP Simple](./examples/cpp-simple) (C++) - C++ example that starts up, stays healthy and then shuts down after 60 seconds.
-- [Xonotic](./examples/xonotic) - Wraps the SDK around the open source FPS game [Xonotic](http://www.xonotic.org) and hosts it on Agones. 
- 
+- [Xonotic](./examples/xonotic) - Wraps the SDK around the open source FPS game [Xonotic](http://www.xonotic.org) and hosts it on Agones.
+
 ## Get involved
 
 - [Slack](https://join.slack.com/t/agones/shared_invite/enQtMzE5NTE0NzkyOTk1LWQ2ZmY1Mjc4ZDQ4NDJhOGYxYTY2NTY0NjUwNjliYzVhMWFjYjMxM2RlMjg3NGU0M2E0YTYzNDIxNDMyZGNjMjU)
 - [Twitter](https://twitter.com/agonesdev)
-- [Mailing List](https://groups.google.com/forum/#!forum/agones-discuss) 
+- [Mailing List](https://groups.google.com/forum/#!forum/agones-discuss)
 
 ## Code of Conduct
 

diff --git a/docs/cloud-shell.png b/docs/cloud-shell.png
diff --git a/docs/installing_agones.md b/docs/installing_agones.md
@@ -0,0 +1,210 @@
+# Install and configure Agones on Kubernetes
+
+In this quickstart, we will create a Kubernetes cluster, and populate it with the resource types that power Agones.
+
+# Table of contents
+
+1. [Setting up a Google Kubernetes Engine (GKE) cluster](#setting-up-a-google-kubernetes-engine-gke-cluster)
+   1. [Before you begin](#before-you-begin)
+   1. [Choosing a shell](#choosing-a-shell)
+      1. [Cloud shell](#cloud-shell)
+      1. [Local shell](#local-shell)
+   1. [Creating the cluster](#creating-the-cluster)
+      1. [Creating the firewall](#creating-the-firewall)
+1. [Setting up a Minikube cluster](#setting-up-a-minikube-cluster)
+   1. [Installing Minikube](#installing-minikube)
+   1. [Creating an agones profile](#creating-an-agones-profile)
+   1. [Starting Minikube](#starting-minikube)
+1. [Enabling creation of RBAC resources](#enabling-creation-of-rbac-resources)
+1. [Installing Agones](#installing-agones)
+   1. [Confirming Agones started successfully](#confirming-agones-started-successfully)
+1. [What's next](#whats-next)
+
+# Setting up a Google Kubernetes Engine (GKE) cluster
+
+Follow these steps to create a cluster and install Agones directly on Google Kubernetes Engine (GKE).
+
+## Before you begin
+
+Take the following steps to enable the Kubernetes Engine API:
+
+1. Visit the [Kubernetes Engine][kubernetes] page in the Google Cloud Platform Console.
+1. Create or select a project.
+1. Wait for the API and related services to be enabled. This can take several minutes.
+1. [Enable billing][billing] for your project.
+   * If you are not an existing GCP user, you may be able to enroll for a $300 US [Free Trial][trial] credit.
+
+[kubernetes]: https://pantheon.corp.google.com/kubernetes/list
+[billing]: https://support.google.com/cloud/answer/6293499#enable-billing
+[trial]: https://cloud.google.com/free/
+
+## Choosing a shell
+
+To complete this quickstart, we can use either [Google Cloud Shell][cloud-shell] or a local shell.
+
+Google Cloud Shell is a shell environment for managing resources hosted on Google Cloud Platform (GCP). Cloud Shell comes preinstalled with the [gcloud][gcloud] and [kubectl][kubectl] command-line tools. `gcloud` provides the primary command-line interface for GCP, and `kubectl` provides the command-line interface for running commands against Kubernetes clusters.
+
+If you prefer using your local shell, you must install the gcloud and kubectl command-line tools in your environment.
+
+[cloud-shell]: https://cloud.google.com/shell/
+[gcloud]: https://cloud.google.com/sdk/gcloud/
+[kubectl]: https://kubernetes.io/docs/user-guide/kubectl-overview/
+
+### Cloud shell
+
+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 **Activate Google Cloud Shell** button: ![cloud shell](/docs/cloud-shell.png?raw=true)
+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].
+   ```bash
+   gcloud config set compute/zone [COMPUTE_ZONE]
+   ```
+
+[cloud]: https://console.cloud.google.com/home/dashboard
+[zones]: https://cloud.google.com/compute/docs/regions-zones/#available
+
+### Local shell
+
+To install `gcloud` and `kubectl`, perform the following steps:
+
+1. [Install the Google Cloud SDK][gcloud-install], which includes the `gcloud` command-line tool.
+1. Initialize some default configuration by running the following command.  
+   * When asked `Do you want to configure a default Compute Region and Zone? (Y/n)?`, enter `Y` and choose a zone in your geographical region of choice.
+   ```bash
+   gcloud init
+   ```
+1. Install the `kubectl` command-line tool by running the following command:
+   ```bash
+   gcloud components install kubectl
+   ```
+
+[gcloud-install]: https://cloud.google.com/sdk/docs/quickstarts
+
+## 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.
+
+```bash
+gcloud container clusters create [CLUSTER_NAME] --cluster-version=1.9.2-gke.1 \
+  --no-enable-legacy-authorization \
+  --tags=game-server \
+  --enable-basic-auth \
+  --password=supersecretpassword \
+  --scopes=https://www.googleapis.com/auth/devstorage.read_only,compute-rw,cloud-platform
+  --num-nodes=3
+  --machine-type=n1-standard-1
+```
+
+Flag explanations:
+
+* cluster-version: Agones requires Kubernetes version 1.9+. Once the default version reaches 1.9, this will no longer be necessary.
+* no-enable-legacy-authorization: This enables RBAC, the authorization scheme used by Agones to control access to resources.
+* 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.
+* enable-basic-auth/password: Sets the master auth scheme for interacting with the cluster.
+* 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: 3
+* machine-type: The type of machine to use for nodes. Default: n1-standard-1.
+
+Finally, let's tell `gcloud` that we are speaking with this cluster, and get auth credentials for `kubectl` to use.
+
+```bash
+gcloud config set container/cluster [CLUSTER_NAME]
+gcloud container clusters get-credentials [CLUSTER_NAME]
+```
+
+[cluster]: https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-architecture
+[vms]: https://cloud.google.com/compute/docs/instances/
+
+### Creating the firewall
+
+We need a firewall to allow UDP traffic to nodes tagged as `game-server` via ports 7000-8000.
+
+```bash
+gcloud compute firewall-rules create game-server-firewall \
+  --allow udp:7000-8000 \
+  --target-tags game-server \
+  --description "Firewall to allow game server udp traffic"
+```
+
+Continue to [Enabling creation of RBAC resources](#enabling-creation-of-rbac-resources)
+
+# Setting up a Minikube cluster
+
+This will setup a [Minikube](https://github.com/kubernetes/minikube) cluster, running on an `agones` profile.
+
+## Installing Minikube
+
+First, [install Minikube][minikube], which may also require you to install
+a virtualisation solution, such as [VirtualBox][vb] as well.
+
+[minikube]: https://github.com/kubernetes/minikube#installation
+[vb]: https://www.virtualbox.org
+
+## Creating an `agones` profile
+
+Let's use a minikube profile for `agones`.
+
+```bash
+minikube profile agones
+```
+
+## Starting Minikube
+
+The following command starts a local minikube cluster via virtualbox.
+
+```bash
+minikube start --kubernetes-version v1.9.0 --vm-driver virtualbox \
+  --extra-config=apiserver.Admission.PluginNames=NamespaceLifecycle,LimitRanger,ServiceAccount,PersistentVolumeLabel,DefaultStorageClass,DefaultTolerationSeconds,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota \
+  --extra-config=apiserver.Authorization.Mode=RBAC
+```
+
+# Enabling creation of RBAC resources
+
+To install Agones, a service account needs permission to create some special RBAC resource types.
+
+```bash
+# Kubernetes Engine
+kubectl create clusterrolebinding cluster-admin-binding \
+  --clusterrole cluster-admin --user `gcloud config get-value account`
+# Minikube
+kubectl create clusterrolebinding cluster-admin-binding \
+  --clusterrole=cluster-admin --serviceaccount=kube-system:default
+```
+
+# Installing Agones
+
+Finally, we install Agones to the cluster.
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/googlecloudplatform/agones/release-0.1/install.yaml
+```
+
+## Confirming Agones started successfully
+
+To confirm Agones is up and running, run the following command:
+
+```bash
+kubectl describe --namespace agones-system pods
+```
+
+It should describe the single pod created in the `agones-system` namespace, with no error messages or status. The `Conditions` section should look like this:
+
+```
+Conditions:
+  Type           Status
+  Initialized    True 
+  Ready          True 
+  PodScheduled   True
+```
+
+That's it! This creates the [Custom Resource Definitions][crds] that power Agones and allows us to define resources of type `GameServer`.
+
+[crds]: https://kubernetes.io/docs/concepts/api-extension/custom-resources/
+
+# What's next
+
+* Go through the [Create a Game Server Quickstart][quickstart]
+
+[quickstart]: /docs/create_gameserver.md