Fixes based on feedback.

site/content/en/docs/Installation/upgrading.md

@@ -4,11 +4,11 @@ linkTitle: "Upgrading"
 weight: 100
 date: 2019-08-16T00:19:19Z
 description: >
-  Strategies and techniques for managing Agones and Kubernetes upgrades in a safe manner
+  Strategies and techniques for managing Agones and Kubernetes upgrades in a safe manner.
 ---
 
 > Note: Whichever approach you take to upgrading Agones, make sure to test it in your development environment 
-> before applying it to production 
+> before applying it to production.
 
 ## Upgrading Agones
 
@@ -20,11 +20,11 @@ gradually with production load and easily rolled back if need arises.
 
 ### Multiple Clusters
 
-Essentially, we want to do a [blue/green deployment](https://martinfowler.com/bliki/BlueGreenDeployment.html) to the 
-new version of Agones.  This means that we can slowly migrate our game servers from the older version's cluster (blue)
-to the new version's cluster (green), and ensure nothing surprising happens during this process.
+We essentially want to transition our GameServer allocations from a cluster with the old version of Agones,
+to a cluster with the upgraded version of Agones while ensuring nothing surprising 
+happens during this process.
 
-This also allows easy rollback to the previous infrastrucutre that we already know to be working in production, with
+This also allows easy rollback to the previous infrastructure that we already know to be working in production, with
 minimal interruptions to player experience.
 
 The following are steps to implement this:
@@ -42,7 +42,7 @@ The following are steps to implement this:
 If you are upgrading a single cluster, we recommend creating a maintenance window, in which your game goes offline
 for the period of your upgrade, as there will be a short period in which Agones will be non-responsive during the upgrade.
 
-### Installation with install.yaml
+#### Installation with install.yaml
 
 If you installed [Agones with install.yaml]({{< relref "_index.md#install-with-yaml" >}}), then you will need to delete
 the previous installation of Agones before upgrading to the new version, as we need to remove all of Agones before installing
@@ -58,10 +58,12 @@ the new version.
 1. Close your maintenance window.
 7. Congratulations - you have now upgraded to a new version of Agones! 👍
 
-### Installation with Helm
+#### Installation with Helm
+
+Helm features capabilities for upgrading to newer versions of Agones without having to delete the older version or your
+existing Fleets.
 
-Helm features capabilities for upgrading to newer versions without having to delete the older version. For details on
-how to use Helm for upgrades, see the [helm upgrade](https://helm.sh/docs/helm/#helm-upgrade) documentation.
+For details on how to use Helm for upgrades, see the [helm upgrade](https://helm.sh/docs/helm/#helm-upgrade) documentation.
 
 Given the above, the steps for upgrade are simpler:
 
@@ -79,16 +81,27 @@ They may require adjustment to your particular game architecture but should prov
 The recommended approach is to use [multiple clusters](#multiple-clusters-1), such that the upgrade can be tested
 gradually with production load and easily rolled back if need arises.
 
+Agones currently has only a [single supported Kubernetes version]({{< relref "_index.md#usage-requirements" >}}) for each version,
+so it is recommended to do supported minor (1.12.1 ➡ 1.13.2) Kubernetes version upgrades at the same time as matching Agones upgrades.
+
+Patch upgrades (e.g. 1.12.1 ➡ 1.12.3) within the same major version of Kubernetes can be done at any time. 
+
 ### Multiple Clusters
 
 This process is very similar to the [Agones: Multiple Cluster](#multiple-clusters) approach above.
 
+We essentially want to transition our GameServer allocations from a cluster with the old version of Kubernetes,
+to a cluster with the upgraded version of Kubernetes while ensuring nothing surprising 
+happens during this process.
+
+This also allows easy rollback to the previous infrastructure that we already know to be working in production, with
+minimal interruptions to player experience.
+
+
 Essentially, we want to do a [blue/green deployment](https://martinfowler.com/bliki/BlueGreenDeployment.html) to the new 
 version of Kubernetes.  This means that we can slowly migrate our game servers from the older version's cluster (blue) 
 to the new version's cluster (green), and ensure nothing surprising happens during this process.
 
-This also allows easy rollback to the previous infrastructure that we already know to be working in production,
-with minimal interruptions to player experience.
 
 The following are steps to implement this:
 
@@ -107,9 +120,10 @@ for the period of your upgrade, as there will be a short period in which Agones
 upgrades.
 
 1. Start your maintenance window.
-1. Scale your Fleets down to 0 and/or delete your GameServers.
+1. Scale your Fleets down to 0 and/or delete your GameServers. This is a good safety measure so there aren't race conditions
+   between the Agones controller being recreated and GameServers being deleted doesn't occur, and GameServers can end up stuck in erroneous states.
+1. Start and complete you master upgrade(s).
 1. Start and complete your node upgrades.
-1. Start and complete you master upgrade.
 1. Scale your Fleets back up and/or recreate your GameServers. 
 1. Run any other tests to ensure the Agones installation is still working as expected.
 1. Close your maintenance window.