[Breaking Change] Multiple port support for GameServer

This allows the `GameServer` (and anything that uses it as a template, such as `Fleets`), to provide configuration and assignment of multiple ports to the game server container. For example: ```yaml apiVersion: "stable.agones.dev/v1alpha1" kind: GameServer metadata: name: "simple-udp" spec: ports: - name: default portPolicy: "dynamic" containerPort: 7654 template: spec: containers: - name: simple-udp image: gcr.io/agones-images/udp-server:0.1 ``` This also includes update to documentation - but in a separate bottom section of each document, to allow for moving into the live version at release time. (This is becoming a mess - a website can't come soon enough). This also adjusts the `GameServer > Status`, to be able to handle multiple ports. It now looks like this: ``` Status: Address: 192.168.99.100 Node Name: agones Ports: Name: default Port: 7502 State: Ready ``` While this a breaking change (due to the change in `GameServer > status`, the previous legacy configuration of still works (even thought it's no longer documented), as it is automatically converted to the new version. Plans are to remove this legacy conversion functionality in 0.4.0, since being in alpha, we have a very low commitment to backward compatibility. As an aside - versioning for CRDs is coming soon, so this will also solve this type of problem long term.
googleforgames · Jul 9, 2018 · 4327502 · 4327502
1 parent d3e9d7e
commit 4327502
Show file tree

Hide file tree

Showing 29 changed files with 1,037 additions and 227 deletions.
diff --git a/docs/create_fleet.md b/docs/create_fleet.md
@@ -338,3 +338,132 @@ You have now deployed a new version of your game!
 ## Next Steps
 
 If you want to use your own GameServer container make sure you have properly integrated the [Agones SDK](../sdks/).
