title	description	ms.topic	ms.date	author	ms.author	ms.custom
Kubernetes on Azure tutorial - Upgrade an Azure Kubernetes Service (AKS) cluster	In this Azure Kubernetes Service (AKS) tutorial, you learn how to upgrade an existing AKS cluster to the latest available Kubernetes version.	tutorial	11/02/2023	schaffererin	schaffererin	mvc, devx-track-azurepowershell

Tutorial - Upgrade an Azure Kubernetes Service (AKS) cluster

As part of the application and cluster lifecycle, you might want to upgrade to the latest available version of Kubernetes. You can upgrade your Azure Kubernetes Service (AKS) cluster using the Azure CLI, Azure PowerShell, or the Azure portal.

In this tutorial, part seven of seven, you upgrade an AKS cluster. You learn how to:

[!div class="checklist"]

Identify current and available Kubernetes versions.

Upgrade your Kubernetes nodes.

Validate a successful upgrade.

Before you begin

In previous tutorials, you packaged an application into a container image and uploaded the container image to Azure Container Registry (ACR). You also created an AKS cluster and deployed an application to it. If you haven't completed these steps and want to follow along, start with Tutorial 1 - Prepare application for AKS.

If using Azure CLI, this tutorial requires Azure CLI version 2.34.1 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

If using Azure PowerShell, this tutorial requires Azure PowerShell version 5.9.0 or later. Run Get-InstalledModule -Name Az to find the version. If you need to install or upgrade, see Install Azure PowerShell.

Get available cluster versions

Azure CLI

Before you upgrade, check which Kubernetes releases are available for your cluster using the az aks get-upgrades command.

az aks get-upgrades --resource-group myResourceGroup --name myAKSCluster

The following example output shows the current version as 1.26.6 and lists the available versions under upgrades:

{
  "agentPoolProfiles": null,
  "controlPlaneProfile": {
    "kubernetesVersion": "1.26.6",
    ...
    "upgrades": [
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.1"
      },
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.3"
      }
    ]
  },
  ...
}

Azure PowerShell

Before you upgrade, check which Kubernetes releases are available for your cluster and the region where your cluster resides using the Get-AzAksCluster cmdlet.

Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster |
  Select-Object -Property Name, KubernetesVersion, Location

The following example output shows the current version as 1.26.6 and the location as eastus:

Name            KubernetesVersion       Location
----            -----------------       --------
myAKSCluster    1.26.6                  eastus

Check which Kubernetes upgrade releases are available in the region where your cluster resides using the Get-AzAksVersion cmdlet.

Get-AzAksVersion -Location eastus | Where-Object OrchestratorVersion

The following example output shows the available versions under OrchestratorVersion:

Default     IsPreview     OrchestratorType     OrchestratorVersion
-------     ---------     ----------------     -------------------
                          Kubernetes           1.27.1
                          Kubernetes           1.27.3

Azure portal

Sign in to the Azure portal.
Navigate to your AKS cluster.
Under Settings, select Cluster configuration.
In Kubernetes version, select Upgrade version. This redirects you to a new page.
In Kubernetes version, select the version to check for available upgrades.

:::image type="content" source="media/tutorial-kubernetes-upgrade-cluster/upgrade-kubernetes-version.png" alt-text="Screenshot of the Upgrade version screen.":::

If no upgrades are available, create a new cluster with a supported version of Kubernetes and migrate your workloads from the existing cluster to the new cluster. It's not supported to upgrade a cluster to a newer Kubernetes version when no upgrades are available.

Upgrade an AKS cluster

AKS nodes are carefully cordoned and drained to minimize any potential disruptions to running applications. During this process, AKS performs the following steps:

Adds a new buffer node (or as many nodes as configured in max surge) to the cluster that runs the specified Kubernetes version.
Cordons and drains one of the old nodes to minimize disruption to running applications. If you're using max surge, it cordons and drains as many nodes at the same time as the number of buffer nodes specified.
When the old node is fully drained, it's reimaged to receive the new version and becomes the buffer node for the following node to be upgraded.
This process repeats until all nodes in the cluster have been upgraded.
At the end of the process, the last buffer node is deleted, maintaining the existing agent node count and zone balance.

[!INCLUDE alias minor version callout]

You can either manually upgrade your cluster or configure automatic cluster upgrades. We recommend you configure automatic cluster upgrades to ensure your cluster is always running the latest version of Kubernetes.

Manually upgrade cluster

Azure CLI

Upgrade your cluster using the az aks upgrade command.

