Edit

Share via

Use Windows Annual Channel for Containers on Azure Kubernetes Service (AKS) (Preview)

  • Article

AKS supports Windows Server Annual Channel for Containers in public preview. Each channel version is released annually and is supported for two years. This channel is beneficial if you require increased innovation cycles and portability.

Windows Annual Channel versions are based on the Kubernetes version of your node pool. To upgrade from one Annual Channel version to the next, you can upgrade to a Kubernetes version that supports the next Annual Channel version.

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:

Supported Annual Channel releases

AKS releases support for new releases of Windows Server Annual Channel for Containers in alignment with Kubernetes versions. For the latest updates, see the AKS release notes. The following table provides an estimated release schedule for upcoming Annual Channel releases:

K8s version Annual Channel (host) version Container image supported End of support date
1.28 23H2 (preview only) Windows Server 2022 End of 1.30 support
1.31 24H2 Windows Server 2022 & Windows Server 2025 End of 1.34 support
1.35 25H2 Windows Server 2025 End of 1.38 support

Windows Annual Channel vs. Long Term Servicing Channel Releases (LTSC)

AKS supports Long Term Servicing Channel Releases (LTSC), including Windows Server 2022 and Windows Server 2019. These come from a different release channel than Windows Server Annual Channel for Containers. To view our current recommendations, see the Windows best practices documentation.

Note

Windows Server 2019 will retire after Kubernetes version 1.32 reaches end of life, and Windows Server 2022 will retire after Kubernetes version 1.34 reaches end of life. For more information, see the AKS release notes.

The following table compares Windows Annual Channel and Long Term Servicing Channel releases:

Channel Support Upgrades
Long Term Servicing Channel (LTSC) LTSC channels are released every three years and are supported for five years. This channel is recommended for customers using Long Term Support. To upgrade from one release to the next, you need to migrate your node pools to a new OS SKU option and rebuild your container images with the new OS version.
Annual Channel for Containers Annual Channel releases occur annually and are supported for two years. To upgrade to the latest release, you can upgrade the Kubernetes version of your node pool.

Before you begin

  • You need the Azure CLI version 2.56.0 or later installed and configured to set os-sku to WindowsAnnual with the az aks nodepool add command. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Limitations

  • Windows Annual Channel doesn't support Azure Network Policy Manager (NPM).

Install the aks-preview Azure CLI extension

  • Register or update the aks-preview extension using the az extension add or az extension update command.

    # Register the aks-preview extension
az extension add --name aks-preview
# Update the aks-preview extension
az extension update --name aks-preview

Register the AKSWindowsAnnualPreview feature flag

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

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

    It takes a few minutes for the status to show Registered.

  2. Verify the registration status using the az feature show command.

    az feature show --namespace "Microsoft.ContainerService" --name "AKSWindowsAnnualPreview"

  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

Use Windows Annual Channel for Containers on AKS

To use Windows Annual Channel on AKS, specify the following parameters:

  • os-type set to Windows
  • os-sku set to WindowsAnnual

Windows Annual Channel versions are based on the Kubernetes version of your node pool. To check which release you'll get based on the Kubernetes version of your node pool, see the supported Annual Channel releases.

Create a new Windows Annual Channel node pool

  • Create a Windows Annual Channel node pool using the az aks nodepool add command. The following example creates a Windows Annual Channel node pool with the 23H2 release:

    az aks nodepool add \
    --resource-group $RESOURCE_GROUP_NAME \
    --cluster-name $CLUSTER_NAME \
    --os-type Windows \
    --os-sku WindowsAnnual \
    --kubernetes-version 1.29
    --name $NODE_POOL_NAME \
    --node-count 1

    Note

    If you don't specify the Kubernetes version during node pool creation, AKS uses the same Kubernetes version as your cluster.

Verify Windows Annual Channel node pool creation

  • Verify Windows Annual Channel node pool creation by checking the OS SKU of your node pool using kubectl describe node command.

    kubectl describe node $NODE_POOL_NAME

    If you successfully created a Windows Annual Channel node pool, you should see the following output:

    Name:               npwin
Roles:              agent
Labels:             agentpool=npwin
...
                    kubernetes.azure.com/os=windows
...
                    kubernetes.azure.com/node-image-version=AKSWindows-23H2-gen2
...
                    kubernetes.azure.com/os-sku=WindowsAnnual

Upgrade an existing node pool to Windows Annual Channel

You can upgrade an existing node pool from an LTSC release to Windows Annual Channel by following the guidance in Upgrade the OS version for your Azure Kubernetes Service (AKS) Windows workloads.

To upgrade from one Annual Channel version to the next, you can upgrade to a Kubernetes version that supports the next Annual Channel version.

Next steps

To learn more about Windows Containers on AKS, see the following resources:

Windows best practices Windows FAQ