Tutorial: Upgrade Azure Linux with OS Guard (preview) nodes in an Azure Kubernetes Service (AKS) cluster

Note

Azure Linux with OS Guard (preview) is being replaced by Azure Container Linux (ACL).

Azure Container Linux is the long‑term, immutable, container‑optimized Linux operating system (OS) for Azure Kubernetes Service (AKS). It provides a secure, minimal, and operationally consistent host OS designed to run containerized workloads at scale.

For more information, see the Azure Container Linux (ACL) overview.

Azure Linux with OS Guard ships updates through updated node images and automatic package updates. As part of the application and cluster lifecycle, we recommend keeping your clusters up to date and secured by enabling upgrades for your cluster. You can enable automatic node image upgrades to ensure your clusters use the latest Azure Linux with OS Guard image when it scales up. You can also manually upgrade the node image on a cluster.

In this tutorial, part five of five, you learn how to:

Manually upgrade the node image on a cluster.
Automatically upgrade an Azure Linux with OS Guard cluster.
Deploy Kured in an Azure Linux with OS Guard cluster.

Note

Any upgrade operation, whether performed manually or automatically, upgrades the node image version if it's not already on the latest version. The latest version is contingent on a full AKS release, and you can determine it by visiting the AKS release tracker.

Prerequisites

In previous tutorials, you created and deployed an Azure Linux with OS Guard cluster. To complete this tutorial, you need an existing cluster. If you haven't completed this step and want to follow along, see Tutorial 1: Create a cluster with Azure Linux with OS Guard for AKS.
You need the latest version of Azure CLI. Use the az version command to find the version. To upgrade to the latest version, use the az upgrade command.

Azure Linux with OS Guard considerations and limitations

Before you begin, review the following considerations and limitations for Azure Linux with OS Guard (preview):

Kubernetes version 1.32.0 or higher is required for Azure Linux with OS Guard.
All Azure Linux with OS Guard images have Federal Information Process Standard (FIPS) and Trusted Launch enabled.
Azure CLI and ARM templates are the only supported deployment methods for Azure Linux with OS Guard on AKS in preview. PowerShell and Terraform aren't supported.
NodeImage and None are the only supported operating system (OS) upgrade channels for Azure Linux with OS Guard on AKS. Unmanaged and SecurityPatch are incompatible with Azure Linux with OS Guard due to the immutable /usr directory.
Artifact Streaming isn't supported.
Pod Sandboxing isn't supported.
Confidential Virtual Machines (CVMs) aren't supported.
Gen 1 virtual machines (VMs) aren't supported.

Manually upgrade your cluster

Manually upgrade the node image on your cluster using the az aks nodepool upgrade command.

az aks nodepool upgrade --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name <node-pool-name>

Automatically upgrade your cluster

Automatic upgrades are functionally the same as manual upgrades. The selected channel determines the timing of upgrades. When making changes to auto-upgrade, allow 24 hours for the changes to take effect.

Set the auto-upgrade channel on an existing cluster using the az aks update command with the --auto-upgrade-channel parameter. The following example sets the auto-upgrade channel to stable for an existing cluster:

az aks update --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --auto-upgrade-channel stable

Example output:

{
  "id": "/subscriptions/xxxxx/resourceGroups/testAzureLinuxResourceGroup",
  "location": "chinanorth3",
  "name": "testAzureLinuxCluster",
  "properties": {
    "autoUpgradeChannel": "stable",
    "provisioningState": "Succeeded"
  }
}

For more information on upgrade channels, see Using cluster auto-upgrade.

Automatically upgrade your node OS image

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

Important

NodeImage and None are the only supported operating system (OS) upgrade channels for Azure Linux with OS Guard on AKS. Unmanaged and SecurityPatch are incompatible with Azure Linux with OS Guard due to the immutable /usr directory.

Set the node OS upgrade channel on an existing cluster using the az aks update command with the --node-os-upgrade-channel parameter. The following example sets the node OS upgrade channel to NodeImage for an existing cluster:

az aks update --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --node-os-upgrade-channel NodeImage

Example output:

{
  "id": "/subscriptions/xxxxx/resourceGroups/testAzureLinuxResourceGroup",
  "location": "chinanorth3",
  "name": "testAzureLinuxCluster",
  "properties": {
    "nodeOsUpgradeChannel": "NodeImage",
    "provisioningState": "Succeeded"
  }
}

For more information on node upgrade channels, see Using node OS auto-upgrade.

Clean up resources

As this tutorial is the last part of the series, you might want to delete your Azure Linux with OS Guard cluster. The Kubernetes nodes run on Azure virtual machines (VMs) and continue incurring charges even if you don't use the cluster.

Delete the Azure resource group and all related resources using the az group delete command.

az group delete --name $RESOURCE_GROUP --yes --no-wait

Next steps

In this tutorial, you upgraded your Azure Linux Container Host cluster.

For more information on Azure Linux with OS Guard, see the Azure Linux with OS Guard overview.

Last updated on 2026-06-11