Upgrading Agones

Stay organized with collections Save and categorize content based on your preferences.

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 gcloud CLI installed, or use an API client:
  • Cloud Shell

    To launch Cloud Shell, perform the following steps:

    1. Go to Google Cloud console.

      Google Cloud console

    2. From the upper-right corner of the console, click the Activate Cloud Shell button:

    A Cloud Shell session opens inside a frame lower on the console. You use this shell to run gcloud commands.

    Local shell

    Install the gcloud CLI.

    Verify that you have set desired default project for Google Cloud CLI (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 CLI. Game Servers requires version 306.0.0 or higher of the gcloud CLI.

    gcloud version

    To update your installation, run the following command:

    gcloud components update

    curl / PowerShell

    To use the REST API with curl or Windows PowerShell, do the following:

    1. Create a service account.
    2. Download a private key as a JSON file.
    3. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

    Client Library

    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:

  1. 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.
  2. 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.
  3. 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 you have 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:

  1. Create a new cluster of the same size as the current cluster.

  2. 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.

  3. 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.

  4. 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.

  5. 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
  6. 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
    fleet-1      Packed       10        10        0           10      2d23h

Repeat the steps in this upgrade procedure for each cluster that needs to be upgraded.