Autoupgrade node OS images in Azure Kubernetes Service (AKS)

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.

Node OS channel changes that cause a reimage

The following node os channel transitions will trigger reimage on the nodes:

Available node OS upgrade channels

The following upgrade channels are available for AKS Standard clusters. (AKS Automatic clusters use the NodeImage channel by default.)

What to choose - SecurityPatch Channel or NodeImage Channel?

For AKS Automatic clusters

AKS Automatic uses the NodeImage channel by default. This channel provides the best balance of security fixes, bug fixes, and manageability for production workloads. The weekly cadence aligns with AKS best practices and is tuned for optimal cluster performance without manual intervention.

No configuration is required - upgrades happen automatically within your maintenance window. You can adjust maintenance windows if you want to control when updates occur, but the channel choice is fixed.

Why NodeImage for AKS Automatic?

• Includes both security fixes and bug fixes for comprehensive stability
• Weekly cadence provides predictable update timing
• Fully managed by AKS with safe deployment practices
• No extra VHD hosting costs
• Optimized for production workloads with recommended defaults

For AKS Standard clusters

If you're using AKS Standard, evaluate your requirements using the comparison below to choose between SecurityPatch or NodeImage channels.

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

Cluster mode comparison

The following table summarizes node OS autoupgrade configuration by cluster mode:

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"
  }
}

Adjust maintenance windows for AKS Automatic clusters

az aks update \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER \
    --node-os-upgrade-channel NodeImage \
    --schedule-config "scheduled-maintenance-window=true" \
    --maintenance-window "frequency=Weekly,day-of-week=Sunday,utc-offset=+00:00,duration-hours=4,start-hour=2"

Update ownership and cadence by channel

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

Node OS autoupgrade 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 the node OS autoupgrade channel value if your cluster autoupgrade channel is node-image. 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"
}

Is node OS autoupgrade configured differently for AKS Automatic?

Yes. AKS Automatic clusters are preconfigured to use the NodeImage channel by default - you don't need to configure anything. This configuration provides:

• Weekly security fixes and bug fixes
• Automatic reimage with safe deployment practices
• Maintenance window control (optional)
• Production-ready defaults optimized for most workloads
• No extra VHD hosting costs

AKS Standard clusters require you to select a channel based on your specific needs. To migrate from AKS Standard to AKS Automatic and benefit from these preconfigured defaults, see What is Azure Kubernetes Service (AKS) Automatic?

Can I change the node OS autoupgrade channel on an AKS Automatic cluster?

No. AKS Automatic clusters use the NodeImage channel, and you can't change this channel. If you need a different channel, use an AKS Standard cluster. However, you can adjust maintenance windows to control when upgrades occur on your AKS Automatic cluster.

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. 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 information, 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 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 patches 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 preceding example, it's 2024.12.01.

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

Related content

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

To learn more about AKS Automatic's preconfigured settings and production-ready defaults, see What is Azure Kubernetes Service (AKS) Automatic?