Supported Kubernetes versions in Azure Operator Nexus Kubernetes service

This article 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. The support window for a given version is one year.

Minor version releases might include new capabilities and 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.

Stay 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 for the 1.25 series, upgrade to 1.25.6 as soon as possible to ensure your cluster is fully patched and supported. For more information, see Upgrading Kubernetes versions.

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 consists of two discrete components that combine into a single representation:

• The Kubernetes version. For example, 1.25.4, is the version of Kubernetes that you deploy in Operator Nexus. Azure AKS supplies these packages, 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 API represents the combination of these values as the single kubernetesVersion. For example, 1.25.4-2 or the alternatively supported v notation: v1.25.4-2.

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 incremented starting from 1. The numbers varied depending on how long a particular Kubernetes patch version was available on Nexus. After April 2025, all version bundles in the same release use the same release identifier, such as -4.4.0 or -4.5.0.

Version bundles help you plan and manage the process of upgrading your Kubernetes clusters offered by the Operator Nexus Kubernetes service.

All Nexus cluster upgrades follow the standard Kubernetes versions skew policy. In some cases, you might need more than one upgrade to bring a cluster to the desired Kubernetes version. You can skip over any version bundle release, but you can't downgrade to a previous version bundle series.

You should only apply changes to the configuration of a deployed Operator Nexus Kubernetes cluster within a Kubernetes minor version upgrade, not during a patch version upgrade. Examples of configuration changes that you can apply 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

Operator Nexus enables you to upgrade from any patch version in one Kubernetes minor version to any patch version in the next Kubernetes minor version, so you have flexibility. For example, you can upgrade from 1.31.1-x.x.x to 1.32.x-x.x.x regardless of whether an intermediate 1.31.2-x.x.x version exists.

When Microsoft releases new version bundles, 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. Here are 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. For example, 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, select 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, choose the 1.32.1-4.5.0 bundle.

Kubernetes, OS, and component version update

To patch or update 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, 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 desired upgrades isn'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. Choose the latest release version for a given version bundle.

Components version and breaking changes

Before upgrading to any of the available minor versions, review the following important changes:

• 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 versions are shown for transition's sake.
• When a high-risk or known breaking change exists, the system automatically blocks certain upgrade paths. Examples include double-jumps across CoreDNS versions, which only support n-1 to n upgrades, and the etcd upgrade issue described in the following caution. In such cases, you must first upgrade to an intermediate version bundle before you can upgrade to the latest version bundle. Ensure that your upgrade path decisions are valid and don't rely solely on the available upgrades presented in the CLI or API.
• Higher jumps across version bundles introduce more risk to the upgrade process. Upgrade your cluster frequently to stay up to date with the latest Kubernetes versions, OS images, and feature versions for the best experience with Nexus Kubernetes.

Current version bundle information

Starting with 4.8.0, the reference table lists both the application version and the chart version for features that have both. The format is app version/chart version. This update enables mapping chart versions to application versions. You 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 five 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 about 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 is N).
• Two previous minor versions.
• Each supported minor version also supports up to 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 it releases. Versions adhere to two different timelines, reflecting:

• Duration of support – How long a version is actively maintained. At the end of the supported period, the version is considered End of Support.
• Extended availability – How long a version can 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 represents patch versions.

For example, if Operator Nexus introduces 1.17.a today, it supports the following versions:

When Operator Nexus introduces a new minor version, the oldest supported minor version and patch releases go 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 typically provides support for 12 months from the initial AKS GA release of a minor version. This timeline follows the timing of Azure AKS, which includes a declared Long-Term Support version 1.27.

Supported versions:

• You can deploy them as new Operator Nexus Kubernetes clusters.
• You can upgrade to them from prior versions, limited by normal upgrade paths.
• They might include extra patches or Version Bundles within the minor version.

End of support

End of Support means Microsoft no longer produces patches or version bundles. You might not be able to upgrade the cluster 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 by using the newer version that is supported. To return to a supported version, you might be able to use unsupported upgrades through Extended availability.

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, see 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 a kubectl version that's one minor version older or newer than your kube-apiserver version, consistent with the Kubernetes support policy for kubectl.

For example, if your kube-apiserver is at 1.17, you can use kubectl versions 1.16 to 1.18 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. Each version has a support window of 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. This support ensures that AKS receives bug fixes and security updates from community releases.

This release cadence delivers the latest Kubernetes features and up-to-date security. However, it might be challenging to stay current based on the number of clusters you need 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?

Microsoft updates this article periodically with planned dates for 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 that match the upstream commitments. For Operator Nexus clusters on 1.19 and greater, you need to upgrade at least once a year to stay on a supported version.

What happens when you upgrade a Kubernetes cluster to 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 the 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 the support window.
• "Skip-level upgrades" aren't supported. 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 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 by 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 that aren't on the supported versions list.

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

For minor versions that Operator Nexus doesn't support, scaling in or out should continue to work. Since there are no guarantees with quality of service, upgrade 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, you can't skip Kubernetes minor versions. 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, create a new cluster by using 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, use the extended availability to first upgrade from N-4 to N-3. After the N-3 upgrade finishes, 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 can add node pools to the cluster.