Docs: Note that Feature Gate changes are upgrades (#2678)

Noting that we get reports that when doing in-place updates with feature
gates can cause issues when existing resources are left in place, and
therefore making a note in the docs to:

a) Feature Gate changes are upgrades
b) Delete all resource (including FleetAutoscalers)
c) Even on Helm upgrades, delete the Agones resources.

Work on #2675

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

@@ -20,6 +20,13 @@ your particular game architecture but should provide a solid foundation for upda
 The recommended approach is to use [multiple clusters](#upgrading-agones-multiple-clusters), such that the upgrade can be tested
 gradually with production load and easily rolled back if the need arises.
 
+{{< alert color="warning" title="Warning" >}}
+Changing [Feature Gates]({{% ref "/docs/Guides/feature-stages.md#feature-gates" %}}) within your Agones install
+can constitute an "upgrade" as it may create or remove functionality
+in the Agones installation that may not be forward or backward compatible with installed resources in an existing 
+installation.
+{{< /alert >}}
+
 ### Upgrading Agones: Multiple Clusters
 
 We essentially want to transition our GameServer allocations from a cluster with the old version of Agones,
@@ -33,7 +40,7 @@ The following are steps to implement this:
 
 1. Create a new cluster of the same size or smaller as the current cluster.
 2. Install the new version of Agones on the new cluster.
-3. Deploy the same set of Fleets and/or GameServers from the old cluster into the new cluster.
+3. Deploy the same set of Fleets, GameServers and FleetAutoscalers from the old cluster into the new cluster.
 4. With your matchmaker, start sending a small percentage of your matched players' game sessions to the new cluster.
 5. Assuming everything is working successfully on the new cluster, slowly increase the percentage of matched sessions to the new cluster, until you reach 100%.
 6. Once you are comfortable with the stability of the new cluster with the new Agones version, shut down the old cluster.
@@ -51,28 +58,29 @@ the previous installation of Agones before upgrading to the new version, as we n
 the new version.
 
 1. Start your maintenance window.
-1. Delete the current set of Fleets and/or GameServers in your cluster.
+1. Delete the current set of Fleets, GameServers and FleetAutoscalers in your cluster.
 1. Make sure to delete the same version of Agones that was previously installed, for example:
    `kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/<old-release-version>/install/yaml/install.yaml`
 1. Install Agones [with install.yaml]({{< relref "./Install Agones/yaml.md" >}}).
-1. Deploy the same set of Fleets and/or GameServers back into the cluster.
+1. Deploy the same set of Fleets, GameServers and FleetAutoscalers back into the cluster.
 1. Run any other tests to ensure the Agones installation is working as expected.
 1. Close your maintenance window.
 7. Congratulations - you have now upgraded to a new version of Agones! 👍
 
 #### 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 of Agones without having to uninstall Agones completely.
 
 For details on how to use Helm for upgrades, see the [helm upgrade](https://v2.helm.sh/docs/helm/#helm-upgrade) documentation.
 
 Given the above, the steps for upgrade are simpler:
 
 1. Start your maintenance window.
-1. Run `helm upgrade` with the appropriate arguments, such a `--version`, for your specific upgrade
-1. Run any other tests to ensure the Agones installation is working as expected.
-1. Close your maintenance window.
+2. Delete the current set of Fleets, GameServers and FleetAutoscalers in your cluster.
+3. Run `helm upgrade` with the appropriate arguments, such a `--version`, for your specific upgrade
+4. Deploy the same set of Fleets, GameServers and FleetAutoscalers back into the cluster.
+5. Run any other tests to ensure the Agones installation is working as expected.
+6. Close your maintenance window.
 7. Congratulations - you have now upgraded to a new version of Agones! 👍
 
 {{< alert color="warning" title="Warning" >}}