Edit

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.
  • To perform upgrade operations, you need the Azure Kubernetes Service Contributor Role or equivalent permissions.
  • Beta APIs are disabled by default when you upgrade to Kubernetes version 1.30 and 1.27 LTS versions.

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 non-LTS 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.

An LTS cluster can skip minor versions when moving to a higher LTS version offered by AKS, provided the upgrade satisfies version-skew requirements and validation checks. For more information, see Can I skip multiple AKS versions during a cluster upgrade?.

Starting with Kubernetes 1.28, the control plane can be up to three minor versions ahead of node pools. For example, if your control plane is at 1.35.x, your node pools can be at 1.32.x, 1.33.x, 1.34.x, or 1.35.x. For current constraints, see the AKS version skew policy.

Check for available AKS upgrades

Tip

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

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

Upgrade the AKS control plane only

Important

You can't perform a control-plane-only upgrade when cluster autoupgrade is enabled. Cluster autoupgrade always upgrades the control plane and all node pools together.

  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 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.

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.

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

AKS control plane upgrade frequently asked questions (FAQ)

Does a control-plane-only upgrade also upgrade node pools?

No. A control-plane-only upgrade doesn't change node pools. Cluster autoupgrade works differently: it doesn't support control-plane-only upgrades and upgrades the control plane and all node pools together.

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?

Upgrade duration varies based on the cluster state and Azure conditions. Monitor provisioningState using az aks show or Get-AzAksCluster. The upgrade is complete when the provisioning state is Succeeded.

Resolve control plane upgrade issues

No upgrades available

For an unsupported cluster, use az aks get-upgrades to check whether AKS offers an eligible supported target. If a target is available, perform a full-cluster upgrade. Control-plane-only upgrades aren't supported for this recovery path.

If no target is available, your cluster might already be on the latest supported version. If the cluster is running an unsupported version, 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

The command scans resources accessible through the current kubeconfig context for deprecated Kubernetes API versions. The output groups findings by Kubernetes version and identifies each affected resource by KIND, NAMESPACE, NAME, and API_VERSION. Update the source manifest for every listed resource to use a supported API version before upgrading.

Related content

  • Last updated on