az aks upgrade \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --kubernetes-version KUBERNETES_VERSION

[!NOTE] You can only upgrade one minor version at a time. For example, you can upgrade from 1.14.x to 1.15.x, but you can't upgrade from 1.14.x to 1.16.x directly. To upgrade from 1.14.x to 1.16.x, you must first upgrade from 1.14.x to 1.15.x, then perform another upgrade from 1.15.x to 1.16.x.

The following example output shows the result of upgrading to 1.27.3. Notice the kubernetesVersion now shows 1.27.3:

{
  "agentPoolProfiles": [
    {
      "count": 3,
      "maxPods": 110,
      "name": "nodepool1",
      "osType": "Linux",
      "vmSize": "Standard_DS1_v2",
    }
  ],
  "dnsPrefix": "myAKSClust-myResourceGroup-19da35",
  "enableRbac": false,
  "fqdn": "myaksclust-myresourcegroup-19da35-bd54a4be.hcp.eastus.azmk8s.io",
  "id": "/subscriptions/<Subscription ID>/resourcegroups/myResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster",
  "kubernetesVersion": "1.27.3",
  "location": "eastus",
  "name": "myAKSCluster",
  "type": "Microsoft.ContainerService/ManagedClusters"
}

Azure PowerShell

Upgrade your cluster using the Set-AzAksCluster cmdlet.

Set-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -KubernetesVersion <KUBERNETES_VERSION>

[!NOTE] You can only upgrade one minor version at a time. For example, you can upgrade from 1.14.x to 1.15.x, but you can't upgrade from 1.14.x to 1.16.x directly. To upgrade from 1.14.x to 1.16.x, first upgrade from 1.14.x to 1.15.x, then perform another upgrade from 1.15.x to 1.16.x.

The following example output shows the result of upgrading to 1.27.3. Notice the KubernetesVersion now shows 1.27.3:

ProvisioningState       : Succeeded
MaxAgentPools           : 100
KubernetesVersion       : 1.27.3
PrivateFQDN             :
AgentPoolProfiles       : {default}
Name                    : myAKSCluster
Type                    : Microsoft.ContainerService/ManagedClusters
Location                : eastus
Tags                    : {}

Azure portal

In the Azure portal, navigate to your AKS cluster.
Under Settings, select Cluster configuration.
In Kubernetes version, select Upgrade version. This redirects you to a new page.
In Kubernetes version, select your desired version and then select Save.

:::image type="content" source="media/tutorial-kubernetes-upgrade-cluster/available-upgrade-versions.png" alt-text="Screenshot of the Upgrade version screen with available upgrade versions.":::

It takes a few minutes to upgrade the cluster, depending on how many nodes you have.

Configure automatic cluster upgrades

Azure CLI

Set an auto-upgrade channel on your cluster using the az aks update command with the --auto-upgrade-channel parameter set to patch.
```
az aks update --resource-group myResourceGroup --name myAKSCluster --auto-upgrade-channel patch
```

Azure PowerShell

Set an auto-upgrade channel on your cluster using the Set-AzAksCluster cmdlet with the -AutoUpgradeChannel parameter set to Patch.
```
Set-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -AutoUpgradeChannel Patch
```

Azure portal

In the Azure portal, navigate to your AKS cluster.
Under Settings, select Cluster configuration.
In Kubernetes version, select Upgrade version.
For Automatic upgrade, select Enabled with patch (recommended) > Save.

:::image type="content" source="media/tutorial-kubernetes-upgrade-cluster/automatic-upgrade-kubernetes-version.png" alt-text="Screenshot of the Upgrade version screen with the Automatic upgrade option set to Enabled with patch (recommended).":::

For more information, see Automatically upgrade an Azure Kubernetes Service (AKS) cluster.

Upgrade AKS node images

AKS regularly provides new node images. Linux node images are updated weekly, and Windows node images are updated monthly. We recommend upgrading your node images frequently to use the latest AKS features and security updates. For more information, see Upgrade node images in Azure Kubernetes Service (AKS). To configure automatic node image upgrades, see Automatically upgrade Azure Kubernetes Service (AKS) cluster node operating system images.

View the upgrade events

Note

When you upgrade your cluster, the following Kubernetes events might occur on the nodes:

Surge: Create a surge node.
Drain: Evict pods from the node. Each pod has a five minute timeout to complete the eviction.
Update: Update of a node has succeeded or failed.
Delete: Delete a surge node.

View the upgrade events in the default namespaces using the kubectl get events command.

