Picking the Latest Kubernetes Release on AKS Without Shooting Yourself in the Foot

Every few months a platform engineer opens a Slack message that reads something like: "Hey, our AKS cluster is on a version that's being retired — what do we do?" The answer is never "just click upgrade," but it also shouldn't be a three-week fire drill. This post walks through how AKS versions work, how to find what's actually available in your region, and how to set a defensible upgrade posture — without repeating the node pool mechanics we've already covered in earlier posts in this series.

How AKS Manages Version Support Windows

AKS doesn't support every Kubernetes minor version forever. Microsoft maintains a sliding support window — commonly described as the three most recent minor versions (N, N-1, N-2) — and retires older releases on a rolling basis. ¹ NEEDS_VALIDATION: confirm the exact N/N-1/N-2 window against current Microsoft docs, as the supported count has varied historically.

What that means operationally: if 1.30 is the current stable release, you can expect 1.29 and 1.28 to remain supported, while 1.27 approaches end-of-life. Clusters still running a retired version don't immediately explode, but they stop receiving security patches and you lose Microsoft support SLA coverage — two things you do not want to explain to your CISO.

Patch versions (the third digit) within a supported minor are more granular. AKS regularly ships node OS patches and Kubernetes patch releases; these are where most of the day-to-day CVE fixes land.

Finding What's Available in Your Region

Version availability is per-region. A version that GA'd last week in East US may still be in preview in Southeast Asia. Always query your actual deployment region before planning an upgrade:

az aks get-versions --location eastus --output table

NEEDS_VALIDATION: confirm --output table renders usefully for this subcommand in current CLI versions; --output json is always safe if the table format shifts.

The output lists minor versions, their patch variants, and whether each is in preview or GA. Treat anything marked preview as off-limits for production unless you have a specific reason and the risk tolerance to match.

If you want the current default version AKS would pick if you didn't specify one:

az aks get-versions --location eastus --output json \
  | jq '[.values[] | select(.isDefault == true)]'

NEEDS_VALIDATION: the isDefault field name — verify against current CLI JSON schema.

Key insight: the AKS default is not necessarily the latest GA patch. ¹ Microsoft selects a "recommended" version that has had some soak time. If you want the latest, you have to ask for it explicitly.

Pinning a Version at Cluster Create Time

To be explicit about your version at cluster creation:

az aks create \
  --resource-group my-rg \
  --name my-cluster \
  --location eastus \
  --kubernetes-version 1.30.2 \
  --node-count 3 \
  --generate-ssh-keys

NEEDS_VALIDATION: substitute the actual latest GA patch for your region; 1.30.2 is illustrative only — do not copy-paste without checking az aks get-versions first.

Omitting --kubernetes-version hands the decision to Microsoft's recommended default. That's fine for dev clusters. For production, pin it, document why you chose that version, and put the upgrade decision in your change process.

Auto-Upgrade Channels: Declaring Upgrade Intent

Manually upgrading clusters is fine until you have fifteen of them. Auto-upgrade channels let you express intent rather than managing individual upgrade events. AKS supports the following channels ¹:

• none — no automatic upgrades; you control everything manually.
• patch — automatically upgrades to the latest patch within the current minor version.
• stable — targets the latest patch on the N-1 minor version.
• rapid — targets the latest patch on the latest supported minor version (N).
• node-image — upgrades only the node OS image, not the Kubernetes version itself.

NEEDS_VALIDATION: confirm exact current semantics for stable and rapid against Microsoft docs — the mapping of "N" vs "N-1" has been adjusted in past releases.

The node-image channel is worth calling out explicitly: node image upgrades and Kubernetes version upgrades are decoupled. ¹ You can roll fresh OS images (security patches, kernel updates) without touching your Kubernetes minor or patch version. This is the channel most production clusters should be running continuously — there's little reason to let node images go stale.

Setting the channel on an existing cluster:

az aks update \
  --resource-group my-rg \
  --name my-cluster \
  --auto-upgrade-channel patch

Gating Upgrades with Planned Maintenance Windows

