List supported Kubernetes versions for Azure Operator Nexus

This article explains how to discover the Nexus Kubernetes version bundles that an Operator Nexus cluster can deploy or upgrade Nexus Kubernetes clusters to. The kubernetesVersions catalog is published per Operator Nexus cluster as a Microsoft.NetworkCloud/kubernetesVersions resource named default. It's anchored to the Operator Nexus cluster's custom location (extended location).

Use this API when you want to:

• Plan Nexus Kubernetes cluster creations or upgrades against a known list of available bundles before targeting a specific Nexus Kubernetes cluster.
• Verify the general availability (GA), end-of-support (EOS), and end-of-extended-availability (EOEA) dates for a bundle.
• Inspect the Features and component versions packaged inside a version bundle.

For upgrade options for an existing Nexus Kubernetes cluster, see Check for available upgrades.

What the kubernetesVersions catalog contains

Each Microsoft.NetworkCloud/kubernetesVersions resource is the catalog of every Nexus Kubernetes version bundle that the owning Operator Nexus cluster can deploy or upgrade Nexus Kubernetes clusters to. The catalog is structured as follows:

• Supported Kubernetes minor versions. The catalog's properties.values[] array lists every Kubernetes minor version (for example, 1.30, 1.31, 1.32, 1.33) for which Operator Nexus currently ships at least one bundle on this Operator Nexus cluster.
• Version bundles per minor version. Each minor version entry contains one or more patch-level version bundles. A bundle is the unit Operator Nexus deploys: it pins a specific Kubernetes patch release together with the Features (Calico, MetalLB, Azure Arc agents, CSI drivers, and so on) and the OS image that ship with that release.
• Lifecycle dates per bundle. Each bundle carries a general-availability date, an end-of-support date, and an end-of-extended-availability date. Operator Nexus uses these dates to govern which bundles are valid creation or upgrade targets at any given time. See Lifecycle visibility rules.
• Component manifest per bundle. Each bundle records the exact Feature and OS image versions it packages, so you can correlate a Kubernetes patch release with the supporting components that ship alongside it.

In the current preview API version (2026-01-01-preview), the patch-level bundle data for a minor version is returned as a single text field named description. The remainder of this article shows how to retrieve that field, how to read it, and how to filter it.

Prerequisites

