autoupgrade node OS images

AKS provides multiple autoupgrade channels dedicated to timely node-level OS security updates. This channel is different from cluster-level Kubernetes version upgrades and supersedes it.

Interactions between node OS autoupgrade and cluster autoupgrade

Node-level OS security updates are released at a faster rate than Kubernetes patch or minor version updates. The node OS autoupgrade channel grants you flexibility and enables a customized strategy for node-level OS security updates. Then, you can choose a separate plan for cluster-level Kubernetes version autoupgrades. It's best to use both cluster-level autoupgrades and the node OS autoupgrade channel together. Scheduling can be fine-tuned by applying two separate sets of maintenance windows - aksManagedAutoUpgradeSchedule for the cluster autoupgrade channel and aksManagedNodeOSUpgradeSchedule for the node OS autoupgrade channel.

Channels for node OS image upgrades

The selected channel determines the timing of upgrades. When making changes to node OS auto-upgrade channels, allow up to 24 hours for the changes to take effect.

The following upgrade channels are available. You're allowed to choose one of these options:

What to choose - SecurityPatch Channel or NodeImage Channel?

There are two important considerations for you to choose between SecurityPatch or NodeImage channels.

Set the node OS autoupgrade channel on a new cluster

export RANDOM_SUFFIX=$(openssl rand -hex 3)
export RESOURCE_GROUP="myResourceGroup$RANDOM_SUFFIX"
export AKS_CLUSTER="myAKSCluster$RANDOM_SUFFIX"
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER \
    --node-os-upgrade-channel SecurityPatch \
    --generate-ssh-keys

Set the node OS autoupgrade channel on an existing cluster

az aks update --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER --node-os-upgrade-channel SecurityPatch

{
  "autoUpgradeProfile": {
      "nodeOsUpgradeChannel": "SecurityPatch"
  }
}

Update ownership and schedule

The default cadence means there's no planned maintenance window applied.

Node channel known limitations

• Currently, when you set the cluster autoupgrade channel to node-image, it also automatically sets the node OS autoupgrade channel to NodeImage. You can't change node OS autoupgrade channel value if your cluster autoupgrade channel is node-image. In order to set the node OS autoupgrade channel value, check the cluster autoupgrade channel value isn't node-image.

• The SecurityPatch channel isn't supported on Windows OS node pools.

Node OS planned maintenance windows

Planned maintenance for the node OS autoupgrade starts at your specified maintenance window.

For more information on Planned Maintenance, see Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster.

Node OS autoupgrades FAQ

How can I check the current nodeOsUpgradeChannel value on a cluster?

Run the az aks show command and check the "autoUpgradeProfile" to determine what value the nodeOsUpgradeChannel is set to:

az aks show --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER --query "autoUpgradeProfile"

Results:

{
  "nodeOsUpgradeChannel": "SecurityPatch"
}

How can I monitor the status of node OS autoupgrades?

To view the status of your node OS auto upgrades, look up activity logs on your cluster. You can also look up specific upgrade-related events as mentioned in Upgrade an AKS cluster. AKS also emits upgrade-related Event Grid events. To learn more, see AKS as an Event Grid source.

Can I change the node OS autoupgrade channel value if my cluster autoupgrade channel is set to node-image?

No. Currently, when you set the cluster autoupgrade channel to node-image, it also automatically sets the node OS autoupgrade channel to NodeImage. You can't change the node OS autoupgrade channel value if your cluster autoupgrade channel is node-image. In order to be able to change the node OS autoupgrade channel values, make sure the cluster autoupgrade channel isn't node-image.

Why is SecurityPatch recommended over Unmanaged channel?

On the Unmanaged channel, AKS has no control over how and when the security updates are delivered. With SecurityPatch, the security updates are fully tested and follow safe deployment practices. SecurityPatch also honors maintenance windows. For more details, see Increased security and resiliency of Canonical workloads on Azure.

Does SecurityPatch always lead to a reimage of my nodes?

AKS limits reimages to only when absolutely necessary, such as certain kernel packages that may require a reimage to get fully applied. SecurityPatch is designed to minimize disruptions as much as possible. If AKS decides reimaging nodes isn't necessary, it will patch nodes live without draining pods and no VHD update is performed in such cases.

Why does SecurityPatch channel requires to reach snapshot.ubuntu.com endpoint?

With the SecurityPatch channel, the Linux cluster nodes have to download the required security patches and updates from ubuntu snapshot service described in ubuntu-snapshots-on-azure-ensuring-predictability-and-consistency-in-cloud-deployments.

How do I know if a SecurityPatch or NodeImage upgrade is applied on my node?

Run the kubectl get nodes --show-labels command to list the nodes in your cluster and their labels.

Among the returned labels, you should see a line similar to the following output:

kubernetes.azure.com/node-image-version=AKSUbuntu-2204gen2containerd-202410.27.0-2024.12.01

Here, the base node image version is AKSUbuntu-2204gen2containerd-202410.27.0. If applicable, the security patch version typically follows. In the above example, it's 2024.12.01.

The same details also be looked up in the Azure portal under the node label view:

Next steps

For a detailed discussion of upgrade best practices and other considerations, see AKS patch and upgrade guidance.