Stay organized with collections
Save and categorize content based on your preferences.
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:
Choose one control plane instance to update. GKE on Azure updates
unhealthy instances, if any, before healthy ones.
Delete the instance. GKE on Azure recreates the instance and the
instance boots with the new configuration.
Perform health checks on the new instance.
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:
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
In the Google Cloud console, go to the Google Kubernetes Engine clusters
overview page.
Select the Google Cloud project that the cluster is in.
In the cluster list, select the name of the cluster, and then select
View details in the side panel.
On the Details tab, select edit
Upgrade.
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:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[],[],null,["# Upgrade your Azure cluster version\n==================================\n\nThis page explains how to upgrade the Kubernetes version of your\nGKE on Azure clusters.\n\nPrerequisites\n-------------\n\nUpgrading your cluster's Kubernetes version is a specific case of the more\ngeneral cluster update operation. You can read about cluster update operations\nin general at the [update your cluster](/kubernetes-engine/multi-cloud/docs/azure/how-to/update-cluster)\npage. To upgrade your cluster version:\n\n- 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.\n- You must have the `gkemulticloud.googleapis.com/azureClusters.update` Identity and Access Management permission.\n\nHow GKE on Azure performs updates\n---------------------------------\n\nBecause upgrading a cluster requires restarting the control plane nodes,\nGKE on Azure performs a \"rolling update\" with the following steps:\n\n1. Choose one control plane instance to update. GKE on Azure updates unhealthy instances, if any, before healthy ones.\n2. Delete the instance. GKE on Azure recreates the instance and the instance boots with the new configuration.\n3. Perform health checks on the new instance.\n4. 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.\n\nWhen an update fails\n--------------------\n\nAfter an update, GKE on Azure performs a health check on the cluster.\nIf the health check fails, the cluster is marked as `DEGRADED`. You can display\nthe status of your cluster with the following Google Cloud CLI command: \n\n gcloud container azure clusters describe \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --location=\u003cvar translate=\"no\"\u003eGOOGLE_CLOUD_LOCATION\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: the name of your cluster\n- \u003cvar translate=\"no\"\u003eGOOGLE_CLOUD_LOCATION\u003c/var\u003e: the Google Cloud region that manages your cluster\n\nPerform the upgrade\n-------------------\n\n### Check your cluster version\n\nBefore upgrading your cluster version, use the following command to check which\nversions are available in your region: \n\n gcloud container azure get-server-config \\\n --location=\u003cvar translate=\"no\"\u003eGOOGLE_CLOUD_LOCATION\u003c/var\u003e\n\nReplace \u003cvar translate=\"no\"\u003eGOOGLE_CLOUD_LOCATION\u003c/var\u003e with the Google Cloud\nlocation from which you manage your clusters.\n\n### Choose an upgrade method\n\nYou can upgrade your cluster version through either the Google Cloud console, the\nGoogle Cloud CLI or the GKE Multi-Cloud API. If you want to use the console to upgrade\na cluster, you must first choose and configure an authentication method for\nlogging in to the cluster. For more information, see\n[Connect and authenticate to your cluster](/kubernetes-engine/multi-cloud/docs/azure/how-to/connect-and-authenticate-to-your-cluster). \n\n### Console\n\n1. In the Google Cloud console, go to the **Google Kubernetes Engine clusters\n overview** page.\n\n [Go to GKE clusters](https://console.cloud.google.com/kubernetes/list/overview)\n2. Select the Google Cloud project that the cluster is in.\n\n3. In the cluster list, select the name of the cluster, and then select\n **View details** in the side panel.\n\n4. On the **Details** tab, select edit **Upgrade**.\n\n5. In the **Upgrade the Kubernetes version for the cluster** dialog box,\n select the version that you want to upgrade to and click **Done**. Note that\n you must upgrade through all minor versions when upgrading your cluster.\n\n### gcloud\n\nTo upgrade your cluster's Kubernetes version, run the following command: \n\n gcloud container azure clusters update \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --location=\u003cvar translate=\"no\"\u003eGOOGLE_CLOUD_LOCATION\u003c/var\u003e \\\n --cluster-version=\u003cvar translate=\"no\"\u003eCLUSTER_VERSION\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: your cluster's name\n- \u003cvar translate=\"no\"\u003eGOOGLE_CLOUD_LOCATION\u003c/var\u003e: the [supported Google Cloud region](/kubernetes-engine/multi-cloud/docs/azure/reference/supported-regions) that manages your cluster---for example, `us-west1`\n- \u003cvar translate=\"no\"\u003eCLUSTER_VERSION\u003c/var\u003e: the new [supported cluster version](/kubernetes-engine/multi-cloud/docs/azure/reference/supported-versions)\n\n### API\n\nTo update your cluster through the API, use a `PATCH` operation on the\nGKE Multi-Cloud API.\n\n1. Create a JSON file named `cluster_update.json` with the following\n contents:\n\n ```json\n {\n \"controlPlane\": {\n \"version\": \"CLUSTER_VERSION\",\n },\n }\n ```\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eCLUSTER_VERSION\u003c/var\u003e: the new [supported cluster version](/kubernetes-engine/multi-cloud/docs/azure/reference/supported-versions). Note that you must upgrade through all minor versions when upgrading your cluster\n2. Update these settings through the GKE Multi-Cloud API with following command.\n\n curl -d @cluster_update.json -X PATCH \\\n \u003cvar translate=\"no\"\u003eENDPOINT\u003c/var\u003e/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/locations/\u003cvar translate=\"no\"\u003eGOOGLE_CLOUD_LOCATION\u003c/var\u003e/azureClusters/\u003cvar translate=\"no\"\u003eCLUSTER_ID\u003c/var\u003e?update_mask=controlPlane.Version\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eENDPOINT\u003c/var\u003e: Your Google Cloud [service endpoint](/kubernetes-engine/multi-cloud/docs/reference/rest#rest_endpoints)\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: Your Google Cloud project\n- \u003cvar translate=\"no\"\u003eGOOGLE_CLOUD_LOCATION\u003c/var\u003e: the [supported Google Cloud region](/kubernetes-engine/multi-cloud/docs/azure/reference/supported-regions) that manages your cluster---for example, `us-west1`\n- \u003cvar translate=\"no\"\u003eCLUSTER_ID\u003c/var\u003e: Your cluster ID\n\nFor more information, see the\n[`projects.locations.azureClusters.patch`](/kubernetes-engine/multi-cloud/docs/reference/rest/v1/projects.locations.azureClusters/patch)\nmethod documentation.\n\nUpgrade your node pools\n-----------------------\n\nAfter you upgrade your cluster version, upgrade your node pools to complete the\nprocess. To learn how, see\n[Update a node pool](/kubernetes-engine/multi-cloud/docs/azure/how-to/update-node-pool).\n\nWhat's next\n-----------\n\n- Learn how to perform other [cluster updates](/kubernetes-engine/multi-cloud/docs/azure/how-to/update-cluster).\n\n- For more information on updatable fields, see the\n [`gcloud container azure clusters update`](/sdk/gcloud/reference/container/azure/clusters/update)\n reference documentation.\n\n- See the\n [`projects.locations.azureClusters.patch`](/kubernetes-engine/multi-cloud/docs/reference/rest/v1/projects.locations.azureClusters/patch)\n REST API documentation."]]