+
+---
+
+⚠️⚠️⚠️ **This is currently a development feature and has not been released** ⚠️⚠️⚠️
+
+> Development version of the Fleet response
+
+```
+Name:         simple-udp
+Namespace:    default
+Labels:       <none>
+Annotations:  kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"stable.agones.dev/v1alpha1","kind":"Fleet","metadata":{"annotations":{},"name":"simple-udp","namespace":"default"},"spec":{"replicas":2,...
+API Version:  stable.agones.dev/v1alpha1
+Kind:         Fleet
+Metadata:
+  Cluster Name:
+  Creation Timestamp:  2018-07-01T18:55:35Z
+  Generation:          1
+  Resource Version:    24685
+  Self Link:           /apis/stable.agones.dev/v1alpha1/namespaces/default/fleets/simple-udp
+  UID:                 56710a91-7d60-11e8-b2dd-08002703ef08
+Spec:
+  Replicas:  2
+  Strategy:
+    Rolling Update:
+      Max Surge:        25%
+      Max Unavailable:  25%
+    Type:               RollingUpdate
+  Template:
+    Metadata:
+      Creation Timestamp:  <nil>
+    Spec:
+      Health:
+      Ports:
+        Container Port:  7654
+        Name:            default
+        Port Policy:     dynamic
+      Template:
+        Metadata:
+          Creation Timestamp:  <nil>
+        Spec:
+          Containers:
+            Image:  gcr.io/agones-images/udp-server:0.1
+            Name:   simple-udp
+            Resources:
+Status:
+  Allocated Replicas:  0
+  Ready Replicas:      2
+  Replicas:            2
+Events:
+  Type    Reason                 Age   From              Message
+  ----    ------                 ----  ----              -------
+  Normal  CreatingGameServerSet  13s   fleet-controller  Created GameServerSet simple-udp-wlqnd
+```
+
+> Development version of the Fleet Allocation response
+
+```
+apiVersion: stable.agones.dev/v1alpha1
+kind: FleetAllocation
+metadata:
+  clusterName: ""
+  creationTimestamp: 2018-07-01T18:56:31Z
+  generateName: simple-udp-
+  generation: 1
+  name: simple-udp-l7dn9
+  namespace: default
+  ownerReferences:
+  - apiVersion: stable.agones.dev/v1alpha1
+    blockOwnerDeletion: true
+    controller: true
+    kind: GameServer
+    name: simple-udp-wlqnd-s2xr5
+    uid: 5676a611-7d60-11e8-b2dd-08002703ef08
+  resourceVersion: "24719"
+  selfLink: /apis/stable.agones.dev/v1alpha1/namespaces/default/fleetallocations/simple-udp-l7dn9
+  uid: 77c22f17-7d60-11e8-b2dd-08002703ef08
+spec:
+  fleetName: simple-udp
+status:
+  GameServer:
+    metadata:
+      creationTimestamp: 2018-07-01T18:55:35Z
+      finalizers:
+      - stable.agones.dev
+      generateName: simple-udp-wlqnd-
+      generation: 1
+      labels:
+        stable.agones.dev/gameserverset: simple-udp-wlqnd
+      name: simple-udp-wlqnd-s2xr5
+      namespace: default
+      ownerReferences:
+      - apiVersion: stable.agones.dev/v1alpha1
+        blockOwnerDeletion: true
+        controller: true
+        kind: GameServerSet
+        name: simple-udp-wlqnd
+        uid: 56731f1a-7d60-11e8-b2dd-08002703ef08
+      resourceVersion: "24716"
+      selfLink: /apis/stable.agones.dev/v1alpha1/namespaces/default/gameservers/simple-udp-wlqnd-s2xr5
+      uid: 5676a611-7d60-11e8-b2dd-08002703ef08
+    spec:
+      container: simple-udp
+      health:
+        failureThreshold: 3
+        initialDelaySeconds: 5
+        periodSeconds: 5
+      ports:
+      - containerPort: 7654
+        hostPort: 7604
+        name: default
+        portPolicy: dynamic
+        protocol: UDP
+      template:
+        metadata:
+          creationTimestamp: null
+        spec:
+          containers:
+          - image: gcr.io/agones-images/udp-server:0.1
+            name: simple-udp
+            resources: {}
+    status:
+      address: 192.168.99.100
+      nodeName: agones
+      ports:
+      - name: default
+        port: 7604
+      state: Allocated
+```
diff --git a/docs/create_gameserver.md b/docs/create_gameserver.md
@@ -160,3 +160,69 @@ If you run `kubectl describe gameserver` again - either the GameServer will be g
 ## Next Step
 
 If you want to use your own GameServer container make sure you have properly integrated the [Agones SDK](../sdks/).
