# 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](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/update-cluster.md.txt)
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:

```bash
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:

```bash
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](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/connect-and-authenticate-to-your-cluster.md.txt).

### Console

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

   [Go to GKE clusters](https://console.cloud.google.com/kubernetes/list/overview)
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:

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

Replace the following:

- `CLUSTER_NAME`: your cluster's name
- `GOOGLE_CLOUD_LOCATION`: the [supported Google Cloud region](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/reference/supported-regions.md.txt) that manages your cluster---for example, `us-west1`
- `CLUSTER_VERSION`: the new [supported cluster version](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/reference/supported-versions.md.txt)

### 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:

   ```json
   {
       "controlPlane": {
          "version": "CLUSTER_VERSION",
       },
   }
   ```

   Replace the following:
   - `CLUSTER_VERSION`: the new [supported cluster version](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/reference/supported-versions.md.txt). 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.

   ```bash
   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:

- `ENDPOINT`: Your Google Cloud [service endpoint](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/reference/rest.md.txt#rest_endpoints)
- `PROJECT_ID`: Your Google Cloud project
- `GOOGLE_CLOUD_LOCATION`: the [supported Google Cloud region](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/reference/supported-regions.md.txt) that manages your cluster---for example, `us-west1`
- `CLUSTER_ID`: Your cluster ID

For more information, see the
[`projects.locations.azureClusters.patch`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/reference/rest/v1/projects.locations.azureClusters/patch.md.txt)
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](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/update-node-pool.md.txt).

## What's next

- Learn how to perform other [cluster updates](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/update-cluster.md.txt).

- For more information on updatable fields, see the
  [`gcloud container azure clusters update`](https://docs.cloud.google.com/sdk/gcloud/reference/container/azure/clusters/update)
  reference documentation.

- See the
  [`projects.locations.azureClusters.patch`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/reference/rest/v1/projects.locations.azureClusters/patch.md.txt)
  REST API documentation.