This page explains how to safely upgrade Agones for Game Servers clusters.
Before you begin
Before you start, we recommend you familiarize yourself with key concepts in the Game Servers Overview. Make sure you have also performed the following tasks:
- Ensure that you have enabled the Game Services API. Enable Game Services API
- Either choose a shell with Cloud SDK installed, or use an API client:
Go to Google Cloud Console.
From the upper-right corner of the console, click the Activate Cloud Shell button:
To launch Cloud Shell, perform the following steps:
A Cloud Shell session opens inside a frame lower on the console.
You use this shell to run
gcloud, install the Cloud SDK,
which includes the
gcloud command-line tool.
Verify that you have set desired default project for
gcloud command-line tool (otherwise you need to specify flag
--project explicitly for each command later):
gcloud config list project
If not you can run the following command to set a default project, replacing
project-id with your desired project ID :
gcloud config set project project-id
Run the following command to verify your version of the Google Cloud SDK.
Game Servers requires version
306.0.0 or higher of the SDK.
To update your installation, run the following command:
gcloud components update
Google Cloud Game Servers can be controlled programmatically using a client library. See Client Libraries Overview for instructions on using the library and authenticating.
Planning an upgrade
We recommend that you perform Agones upgrades by adding new Game Servers clusters to a realm and then removing the old ones. This approach has the following benefits:
- It aligns with the best practices recommended by the Agones project to create a new cluster when performing upgrades without maintenance windows. This approach avoids any potential problems related to trying to upgrade Agones while games are running on the cluster.
- You don't have to try and upgrade Kubernetes or Google Kubernetes Engine nodes in place, so you can avoid problems such as those associated with removing a node from service.
- You can test a larger number of components as part of the upgrade process, including new versions of Kubernetes and Agones as a single operation and then roll them out to production together.
Planning canary upgrades
Make sure to test the new Agones version in a non-production environment before applying it to production. After validating the new Agones version, start by upgrading a canary realm in production. A canary upgrade is an upgrade that is applied initially to a single or small number of realms. Canary upgrades let you test new functionality on a small percentage of your infrastructure, instead of rolling out a potentially disruptive upgrade to all your realms. If an upgrade isn't going well, you can minimize disruption to your users and roll back the affected realm. If there isn't a designated canary realm, choose a realm with the least traffic.
Performing an upgrade
This section describes an upgrade procedure that transitions a
GameServer allocation from a cluster with the old version of Agones, to a
cluster with the upgraded version of Agones. The upgrade procedure assumes
configured multicluster allocation
in the new cluster.
The following steps also allow you to easily rollback to the previous infrastructure that you know is working in production, with minimal interruptions to player experience:
Create a new cluster of the same size as the current cluster.
Install the new version of Agones on the new cluster with a compatible version of Kubernetes. For a list of supported versions, see versions and upgrades.
Register the new cluster with the realm. This creates fleet and autoscaler resources similar to the existing clusters registered in the realm. After the fleets are ready, some matched players game sessions are sent to the new cluster.
After you have verified the stability of the new cluster running the new version of Agones, unregister and delete the old cluster. When you unregister and delete a Game Servers cluster, the allocated servers, fleets, and fleet autoscaler configurations are left as-is. The only noteable change on the actual Kubernetes cluster is that it is no longer managed by Game Servers and it is no longer connected to the multi-cluster allocation.Game Servers stops sending new allocation requests to clusters that are unregistered.
To prevent additional allocations to the old cluster if its associated endpoint is accessed directly, remove all the pods in the allocator service of the old server:
kubectl scale --replicas=0 -n agones-system deployment/agones-allocator
When there are no longer any allocated servers in the cluster, shut down the old cluster. To determine the number of allocated servers, run the following command, where namespace is the namespace you used when registering the Kubernetes cluster as a Game Servers cluster:
kubectl get fleet --namespace namespace NAME SCHEDULING DESIRED CURRENT ALLOCATED READY AGE fleet-1 Packed 10 10 0 10 2d23h
Repeat the steps in this upgrade procedure for each cluster that needs to be upgraded.