+
+---
+
+⚠️⚠️⚠️ **This is currently a development feature and has not been released** ⚠️⚠️⚠️
+
+> Development version of the GameServer description
+
+```bash
+Name:         simple-udp-jq8kd-q8dzg
+Namespace:    default
+Labels:       stable.agones.dev/gameserverset=simple-udp-jq8kd
+Annotations:  <none>
+API Version:  stable.agones.dev/v1alpha1
+Kind:         GameServer
+Metadata:
+  Cluster Name:
+  Creation Timestamp:  2018-06-30T14:15:43Z
+  Finalizers:
+    stable.agones.dev
+  Generate Name:  simple-udp-jq8kd-
+  Generation:     1
+  Owner References:
+    API Version:           stable.agones.dev/v1alpha1
+    Block Owner Deletion:  true
+    Controller:            true
+    Kind:                  GameServerSet
+    Name:                  simple-udp-jq8kd
+    UID:                   132a214e-7c70-11e8-b9be-08002703ef08
+  Resource Version:        11978
+  Self Link:               /apis/stable.agones.dev/v1alpha1/namespaces/default/gameservers/simple-udp-jq8kd-q8dzg
+  UID:                     132bb210-7c70-11e8-b9be-08002703ef08
+Spec:
+  Container:  simple-udp
+  Health:
+    Failure Threshold:      3
+    Initial Delay Seconds:  5
+    Period Seconds:         5
+  Ports:
+    Container Port:  7654
+    Host Port:       7614
+    Name:            default
+    Port Policy:     dynamic
+    Protocol:        UDP
+  Template:
+    Metadata:
+      Creation Timestamp:  <nil>
+    Spec:
+      Containers:
+        Image:  gcr.io/agones-images/udp-server:0.1
+        Name:   simple-udp
+        Resources:
+Status:
+  Address:    192.168.99.100
+  Node Name:  agones
+  Ports:
+    Name:  default
+    Port:  7614
+  State:   Ready
+Events:
+  Type    Reason          Age   From                   Message
+  ----    ------          ----  ----                   -------
+  Normal  PortAllocation  23s   gameserver-controller  Port allocated
+  Normal  Creating        23s   gameserver-controller  Pod simple-udp-jq8kd-q8dzg-9kww8 created
+  Normal  Starting        23s   gameserver-controller  Synced
+  Normal  Ready           20s   gameserver-controller  Address and Port populated
+```
diff --git a/docs/fleet_spec.md b/docs/fleet_spec.md
@@ -85,4 +85,41 @@ name for the `FleetAllocation` is generated when the `FleetAllocation` is create
 The `spec` field is the actual `FleetAllocation` specification and it is composed as follow:
 
 - `fleetName` is the name of an existing Fleet. If this doesn't exist, and error will be returned
-  when the `FleetAllocation` is created
+  when the `FleetAllocation` is created
+
+---
+
+⚠️⚠️⚠️ **This is currently a development feature and has not been released** ⚠️⚠️⚠️
+
+> Development version of the Fleet spec
+
+```yaml
+apiVersion: "stable.agones.dev/v1alpha1"
+kind: Fleet
+metadata:
+  name: fleet-example
+spec:
+  replicas: 2
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 25%
+      maxUnavailable: 25%  
+  template:
+    metadata:
+      labels:
+        foo: bar
+    spec:
+      ports:
+      - name: default
+        portPolicy: "dynamic"
+        containerPort: 26000
+      health:
+        initialDelaySeconds: 30
+        periodSeconds: 60
+      template:
+        spec:
+          containers:
+          - name: example-server
+            image: gcr.io/agones/test-server:0.1
+```  
diff --git a/docs/gameserver_spec.md b/docs/gameserver_spec.md
@@ -2,7 +2,7 @@
 
 Like any other Kubernetes resource you describe a GameServer's 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 and in the [example folder](../examples/gameserver.yaml) for reference :