kubectl get events --field-selector source=upgrader

The following example output shows some of the above events listed during an upgrade:

...
default 2m1s Normal Drain node/aks-nodepool1-96663640-vmss000001 Draining node: [aks-nodepool1-96663640-vmss000001]
...
default 9m22s Normal Surge node/aks-nodepool1-96663640-vmss000002 Created a surge node [aks-nodepool1-96663640-vmss000002 nodepool1] for agentpool %!s(MISSING)
...

Validate an upgrade

Azure CLI

Confirm the upgrade was successful using the az aks show command.

az aks show --resource-group myResourceGroup --name myAKSCluster --output table

The following example output shows the AKS cluster runs KubernetesVersion 1.27.3:

Name          Location    ResourceGroup    KubernetesVersion    CurrentKubernetesVersion  ProvisioningState    Fqdn
------------  ----------  ---------------  -------------------  ------------------------  -------------------  ----------------------------------------------------------------
myAKSCluster  eastus      myResourceGroup  1.27.3               1.27.3                    Succeeded            myaksclust-myresourcegroup-19da35-bd54a4be.hcp.eastus.azmk8s.io

Azure PowerShell

Confirm the upgrade was successful using the Get-AzAksCluster cmdlet.

Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster |
  Select-Object -Property Name, Location, KubernetesVersion, ProvisioningState

The following example output shows the AKS cluster runs KubernetesVersion 1.27.3:

Name         Location   KubernetesVersion   ProvisioningState
----         --------   -----------------   -----------------
myAKSCluster eastus     1.27.3              Succeeded

Azure portal

In the Azure portal, navigate to your AKS cluster.
On the Overview page, select the Kubernetes version and ensure it's the latest version you installed in the previous step.

:::image type="content" source="media/tutorial-kubernetes-upgrade-cluster/validate-kubernetes-upgrade.png" alt-text="Screenshot of the Upgrade version screen with the current updated Kubernetes version.":::

Delete the cluster

As this tutorial is the last part of the series, you might want to delete your AKS cluster to avoid incurring Azure charges.

Azure CLI

Remove the resource group, container service, and all related resources using the az group delete command.
```
az group delete --name myResourceGroup --yes --no-wait
```

Azure PowerShell

Remove the resource group, container service, and all related resources using the Remove-AzResourceGroup cmdlet.
```
Remove-AzResourceGroup -Name myResourceGroup
```

Azure portal

In the Azure portal, navigate to your AKS cluster.
On the Overview page, select Delete.
On the Delete cluster confirmation page, select Delete.

:::image type="content" source="media/tutorial-kubernetes-upgrade-cluster/delete-cluster-confirmation.png" alt-text="Screenshot of the Delete cluster confirmation screen.":::

Note

When you delete the cluster, the Microsoft Entra service principal used by the AKS cluster isn't removed. For steps on how to remove the service principal, see AKS service principal considerations and deletion. If you used a managed identity, the identity is managed by the platform and doesn't require that you provision or rotate any secrets.

Next steps

In this tutorial, you upgraded Kubernetes in an AKS cluster. You learned how to:

[!div class="checklist"]

Identify current and available Kubernetes versions.

Upgrade your Kubernetes nodes.

Validate a successful upgrade.

For more information on AKS, see the AKS overview. For guidance on how to create full solutions with AKS, see the AKS solution guidance.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tutorial-kubernetes-upgrade-cluster.md

tutorial-kubernetes-upgrade-cluster.md

Tutorial - Upgrade an Azure Kubernetes Service (AKS) cluster

Before you begin

Get available cluster versions

Azure CLI

Azure PowerShell

Azure portal

Upgrade an AKS cluster

Manually upgrade cluster

Azure CLI

Azure PowerShell

Azure portal

Configure automatic cluster upgrades

Azure CLI

Azure PowerShell

Azure portal

Upgrade AKS node images

View the upgrade events

Validate an upgrade

Azure CLI

Azure PowerShell

Azure portal

Delete the cluster

Azure CLI

Azure PowerShell

Azure portal

Next steps

Files

tutorial-kubernetes-upgrade-cluster.md

Latest commit

History

tutorial-kubernetes-upgrade-cluster.md

File metadata and controls

Tutorial - Upgrade an Azure Kubernetes Service (AKS) cluster

Before you begin

Get available cluster versions

Upgrade an AKS cluster

Manually upgrade cluster

Configure automatic cluster upgrades

Upgrade AKS node images

View the upgrade events

Validate an upgrade

Delete the cluster

Next steps