Supported Kubernetes versions in Azure Operator Nexus Kubernetes service

This document provides an overview of the versioning schema used for the Operator Nexus Kubernetes service, including the supported Kubernetes versions. It explains the differences between major, minor, and patch versions, and provides guidance on upgrading Kubernetes versions, and what to expect from the upgrade experience. It also covers the version support lifecycle including end of support for each version bundle. Features, previously known as Add-ons, are software components included in each version bundle. Components version and breaking changes articulates the Feature versions included in the version bundles. For more in-depth information about Features, see Nexus Kubernetes Cluster Features.

The Kubernetes community releases minor versions roughly every three months. Starting with version 1.19, the Kubernetes community increased the support window for each version from nine months to one year.

Minor version releases might include new capabilities and/or improvements. Patch releases are more frequent (sometimes weekly) and are intended for critical bug fixes within a minor version. Patch releases include fixes for security vulnerabilities or major bugs.

Kubernetes versions

Kubernetes uses the standard Semantic Versioning versioning scheme for each version:

[major].[minor].[patch]

Examples:
 1.24.7
 1.25.4

Each number in the version indicates general compatibility with the previous version:

• Major version numbers change when breaking changes to the API might be introduced
• Minor version numbers change when functionality updates are made that are backwards compatible to the other minor releases.
• Patch version numbers change when backwards-compatible bug fixes are made.

We strongly recommend staying up to date with the latest available patches. For example, if your production cluster is on 1.25.4, and 1.25.6 is the latest available patch version available for the 1.25 series. You should upgrade to 1.25.6 as soon as possible to ensure your cluster is fully patched and supported. Further details on upgrading your cluster can be found in the Upgrading Kubernetes versions documentation.

Nexus Kubernetes release calendar

View the upcoming version releases on the Nexus Kubernetes release calendar.

For the past release history, see Kubernetes history.

Nexus Kubernetes service version components

An Operator Nexus Kubernetes service version is made of two discrete components that are combined into a single representation:

• The Kubernetes version. For example, 1.25.4, is the version of Kubernetes that you deploy in Operator Nexus. These packages are supplied by Azure AKS, including all patch versions that Operator Nexus supports. For more information on Azure AKS versions, see AKS Supported Kubernetes Versions
• A Version Bundle number that encapsulates the Kubernetes version, Features, and operating system (OS) image used by nodes in the Operator Nexus Kubernetes cluster, as a single number. For example, 2.†

The combination of these values is represented in the API as the single kubernetesVersion. For example, 1.25.4-2 or the alternatively supported v notation: v1.25.4-2.

† As of April 2025 version bundle increments changed to include release versioning rather than sequential numbering to provide release-to-release distinctiveness at a glance. Continue reading for more information on this change.

Version bundles

A version bundle is a secondary value added to the Kubernetes version. Version bundles account for cases where the Kubernetes version is unchanged, but the operating system and/or Features are updated with a Nexus release. Such updates might include but aren't limited to: updated operating system images, patch releases for Features, and the introduction of new platform Features.

Before April 2025, version bundle numbers were incremented starting from 1 and varied depending on how long a particular Kubernetes patch version was available on Nexus. After April 2025, all version bundles in the same release are numbered with the same release identifier, for example -4.4.0 or -4.5.0. The chart below details which version bundles are in the same series.

Version bundles give users the ability to plan and manage the process of upgrading their Kubernetes clusters offered by the Operator Nexus Kubernetes service.

All Nexus cluster upgrades follow the standard Kubernetes versions skew policy. In some cases, more than one upgrade might be needed to bring a cluster to the desired Kubernetes version. Skipping over any version bundle release is accepted, however you can't downgrade to a previous version bundle series.

Changes to the configuration of a deployed Operator Nexus Kubernetes cluster should only be applied within a Kubernetes minor version upgrade, not during a patch version upgrade. Examples of configuration changes that could be applied during the minor version upgrade include:

• Changing the configuration of the kube-proxy from using the iptables to ipvs.
• Changing the container networking interface (CNI) from one product to another.

Choosing a version bundle for an upgrade scenario

We allow upgrade from any patch version in one Kubernetes minor version to any patch version in the next Kubernetes minor version, giving you flexibility. For example, an upgrade from 1.31.1-x.x.x to 1.32.x-x.x.x would be allowed, regardless of the presence of an intermediate 1.31.2-x.x.x version.

When new version bundles are released, all the Kubernetes patch versions in that version bundle release use the same versions of both OS and Features; only the Kubernetes code differs between them. Let's look at a few examples of upgrade routes that might be desirable:

Kubernetes version update

To patch or update the Kubernetes minor version, select an available Kubernetes version from the same version bundle series. E.G., if 1.32.1-4.4.0 is your current version bundle, and 1.33.1-4.4.0 is the latest 1.33.x version bundle, then you should choose 1.33.1-4.4.0.