+A full GameServer specification is available below and in the [example folder](https://github.com/GoogleCloudPlatform/agones/blob/release-0.2.0/examples/gameserver.yaml) for reference :
 
 ```
 apiVersion: "stable.agones.dev/v1alpha1"
@@ -43,3 +43,52 @@ The `spec` field is the actual GameServer specification and it is composed as fo
 - `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://v1-10.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#podtemplatespec-v1-core) to run your GameServer containers, [see](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/#pod-templates) for more information.
+
+---
+
+⚠️⚠️⚠️ **This is currently a development feature and has not been released** ⚠️⚠️⚠️
+
+> Development version of the GameServer spec
+
+```yaml
+apiVersion: "stable.agones.dev/v1alpha1"
+kind: GameServer
+metadata:
+  name: "gds-example"
+spec:
+  ports:
+  - name: default
+    portPolicy: "static"
+    containerPort: 7654
+    hostPort: 7777
+    protocol: UDP
+  health:
+    disabled: false
+    initialDelaySeconds: 5
+    periodSeconds: 5
+    failureThreshold: 3
+  template:
+    metadata:
+      labels:
+        myspeciallabel: myspecialvalue
+    spec:
+      containers:
+      - name: example-server
+        image: gcr.io/agones/test-server:0.1
+        imagePullPolicy: Always
+```
+
+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 `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.
+
+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 have more than one container defined in the [pod](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/). If you do,  this is a mandatory field. For instance this is useful if you want to run a sidecar to ship logs.
+- `ports` are an array of ports that can be exposed as direct connections to the game server container
+  - `name` is an optional descriptive name for a port
+  - `portPolicy` has two options `dynamic` (default) the system allocates a free hostPort for the gameserver, for game clients to connect to. And `static`, user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the port is available. When static is the policy specified, `hostPort` is required to be populated.
+  - `containerPort` the port that is being opened on the game server process, this is a 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://v1-10.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#podtemplatespec-v1-core) to run your GameServer containers, [see](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/#pod-templates) for more information.
diff --git a/examples/cpp-simple/fleet.yaml b/examples/cpp-simple/fleet.yaml
@@ -19,10 +19,16 @@ metadata:
   # will need to be created with `kubectl create`
   generateName: cpp-simple-
 spec:
-  containerPort: 7654
+  replicas: 2
   template:
     spec:
-      containers:
-      - name: cpp-simple
-        image: gcr.io/agones-images/cpp-simple-server:0.1
-        # imagePullPolicy: Always # add for development
+      ports:
+      - name: default
+        portPolicy: "dynamic"
+        containerPort: 7654
+      template:
+        spec:
+          containers:
+            - name: cpp-simple
+              image: gcr.io/agones-images/cpp-simple-server:0.1
+              # imagePullPolicy: Always # add for development
diff --git a/examples/cpp-simple/gameserver.yaml b/examples/cpp-simple/gameserver.yaml
@@ -19,7 +19,10 @@ metadata:
   # will need to be created with `kubectl create`
   generateName: cpp-simple-
 spec:
-  containerPort: 7654
+  ports:
+    - name: default
+      portPolicy: "dynamic"
+      containerPort: 7654
   template:
     spec:
       containers:

diff --git a/examples/fleet.yaml b/examples/fleet.yaml
@@ -48,8 +48,10 @@ spec:
         foo: bar
     # GameServer specification
     spec:
-      portPolicy: "dynamic"
-      containerPort: 26000
+      ports:
+      - name: default
+        portPolicy: "dynamic"
+        containerPort: 26000
       health:
         initialDelaySeconds: 30
         periodSeconds: 60

diff --git a/examples/gameserver.yaml b/examples/gameserver.yaml
@@ -31,17 +31,21 @@ metadata:
 spec:
   # if there is more than one container, specify which one is the game server
   container: example-server
-  # portPolicy has two options:
-  # - "dynamic" (default) the system allocates a free hostPort for the gameserver, for game clients to connect to
-  # - "static", user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the
-  # port is available. When static is the policy specified, `hostPort` is required to be populated
-  portPolicy: "static"
-  # the port that is being opened on the game server process
-  containerPort: 7654
-  # the port exposed on the host, only required when `portPolicy` is "static". Overwritten when portPolicy is "dynamic".
-  hostPort: 7777
-  # protocol being used. Defaults to UDP. TCP is the only other option
-  protocol: UDP
+  # Array of ports that can be exposed as direct connections to the game server container
+  ports:
+    # name is a descriptive name for the port
+  - name: default
+    # portPolicy has two options:
+    # - "dynamic" (default) the system allocates a free hostPort for the gameserver, for game clients to connect to
+    # - "static", user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the
+    # port is available. When static is the policy specified, `hostPort` is required to be populated
+    portPolicy: "static"
+    # the port that is being opened on the game server process
+    containerPort: 7654
+    # the port exposed on the host, only required when `portPolicy` is "static". Overwritten when portPolicy is "dynamic".
+    hostPort: 7777
+    # protocol being used. Defaults to UDP. TCP is the only other option
+    protocol: UDP
   # Health checking for the running game server
   health:
     # Disable health checking. defaults to false, but can be set to true