Upgrade operating system (OS) versions in AKS

This article describes OS versions available for Azure Kubernetes Service (AKS) nodes, and best practices for testing and upgrading your OS version.

Supported OS versions

Each node image corresponds to an OS version, which you can specify using OS SKU. You can specify the following parameters when creating clusters and node pools:

• --os-type: OS type, including Linux or Windows. You can't specify the Windows OS type during cluster creation or update.
• --os-sku: Used to specify OS version or OS variant. You can't specify the Windows OS SKU during cluster creation or update. For more information for supported OS SKU options, see Azure AKS CLI or API.
• --kubernetes-version: Version of Kubernetes to use for creating the node pool or cluster.

Best practice guidance

The default OS version is the most recent validated version.

• For Ubuntu, we recommend creating clusters and node pools while specifying --os-type Linux and --os-sku Ubuntu. This will automatically update you to the latest default Ubuntu version based on your Kubernetes version.
• For Azure Linux, we recommend creating clusters and node pools while specifying --os-type Linux and --os-sku AzureLinux. This will automatically update you to the latest default Azure Linux version based on your Kubernetes version.
• For Windows, we recommend creating node pools while specifying --os-type Windows and --os-sku Windows2022. You need to manually update node pools to the next OS version when it's released.

Migrate to a new OS version

When a new OS version releases on AKS, it's supported in preview before it becomes generally available and default. We recommend testing your nonproduction workloads with the new OS version when it becomes available in preview. In order to access preview functions, make sure you have the preview extension installed. You can install the extension using the az extension add --name aks-preview command.

Update OS SKU on an existing node pool

Update the os-sku on an existing node pool using the az aks nodepool update command. In cases where there's a new OS version available in preview, this functionality allows you to migrate your node pool to the new OS version without needing to upgrade your Kubernetes version.

az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --os-type Linux \
    --os-sku Ubuntu \
    --name $NODE_POOL_NAME \
    --node-count 1

You can use the az aks nodepool update command to migrate between any supported Linux os-sku. The command might fail if the target OS doesn't have a supported node image for your Kubernetes version, VM size, or FIPS enablement.

Migrate to Ubuntu 24.04 (preview)

Ubuntu 24.04 is available in preview by specifying --os-sku Ubuntu2404.

• --os-sku Ubuntu2404 doesn't support FIPS.

• Ubuntu 24.04 will be supported in Kubernetes versions 1.32 to 1.38.
• You need to update your OS SKU to a supported OS option before upgrading your Kubernetes version to 1.39+. --os-sku Ubuntu2404 is an option and is intended for testing the new OS Linux version without requiring you to upgrade your Kubernetes version.
• You need the Azure CLI version 18.0.0b5 or later installed and configured. To find your CLI version, run az --version. If you need to install or upgrade, see Install Azure CLI.

Install aks-preview extension

1. Install the aks-preview Azure CLI extension using the az extension add command.

   Important

   AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

   • AKS support policies
   • Azure support FAQ

   az extension add --name aks-preview
   

2. Update to the latest version of the extension using the az extension update command. Ubuntu 24.04 requires a minimum of 18.0.0b5.

   az extension update --name aks-preview
   

Register Ubuntu2404Preview feature flag

1. Register the Ubuntu2404Preview feature flag using the az feature register command.

   az feature register --namespace "Microsoft.ContainerService" --name "Ubuntu2404Preview"
   

2. Verify the registration status using the az feature show command. It takes a few minutes for the status to show Registered.

   az feature show --namespace Microsoft.ContainerService --name Ubuntu2404Preview
   

3. When the status reflects Registered, refresh the registration of the Microsoft.ContainerService resource provider using the az provider register command.

   az provider register --namespace Microsoft.ContainerService
   

Update your node pool to use Ubuntu 24.04

Update to --os-sku Ubuntu2404 on an existing node pool using the az aks nodepool update command.

az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --os-type Linux \
    --os-sku Ubuntu2404 \
    --kubernetes-version 1.32.0 \
    --name $NODE_POOL_NAME \
    --node-count 1

Migrate to Azure Linux 3.0

Azure Linux 3.0 is the default for --os-sku AzureLinux in Kubernetes versions 1.32-1.36. You can also use Azure Linux 3.0 by specifying --os-sku AzureLinux3.

Update your node pool to use Azure Linux 3.0

Update to --os-sku AzureLinux3 on an existing node pool using the az aks nodepool update command.

az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --os-type Linux \
    --os-sku AzureLinux3 \
    --kubernetes-version 1.30.0 \
    --name $NODE_POOL_NAME \
    --node-count 1

Roll back your OS version

In Kubernetes versions where multiple OS versions are supported, you can use the az aks nodepool update command to roll back to a previous OS version.

You might want to roll back your OS version in the following scenarios:

• If you're testing a new OS version and you run into any issues.
• Once you upgrade to a Kubernetes version that supports the new OS version as default, you might want to roll back to the default Ubuntu or AzureLinux OS SKU. This allows you to get future OS versions as a part of your Kubernetes upgrades instead of requiring a node pool update.

Roll back your OS version to the default OS SKU

You can use the az aks nodepool update command to update the os-sku on an existing node pool. In cases where there's a previous OS version supported in your Kubernetes version, this functionality can allow you to roll back your OS version.

Update your OS SKU to Ubuntu on an existing node pool

When updating your node pool to use OS SKU Ubuntu, you'll get the default OS version based on your Kubernetes version. This might trigger an automatic reimage if the OS version changes during the node pool update command.

Update to --os-sku Ubuntuon an existing node pool using the az aks nodepool update command.

az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --os-type Linux \
    --os-sku Ubuntu \
    --name $NODE_POOL_NAME \
    --node-count 1

You can use the az aks nodepool update command to migrate between any supported Linux os-sku. The command might fail if the target OS doesn't have a supported node image for your Kubernetes version, VM size, or FIPS enablement.

Update your OS SKU to Azure Linux on an existing node pool

When updating your node pool to use OS SKU AzureLinux, you'll get the default OS version based on your Kubernetes version. This might trigger an automatic reimage if the OS version changes during the node pool update command.

Update to --os-sku AzureLinux on an existing node pool using the az aks nodepool update command.

az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --os-type Linux \
    --os-sku AzureLinux \
    --name $NODE_POOL_NAME \
    --node-count 1

Roll back to Ubuntu 22.04

• --os-sku Ubuntu2204 doesn't support FIPS.

• Ubuntu 24.04 is supported in Kubernetes versions 1.25 to 1.33.
• --os-sku Ubuntu2204 is intended for roll back to Ubuntu 22.04 on your current Kubernetes version. You need to update your OS SKU to a supported OS option to upgrade your Kubernetes version to 1.34+.

Roll back to --os-sku Ubuntu2204 on an existing node pool using the az aks nodepool update command.

az aks nodepool update \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --os-type Linux \
    --os-sku Ubuntu2204 \
    --kubernetes-version 1.32.0 \
    --name $NODE_POOL_NAME \
    --node-count 1

Next steps

To learn more about node images, node pool upgrades, and node configurations on AKS, see the following resources:

• To learn about nodes and node configurations, see AKS core concepts.
• Configure automatic node image upgrades and schedule them using planned maintenance.
• Apply custom node configurations to modify OS or kubelet settings.
• For information about the latest node images, see the AKS release notes.
• Automatically apply cluster and node pool upgrades with GitHub Actions.