Documentation quickstart and specification gameserver #124

cyriltovena · 2018-03-01T19:36:41Z

This should resolves #45

the simple-udp 0.1 need to be pushed again.

markmandel

This is awesome.

Still want to run through this and test it, but thought I'd drop a few initial thoughts down before I had a chance to do that.

markmandel · 2018-03-01T19:52:14Z

README.md


 ### Guides
- - Integrating the C++ SDK (forthcoming)
+ - [Game Server Specification](./docs/gameserver_spec.md)
+ - [Integrating the C++ SDK](./docs/integrating_sdk.md)


Did you mean to include this line (and the accompanying empty doc?)

Just since there isn't anything in it, I have a minor concern it will get skipped ;)

I was willing to do it but then time run out. I'll remove it.

Sounds good. I've got a PR coming where I expand and move the SDK section around a bit, so it should take care of this. It's coming down the pike.

markmandel · 2018-03-01T19:52:20Z

docs/create_gameserver.md

+
+>NOTE: Agones required Kubernetes versions 1.9 with role-based access controls (RBAC) and MutatingAdmissionWebhook features activated. To check your version, enter `kubectl version`.
+
+If you don't have a Kubernetes cluster you can follow the [build](../build/README.md#running-a-test-minikube-cluster) instructions to either use [Minikube](https://github.com/kubernetes/minikube) single node cluster or create one in [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/).


We can update this section once @dzlier-gcp has the new install guide, and redirect to that.

@dzlier-gcp let me know when it's ready

actually I referenced it already !

markmandel · 2018-03-01T19:56:30Z

docs/gameserver_spec.md

+
+Like any other kubernetes ressources you describe a GameServer desired state via a specification written in YAML or JSON to the kubernetes API. The Agones controller will then change the actual state to the desired state.
+
+A full GameServer specification is available below for reference :


Shall we also link to the example.yaml in case people want a straight up yaml file as well?

markmandel · 2018-03-01T19:59:39Z

docs/gameserver_spec.md

+
+The `spec` field is the actual GameServer specification and it is composed as follow:
+
+- `container` is the name of container running the GameServer in case you are running a [multi-container pod](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/) , if you do this is mandatory. For instance this is useful if you want to run a sidecar to ship logs.


Rather than saying "multi container" - can we simplify this and say "if you have than one container definied in a pod" (or similar). I think it would be easier to parse.

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

docs/create_gameserver.md

+Let's wait for the GameServer state to become `Ready`:
+
+```
+watch kubectl describe gameserver


Should we put an example in here of what it should look like, and some directions, so the user knows where to look to know that the GameServer is Ready?

(Maybe also direct them to look at some of the events, just as a point of interest?)

Let me know, wasn't sure what to say

markmandel · 2018-03-01T20:03:34Z

docs/integrating_sdk.md

@@ -0,0 +1 @@
+# Integrating the C++ SDK


Should we remove this?

markmandel · 2018-03-01T20:04:22Z

examples/simple-udp/server/gameserver.yaml

@@ -17,12 +17,9 @@ kind: GameServer
 metadata:
  name: "simple-udp"
 spec:
-  portPolicy: "static"


Question: do we want to be explicit about being dynamic? I don't have strong opinions, but thought I'd raise the question.

I think it's a good point let's do that, if users look at the file at least it is more explanatory

markmandel

Looking good - some more thoughts and feeling.

markmandel · 2018-03-01T21:14:02Z

docs/create_gameserver.md

+  Normal  Starting        11s   gameserver-controller  Synced
+  Normal  Ready           4s    gameserver-controller  Address and Port populated
+```
+


"If you look towards the bottom, you can see there is a Status > State value. We are waiting for it to move to Ready, which means that the game server is ready to accept connections.

You might also be interested to see the Events section, which outlines when various lifecycle events of the GameSever occur. We can also see when the GameServer is ready on the event stream as well - at which time the Status > Address and Status > Port have also been populated, letting us know what IP and port our client can now connect to!

^ Something like that sound good?

yep changing it.

markmandel · 2018-03-01T21:14:23Z

docs/create_gameserver.md

+        Name:   simple-udp
+        Resources:
+Status:
+  Address:    10.130.65.212


Just want to double check this isn't a real IP you care about

it's internal (10.x.x.x) I don't think anyone can do anything with it. Should I changed that ?

As long as it's fine. Just wanted to double check. Security FTW.