OS and component version update

To patch or update OS or platform components while maintaining the same Kubernetes version, select a version bundle within the same Kubernetes minor version as your cluster, but with a later release number. For example, if 1.32.1-4.4.0 is your current version bundle, and 1.32.1-4.5.0 is the latest 1.32.1 version bundle, then choose the 1.32.1-4.5.0 bundle.

Kubernetes, OS, and Component version update

To patch or update both Kubernetes version, OS version, and platform components together, select the latest release version for the subsequent Kubernetes minor version. For example, if 1.32.1-4.4.0 is your current version bundle and the latest version bundle for the subsequent Kubernetes minor version is 1.33.2-4.5.0, then select 1.33.2-4.5.0 to upgrade all components.

In the first two cases, you might need to accept an updated Kubernetes version or component version if a version bundle containing the desires upgrades wasn't released. In this case, any subsequent Kubernetes minor version works, but the version bundle with the latest release version is the most up-to-date and secure version of that Kubernetes minor version. The recommendation is to choose the latest release version for a given version bundle.

Components version and breaking changes

Note the following important changes to make before you upgrade to any of the available minor versions:

• The azure-arc-k8sagents version refers to the version of this Feature shipped with the version bundle. The Arc-enabled Kubernetes agent is set to auto upgrade to the latest version of the agent whenever it's available.
• Starting with 4.6.0, the ipam-cni-plugin version reflects the internal app version (4.6.0-32) versus the chart version (1.0.10). For 4.6.0, both are shown for transition's sake.

Current version bundle information

Starting with 4.8.0, features that have both an application version and a chart version have both listed in the reference table. The format is app version/chart version. This update enables mapping chart versions to application versions. Users might see the features' chart versions in the output of the Nexus Kubernetes create and update commands. External links to features' release notes are based on application version where available.

azure-arc-k8sagent is an exception. The chart manifest has the versions flipped so the application version appears in the chart version and vice versa. For consistency purposes, the reference table reflects the versions where they should be displayed.

If a feature has the same value for both application and chart versions, it indicates the chart version is the only available version.

OS Image, coredns image, etcd image, kube-vip image, and pause image just have the image version identifier.

To assist with readability, the latest two version bundles are included in the current version section. Older versions are listed in the Older version bundle information section.

Older version bundle information

Version bundle Features

Upgrading Kubernetes versions

For more information on upgrading your cluster, see Upgrade an Azure Operator Nexus Kubernetes Service cluster.

Kubernetes version support policy

Operator Nexus supports three minor versions of Kubernetes:

• The latest GA minor version released in Operator Nexus (which we refer to as N).
• Two previous minor versions.
• Each supported minor version also supports a maximum of two latest stable patches while the previous patches are under extended availability policy for the lifetime of the minor version.

Operator Nexus Kubernetes service provides a standardized duration of support for each minor version of Kubernetes that is released. Versions adhere to two different timelines, reflecting:

• Duration of support – How long is a version actively maintained. At the end of the supported period, the version is considered End of Support.
• Extended availability – How long can a version be selected for deployment after End of Support.

The supported window of Kubernetes versions on Operator Nexus is known as N-2: (N (Latest release) - 2 (minor versions)), and .letter is representative of patch versions.

For example, if Operator Nexus introduces 1.17.a today, support is provided for the following versions:

When a new minor version is introduced, the oldest supported minor version and patch releases are out of support. For example, the current supported version list is:

1.17.a
1.17.b
1.16.c
1.16.d
1.15.e
1.15.f

When Operator Nexus releases 1.18.*, all the 1.15.* versions go out of support.

Support timeline

Operator Nexus Kubernetes service provides support for 12 months from the initial AKS GA release of a minor version typically. This timeline follows the timing of Azure AKS, which includes a declared Long-Term Support version 1.27.

Supported versions:

• Can be deployed as new Operator Nexus Kubernetes clusters.
• Can be the target of upgrades from prior versions. Limited by normal upgrade paths.
• Might have extra patches or Version Bundles within the minor version.

End of support

End of Support means no more patch or version bundles are produced. It's possible the cluster can't be upgraded because the latest supported versions are no longer available. In this event, the only way to upgrade is to completely recreate the Nexus Kubernetes cluster using the newer version that is supported. Unsupported upgrades through Extended availability might be utilized to return to a supported version.

Extended availability policy

During the extended availability period for unsupported Kubernetes versions, users don't receive security patches or bug fixes. For detailed information on support categories, refer to the following table.

Abandoned Nexus Kubernetes clusters

After the end of the extended availability period, the K8s version is removed from Nexus. At this point any existing Nexus Kubernetes clusters that are based on this K8s version become abandoned. The only supported operation on abandoned clusters is deletion. Importantly, once a cluster is abandoned, upgrading to a later K8s version isn't possible.

Supported kubectl versions

