Skip to content

K8s Upgrades

Performing upgrades of Amazon AKS Clusters is supported in the Controller

In Place Upgrades Notification

The administrator is shown a notification when an upgrade is available for a cluster. Clicking on the notification will provide the administrator with additional information on what is available.

  • A red banner appearing as Upgrade Available indicates that the cluster is multiple version(s) behind the latest version
  • A blue banner appearing as Upgrade Available indicates that the cluster is one version behind the latest version
  • A blue banner appearing as Upgrade Nodepools indicates that the Nodepool is one or multiple version(s) behind the current control plane's version

Upgrade Notification

Upgrade Note

  • In version 1.27, AKS clusters will have KMS v2 configured by default when KMS is enabled. Customers with clusters on v1.26 and below, with KMS enabled, will not be able to upgrade to v1.27 if clusters have the v1 version of KMS running. Attempting to upgrade to 1.27 with the v1 version of KMS will result in a failure at the preflight check stage. Please follow the steps outlined in this documentation for migrating from KMS v1 to v2, and then proceed with upgrading the cluster to version v1.27.

  • In version 1.25, Pod Security Policies (PSPs) have been removed. Therefore, if a cluster has any detected PSPs, the update to version 1.25 will be prevented for AKS clusters.

Scope of Upgrade

Two components need to be upgraded during an AKS Cluster upgrade

  1. AKS Control Plane
  2. Attached Node Groups (both Managed and Self Managed)

The Control plane always needs to be upgraded first before the node groups


AKS Cluster upgrades performed by the controller are always performed in a manner where the cluster and resident workloads never encounter any downtime

Upgrade Everything

This is the default option. When selected, it upgrades everything to the new version of k8s i.e.

  • AKS Control Plane
  • All Node Pools (Both Managed and Self Managed)

Upgrade Default


Upgrading the entire AKS cluster can take ~15 minutes.

During the upgrade, an indication is provided to administrators on the main cluster list page. An illustrative example is shown below.

Cluster Upgrade Indication

Preflight Checks

A number of preflight checks are first performed before the upgrade is attempted

Upgrade AKS Control Plane

The AKS control plane is upgraded next. This can be a time-consuming step

Preflight Checks

Upgrade Node Pools

Node Pools are then upgraded to the selected version of k8s. Shown below is an example of an AKS Cluster's Upgrading Node pools progress

Upgraded Node pool

Post Upgrade Validations

Once upgrade is complete, a round of post-upgrade tests are performed to ensure that there are no loose ends and everything is as expected

Nodepool Provision complete

Once the Nodepool provision is complete, the status is shown in the Node Pools screen as Nodepool Provision Complete

Node Pool Upgrade Success

Control Plane Only Upgrade

Users can select Control Plane Only for upgrade. The attached node groups are left untouched. The administrators are allowed to upgrade the node groups individually one by one when required

Upgrade Control Plane Only

Node Pool Upgrade

This option is displayed to the administrator only if the controller detects that the node group is behind the AKS Control Plane from a Kubernetes version perspective.

  • Click the cluster name and select Node Pools tab
  • Click on upgrade notification for available node groups

Node Pool Upgrade

  • Select Upgrade to latest Image and click Upgrade Node Pool

Node Pool Image upgrade

Delete Node Pool

Utilize the Delete icon to removed the deployed node pool(s) within an AKS cluster.

Node Pool Upgrade

Upgrade History

The Controller maintains the upgrade history associated with every upgrade action whether it was successful or not. Administrators can view the entire history through the following steps

  • Click the Cluster name and select Upgrade Jobs

This will display the entire history of upgrades for that specific cluster

Upgrade History

Upgrade Details

To view the detailed information of an upgrade, click the eye icon of that specific row. An illustrative example is shown below

Upgrade History Detail