• An Azure subscription with access to an Azure Operator Nexus instance whose Operator Nexus cluster is running a build that supports the 2026-01-01-preview Microsoft.NetworkCloud API version or newer. If the resource doesn't appear for an Operator Nexus cluster, the build on that instance doesn't yet expose Microsoft.NetworkCloud/kubernetesVersions.
• The Azure CLI installed and signed in. If you need to install or upgrade it, see Install Azure CLI.
• Reader access on the subscription (or on the Operator Nexus cluster's managed HostedResources resource group). Microsoft.NetworkCloud/kubernetesVersions is projected into the HostedResources group.
• To use the az networkcloud kubernetesversion commands, install the preview networkcloud CLI extension (5.0.0b1 or later): az extension add --name networkcloud --version 5.0.0b1 --allow-preview true. The az rest examples in this article work with any Azure CLI install and don't require the preview extension.

Locate the kubernetesVersions resource

Microsoft.NetworkCloud/kubernetesVersions is a singleton named default per Operator Nexus cluster. List the resources visible to your subscription:

az resource list \
  --resource-type Microsoft.NetworkCloud/kubernetesVersions \
  --query "[].{name:name, location:location, id:id}" \
  --output table

Or, with the preview networkcloud extension, list every Operator Nexus cluster's kubernetesVersions catalog in a single call:

az networkcloud kubernetesversion list --output table

Each row corresponds to one Operator Nexus cluster. The table view projects Location, Name (always default), ProvisioningState, and ResourceGroup. To see the full ARM id and extendedLocation, rerun the command with --output json or project them with --query:

az networkcloud kubernetesversion list \
  --query "[].{id:id, resourceGroup:resourceGroup, extendedLocation:extendedLocation.name}" \
  --output table

Each id has the form:

/subscriptions/<sub>/resourceGroups/<cluster>-<hash>-HostedResources-<hash>/providers/Microsoft.NetworkCloud/kubernetesVersions/default

The kubernetesVersions resource's extendedLocation matches the Operator Nexus cluster's custom location. Use the id value as <KubernetesVersionsResourceId> in the next step.

Find the HostedResources resource group for your Operator Nexus cluster

Microsoft.NetworkCloud/kubernetesVersions lives in the Operator Nexus cluster's managed HostedResources resource group, not in the resource group that holds the Operator Nexus cluster. The table output from the previous step already exposes the HostedResources group in the ResourceGroup column. To extract it programmatically for a specific Operator Nexus cluster, filter the list by the Operator Nexus cluster's custom location:

az networkcloud kubernetesversion list \
  --query "[?contains(extendedLocation.name, '<cluster-name>')].resourceGroup" \
  --output tsv

Pass the output as --resource-group to every az networkcloud kubernetesversion command in this article.

Get the kubernetesVersions catalog

Fetch the kubernetesVersions catalog through ARM with az rest:

az rest --method get \
  --url "https://management.azure.com<KubernetesVersionsResourceId>?api-version=2026-01-01-preview"

Or, with the preview networkcloud extension:

az networkcloud kubernetesversion show \
  --resource-group <cluster>-<hash>-HostedResources-<hash> \
  --name default

You can also list every kubernetesVersions catalog visible to a subscription in a single call (one entry per Operator Nexus cluster):

az rest --method get \
  --url "https://management.azure.com/subscriptions/<SubscriptionId>/providers/Microsoft.NetworkCloud/kubernetesVersions?api-version=2026-01-01-preview"

Or:

az networkcloud kubernetesversion list

Sample output

The current preview Microsoft.NetworkCloud/kubernetesVersions API returns a list of supported minor versions. For each minor version, the description field is a single text string that embeds every patch-level entry's component manifest and lifecycle dates. The following example is trimmed for readability:

{
  "id": "/subscriptions/<sub>/resourceGroups/<cluster>-<hash>-HostedResources-<hash>/providers/Microsoft.NetworkCloud/kubernetesVersions/default",
  "name": "default",
  "type": "microsoft.networkcloud/kubernetesversions",
  "location": "uksouth",
  "extendedLocation": {
    "name": "/subscriptions/<sub>/resourceGroups/<cluster>-hostedresources-<hash>/providers/microsoft.extendedlocation/customlocations/<cluster>-cstm-loc",
    "type": "CustomLocation"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "values": [
      {
        "version": "1.33",
        "description": "[{ components: {Name: azure-arc-k8sagents, Type: Feature, Version: 1.31.7},{Name: azure-arc-servers, Type: Feature, Version: v1.2.6},{Name: calico, Type: Feature, Version: v1.9.1},{Name: cloud-provider-kubevirt, Type: Feature, Version: v1.0.8},{Name: csi-nfs, Type: Feature, Version: 10.2.0-41},{Name: csi-volume, Type: Feature, Version: 10.2.0-41},{Name: ipam-cni-plugin, Type: Feature, Version: v1.0.13},{Name: metallb, Type: Feature, Version: v1.3.5},{Name: metrics-server, Type: Feature, Version: v1.0.7},{Name: multus, Type: Feature, Version: v1.4.4},{Name: node-local-dns, Type: Feature, Version: v1.2.3},{Name: sriov-dp, Type: Feature, Version: v1.1.7},{Name: AzureLinux3, Type: OSImage, Version: 1.33.x-y.z}, endOfExtendedAvailabilityDate: 2027-MM-DD 00:00:00 +0000 UTC, generalAvailabilityDate: 2026-MM-DD 00:00:00 +0000 UTC, patchVersion: v1.33.x-y.z, supportExpiryDate: 2027-MM-DD 00:00:00 +0000 UTC }, ... ]"
      },
      {
        "version": "1.32",
        "description": "[{ components: {...}, endOfExtendedAvailabilityDate: ..., generalAvailabilityDate: ..., patchVersion: v1.32.x-y.z, supportExpiryDate: ... }, ... ]"
      },
      {
        "version": "1.31",
        "description": "[{ components: {...}, ... patchVersion: v1.31.x-y.z, ... }, ... ]"
      },
      {
        "version": "1.30",
        "description": "[{ components: {...}, ... patchVersion: v1.30.x-y.z, ... }, ... ]"
      }
    ]
  }
}

kubernetesVersions resource and field reference (preview API)

Top-level kubernetesVersions resource:

Per-entry fields in properties.values[]:

The keys embedded in each patch entry inside description are:

Lifecycle visibility rules

Regardless of how the data is rendered, the lifecycle rules Operator Nexus applies to entries in the kubernetesVersions catalog are:

• Generally available bundles are returned with supportExpiryDate and endOfExtendedAvailabilityDate in the future.
• Bundles past end of support but before end of extended availability are still returned, but Operator Nexus surfaces them with an unsupported warning. New Nexus Kubernetes cluster creation on these bundles isn't recommended; existing Nexus Kubernetes clusters can still be upgraded out of them. Refer to the Extended availability policy for what's supported during this period.
• Bundles past end of extended availability aren't returned. Nexus Kubernetes clusters that remain on a removed bundle become abandoned clusters and the only supported operation is deletion.

For the full set of policy questions, including upgrade behavior outside the support window, see the FAQ in the supported versions reference.

Filter the kubernetesVersions catalog with JMESPath

The standard Azure CLI --query option works on the structured top-level fields. The following examples refine the response.

List only the supported minor versions:

az rest --method get \
  --url "https://management.azure.com<KubernetesVersionsResourceId>?api-version=2026-01-01-preview" \
  --query "properties.values[].version" \
  --output tsv

Get every patch entry text blob for a specific minor version:

az rest --method get \
  --url "https://management.azure.com<KubernetesVersionsResourceId>?api-version=2026-01-01-preview" \
  --query "properties.values[?version=='1.33'].description | [0]" \
  --output tsv

Find every Operator Nexus cluster kubernetesVersions catalog visible to the subscription:

az rest --method get \
  --url "https://management.azure.com/subscriptions/<SubscriptionId>/providers/Microsoft.NetworkCloud/kubernetesVersions?api-version=2026-01-01-preview" \
  --query "value[].{customLocation:extendedLocation.name, location:location, minorVersions:properties.values[].version}" \
  --output json

Render the description in human-readable form

Because each minor version's description is returned as a single text string, the raw response is difficult to read for catalogs with more than a handful of patches. The following convenience script pulls the value with az networkcloud kubernetesversion show and uses two awk passes to:

1. Split each patch entry, component row, and lifecycle date onto its own line and strip the surrounding {, }, and [] punctuation.
2. Reorder each patch block so that patchVersion appears first, the lifecycle dates appear next, and the components list appears last, to match the typical reading order for a version bundle.

The script uses only az, bash, and awk (POSIX), so it can be ran unmodified on Linux operating systems.

#!/usr/bin/env bash
# Pretty-print the Microsoft.NetworkCloud/kubernetesVersions description blob
# for a single minor version. Replace RESOURCE_GROUP and MINOR as needed.

RESOURCE_GROUP="<cluster>-<hash>-HostedResources-<hash>"
MINOR="1.33"

az networkcloud kubernetesversion show \
  --resource-group "$RESOURCE_GROUP" \
  --name default \
  --query "values[?version=='$MINOR'].description | [0]" \
  --output tsv \
| awk '{
    gsub(/\},\{ components:/, "}\n\n{ components:")
    gsub(/, patchVersion:/, "\n  patchVersion:")
    gsub(/, generalAvailabilityDate:/, "\n  generalAvailabilityDate:")
    gsub(/, supportExpiryDate:/, "\n  supportExpiryDate:")
    gsub(/, endOfExtendedAvailabilityDate:/, "\n  endOfExtendedAvailabilityDate:")
    gsub(/\{Name:/, "\n    {Name:")
    gsub(/[\{\}\[\]]/, "")
    print
  }' \
| awk 'BEGIN{RS=""} {
    pv=""; ga=""; se=""; eea=""; nc=0
    n=split($0, lines, "\n")
    for (i=1; i<=n; i++) {
      if      (lines[i] ~ /^[ \t]*patchVersion:/)                  pv=lines[i]
      else if (lines[i] ~ /^[ \t]*generalAvailabilityDate:/)       ga=lines[i]
      else if (lines[i] ~ /^[ \t]*supportExpiryDate:/)             se=lines[i]
      else if (lines[i] ~ /^[ \t]*endOfExtendedAvailabilityDate:/) eea=lines[i]
      else if (lines[i] ~ /^[ \t]*(components:|.*Name:)/)          comp[++nc]=lines[i]
    }
    if (pv == "") next
    sub(/^[ \t]+/, "", pv);  print pv
    if (ga  != "") { sub(/^[ \t]+/, "", ga);  print ga }
    if (se  != "") { sub(/^[ \t]+/, "", se);  print se }
    if (eea != "") { sub(/^[ \t]+/, "", eea); print eea }
    for (i=1; i<=nc; i++) print comp[i]
    print ""
  }'

Sample reformatted output (one patch entry shown; real responses contain several patches per minor version):

patchVersion: v1.33.x-y.z
generalAvailabilityDate: 2026-MM-DD 00:00:00 +0000 UTC
supportExpiryDate: 2027-MM-DD 00:00:00 +0000 UTC
endOfExtendedAvailabilityDate: 2027-MM-DD 00:00:00 +0000 UTC
 components:
    Name: azure-arc-k8sagents, Type: Feature, Version: 1.31.7,
    Name: azure-arc-servers, Type: Feature, Version: v1.2.6,
    Name: calico, Type: Feature, Version: v1.9.1,
    Name: cloud-provider-kubevirt, Type: Feature, Version: v1.0.8,
    Name: csi-nfs, Type: Feature, Version: 10.2.0-41,
    Name: csi-volume, Type: Feature, Version: 10.2.0-41,
    Name: ipam-cni-plugin, Type: Feature, Version: v1.0.13,
    Name: metallb, Type: Feature, Version: v1.3.5,
    Name: metrics-server, Type: Feature, Version: v1.0.8,
    Name: multus, Type: Feature, Version: v1.4.6,
    Name: node-local-dns, Type: Feature, Version: v1.2.4,
    Name: sriov-dp, Type: Feature, Version: v1.1.10,
    Name: AzureLinux3, Type: OSImage, Version: 1.33.x-y.z

To render every minor version in the kubernetesVersions catalog with a banner before each block, wrap the same awk pipeline in a small loop:

URL="https://management.azure.com<KubernetesVersionsResourceId>?api-version=2026-01-01-preview"
for v in $(az rest --method get --url "$URL" --query "properties.values[].version" -o tsv); do
  echo "===== Kubernetes $v ====="
  az rest --method get --url "$URL" \
    --query "properties.values[?version=='$v'].description | [0]" -o tsv \
  | awk '{
      gsub(/\},\{ components:/, "}\n\n{ components:")
      gsub(/, patchVersion:/, "\n  patchVersion:")
      gsub(/, generalAvailabilityDate:/, "\n  generalAvailabilityDate:")
      gsub(/, supportExpiryDate:/, "\n  supportExpiryDate:")
      gsub(/, endOfExtendedAvailabilityDate:/, "\n  endOfExtendedAvailabilityDate:")
      gsub(/\{Name:/, "\n    {Name:")
      gsub(/[\{\}\[\]]/, "")
      print
    }' \
  | awk 'BEGIN{RS=""} {
      pv=""; ga=""; se=""; eea=""; nc=0
      n=split($0, lines, "\n")
      for (i=1; i<=n; i++) {
        if      (lines[i] ~ /^[ \t]*patchVersion:/)                  pv=lines[i]
        else if (lines[i] ~ /^[ \t]*generalAvailabilityDate:/)       ga=lines[i]
        else if (lines[i] ~ /^[ \t]*supportExpiryDate:/)             se=lines[i]
        else if (lines[i] ~ /^[ \t]*endOfExtendedAvailabilityDate:/) eea=lines[i]
        else if (lines[i] ~ /^[ \t]*(components:|.*Name:)/)          comp[++nc]=lines[i]
      }
      if (pv == "") next
      sub(/^[ \t]+/, "", pv);  print pv
      if (ga  != "") { sub(/^[ \t]+/, "", ga);  print ga }
      if (se  != "") { sub(/^[ \t]+/, "", se);  print se }
      if (eea != "") { sub(/^[ \t]+/, "", eea); print eea }
      for (i=1; i<=nc; i++) print comp[i]
      print ""
    }'
  echo
done

Compare with available upgrades for a specific Nexus Kubernetes cluster

Microsoft.NetworkCloud/kubernetesVersions returns the kubernetesVersions catalog for an entire Operator Nexus cluster. To see only the upgrade targets that apply to a specific Nexus Kubernetes cluster, use the cluster-scoped query against that Nexus Kubernetes cluster. That query is already filtered by the Kubernetes version-skew policy and the Nexus Kubernetes cluster's current bundle, and it returns structured upgrade candidates today:

az networkcloud kubernetescluster show \
  --name <NexusK8sClusterName> \
  --resource-group <ResourceGroup> \
  --query availableUpgrades \
  --output json

For the full upgrade workflow, see Upgrade an Azure Operator Nexus Kubernetes cluster.

Related content

• Supported Kubernetes versions in Azure Operator Nexus Kubernetes service
• Nexus Kubernetes version bundles
• Components version and breaking changes
• Upgrade an Azure Operator Nexus Kubernetes cluster
• Nexus Kubernetes cluster Features