Add cluster creation Quickstart. #122

dzlier-gcp · 2018-02-28T23:00:14Z

Closes #93

markmandel

This is a great start, but I think it would be better as a series of gcloud steps, rather than using deployment manager - I think it will feel closer to what our users are actually likely to do. Deployment manager is a tad niche to be honest.

Also need a section on Minikube.

Let me know your thoughts on my review comments.

markmandel · 2018-02-28T23:56:47Z

examples/cluster/README.md

@@ -0,0 +1,84 @@
+# Creating a Kubernetes Cluster Quickstart


I feel like we want a better title for this - because we are both creating a cluster, and installing Agones

"Install and Configure Agones on Kubernetes Quickstart" ?

markmandel · 2018-02-28T23:59:38Z

examples/cluster/README.md

@@ -0,0 +1,84 @@
+# Creating a Kubernetes Cluster Quickstart
+
+In this quickstart, we will create a Kubernetes cluster, and populate it with the CRD's ([Custom Resource Definitions][crd]), service accounts, and [RBAC][rbac] roles and bindings that power Agones.


I don't think we need to mention CRD's - and if we do, we should use the full name, at least the first time.

"In this quickstart we will create a Kubernetes cluster and install Agones"
^ removed references to the technical Kubernetes terms until after the user has done the @steps.

Let's mention what the install script actually did (CRD, RBAC, etc) after we've installed, as to not make the installation steps too intimidating for those not that familiar with Kubermetes

markmandel · 2018-03-01T00:09:31Z

examples/cluster/README.md

+[crd]: https://kubernetes.io/docs/concepts/api-extension/custom-resources/
+[rbac]: https://kubernetes.io/docs/admin/authorization/rbac/
+
+## Prerequisites


Can we split this in two - one for GKE, and one for Minikube?
(We can lift the command for starting minikube from here)

markmandel · 2018-03-01T00:10:09Z

examples/cluster/README.md

+[gcloud-install]: https://cloud.google.com/sdk/docs/#install_the_latest_cloud_tools_version_cloudsdk_current_version
+[kubectl-install]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
+
+We'll also need a Google Cloud Project, which we can create via the [Developer Console][pantheon], or by running `gcloud init`, following the prompts, and selecting `Create a new project` when asked which project to use.


pantheon the term, and this link is internal only. Remove and replace with console.cloud.google.com

markmandel · 2018-03-01T00:12:10Z

examples/cluster/README.md

+
+## Creating a Cluster
+
+We will use the deployment config defined in [gke-test-cluster/deployment.yml](gke-test-cluster/deployment.yml) and [gke-test-cluster/cluster.yml.jinja](gke-test-cluster/cluster.yml.jinja). If you would like more control over the zone, cluster name, or other details, you can edit those files accordingly before running the command to create the cluster. But first, let's make sure we're authenticated.


Sorry - I wasn't clear on my thinking with this.

I think it would be ideal if the user could do this without having to download/git clone anything other than the gcloud tools (maybe we direct them to cloud shell for this - that would actually be really cool - maybe we do that?)

So rather than making them git clone - can we instead have a series of gcloud commands to setup the cluster, and setup the firewall rules and configure rbac.

I think it will be a better learning experience for the user so they can see how they might do this themselves.

How does that sound?

markmandel · 2018-03-01T00:13:03Z

examples/cluster/README.md

+  --clusterrole cluster-admin --user $(gcloud config get-value account)
+```
+
+## Applying Agones CRD's


Let's use "Custom Resource Definition" (and we can link to what they are here).

Let's not assume our users know what these acronyms are.

markmandel · 2018-03-01T00:13:56Z

examples/cluster/README.md

+Finally, it's time to define the CRD's that power Agones to the cluster.
+
+```bash
+kubectl apply -f ../../install.yaml


kubectl can pull straight from a URL - so once we're open source, we can link directly to the install.yaml in the release-1.0 branch, and people can install directly without having to download any code.

Also probably wasn't clear - release-1.0 branch can go live once my do-release #121 PR has been approved and merged, and I'll keep it up to date.

markmandel · 2018-03-01T00:14:22Z

examples/cluster/README.md

+kubectl apply -f ../../install.yaml
+```
+
+That's it! You're ready to create GameServer type resources, using the `gcr.io/agones-images` repository. For a quick and easy example of how to do so, see the [simple-udp example](../simple-udp).


Maybe a placeholder for the Game Server quickstart that @Kuqd is currently working on?

markmandel · 2018-03-01T20:58:49Z

docs/installing_agones.md

+Finally, we install Agones to the cluster.
+
+```bash
+kubectl apply -f ../../install.yaml


This looks awesome!

Very quick question - was this meant to point to the URL? Or did we want to update this when we go public on Monday?

markmandel · 2018-03-01T21:06:40Z

docs/installing_agones.md

+
+## Creating an `agones` profile
+
+We need a minikube profile for `agones`.


So we don't need to have one, maybe this is more of a nice to have?

markmandel

A few minor things I think we could add(some extra links and the like), but this is great!