markmandel · 2018-03-01T21:16:09Z

docs/create_gameserver.md

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


you're either on WSL or linux I guess you have that no ?

I'd err on the side of being explicit? And maybe make a note that it's already installed on most Linux/macOS distros, Windows will need to use WSL) ?

markmandel · 2018-03-01T21:19:38Z

docs/create_gameserver.md

+```
+user@computer:~/$ gameserver "simple-udp" created
+```
+


"This has created a GameServer record inside Kubernetes, which has also created a backing Pod (maybe talk about Pods?) to run our simple udp game server code in"

(I just want to explain a bit more what has happened at each step)

If you want to see all your running GameServers you can run:
kubectl get gameservers

It should look something like this: insert example

(Maybe)

You can also see the Pod that got created by running kubectl get pods, the Pod will be prefixed by simple-udp.

markmandel · 2018-03-01T21:20:42Z

docs/create_gameserver.md

+
+To install Agones controller into your Kubernetes cluster follow the [installation instructions](../README.md#Installation).
+
+For the purpose of this guide we're going to use the [simple-udp](../examples/simple-udp/) example as the GameServer container. This example is very simple UDP server written in Go. Don't hesitate to look at the code of this example for more information.


Do we want to move this up to the top, so we start with what we're trying to achieve?

Otherwise this might get buried in the pre-reqs section.

markmandel · 2018-03-01T21:36:08Z

docs/create_gameserver.md

+EXIT
+```
+
+You can also try to send `UNHEALTHY` to change the Game Server state.


Do we want to do this - or should we tell them to type 'EXIT' which tells the SDK to run the Shutdown command, and therefore shuts down the GameServer?

cyriltovena · 2018-03-01T22:19:26Z

Everything should be resolved.

markmandel

All just super minor stuff.

But I tested out all the steps, and everything works!

markmandel · 2018-03-02T01:59:59Z

README.md


 ### Guides
+ - [Game Server Specification](./docs/gameserver_spec.md)


Should the spec be under "Reference" ? WDYT?

markmandel · 2018-03-02T02:03:05Z

docs/create_gameserver.md

+
+## Objectives
+
+- Create a GameServer in kubernetes using Agones custom ressources.


markmandel · 2018-03-02T02:05:15Z

docs/create_gameserver.md

+EXIT
+```
+
+You can finally type `EXIT` which tells the SDK to run the Shutdown command, and therefore shuts down the `GameServer`.


Link "Shutdown command" to https://github.com/googleprivate/agones/tree/master/sdks#shutdown

Should we also make a note something like:

"Which you can see 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"

Or something to that effect?

Added the text

markmandel · 2018-03-02T02:10:05Z

docs/create_gameserver.md

+watch kubectl describe gameserver
+```
+
+If you look towards the bottom, you can see there is a `Status > State` value. We are waiting for it to move to `Ready`, which means that the game server is ready to accept connections.


Minor thought: Should this section be after the example? Not sure.

Yes read again and I give some space.

markmandel · 2018-03-02T02:10:28Z

docs/create_gameserver.md

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


markmandel · 2018-03-02T02:10:36Z

docs/create_gameserver.md

+Let's wait for the GameServer state to become `Ready`:
+
+```
+watch kubectl describe gameserver


markmandel · 2018-03-02T02:12:27Z

docs/create_gameserver.md

+You can now communicate with the Game Server :
+
+```
+nc -u 10.130.65.208 7936


Should this be nc -u {IP} {PORT}

???

markmandel · 2018-03-02T02:19:58Z

docs/gameserver_spec.md

+
+Since Agones defines a new [Custom Ressources Definition (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources/) we can define a new ressource using the kind `GameServer` with the custom group `stable.agones.dev` and API version `v1alpha1`.
+
+You can use the metadata field to target a specific [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) but also attach specific [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) and [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to your ressource. This is a very common pattern in the kubernetes ecosystem.


Kubernetes (capitol K)

fixed everywhere.

markmandel · 2018-03-02T02:20:47Z

docs/gameserver_spec.md

+- `containerPort` the port that is being opened on the game server process, this is required field.
+- `protocol` the protocol being used. Defaults to UDP. TCP is the only other option.
+- `health` to track the overall healthy state of the GameServer, more information available in the [health check documentation](./health_checking.md).
+- `template` the [pod spec template](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/#pod-v1-core) to run you GameServer containers, [see](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/#pod-templates) for more


for more .... "information" ? 😄

cyriltovena · 2018-03-02T13:38:53Z

Voila

markmandel

LGTM!

cyriltovena added kind/documentation Documentation for Agones area/examples Examples. Usually found in the `examples` directory labels Mar 1, 2018

cyriltovena requested a review from markmandel March 1, 2018 19:36

cyriltovena force-pushed the doc/quickstart-gs branch from e157951 to f444544 Compare March 1, 2018 19:41

markmandel added this to the 0.1 milestone Mar 1, 2018

cyriltovena force-pushed the doc/quickstart-gs branch from f444544 to 0064ea0 Compare March 1, 2018 19:59

markmandel reviewed Mar 1, 2018

View reviewed changes

cyriltovena force-pushed the doc/quickstart-gs branch from 0064ea0 to ce7c685 Compare March 1, 2018 21:02

markmandel added the area/user-experience Pertaining to developers trying to use Agones, e.g. SDK, installation, etc label Mar 1, 2018

cyriltovena force-pushed the doc/quickstart-gs branch 3 times, most recently from 9cf5491 to 671e057 Compare March 1, 2018 21:28

markmandel reviewed Mar 1, 2018

View reviewed changes

cyriltovena force-pushed the doc/quickstart-gs branch from 671e057 to b8a29b5 Compare March 1, 2018 22:19

markmandel mentioned this pull request Mar 2, 2018

Add cluster creation Quickstart. #122

Merged

markmandel reviewed Mar 2, 2018

View reviewed changes

Quick start to create game server & details spec guide

f9b7a40

cyriltovena force-pushed the doc/quickstart-gs branch from b8a29b5 to f9b7a40 Compare March 2, 2018 13:38

markmandel approved these changes Mar 2, 2018

View reviewed changes

markmandel merged commit 980b34f into master Mar 2, 2018

markmandel deleted the doc/quickstart-gs branch March 2, 2018 17:38

markmandel mentioned this pull request May 22, 2018

Target for generating a CHANGELOG from GitHub Milestones. #217

Merged


		>NOTE: Agones required Kubernetes versions 1.9 with role-based access controls (RBAC) and MutatingAdmissionWebhook features activated. To check your version, enter `kubectl version`.

		If you don't have a Kubernetes cluster you can follow the [build](../build/README.md#running-a-test-minikube-cluster) instructions to either use [Minikube](https://github.com/kubernetes/minikube) single node cluster or create one in [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/).


		Like any other kubernetes ressources you describe a GameServer desired state via a specification written in YAML or JSON to the kubernetes API. The Agones controller will then change the actual state to the desired state.

		A full GameServer specification is available below for reference :


		The `spec` field is the actual GameServer specification and it is composed as follow:

		- `container` is the name of container running the GameServer in case you are running a [multi-container pod](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/) , if you do this is mandatory. For instance this is useful if you want to run a sidecar to ship logs.


		To install Agones controller into your Kubernetes cluster follow the [installation instructions](../README.md#Installation).

		For the purpose of this guide we're going to use the [simple-udp](../examples/simple-udp/) example as the GameServer container. This example is very simple UDP server written in Go. Don't hesitate to look at the code of this example for more information.


		### Guides
		- [Game Server Specification](./docs/gameserver_spec.md)


		## Objectives

		- Create a GameServer in kubernetes using Agones custom ressources.


		Since Agones defines a new [Custom Ressources Definition (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources/) we can define a new ressource using the kind `GameServer` with the custom group `stable.agones.dev` and API version `v1alpha1`.

		You can use the metadata field to target a specific [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) but also attach specific [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) and [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to your ressource. This is a very common pattern in the kubernetes ecosystem.

Documentation quickstart and specification gameserver #124

Documentation quickstart and specification gameserver #124

Conversation

cyriltovena commented Mar 1, 2018 • edited by markmandel Loading

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

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

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

cyriltovena 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

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

cyriltovena commented Mar 1, 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

Choose a reason for hiding this comment

cyriltovena Mar 2, 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

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

cyriltovena commented Mar 2, 2018

markmandel left a comment

Choose a reason for hiding this comment

cyriltovena commented Mar 1, 2018 •

edited by markmandel

Loading

cyriltovena Mar 1, 2018 •

edited

Loading

cyriltovena Mar 2, 2018 •

edited

Loading