Upgrade your Azure cluster version

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

Prerequisites

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 gkemulticloud.googleapis.com/azureClusters.update Identity and Access Management permission.

How GKE on Azure performs updates

Because upgrading a cluster requires restarting the control plane nodes, GKE on Azure performs a "rolling update" with the following steps:

  1. Choose one control plane instance to update. GKE on Azure updates unhealthy instances, if any, before healthy ones.
  2. Delete the instance. GKE 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, GKE 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, GKE 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 \
  --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

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 \
    --location=GOOGLE_CLOUD_LOCATION

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 console, the Google Cloud CLI or the GKE Multi-Cloud API. If you want to use the console to upgrade a cluster, you must first choose and configure an authentication method for logging in to the cluster. For more information, see Connect and authenticate to your cluster.

Console

  1. In the Google Cloud console, go to the Google Kubernetes Engine clusters overview page.

    Go to GKE clusters

  2. Select the Google Cloud project that the cluster is in.

  3. In the cluster list, select the name of the cluster, and then select View details in the side panel.

  4. On the Details tab, select Upgrade.

  5. In the Upgrade the Kubernetes version for the cluster dialog box, select the version that you want to upgrade to and click Done. Note that you must upgrade through all minor versions when upgrading your cluster.

gcloud

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

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

Replace the following:

API

To update your cluster through the API, use a PATCH operation on the GKE 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 GKE 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=controlPlane.Version

Replace the following:

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

Upgrade your node pools

After you upgrade your cluster version, upgrade your node pools to complete the process. To learn how, see Update a node pool.

What's next