Edit

Share via

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.

Caution

In this article, there are references to Ubuntu and Azure Linux OS versions that are being deprecated for AKS:

  • Starting on March 17, 2027, AKS will no longer support Ubuntu 20.04. Existing node images will be deleted and AKS will no longer provide security updates. You'll no longer be able to scale your node pools. Migrate to a supported Ubuntu version by upgrading your node pools to Kubernetes version 1.34+. For more information on this retirement, see Retirement: Ubuntu 20.04 node pools on AKS.
  • As of November 30, 2025, Azure Kubernetes Service (AKS) no longer supports or provides security updates for Azure Linux 2.0. The Azure Linux 2.0 node image is frozen at the 202512.06.0 release. Beginning March 31, 2026, node images will be removed, and you'll be unable to scale your node pools. Migrate to a supported Azure Linux version by upgrading your node pools to a supported Kubernetes version or migrating to osSku AzureLinux3. For more information, see [Retirement] Azure Linux 2.0 node pools on AKS.

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.
OS type OS SKU Supported Kubernetes versions Default versioning
Linux Ubuntu This OS SKU is supported in all Kubernetes versions. OS version for this OS SKU changes based on your Kubernetes version. Ubuntu 22.04 is default for Kubernetes versions 1.25 to 1.34. Ubuntu 24.04 is default for Kubernetes versions 1.35+.
Linux Ubuntu2404 This OS SKU will only be supported in Kubernetes 1.32 to 1.38. We recommend this versioned OS SKU if you want to migrate to the new OS version without upgrading your Kubernetes version. Ubuntu 24.04 is default when using --os-sku Ubuntu in Kubernetes versions 1.35+.
Linux Ubuntu2204 This OS SKU is supported in Kubernetes versions 1.25 to 1.36. We recommend this versioned OS SKU if you need to roll back to Ubuntu 22.04. Ubuntu 22.04 is default when using --os-sku Ubuntu in Kubernetes versions 1.25 to 1.35.
Linux AzureLinux This OS SKU is supported in all Kubernetes versions. OS version for this OS SKU changes based on your Kubernetes version. Azure Linux 2.0 is default for Kubernetes version 1.27 to 1.31. Azure Linux 3.0 is default for Kubernetes version 1.32+. When the AzureLinuxV3Preview feature flag is enabled on AKS 1.31, --os-sku AzureLinux defaults to 3.0.
Linux AzureLinux3 This OS SKU is supported in Kubernetes 1.28 to 1.36. We recommend this OS SKU if you want to test out the new OS version without upgrading your Kubernetes version. You can also use this OS SKU to migrate from Azure Linux 2.0 to Azure Linux 3.0.
Linux AzureLinuxOSGuard This OS SKU is supported in Kubernetes versions 1.32 and above. Azure Linux with OS Guard versions are upgraded through node image upgrades. For more information, see Azure Linux with OS Guard for AKS.
Linux Flatcar This OS SKU is supported in all Kubernetes versions. Flatcar versions are upgraded through node image upgrades. For more information, see Flatcar Container Linux for AKS.
Windows Windows2019 1.14 to 1.32 Default for Windows OS Type in Kubernetes version 1.14 to 1.24.
Windows Windows2022 1.23 to 1.34 Default for Windows OS Type in Kubernetes version 1.25 to 1.34.

Migrate to a new OS version

When a new OS version releases on AKS, it's initially supported in preview. After testing in preview for a few months, AKS makes the new OS version generally available (GA) and then updates the default OS SKU (Ubuntu or AzureLinux) to the latest GA OS version. This default update occurs with a new Kubernetes version release.

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.

There are two ways to migrate to a new OS version:

  • Default OS SKU: If you're using a default OS SKU such as Ubuntu or AzureLinux, you automatically get the latest GA version when you upgrade your Kubernetes version. There are no manual changes required to migrate to a new OS version.
  • Versioned OS SKU: If you're using a versioned OS SKU such as Ubuntu2404, AzureLinux3, or Windows2025, you need to manually migrate to a new OS version to avoid blocked Kubernetes upgrades. If you're using a Linux OS, you can update the OS SKU on an existing node pool to manually migrate.

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.

Note

The following values aren't supported for node pool update command:

  • --os-sku Windows2019
  • --os-sku Windows2022
  • --os-sku Windows2025

Instead, you need to add node pools to your cluster with the corresponding --os-sku you intend to use.

az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --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

Ubuntu 24.04 is the default for --os-sku Ubuntu in Kubernetes versions 1.35+. You can also use Ubuntu 24.04 by specifying --os-sku Ubuntu2404.

Note

Keep the following information in mind when migrating to --os-sku Ubuntu2404:

  • FIPS is not supported.
  • Ubuntu 24.04 is 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 preview Azure CLI version 18.0.0b5 or later for preview and version 2.82.0 for GA installed and configured. To find your CLI version, run az --version. If you need to install or upgrade, see Install Azure CLI.

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-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 to 1.36. You can also use Azure Linux 3.0 by specifying --os-sku AzureLinux3.

Note

Keep the following information in mind when migrating to --os-sku AzureLinux3:

  • --os-sku AzureLinux3 is supported in Kubernetes versions 1.28 to 1.36.
  • --os-sku AzureLinux3 is intended for migrating to Azure Linux 3.0 without upgrading your Kubernetes version. You need to update your OS SKU to a supported OS option before upgrading your Kubernetes version to 1.37+.
  • You need the Azure CLI version 18.0.0b36 or later for preview and version 2.78.0 or later for GA installed and configured. To find your CLI version, run az --version. If you need to install or upgrade, see Install Azure CLI.

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-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.

Note

The following values aren't supported for node pool update command:

  • --os-sku Windows2019
  • --os-sku Windows2022
  • --os-sku Windows2025

Instead, you need to add node pools to your cluster with the corresponding --os-sku you intend to use.

OS SKU Default OS version
Ubuntu When you have OS SKU Ubuntu, Ubuntu 22.04 is the default OS version if your Kubernetes version is 1.25 to 1.34. Ubuntu 24.04 is the default for Ubuntu in Kubernetes 1.35 to 1.37.
AzureLinux When you have OS SKU AzureLinux, Azure Linux 2.0 is the default for AzureLinux in Kubernetes 1.26 to 1.31. Azure Linux 3.0 is the default for AzureLinux in Kubernetes 1.32 to 1.36.

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-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-sku AzureLinux \
    --name $NODE_POOL_NAME \
    --node-count 1

Roll back to Ubuntu 22.04

Note

Keep the following information in mind when migrating to --os-sku Ubuntu2204:

  • FIPS and CVM aren't supported.
  • Ubuntu 22.04 is supported in Kubernetes versions 1.25 to 1.35.
  • --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.36 and above.

Roll back to --os-sku Ubuntu2204 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-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:

  • Last updated on