Upgrade Azure Kubernetes Service (AKS) node images

  • Article

Azure Kubernetes Service (AKS) regularly provides new node images, so it's beneficial to upgrade your node images frequently to use the latest AKS features. Linux node images are updated weekly, and Windows node images are updated monthly. Image upgrade announcements are included in the AKS release notes, and it can take up to a week for these updates to be rolled out across all regions. Node image upgrades can also be performed automatically and scheduled using planned maintenance. For more information, see Automatically upgrade node images.

This article shows you how to upgrade AKS cluster node images and how to update node pool images without upgrading the Kubernetes version. For information on upgrading the Kubernetes version for your cluster, see Upgrade an AKS cluster.

Note

The AKS cluster must use virtual machine scale sets for the nodes.

It's not possible to downgrade a node image version (for example AKSUbuntu-2204 to AKSUbuntu-1804, or AKSUbuntu-2204-202308.01.0 to AKSUbuntu-2204-202307.27.0).

Check for available node image upgrades

Check for available node image upgrades using the az aks nodepool get-upgrades command.

az aks nodepool get-upgrades \
    --nodepool-name mynodepool \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup

The output shows the latestNodeImageVersion, like in the following example:

{
  "id": "/subscriptions/XXXX-XXX-XXX-XXX-XXXXX/resourcegroups/myResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster/agentPools/mynodepool/upgradeProfiles/default",
  "kubernetesVersion": "1.17.11",
  "latestNodeImageVersion": "AKSUbuntu-1604-2020.10.28",
  "name": "default",
  "osType": "Linux",
  "resourceGroup": "myResourceGroup",
  "type": "Microsoft.ContainerService/managedClusters/agentPools/upgradeProfiles",
  "upgrades": null
}

The example output shows AKSUbuntu-1604-2020.10.28 as the latestNodeImageVersion.

Compare the latest version with your current node image version using the az aks nodepool show command.

az aks nodepool show \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --name mynodepool \
    --query nodeImageVersion

Your output should look similar to the following example:

"AKSUbuntu-1604-2020.10.08"

In this example, there's an available node image version upgrade, which is from version AKSUbuntu-1604-2020.10.08 to version AKSUbuntu-1604-2020.10.28.

Upgrade all node images in all node pools

Upgrade the node image using the az aks upgrade command with the --node-image-only flag.

az aks upgrade \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-image-only

You can check the status of the node images using the kubectl get nodes command.

Note

This command may differ slightly depending on the shell you use. For more information on Windows and PowerShell environments, see the Kubernetes JSONPath documentation.

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.kubernetes\.azure\.com\/node-image-version}{"\n"}{end}'

When the upgrade is complete, use the az aks show command to get the updated node pool details. The current node image is shown in the nodeImageVersion property.

az aks show \
    --resource-group myResourceGroup \
    --name myAKSCluster

Upgrade a specific node pool

To update the OS image of a node pool without doing a Kubernetes cluster upgrade, use the az aks nodepool upgrade command with the --node-image-only flag.

az aks nodepool upgrade \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --name mynodepool \
    --node-image-only

You can check the status of the node images with the kubectl get nodes command.

Note

This command may differ slightly depending on the shell you use. For more information on Windows and PowerShell environments, see the Kubernetes JSONPath documentation.

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.kubernetes\.azure\.com\/node-image-version}{"\n"}{end}'

When the upgrade is complete, use the az aks nodepool show command to get the updated node pool details. The current node image is shown in the nodeImageVersion property.

az aks nodepool show \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --name mynodepool

Upgrade node images with node surge

To speed up the node image upgrade process, you can upgrade your node images using a customizable node surge value. By default, AKS uses one extra node to configure upgrades.

If you'd like to increase the speed of upgrades, use the az aks nodepool update command with the --max-surge flag to configure the number of nodes used for upgrades. To learn more about the trade-offs of various --max-surge settings, see Customize node surge upgrade.

az aks nodepool update \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --name mynodepool \
    --max-surge 33% \
    --no-wait

You can check the status of the node images with the kubectl get nodes command.

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.kubernetes\.azure\.com\/node-image-version}{"\n"}{end}'

Use az aks nodepool show to get the updated node pool details. The current node image is shown in the nodeImageVersion property.

az aks nodepool show \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --name mynodepool

Next steps