Skip to content

Auto-Upgrade Channels

Cluster auto-upgrade keeps AKS within the supported Kubernetes window with less manual effort, but the channel you choose defines how aggressively the service moves your control plane and node pools.

Prerequisites

  • Know the business tolerance for automatic minor-version movement.
  • Review supported versions and the AKS release tracker for the target region.
  • Pair the chosen channel with a maintenance window, especially in production.

When to Use

  • You want the cluster to stay within support without manual version-by-version intervention.
  • You need a default posture for fleet-scale or subscription-wide platform operations.
  • You want to separate cluster version automation from node OS channel selection.

Procedure

flowchart TD
    A[Choose auto-upgrade posture] --> B{Only patch updates?}
    B -->|Yes| C[patch]
    B -->|No| D{Prefer N-1 production buffer?}
    D -->|Yes| E[stable]
    D -->|No| F{Need fastest GA minor adoption?}
    F -->|Yes| G[rapid]
    F -->|No| H[none]

Channel behavior

Channel What it does What it does not do Best fit
none Disables cluster autoupgrade. Does not keep the cluster current for you. Manual, highly controlled environments.
patch Moves to the latest supported patch within the current minor version. Does not move to the next minor. Teams that want patch automation but manual minor-version gates.
stable Moves to the latest supported patch on minor version N-1. Does not chase the newest GA minor immediately. Conservative production default for AKS Standard.
rapid Moves to the latest supported patch on the newest supported GA minor version. Does not move to preview versions. Fast adopters with strong validation automation.
node-image Legacy channel for node image automation. Should not be treated as the modern default for node OS lifecycle. Existing legacy estates only.

Decision criteria

  • Choose patch when application compatibility review is minor-version sensitive but patch adoption should be automatic.
  • Choose stable when production wants to remain current without leading the newest GA minor immediately.
  • Choose rapid only when your validation discipline is strong enough to absorb faster minor-version movement.
  • Choose none only if you already have a reliable manual upgrade program.
  • Avoid new use of node-image at cluster-channel level; use Node OS Upgrades instead.

Configure the channel

az aks update \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --auto-upgrade-channel stable

az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "autoUpgradeProfile" \
    --output yaml
Command Purpose
az aks update Set the cluster auto-upgrade channel.
--resource-group Resource group that contains the AKS cluster.
--name Name of the AKS cluster.
--auto-upgrade-channel Kubernetes auto-upgrade channel to use.
az aks show Show the resulting auto-upgrade profile.
--resource-group Resource group that contains the AKS cluster.
--name Name of the AKS cluster.
--query Selects the auto-upgrade profile.
--output Output format for the result.

Operational notes

  • Auto-upgrade first upgrades the control plane, then upgrades agent pools.
  • Auto-upgrade only targets GA versions.
  • Changes to the channel can take time to take effect; do not assume immediate behavior change after flipping the setting.
  • Pair the channel with aksManagedAutoUpgradeSchedule so version movement happens during an approved window.

Verification

az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "{clusterChannel:autoUpgradeProfile.upgradeChannel,nodeOsChannel:autoUpgradeProfile.nodeOsUpgradeChannel}" \
    --output yaml
Command Purpose
az aks show Show the cluster and node OS upgrade channels.
--resource-group Resource group that contains the AKS cluster.
--name Name of the AKS cluster.
--query Selects the cluster and node OS upgrade channels.
--output Output format for the result.
  • Confirm the intended cluster channel is present.
  • Confirm the node OS channel is independently set as expected.
  • Confirm a maintenance configuration exists for production clusters that rely on auto-upgrade.

Rollback / Troubleshooting

  • If the chosen channel is too aggressive, move to a more conservative policy such as stable or patch and keep the maintenance window.
  • If the cluster is blocked by workload constraints, fix the blocking cause rather than leaving the cluster unmanaged indefinitely.
  • If you need zero-surprise production cutover, move the highest-risk changes to a Blue-Green Upgrades pattern.

See Also

Sources