Fleet update strategy: Replace

When the template for a Fleet is edited,
a deployment strategy can be defined. At the
moment, this is just the `Replace` strategy, which
terminates all current non-allocated GameServers
and immeadiately starts up new GameServers to replace
them.

Includes documentation as well.

Author: markmandel

cmd/controller/main.go

@@ -25,6 +25,7 @@ import (
 	"agones.dev/agones/pkg"
 	"agones.dev/agones/pkg/client/clientset/versioned"
 	"agones.dev/agones/pkg/client/informers/externalversions"
+	"agones.dev/agones/pkg/fleetallocation"
 	"agones.dev/agones/pkg/fleets"
 	"agones.dev/agones/pkg/gameservers"
 	"agones.dev/agones/pkg/gameserversets"
@@ -39,7 +40,6 @@ import (
 	"k8s.io/client-go/informers"
 	"k8s.io/client-go/kubernetes"
 	"k8s.io/client-go/rest"
-	"agones.dev/agones/pkg/fleetallocation"
 )
 
 const (
@@ -134,7 +134,7 @@ func main() { // nolint: gocyclo
 
 	gsController := gameservers.NewController(wh, health, minPort, maxPort, sidecarImage, alwaysPullSidecar, kubeClient, kubeInformationFactory, extClient, agonesClient, agonesInformerFactory)
 	gsSetController := gameserversets.NewController(wh, health, kubeClient, extClient, agonesClient, agonesInformerFactory)
-	fleetController := fleets.NewController(health, kubeClient, extClient, agonesClient, agonesInformerFactory)
+	fleetController := fleets.NewController(wh, health, kubeClient, extClient, agonesClient, agonesInformerFactory)
 	faController := fleetallocation.NewController(wh, kubeClient, extClient, agonesClient, agonesInformerFactory)
 
 	stop := signals.NewStopChannel()

docs/create_fleet.md

@@ -25,10 +25,10 @@ While not required, you may wish to go through the [Create a Game Server](create
 ## Objectives
 
 - Create a Fleet in Kubernetes using Agones custom resource.
-- Scale the Fleet up from it's initial configuration
-- Request a GameServer allocation from the Fleet to play on
+- Scale the Fleet up from it's initial configuration.
+- Request a GameServer allocation from the Fleet to play on.
 - Connect to the allocated GameServer.
-
+- Deploy a new GameServer configuration to the Fleet
 
 ### 1. Create a Fleet
 
@@ -244,10 +244,7 @@ This will get you a list of all the current `Status > State` of all the `GameSev
   State:      Ready
 ```
 
-### 5. Deploy a new version of the GameServer on the Fleet
-_Coming Soon._
-
-### 6. Scale down the Fleet
+### 5. Scale down the Fleet
 
 Not only can we scale our fleet up, but we can scale it down as well.
 
@@ -260,7 +257,7 @@ Run `kubectl edit fleet simple-udp` and replace `replicas: 5` with `replicas 0`,
 
 It may take a moment for all the `GameServers` to shut down, so let's watch them all and see what happens:
 ```
-watch kubectl describe gs | grep State
+watch 'kubectl describe gs | grep State'
 ```
 
 Eventually, one by one they will be removed from the list, and you should simply see:
@@ -274,7 +271,7 @@ That lone `Allocated` `GameServer` is left all alone, but still running!
 If you would like, try editing the `Fleet` configuration `replicas` field and watch the list of `GameServers`
 grow and shrink.
 
-### 7. Connect to the GameServer
+### 6. Connect to the GameServer
 
 Since we've only got one allocation, we'll just grab the details of the IP and port of the
 only allocated `GameServer`: 
@@ -302,6 +299,44 @@ If you run `kubectl describe gs | grep State` again - either the GameServer will
 Since we are running a `Fleet`, Agones will always do it's best to ensure there are always the configured number
 of `GameServers` in the pool in either a `Ready` or `Allocated` state. 
 
+### 7. Deploy a new version of the GameServer on the Fleet
+
+We can also change the configuration of the `GameServer` of the running `Fleet`, and have the changes
+roll out, without interrupting the currently `Allocated` `GameServers`.
+
+Let's take this for a spin! Run `kubectl edit fleet simple-udp` and set the `replicas` field to back to `5`.
+
+Let's also allocate ourselves a `GameServer`
+
+```
+kubectl create -f https://raw.githubusercontent.com/GoogleCloudPlatform/agones/master/examples/simple-udp/server/fleetallocation.yaml -o yaml
+```
+
+We should now have four `Ready` `GameServers` and one `Allocated`. We can check this by running `kubectl describe gs | grep State`.
+
+```
+  State:      Allocated
+  State:      Ready
+  State:      Ready
+  State:      Ready
+  State:      Ready
+```
+
+In production, we'd likely be changing a `containers > image` configuration to update our `Fleet`
+to run a new game server process, but to make this example simple, change `containerPort` from `7654`
+to `6000`. Save the file and exit.
+
+This will start the deployment of a new set of `GameServers` running
+with a Container Port of `6000`.
+
+> NOTE: This will make it such that you can no longer connect to the simple-udp game server.  
+
+Run `watch 'kubectl describe gs | grep "Container Port"'` until you can see that there are
+one of `7654`, which is the `Allocated` `GameServer`, and four instances to `6000` which
+is the new configuration.
+
+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/).

docs/fleet_spec.md

@@ -15,6 +15,8 @@ metadata:
   name: fleet-example
 spec:
   replicas: 2
+  strategy:
+    type: Recreate  
   template:
     metadata:
       labels:
@@ -45,8 +47,12 @@ This is a very common pattern in the Kubernetes ecosystem.
 
 The `spec` field is the actual `Fleet` specification and it is composed as follow:
 
-- `replicas` is the number of GameServers to keep Ready or Allocated in this Fleet
-- `template` a full `GameServer` configuration template. 
+- `replicas` is the number of `GameServers` to keep Ready or Allocated in this Fleet
+- `strategy` is the `GameServer` replacement strategy for when the `GameServer` template is edited.
+  `type` "Recreate" is the only option. A "RollingUpdate" option will be implemented soon.  
+  - `Recreate` terminates all non-allocated `GameServers`, and starts up a new set with
+  the new `GameServer` configuration to replace them.
+- `template` a full `GameServer` configuration template.
    See the [GameServer](./gameserver_spec.md) reference for all available fields.
 
 # Fleet Allocation Specification

examples/fleet.yaml

@@ -29,6 +29,11 @@ spec:
   replicas: 2
   # a GameServer template - see:
   # https://github.com/GoogleCloudPlatform/agones/blob/master/docs/gameserver_spec.md for all the options
+  strategy:
+    # The replacement strategy for when the GameServer template is changed. Current option is "Recreate",
+    # "RollingUpdate" will come at a later date.
+    # "Recreate" terminates all non-allocated GameServers, and starts up a new set with the new details to replace them.
+    type: Recreate
   template:
     # GameServer metadata
     metadata:

examples/xonotic/fleet.yaml

@@ -21,10 +21,12 @@ metadata:
   name: xonotic
 spec:
   replicas: 2
+  strategy:
+    type: Recreate
   template:
     spec:
-      portPolicy: "dynamic"
       containerPort: 26000
+      portPolicy: "dynamic"
       health:
         initialDelaySeconds: 30
         periodSeconds: 60

install/helm/agones/templates/crds/fleet.yaml

@@ -37,5 +37,11 @@ spec:
             replicas:
               type: integer
               minimum: 0
+            strategy:
+              properties:
+                type:
+                  enum:
+                    - Recreate
+                    - RollingUpdate
             template:
               {{- include "gameserver.validation" . | indent 14 }}

install/helm/agones/templates/mutatingwebhook.yaml

@@ -37,6 +37,7 @@ webhooks:
           - stable.agones.dev
         resources:
           - "gameservers"
+          - "fleets"
           - "fleetallocations"
         apiVersions:
           - "v1alpha1"

install/yaml/install.yaml

@@ -1,29 +1,4 @@
 ---
-# Source: agones/templates/namespace.yaml
-# Copyright 2018 Google Inc. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: agones-system
-  labels:
-    app: agones
-    chart: agones-0.2.0
-    release: agones-manual
-    heritage: Tiller
----
 # Source: agones/templates/serviceaccounts/controller.yaml
 # Copyright 2018 Google Inc. All Rights Reserved.
 #
@@ -199,6 +174,12 @@ spec:
             replicas:
               type: integer
               minimum: 0
+            strategy:
+              properties:
+                type:
+                  enum:
+                    - Recreate
+                    - RollingUpdate
             template:              
               required:
               - spec
@@ -747,12 +728,38 @@ webhooks:
           - stable.agones.dev
         resources:
           - "gameservers"
+          - "fleets"
           - "fleetallocations"
         apiVersions:
           - "v1alpha1"
         operations:
           - CREATE
 ---
+# Source: agones/templates/namespace.yaml
+# Copyright 2018 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: agones-system
+  labels:
+    app: agones
+    chart: agones-0.2.0
+    release: agones-manual
+    heritage: Tiller
+---
 # Source: agones/templates/validatingwebhook.yaml
 # Copyright 2018 Google Inc. All Rights Reserved.
 #

pkg/apis/stable/v1alpha1/fleet.go

@@ -16,6 +16,7 @@ package v1alpha1
 
 import (
 	"agones.dev/agones/pkg/apis/stable"
+	appsv1 "k8s.io/api/apps/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
@@ -52,6 +53,8 @@ type FleetList struct {
 type FleetSpec struct {
 	// Replicas are the number of GameServers that should be in this set
 	Replicas int32 `json:"replicas"`
+	// Deployment strategy
+	Strategy appsv1.DeploymentStrategy `json:"strategy"`
 	// Template the GameServer template to apply for this Fleet
 	Template GameServerTemplateSpec `json:"template"`
 }
@@ -95,3 +98,22 @@ func (f *Fleet) GameServerSet() *GameServerSet {
 
 	return gsSet
 }
+
+// ApplyDefaults applies default values to the Fleet
+func (f *Fleet) ApplyDefaults() {
+	if f.Spec.Strategy.Type == "" {
+		f.Spec.Strategy.Type = appsv1.RecreateDeploymentStrategyType
+	}
+}
+
+// ReplicasMinusSumAllocated returns the number of Replicas that are
+// currently configured against this fleet, subtracting the number
+// of allocated GameServers counted on this list of GameServerSets
+func (f *Fleet) ReplicasMinusSumAllocated(list []*GameServerSet) int32 {
+	result := f.Spec.Replicas
+	for _, gsSet := range list {
+		result -= gsSet.Status.AllocatedReplicas
+	}
+
+	return result
+}

pkg/apis/stable/v1alpha1/fleet_test.go

@@ -18,6 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	appsv1 "k8s.io/api/apps/v1"
 	corev1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/apis/meta/v1"
 )
@@ -53,3 +54,28 @@ func TestFleetGameServerSetGameServer(t *testing.T) {
 	assert.Equal(t, f.Spec.Template, gsSet.Spec.Template)
 	assert.True(t, v1.IsControlledBy(gsSet, &f))
 }
+
+func TestFleetReplicasMinusSumAllocated(t *testing.T) {
+	f := Fleet{
+		Spec: FleetSpec{Replicas: 10},
+	}
+
+	assert.Equal(t, int32(10), f.ReplicasMinusSumAllocated(nil))
+	gsSet1 := f.GameServerSet()
+	gsSet1.Status.AllocatedReplicas = 2
+
+	gsSet2 := f.GameServerSet()
+	gsSet2.Status.AllocatedReplicas = 3
+
+	assert.Equal(t, int32(5), f.ReplicasMinusSumAllocated([]*GameServerSet{gsSet1, gsSet2}))
+}
+
+func TestFleetApplyDefaults(t *testing.T) {
+	f := &Fleet{}
+
+	// gate
+	assert.EqualValues(t, "", f.Spec.Strategy.Type)
+
+	f.ApplyDefaults()
+	assert.Equal(t, appsv1.RecreateDeploymentStrategyType, f.Spec.Strategy.Type)
+}