From a8ea9603e7c122b0f3c83f87983bfa99763d7d90 Mon Sep 17 00:00:00 2001 From: Ivy Gooch Date: Mon, 15 Jul 2024 16:57:23 +0000 Subject: [PATCH] Adds Documention for how to run an in-place Agones upgrade --- .../content/en/docs/Installation/upgrading.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/site/content/en/docs/Installation/upgrading.md b/site/content/en/docs/Installation/upgrading.md index 5d03152808..6b78a48f84 100644 --- a/site/content/en/docs/Installation/upgrading.md +++ b/site/content/en/docs/Installation/upgrading.md @@ -51,6 +51,74 @@ 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. +{{% feature publishVersion="1.43.0" %}} +#### In-Place Agones Upgrades + +{{< alert color="warning" title="Warning" >}} +Work is ongoing for [In-Place Agones Upgrades](https://github.com/googleforgames/agones/issues/3766), +and the feature is currently in `Dev`. Please continue to use the multi-cluster strategy for +production critical upgrades. Feedback on the upcoming `Alpha` and `Beta` releases is appreciated. +{{< /alert >}} + +For In-Place Agones Upgrades we highly recommend installing using Helm. Helm has a significant +advantage over `install.yaml` in that Helm automatically rolls back the upgrade if the agones-system +pods are not all successfully running within the designated `--timeout`. + +Note: By “controller derived configuration” we mean the parts of the Game Server’s final state that +are not part of the Game Server spec template that are instead passed to the Game Server through the +controller, such as the FEATURE_GATES or the Agones SDK Image. + +##### Upgrade Existing Fleet (recommended) + +1. Run `helm upgrade my-release --install --atomic --wait --timeout 10m --namespace=agones-system` +with all the appropriate arguments, such a `--version`, for your specific upgrade. Keep in mind that +`helm upgrade` overwrites all `--set agones.` arguments, so these must be set for each upgrade. See +[Helm Configuration]({{< relref "./Install Agones/helm.md" >}}) for a list of all available +configurable parameters. +2. Wait until the `helm upgrade` is complete. +3. Kick off rolling update of existing Fleet. + 3.1 Make any change to the Fleet Spec Template in your fleet.yaml and reapply with + `kubectl apply -f fleet.yaml`. + 3.2 If you have no changes to make to the existing Fleet Spec Template in the fleet.yaml, + then add a label to the spec.template.metadata.labels. This has the added advantage that Game + Servers can be selected for allocation by label. Reapply with `kubectl apply -f fleet.yaml`. +```bash +apiVersion: agones.dev/v1 +kind: Fleet +metadata: + name: example-fleet +spec: + replicas: 2 + template: + metadata: + # Adding a label will start a Fleet rollout (RollingUpdate or Recreate based on the replacement + # strategy type) with the most up to date Agones config. The label can be any `key: value` pair. + labels: + release: 1.42.0 +``` + 3.3 This creates a new Game Server Set. Ready Game Servers will shut down and be recreated on the + new configuraiton on the new Game Server Set. Allocated Game Servers will use the existing + configuration, and once they are set back to Ready, these Game Servers will shut down and be + replaced by Ready Game Servers at the new configuration on the new Game Server Set. + 3.4 The rollout is complete once there is one Game Server Set at the new configuration. +4. Run any other tests to ensure the Agones installation is working as expected. +5. Congratulations - you have now upgraded to a new version of Agones! 👍 + +##### Delay Upgrade to Existing Fleet (not recommended) + +1. Run `helm upgrade my-release --install --atomic --wait --timeout 10m --namespace=agones-system` +with all the appropriate arguments, such a `--version`, for your specific upgrade. Keep in mind that +`helm upgrade` overwrites all `--set agones.` arguments, so these must be set for each upgrade. See +[Helm Configuration]({{< relref "./Install Agones/helm.md" >}}) for a list of all available +configurable parameters. +2. Continue using Fleet at its existing configuration without kicking off a Fleet upgrade. + 2.1 Allocated Game servers that return to the Ready state retain the old configuration + 2.2 Any new Game Servers (either through manually increasing the number of replicas in + the fleet.yaml file or through an autoscaler) will be at the new configuration +3. Run any other tests to ensure the Agones installation is working as expected. +4. Congratulations - you have now upgraded to a new version of Agones! 👍 +{{% /feature %}} + #### Installation with install.yaml If you installed [Agones with install.yaml]({{< relref "./Install Agones/yaml.md" >}}), then you will need to delete