I also tested everything out on GKE and Minikube, and it all works!

markmandel · 2018-03-02T00:36:11Z

docs/installing_agones.md

+
+# Table of contents
+
+1. [Table of contents](#table-of-contents)


So I totally just noticed that I did the same thing in my build TOC, but should we have the table of contents listed in our table contents?

Or do we need to go deeper 😆

Yeah I was just copying that. I'm good kicking it.

markmandel · 2018-03-02T00:37:51Z

docs/installing_agones.md

+
+Take the following steps to enable the Kubernetes Engine API:
+
+1. Visit the Kubernetes Engine page in the Google Cloud Platform Console.


we can link to: https://console.cloud.google.com/kubernetes/list

markmandel · 2018-03-02T00:38:57Z

docs/installing_agones.md

+1. Visit the Kubernetes Engine 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.


Curious - do you have to enable billing, or can you run off the free trial?

To sign up for the free trial you still need to enter credit card or bank account information, though it doesn't explicitly say you need to enable billing as well. But I would think so.

markmandel · 2018-03-02T00:40:08Z

docs/installing_agones.md

+Our Project ID is chosen or generated when we create the project. The compute zone will be something like `us-west1-a`. A full list can be found [here][zones].
+
+```bash
+gcloud config set project [PROJECT_ID]


Would a better path be to send them down gcloud init (at the very least they are running locally, rather than on cloud shell? - on cloud shell, they only need to set the compute/zone)

Reworked this section to

run gcloud init in the Local Shell section (including choosing a compute zone)

set compute/zone in the Cloud Shell section

markmandel · 2018-03-02T00:49:27Z

docs/installing_agones.md

+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=v1.9.0 \


Version should be 1.9.2-gke.1

So:

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```

markmandel · 2018-03-02T00:50:18Z

docs/installing_agones.md

+  --password=supersecretpassword \
+  --scopes=https://www.googleapis.com/auth/devstorage.read_only,compute-rw,cloud-platform
+```
+


Not sure where, but we I think should probably mention that this defaults to creating a 3 node cluster and what machines it creates (n1-standard-1), just so people know the resources they are spinning up.

Good point. I can include the --machine-type/--num-nodes params with an explanations even if they're the default values

markmandel · 2018-03-02T00:55:08Z

docs/installing_agones.md

+* enable-basic-auth/password: Sets the master auth scheme for interacting with the cluster.
+* scopes: Defines the Oauth scopes required by the nodes.
+
+Finally, let's tell `gcloud` that we are speaking with this cluster, and get auth credentials for it.


"for it" => "for kubectl to use"

Just thinking to be explicit that the auth credentials are for kubectl.

markmandel · 2018-03-02T01:22:05Z

docs/installing_agones.md

+kubectl apply -f https://raw.githubusercontent.com/googlecloudplatform/agones/release-0.1/install.yaml
+```
+
+That's it! This creates the [Custom Resource Definitions][crds] that power Agones and allows us to define resources of type `GameServer`.


Shall we add a step that confirms that the install worked correctly.

I was thinking something like:

To confirm that Agones is running correctly, run the following:
kubectl logs --namespace=agones-system --selector=stable.agones.dev/role=controller

This should return a result like:

{"Version":"0.1","alwaysPullSidecarImage":false,"cert-file":"/home/agones/certs/server.crt","key-file":"/home/agones/certs/server.key","level":"info","maxPort":8000,"minPort":7000,"msg":"starting gameServer operator...","sidecar":"gcr.io/agones-images/agones-sdk:0.1","source":"main","time":"2018-03-02T01:15:06Z"} ....

And no errors should be displayed in the output.

WDYT? I figured the best way would to output the logs, but this way, we don't have to specify the Pod name.

That works.

As an alternative, if we wanted to use describe, did you know that if you ask kubectl to describe a resource type of which you only have one instance, it will just describe that instance?

I use kubectl describe gs all the time when I don't feel like typing out the name of it.

Which do you think would be better? There'd be no danger of there being more than one pod even if it's a cluster they've used before, since we create it in the agones-system namespace.

markmandel · 2018-03-02T01:25:54Z

docs/installing_agones.md

+
+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/


Shall we add a (for when #124 is merged):

What's next

Go through the Create a Game Server Quickstart

markmandel · 2018-03-05T19:22:41Z

docs/installing_agones.md

+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.


Stealing from the istio docs, shall we add:

If you are not an existing GCP user, you may be able to enrol for a $300 US Free Trial credit.

Just so that it's clear you can use the free trial 👍

markmandel

Found a couple of broken links, but otherwise - LGTM!

markmandel · 2018-03-05T20:24:56Z

README.md

-
-_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.


Whoops, broken link! :)

markmandel · 2018-03-05T20:28:11Z

docs/installing_agones.md

+
+* Go through the [Create a Game Server Quickstart][quickstart]
+
+[quickstart]: docs/create_gameserver.md


Broken link - should be create_gameserver.md (since it is already in the docs folder)

damn it. Done.

dzlier-gcp requested a review from markmandel February 28, 2018 23:00

markmandel requested changes Mar 1, 2018

View reviewed changes

dzlier-gcp force-pushed the cluster-quickstart branch 2 times, most recently from e5664a2 to c8ee09c Compare March 1, 2018 20:44

markmandel reviewed Mar 1, 2018

View reviewed changes

markmandel added kind/documentation Documentation for Agones area/user-experience Pertaining to developers trying to use Agones, e.g. SDK, installation, etc area/examples Examples. Usually found in the `examples` directory labels Mar 1, 2018

markmandel added this to the 0.1 milestone Mar 1, 2018

markmandel reviewed Mar 1, 2018

View reviewed changes

dzlier-gcp force-pushed the cluster-quickstart branch from c8ee09c to 580be35 Compare March 1, 2018 21:12

markmandel reviewed Mar 2, 2018

View reviewed changes

dzlier-gcp force-pushed the cluster-quickstart branch 2 times, most recently from 945ab0d to 129c70a Compare March 5, 2018 19:05

markmandel reviewed Mar 5, 2018

View reviewed changes

dzlier-gcp force-pushed the cluster-quickstart branch 2 times, most recently from 88e1777 to 6445aae Compare March 5, 2018 19:30

markmandel reviewed Mar 5, 2018

View reviewed changes

Add cluster creation Quickstart with no build tools.

df40107

dzlier-gcp force-pushed the cluster-quickstart branch from 6445aae to df40107 Compare March 5, 2018 20:45

markmandel approved these changes Mar 5, 2018

View reviewed changes

dzlier-gcp merged commit 51efcc2 into master Mar 5, 2018

markmandel deleted the cluster-quickstart branch March 5, 2018 21:02

markmandel mentioned this pull request May 22, 2018

Target for generating a CHANGELOG from GitHub Milestones. #217

Merged

WontonSam mentioned this pull request Oct 2, 2023

[Snyk] Fix for 1 vulnerabilities WontonSam/Phiahplay-#6

Open

WontonSam mentioned this pull request Nov 29, 2023

[Snyk] Fix for 13 vulnerabilities WontonSam/Phiahplay-#7

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add cluster creation Quickstart. #122

Add cluster creation Quickstart. #122

dzlier-gcp commented Feb 28, 2018

markmandel left a comment

markmandel Feb 28, 2018

markmandel Feb 28, 2018

markmandel Mar 1, 2018

markmandel Mar 1, 2018

markmandel Mar 1, 2018

markmandel Mar 1, 2018

markmandel Mar 1, 2018

markmandel Mar 1, 2018 •

edited

Loading

markmandel Mar 1, 2018

markmandel Mar 1, 2018

markmandel Mar 1, 2018

markmandel left a comment •

edited

Loading

markmandel Mar 2, 2018

dzlier-gcp Mar 5, 2018

markmandel Mar 2, 2018

markmandel Mar 2, 2018

dzlier-gcp Mar 5, 2018

markmandel Mar 2, 2018

dzlier-gcp Mar 5, 2018

markmandel Mar 2, 2018

markmandel Mar 2, 2018

dzlier-gcp Mar 5, 2018

markmandel Mar 2, 2018

markmandel Mar 2, 2018

dzlier-gcp Mar 5, 2018

markmandel Mar 2, 2018

markmandel Mar 5, 2018

dzlier-gcp Mar 5, 2018

markmandel left a comment

markmandel Mar 5, 2018

dzlier-gcp Mar 5, 2018

markmandel Mar 5, 2018

dzlier-gcp Mar 5, 2018

		@@ -0,0 +1,84 @@
		# Creating a Kubernetes Cluster Quickstart

		In this quickstart, we will create a Kubernetes cluster, and populate it with the CRD's ([Custom Resource Definitions][crd]), service accounts, and [RBAC][rbac] roles and bindings that power Agones.


		## Creating a Cluster

		We will use the deployment config defined in [gke-test-cluster/deployment.yml](gke-test-cluster/deployment.yml) and [gke-test-cluster/cluster.yml.jinja](gke-test-cluster/cluster.yml.jinja). If you would like more control over the zone, cluster name, or other details, you can edit those files accordingly before running the command to create the cluster. But first, let's make sure we're authenticated.


		## Creating an `agones` profile

		We need a minikube profile for `agones`.


		# Table of contents

		1. [Table of contents](#table-of-contents)


		Take the following steps to enable the Kubernetes Engine API:

		1. Visit the Kubernetes Engine page in the Google Cloud Platform Console.


		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/


		* Go through the [Create a Game Server Quickstart][quickstart]

		[quickstart]: docs/create_gameserver.md

Add cluster creation Quickstart. #122

Add cluster creation Quickstart. #122

Conversation

dzlier-gcp commented Feb 28, 2018

markmandel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markmandel Mar 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markmandel left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

What's next

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markmandel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markmandel Mar 1, 2018 •

edited

Loading

markmandel left a comment •

edited

Loading