You can use one minor version older or newer of kubectl relative to your kube-apiserver version, consistent with the Kubernetes support policy for kubectl.

For example, if your kube-apiserver is at 1.17, then you can use versions 1.16 to 1.18 of kubectl with that kube-apiserver.

To install or update kubectl to the latest version, run:

az aks install-cli

Install-AzAksKubectl -Version latest

Long Term Support (LTS)

The Kubernetes community releases a new minor version approximately every four months, with a support window for each version for one year. In Azure Kubernetes Service (AKS), this support window is called "Community support."

AKS supports versions of Kubernetes that are within this Community support window, to push bug fixes and security updates from community releases.

Innovations delivered with this release cadence provide the latest Kubernetes features and up to date security. However, it might be challenging to remain current based on the number of clusters you have to maintain.

Support types

After approximately one year, the Kubernetes version exits Community support and your AKS clusters are now at risk as bug fixes, and security updates become unavailable.

AKS provides one year Community support and one year of long-term support (LTS) to back port security fixes from the community upstream in our public repository. Our upstream LTS working group contributes efforts back to the community to provide our customers with a longer support window.

LTS provides an extended period of time to plan and test upgrades over a two-year period from the General Availability of a Kubernetes version.

Migrate from LTS to the next LTS release

Nexus Kubernetes clusters don't support direct upgrades between LTS versions. To transition from one LTS version to the next, you have two options:

• Create a new cluster with the desired LTS version and move your workloads to this new cluster.
• Perform a series of intermediate upgrades through the supported versions before reaching the next LTS version.

FAQ

How does Microsoft notify me of new Kubernetes versions?

This document is updated periodically with planned dates of the new Kubernetes versions.

How often should I expect to upgrade Kubernetes versions to stay in support?

Starting with Kubernetes 1.19, the open source community expanded support to one year. Operator Nexus commits to enabling patches and support matching the upstream commitments. For Operator Nexus clusters on 1.19 and greater, you can upgrade at a minimum of once a year to stay on a supported version.

What happens when you upgrade a Kubernetes cluster with a minor version that isn't supported?

If you're on the N-3 version or older, you're outside of the support window. When you upgrade from version N-3 to N-2, you're back within our support window. For example:

• If the oldest supported AKS version is 1.25.x and you're on 1.24.x or older, you're outside of support.
• Successfully upgrading from 1.24.x to 1.25.x or higher brings you back within our support window.
• "Skip-level upgrades" aren't supported. In order to upgrade from 1.23.x to 1.25.x, you must upgrade first to 1.24.x and then to 1.25.x.

Downgrades aren't supported.

What happens if I don't upgrade my cluster?

If you don't upgrade your cluster, you continue to receive support for the Kubernetes version you're running until the end of the support period. After that, you'll no longer receive support for your cluster. You need to upgrade your cluster to a supported version to continue receiving support.

What happens if I don't upgrade my cluster before the end of the Extended availability period?

If you don't upgrade your cluster before the end of the Extended availability period, you can no longer upgrade your cluster to a supported version or scale-out agent pools. You need to recreate your cluster using a supported version to continue receiving support.

What does 'Outside of Support' mean?

'Outside of Support' means that:

• The version you're running is outside of the supported versions list.
• You're asked to upgrade the cluster to a supported version when requesting support.

Additionally, Operator Nexus doesn't make any runtime or other guarantees for clusters outside of the supported versions list.

What happens when a user scales a Kubernetes cluster with a minor version that isn't supported?

For minor versions not supported by Operator Nexus, scaling in or out should continue to work. Since there are no guarantees with quality of service, we recommend upgrading to bring your cluster back into support.

Can I skip multiple Kubernetes versions during cluster upgrade?

When you upgrade a supported Operator Nexus Kubernetes cluster, Kubernetes minor versions can't be skipped. Kubernetes control planes version skew policy doesn't support minor version skipping. For example, upgrades between:

• 1.12.x -> 1.13.x: allowed.
• 1.13.x -> 1.14.x: allowed.
• 1.12.x -> 1.14.x: not allowed.

To upgrade from 1.12.x -> 1.14.x:

1. Upgrade from 1.12.x -> 1.13.x.
2. Upgrade from 1.13.x -> 1.14.x.

Can I create a new cluster during its extended availability window?

Yes, you can create a new 1.xx.x cluster during its extended availability window. However, we recommend that you create a new cluster with the latest supported version.

Can I upgrade a cluster to a newer version during its extended availability window?

Yes, you can upgrade an N-3 cluster to N-2 during its extended availability window. If your cluster is currently on N-4, you can make use of the extended availability to first upgrade from N-4 to N-3. Once the N-3 upgrade completes, proceed with the upgrade to a supported version (N-2).

I'm on an extended availability window, can I still add new node pools or must I upgrade?

Yes, you're allowed to add node pools to the cluster.