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

Upgrade your Azure cluster version

This page explains how to upgrade the Kubernetes version of your Anthos clusters on Azure clusters.


Upgrading your cluster's Kubernetes version is a specific case of the more general cluster update operation. You can read about cluster update operations in general at the update your cluster page. To upgrade your cluster version:

  • You must upgrade through every minor version between the current and target version. For example, to upgrade from 1.20 to 1.22, you must first upgrade from 1.20 to 1.21, and then upgrade from 1.21 to 1.22.
  • You must have the Identity and Access Management permission.

How Anthos clusters on Azure performs updates

Because upgrading a cluster requires restarting the control plane nodes, Anthos clusters on Azure performs a "rolling update" with 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.

When an update fails

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

gcloud container azure clusters describe CLUSTER_NAME \

Replace the following:

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

Perform the upgrade

Check your cluster version

Before upgrading your cluster version, use the following command to check which versions are available in your region:

gcloud container azure get-server-config \

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

Choose an upgrade method

You can upgrade your cluster version through either the Google Cloud CLI or the Anthos Multi-Cloud API.


To upgrade your cluster's Kubernetes version, run the following command:

gcloud container azure clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \

Replace the following:


To update your cluster through the API, use a PATCH operation on the Anthos Multi-Cloud API.

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

        "controlPlane": {
           "version": "CLUSTER_VERSION",

    Replace the following:

    • CLUSTER_VERSION: the new supported cluster version. Note that you must upgrade through all minor versions when upgrading your cluster
  2. Update these settings through the Anthos Multi-Cloud API with following command.

    curl -d @cluster_update.json -X PATCH \

Replace the following:

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

What's next