This documentation is for the most recent version of Anthos clusters on Azure, released on April 13. See the Release notes for more information.

Upgrade or update your cluster

This page explains how Anthos clusters on Azure updates your cluster configuration and how you can update your clusters.

You might update your clusters for any of the following reasons:

  • To upgrade your cluster's Kubernetes version. When upgrading your cluster version, you must upgrade through every minor version between the current and target version.
  • To update your cluster's description (Only updatable with the API).
  • To update your cluster's annotations (Only updatable with the API).
  • To update your cluster's list of administrative users.
  • To update your cluster's AzureClient.

You can also change additional parameters on your clusters not listed above. For a complete list of parameters you can update, see the gcloud container azure clusters update and the projects.locations.azureClusters.patch documentation.

Update process

This section describes the methods by which Anthos clusters on Azure updates a cluster. The process differs depending on the changes necessary to the cluster.

Configuration-only update

If Anthos clusters on Azure can update a cluster without restarting or recreating any resources, it will make those changes— for example, updating the cluster's description.

Rolling update

When a change to a cluster requires changes to its virtual machine scale set— for example, when updating the Kubernetes version— Anthos clusters on Azure performs the following steps:

  1. Choose one control plane instance to update. Anthos clusters on Azure updates unhealthy instances, if any, before healthy ones.
  2. Delete the instance. Anthos clusters on Azure recreates the instance and the instance boots with the new configuration.
  3. Perform health checks on the new instance.
  4. If the health checks succeed, select another instance and perform the same steps on it. Repeat this cycle until all instances are restarted or recreated. If the health check fails, Anthos clusters on Azure places the cluster into a DEGRADED state and stops the update. For more information, see the following section.

Failed updates

Anthos clusters on Azure performs a health check after an update. If the health check fails, the cluster is marked as DEGRADED. You can find status information on your cluster with the following Google Cloud CLI command:

gcloud container azure clusters describe CLUSTER_NAME \
  --location GOOGLE_CLOUD_LOCATION

Replace the following:

  • CLUSTER_NAME: the name of your cluster
  • GOOGLE_CLOUD_LOCATION: the Google Cloud region that manages your cluster

Prerequisites

To update a cluster, you must have the gkemulticloud.googleapis.com/azureClusters.update Identity and Access Management permission.

Upgrade a cluster version

To check which cluster versions are available in a given region, run the following command:

gcloud container azure get-server-config \
    --location GOOGLE_CLOUD_LOCATION 

Replace GOOGLE_CLOUD_LOCATION with the Google Cloud location where you manage your clusters.

You can upgrade a cluster version with the Google Cloud CLI or the Anthos Multi-Cloud API.

gcloud

To update your cluster, run the following command:

gcloud container azure clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --cluster-version=CLUSTER_VERSION  \
    --client=CLIENT_NAME

Replace the following:

CLUSTER_NAME and GOOGLE_CLOUD_LOCATION are required for this command. Include the other flags only if you're updating those fields.

API

You update your clusters with a PATCH operation on the Anthos Multi-Cloud API.

  1. Create a JSON file named cluster_update.json with the following contents:

    {
        "description": "CLUSTER_DESCRIPTION",
        "controlPlane": {
            "version": "CLUSTER_VERSION"
        },
        "azureClient": "CLIENT_NAME"
        
    }
    

    Replace the following:

    • CLUSTER_VERSION: the new supported cluster version. Note that you must upgrade through all minor versions when upgrading your cluster
    • CLUSTER_DESCRIPTION: the new cluster description
    • CLIENT_NAME: your AzureClient name.

    These fields are optional. Include only the ones you want to change.

  2. Update a control plane using the Anthos Multi-Cloud API with following command:

   curl -d @cluster_update.json -X PATCH \
      ENDPOINT/projects/PROJECT_ID/locations/GOOGLE_CLOUD_LOCATION/azureClusters/CLUSTER_ID?update_mask=description,azure_client,control_plane.version

Replace the following:

For more information, see the projects.locations.azureClusters.patch method documentation.

Update your cluster's administrative users

You can update the list of users with administrative permissions on your cluster with either the Google Cloud CLI or the Anthos Multi-Cloud API.

gcloud

To update your cluster, run the following command:

gcloud container azure clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --admin-users USERNAME_LIST

Replace the following:

  • CLUSTER_NAME: your cluster's name
  • GOOGLE_CLOUD_LOCATION: the supported Google Cloud region that manages your cluster—for example, us-west1
  • USERNAME_LIST: a comma-separated list of usernames, for example, "kai@example.com,hao@example.com,kalani@example.com". These are the email addresses of the users you're granting administrative privileges on this cluster to. The names in this field will replace any previous list of admin-users on the cluster.

API

You update your clusters with a PATCH operation on the Anthos Multi-Cloud API.

  1. Create a JSON file named cluster_update.json with the following contents:

    {
        "authorization": {
            "adminUsers": [
                {
                "username": USERNAME1,
                "username": USERNAME2,
                "username": USERNAME3
                }
            ]
        },
    }
    

    Replace the following:

    • USERNAME1,USERNAME2,USERNAME3: the email addresses of one or more users you're granting administrative privileges on this cluster to. The names in this list will replace any previous list of admin-users on this cluster.
  2. Update a control plane using the Anthos Multi-Cloud API with following command:

    curl -d @cluster_update.json -X PATCH \
      ENDPOINT/projects/PROJECT_ID/locations/GOOGLE_CLOUD_LOCATION/azureClusters/CLUSTER_ID?update_mask=authorization.admin_users
    

    Replace the following:

For more information, see the projects.locations.azureClusters.patch method documentation.

What's next