Tutorial - Upgrade an Azure Kubernetes Service (AKS) cluster

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 using the Azure CLI

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

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

The following example output shows a cluster's current version and lists newer versions under upgrades:

  {
    "agentPoolProfiles": null,
    "controlPlaneProfile": {
      "kubernetesVersion": "1.33.7",
      ...
      "upgrades": [
        {
          "isPreview": null,
          "kubernetesVersion": "1.34.10"
        },
        {
          "isPreview": null,
          "kubernetesVersion": "1.34.9"
        }
      ]
    },
    ...
  }

Get available cluster versions using Azure PowerShell

1. Before you upgrade, check your cluster's current Kubernetes version and region by using the Get-AzAksCluster cmdlet.

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

   The following example output shows the cluster's current version and location:

   Name              CurrentKubernetesVersion      Location
   ----              ------------------------      --------
   myAKSCluster      1.33.7                        westus2
   

2. List the Kubernetes releases available in the region where your cluster resides by using the Get-AzAksVersion cmdlet.

   Get-AzAksVersion -Location westus2 | Where-Object OrchestratorVersion
   

   The following example output shows the regional versions under OrchestratorVersion:

   Default     IsPreview     OrchestratorType     OrchestratorVersion
   -------     ---------     ----------------     -------------------
                             Kubernetes               1.34.10
                             Kubernetes               1.34.9
   True                      Kubernetes               1.33.7
   ...
   

   To identify potential upgrade targets, compare versions newer than your cluster's current version with the Kubernetes version upgrade rules. This cmdlet lists regional availability and doesn't validate the upgrade path for a specific cluster.

Get available cluster versions by using the Azure portal

1. Sign in to the Azure portal.

2. Navigate to your AKS cluster resource.

3. From the service menu, under Settings, select Upgrades.

4. By Kubernetes version, select Upgrade version.

   

5. On the Upgrade Kubernetes version page, select the Kubernetes Version dropdown to view available Kubernetes versions for upgrade.

   

If no upgrades are available, your cluster might already be on the latest available version or the cluster version might be outside the support window. If the version is unsupported and AKS doesn't offer a recovery upgrade, create a new cluster with a supported Kubernetes version and migrate your workloads. For more information, see AKS support policies for Kubernetes versions.

Manually upgrade cluster using the Azure CLI

Upgrade your cluster by using the az aks upgrade command. This example upgrades the cluster to version 1.34.10:

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

The following example output shows the result of upgrading. The kubernetesVersion value now matches the version specified in the example command:

{
  ...
  "agentPoolProfiles": [
    {
      ...
      "count": 3,
      "currentOrchestratorVersion": "1.34.10",
      "maxPods": 110,
      "name": "nodepool1",
      "nodeImageVersion": "AKSUbuntu-2204gen2containerd-202608.26.0",
      "orchestratorVersion": "1.34.10",
      "osType": "Linux",
      "upgradeSettings": {
        "drainTimeoutInMinutes": null,
        "maxSurge": "10%",
        "nodeSoakDurationInMinutes": null,
        "undrainableNodeBehavior": null
      },
      "vmSize": "Standard_DS2_v2",
      ...
    }
  ],
  ...
  "currentKubernetesVersion": "1.34.10",
  "dnsPrefix": "myAKSClust-myResourceGroup-12ab34",
  "enableRbac": false,
  "fqdn": "myaksclust-myresourcegroup-12ab34-cd56e7fg.hcp.westus2.azmk8s.io",
  "id": "/subscriptions/<Subscription ID>/resourcegroups/myResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster",
  "kubernetesVersion": "1.34.10",
  "location": "westus2",
  "name": "myAKSCluster",
  "type": "Microsoft.ContainerService/ManagedClusters"
  ...
}

Manually upgrade cluster using Azure PowerShell

Upgrade your cluster by using the Set-AzAksCluster cmdlet. This example upgrades the cluster to version 1.34.10:

Set-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -KubernetesVersion 1.34.10

The following example output shows the result of upgrading. The KubernetesVersion value now matches the version specified in the example cmdlet:

...
ProvisioningState        : Succeeded
MaxAgentPools            : 100
KubernetesVersion        : 1.34.10
CurrentKubernetesVersion : 1.34.10
...
ResourceGroupName        : myResourceGroup
Name                     : myAKSCluster
Type                     : Microsoft.ContainerService/ManagedClusters
Location                 : westus2
Tags                     :

Manually upgrade cluster using the Azure portal

1. In the Azure portal, navigate to your AKS cluster resource.

2. From the service menu, under Settings, select Upgrades.

3. By Kubernetes version, select Upgrade version.

   

4. On the Upgrade Kubernetes version page, select the Kubernetes Version dropdown to view available Kubernetes versions for upgrade.

   

5. Select the Kubernetes version you want to upgrade to, and then select Save.

Upgrade duration depends on factors such as the number of nodes, surge settings, workload disruption constraints, drain timeout, and node soak duration. The default drain timeout is 30 minutes per node and can be configured from five minutes to 24 hours. Node soak duration can add zero to 30 minutes per node. For more information, see Customize node pool surge and unavailable settings.

Configure automatic cluster upgrades using the Azure CLI

Configure automatic cluster upgrades using Azure PowerShell

Configure automatic cluster upgrades by using the Azure portal

On an AKS Standard cluster, set the autoupgrade channel by using the az aks update command. The following example uses the stable channel:

az aks update --resource-group myResourceGroup --name myAKSCluster --auto-upgrade-channel stable

On an AKS Standard cluster, set the autoupgrade channel by using the Set-AzAksCluster cmdlet. The following example uses the Stable channel:

Set-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -AutoUpgradeChannel Stable

1. In the Azure portal, navigate to your AKS cluster resource.

2. From the service menu, under Settings, select Upgrades.

3. By Kubernetes version, select Upgrade version.

   

4. For an AKS Standard cluster, on the Upgrade Kubernetes version page, select the Automatic upgrade dropdown, select Enabled with stable, and then select Save.

   

Validate an upgrade by using the Azure CLI

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

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

The following example output shows that the AKS cluster runs the target Kubernetes version:

Name          Location    ResourceGroup    KubernetesVersion    CurrentKubernetesVersion  ProvisioningState    Fqdn
------------  ----------  ---------------  -------------------  ------------------------  -------------------  ----------------------------------------------------------------
myAKSCluster  westus2      myResourceGroup  1.34.10              1.34.10                   Succeeded            myaksclust-myresourcegroup-12ab34-cd56e7fg.hcp.westus2.azmk8s.io

Validate an upgrade by using Azure PowerShell

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

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

The following example output shows that the AKS cluster runs the target Kubernetes version:

Name             Location     KubernetesVersion     ProvisioningState
----             --------     -----------------     -----------------
myAKSCluster     westus2       1.34.10               Succeeded

Validate an upgrade using the Azure portal

1. In the Azure portal, navigate to your AKS cluster resource.
2. On the Overview page, under Essentials, check the Kubernetes version to confirm the upgrade was successful.

Delete the cluster using the Azure CLI

Delete the cluster using Azure PowerShell

Delete the cluster by using the Azure portal

Remove the resource group, container service, and all related resources by using the az group delete command.

az group delete --name myResourceGroup --yes --no-wait

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

Remove-AzResourceGroup -Name myResourceGroup

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