Upgrade the Azure Kubernetes Service (AKS) cluster control plane

Azure Kubernetes Service (AKS) clusters consist of two main components: the control plane managed by Azure and the node pools where your workloads run. This article focuses on upgrading the control plane independently, which allows you to adopt new Kubernetes versions for API server features while separately managing node pool upgrades.

Before you begin

• If you're using the Azure CLI, this article requires Azure CLI version 2.34.1 or later. Use the az --version command to find the version. If you need to install or upgrade, see Install Azure CLI.
• If you're using Azure PowerShell, this article requires Azure PowerShell version 5.9.0 or later. Use the Get-InstalledModule -Name Az cmdlet to find the version. If you need to install or upgrade, see Install Azure PowerShell.
• Performing upgrade operations requires the Microsoft.ContainerService/managedClusters/agentPools/write RBAC role. For more on Azure RBAC roles, see the Azure resource provider operations.
• Starting with Kubernetes version 1.30 and 1.27 LTS versions, beta APIs are disabled by default when you upgrade to them.

Warning

Ensure you have sufficient compute quota before upgrading. If quota is low, the upgrade might fail. For more information, see increase quotas.

Overview of AKS upgrade types

The following table outlines three types of AKS upgrades, highlighting their scope and use cases:

Upgrade type	Scope	Use case
Control plane only	API server, etcd, controller manager, scheduler	Test new Kubernetes APIs before upgrading workloads
Full cluster	Control plane and all node pools	Standard upgrade to keep cluster up to date
Node pool only	Specific node pools	Staged rollout after control plane upgrade

Tip

Upgrading the control plane first allows you to validate Kubernetes API compatibility before affecting running workloads. For node pool upgrade strategies, see Configure rolling upgrades.

Kubernetes version upgrade rules

When you upgrade a supported AKS cluster, you can't skip Kubernetes minor versions. You must perform all upgrades sequentially by minor version number. For example, upgrades between 1.28.x -> 1.29.x or 1.29.x -> 1.30.x are allowed. 1.28.x -> 1.30.x isn't allowed.

The control plane can be up to two minor versions ahead of node pools. For example, if your control plane is at 1.30.x, your node pools can be at 1.28.x, 1.29.x, or 1.30.x.

Check for available AKS upgrades

Tip

To stay up to date with the latest AKS releases and updates, see the AKS release tracker.

Azure CLI

Check for available Kubernetes releases for your AKS cluster using the az aks get-upgrades command.

az aks get-upgrades --resource-group <resource-group-name> --name <cluster-name> --output table

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

Name     ResourceGroup          MasterVersion    Upgrades
-------  ---------------        ---------------  --------------
default  <resource-group-name>  1.28.9           1.29.2, 1.29.4

Azure PowerShell

Check for available Kubernetes releases for your AKS cluster using the Get-AzAksVersion cmdlet.

Get-AzAksVersion -Location <your-region> | Where-Object OrchestratorVersion

Azure portal

1. Sign in to the Azure portal and navigate to your AKS cluster resource.
2. Under Settings, select Cluster configuration.
3. For Kubernetes version, select Upgrade version to see available upgrades.

The Azure portal highlights deprecated APIs between your current version and available target versions.

Upgrade the AKS control plane only

Azure CLI

1. Upgrade the control plane using the az aks upgrade command with the --control-plane-only flag. The following example upgrades the control plane to Kubernetes version 1.29.4:

   az aks upgrade \
       --resource-group <resource-group-name> \
       --name <cluster-name> \
       --kubernetes-version 1.29.4 \
       --control-plane-only
   

2. Confirm the control plane upgrade was successful using the az aks show command.

   az aks show --resource-group <resource-group-name> --name <cluster-name> --output table
   

   The following example output shows the control plane now runs 1.29.4:

   Name            Location    ResourceGroup          KubernetesVersion    ProvisioningState    Fqdn
   ------------    ----------  ---------------        -------------------  -------------------  ------------------------------------------------
   <cluster-name>  eastus      <resource-group-name>  1.29.4               Succeeded            <cluster-name>-dns-123abcd4.hcp.eastus.azmk8s.io
   

3. Verify the node pool versions remain unchanged using the [az aks nodepool list][az-aks-nodepool-list] command.

   az aks nodepool list --resource-group <resource-group-name> --cluster-name <cluster-name> --query "[].{Name:name,Version:orchestratorVersion}" --output table
   

   In the output, the node pools should still show the previous Kubernetes version.

Azure PowerShell

1. Upgrade the control plane using the Set-AzAksCluster cmdlet with the -ControlPlaneOnly parameter. The following example upgrades the control plane to Kubernetes version 1.29.4:

   Set-AzAksCluster -ResourceGroupName <resource-group-name> -Name <cluster-name> -KubernetesVersion 1.29.4 -ControlPlaneOnly
   

2. Confirm the upgrade was successful using the [Get-AzAksCluster][get-azakcluster] cmdlet.

   Get-AzAksCluster -ResourceGroupName <resource-group-name> -Name <cluster-name> |
    Format-Table -Property Name, Location, KubernetesVersion, ProvisioningState
   

Azure portal

1. Sign in to the Azure portal and navigate to your AKS cluster resource.
2. Under Settings, select Cluster configuration.
3. Select Upgrade version > Control plane only.
4. Select the desired Kubernetes version > Save.

Upgrade the full AKS cluster

Note

During a full cluster upgrade, AKS upgrades the control plane first, then upgrades each node pool sequentially. For more control over node pool upgrades, see Configure rolling upgrades.

Azure CLI

Upgrade the full cluster (control plane and all node pools) using the az aks upgrade command. The following example upgrades the cluster to Kubernetes version 1.29.4:

az aks upgrade \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --kubernetes-version 1.29.4

Azure PowerShell

Upgrade the full cluster (control plane and all node pools) using the Set-AzAksCluster cmdlet. The following example upgrades the cluster to Kubernetes version 1.29.4:

Set-AzAksCluster -ResourceGroupName <resource-group-name> -Name <cluster-name> -KubernetesVersion 1.29.4

Azure portal

1. Sign in to the Azure portal and navigate to your AKS cluster resource.
2. Under Settings, select Cluster configuration.
3. Select Upgrade version > Control plane and all node pools.
4. Select the desired Kubernetes version > Save.

Frequently asked questions (FAQs)

Why were my node pools upgraded when I only upgraded the control plane?

AKS might trigger a rolling node pool upgrade alongside a control plane upgrade to keep the cluster compliant and healthy. This upgrade typically occurs when a previous node upgrade failed or left nodes on mixed versions.

Can I upgrade node pools before the control plane?

No. The control plane version must always be equal to or greater than any node pool version. You must upgrade the control plane first.

How long does a control plane upgrade take?

Control plane upgrades typically complete within 5-15 minutes, depending on cluster configuration and Azure region load. Node pool upgrades take longer as they involve draining and reimaging nodes.

Resolve control plane upgrade issues

No upgrades available

If az aks get-upgrades shows no available upgrades, your cluster might be:

• Already on the latest supported version.
• On an unsupported version that requires migration.

For unsupported versions, create a new cluster with a supported version and migrate your workloads.

Upgrade failed due to deprecated APIs

Before upgrading, check for deprecated APIs using tools like kube-no-trouble (kubent):

kubent

Update your manifests to use supported API versions before upgrading.

Related content

• Configure rolling upgrades for node pools
• Configure automatic cluster upgrades
• Upgrade node OS images