Auto-upgrade without a maintenance window means upgrades can fire at any time AKS decides conditions are met. That's a bad day when it happens at 2 PM on a Tuesday during peak traffic. Planned Maintenance lets you constrain when auto-upgrades are allowed to execute. ¹ NEEDS_VALIDATION: confirm current Planned Maintenance API capabilities and whether it gates both K8s and node-image upgrades or only one.

apiVersion: maintenance.azure.com/v1
kind: MaintenanceConfiguration
metadata:
  name: aksmaintenance
spec:
  timeInWeek:
    - day: Saturday
      hourSlots:
        - 2
        - 3
  notAllowedTime:
    - start: "2024-12-20T00:00:00Z"
      end: "2025-01-03T00:00:00Z"

NEEDS_VALIDATION: the above YAML structure is illustrative — validate the exact CRD schema against current AKS documentation before applying.

Alternatively via CLI:

az aks maintenanceconfiguration add \
  --resource-group my-rg \
  --cluster-name my-cluster \
  --name aksManagedAutoUpgradeSchedule \
  --weekday Saturday \
  --start-hour 2

NEEDS_VALIDATION: confirm subcommand name and flags for the current CLI version.

A Concrete Upgrade Decision Process

Here's the numbered checklist I'd run through before touching a production cluster's Kubernetes version:

1. Query available versions in your target region with az aks get-versions. Confirm the version you want is GA, not preview.
2. Check your current cluster version with az aks show --resource-group my-rg --name my-cluster --query kubernetesVersion.
3. Review the Kubernetes changelog for the target minor version. Focus on API deprecations — if your workloads use APIs removed in the target version, fix that first.
4. Run kubectl deprecations (via the kubent tool or similar) against your cluster to catch any in-use deprecated APIs before the upgrade window. NEEDS_VALIDATION: confirm kubent compatibility with your target version.
5. Upgrade control plane first, validate, then upgrade node pools — this is standard AKS sequencing. If you need the node pool mechanics, see our earlier posts in this series.
6. Set your auto-upgrade channel to patch at minimum so you don't fall behind on patch releases between planned minor upgrades.
7. Configure a Planned Maintenance window so automated patch upgrades don't surprise you in business hours.

The Version Skew Problem

One thing that catches teams off guard: AKS allows your control plane and node pools to differ by at most one minor version, with the control plane always ahead. ² If you're running control plane 1.30 and node pools at 1.28, you have a problem — the node pools need to come up through 1.29 before they can reach 1.30. You cannot skip minor versions on node pools.

This is why letting clusters drift is expensive. A cluster that hasn't been upgraded in a year may require sequential minor version upgrades, each with its own validation cycle.

Putting It Together

Version management on AKS is less about clicking the upgrade button and more about having a policy that makes the decision for you at the right time. Set the patch auto-upgrade channel, add a maintenance window, keep node images continuously current via node-image channel, and plan minor version upgrades quarterly. That's a posture you can defend, automate, and sleep through.

The clusters that cause incidents are the ones where version management was treated as a one-time task rather than a continuous process.

Sources

Architecture

flowchart TD
    A([Platform Engineer]) --> B[az aks get-versions\n--location region]
    B --> C{Version Selection\nStrategy}
    C -->|Pin explicit version| D[az aks create\n--kubernetes-version X.Y.Z]
    C -->|Declare upgrade intent| E[Set Auto-Upgrade Channel]
    E --> F{Channel Choice}
    F -->|Conservative| G[patch\nStay on current minor]
    F -->|Balanced| H[stable\nN-1 minor version]
    F -->|Aggressive| I[rapid\nLatest supported minor]
    D --> J[AKS Cluster]
    G --> J
    H --> J
    I --> J
    J --> K[Planned Maintenance\nWindow Gates Upgrades]
    K --> L{Upgrade Scope}
    L -->|K8s version| M[Control Plane\n+ Node Pools]
    L -->|OS patches only| N[Node Image Upgrade\nDecoupled from K8s]

1. What is Azure Kubernetes Service (AKS)? ↩

2. Azure Kubernetes Service (AKS) Core Concepts ↩