diff --git a/site/content/en/docs/Installation/upgrading.md b/site/content/en/docs/Installation/upgrading.md new file mode 100644 index 0000000000..556d65f0e8 --- /dev/null +++ b/site/content/en/docs/Installation/upgrading.md @@ -0,0 +1,124 @@ +--- +title: "Upgrading Agones and Kubernetes" +linkTitle: "Upgrading" +weight: 100 +date: 2019-08-16T00:19:19Z +description: > + 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. + +## Upgrading Agones + +The following are strategies for safely upgrading Agones from one version to another. They may require adjustment to +your particular game architecture but should provide a solid foundation for updating Agones safely. + +The recommended approach is to use [multiple clusters](#multiple-clusters), such that the upgrade can be tested +gradually with production load and easily rolled back if need arises. + +### Multiple Clusters + +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 infrastructure that we already know to be working in production, with +minimal interruptions to player experience. + +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. +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. +7. Congratulations - you have now upgraded to a new version of Agones! 👍 + +### Single Cluster + +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 + +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 +the new version. + +1. Start your maintenance window. +1. Delete the current set of Fleets and/or GameServers 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//install/yaml/install.yaml` +1. Install Agones [with install.yaml]({{< relref "_index.md#install-with-yaml" >}}). +1. Deploy the same set of Fleets and/or GameServers 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. + +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: + +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. +7. Congratulations - you have now upgraded to a new version of Agones! 👍 + +## Upgrading Kubernetes + +The following are strategies for safely upgrading the underlying Kubernetes cluster from one version to another. +They may require adjustment to your particular game architecture but should provide a solid foundation for updating your cluster safely. + +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 (e.g. 1.12.1 ➡ 1.13.2) Kubernetes version upgrades at the same time as a matching Agones upgrades. + +Patch upgrades (e.g. 1.12.1 ➡ 1.12.3) within the same minor 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. + +The following are steps to implement this: + +1. Create a new cluster of the same size or smaller as the current cluster, with the new version of Kubernetes +2. Install the same version of Agones on the new cluster, as you have on the previous cluster. +3. Deploy the same set of Fleets and/or GameServers 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 Kubernetes version, shut down the old cluster. +7. Congratulations - you have now upgraded to a new version of Kubernetes! 👍 + +### Single Cluster + +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 node +upgrades. + +1. Start your maintenance window. +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. 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. +7. Congratulations - you have now upgraded to a new version of Kubernetes! 👍