Upgrades¶

AKS upgrades are lifecycle operations, not one-click events. A safe production path combines support-window awareness, maintenance scheduling, workload disruption controls, and explicit post-upgrade validation.

Prerequisites¶

• Confirm the cluster and target version are still within the AKS support model.
• Review maintenance windows, auto-upgrade channels, and node OS channel settings.
• Validate workload resilience: replicas, readiness probes, PodDisruptionBudgets, and zone design.
• Confirm the change window includes rollback-by-traffic or rollback-by-capacity options.

When to Use¶

• Moving to a newer supported Kubernetes minor or patch version.
• Rolling out node image or node OS security updates.
• Normalizing production clusters onto an auto-upgrade and maintenance policy.
• Preparing a high-risk version change that needs staged or blue/green execution.

Procedure¶

flowchart TD
    A[Pick supported target version] --> B[Review release tracker and maintenance windows]
    B --> C[Run preflight checks for APIs capacity and PDBs]
    C --> D[Set surge and channel strategy]
    D --> E[Upgrade non-production first]
    E --> F[Upgrade production or shift traffic to green cluster]
    F --> G[Validate nodes add-ons workloads and networking]
    G --> H[Keep rollback as traffic reversal or retained capacity]

1) Pick the target deliberately¶

Use az aks get-upgrades and the AKS release tracker together:

• az aks get-upgrades tells you what the control plane can target now.
• The release tracker tells you whether the desired minor version, patch, or node image is actually available in your region.
• The version-support policy tells you whether you are staying in community support, entering platform support, or opting into LTS.

az aks get-upgrades \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --output table

az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "{kubernetesVersion:currentKubernetesVersion,autoUpgradeProfile:autoUpgradeProfile,supportPlan:supportPlan}" \
    --output yaml

2) Run preflight checks before touching production¶

At minimum, review these failure domains before the first upgrade action:

• Deprecated APIs: check manifests, CRDs, admission webhooks, and controllers before the target minor version removes them.
• Subnet and IP headroom: surge nodes and pod density can fail upgrades before workloads move.
• Quota and SKU capacity: specialized pools and regional constraints can block surge creation.
• Add-on and controller compatibility: ingress, CSI drivers, policy engines, and workload identity dependencies must tolerate the target release.
• PodDisruptionBudgets: PDBs that allow zero effective disruption commonly block drain operations.
• Max surge: the faster you upgrade, the more temporary capacity and IP headroom you consume.

Useful checks:

kubectl get pdb --all-namespaces
kubectl api-resources
kubectl get nodes --show-labels

az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "networkProfile" \
    --output yaml

3) Choose the operating model¶

Use the least risky model that still meets delivery speed:

• Manual upgrade: best when you need explicit operator gates for every environment.
• Cluster auto-upgrade + maintenance window: best when you want to stay within the support window with less operator effort.
• Blue/green cluster replacement: best when the blast radius is unacceptable for in-place production rollout.

See Auto-Upgrade Channels, Node OS Upgrades, and Blue-Green Upgrades before finalizing the path.

4) Stage non-production first¶

Run the same upgrade mechanics you intend to use in production:

• Same channel or manual command path.
• Same max surge philosophy.
• Same maintenance schedule shape.
• Same critical controllers, webhooks, policy engines, and ingress components.

If non-production hides too many production-only controllers or traffic patterns, it is not a sufficient rehearsal.

5) Execute with explicit validation gates¶

For manual execution:

az aks upgrade \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --kubernetes-version <target-version> \
    --yes

During execution, watch for:

• Drain failures caused by PDBs.
• Stuck or quarantined nodes.
• Node image rollout lag.
• Ingress or network-policy regressions.
• Add-on pods that never return to Ready.

6) Validate the cluster after the change¶

Post-upgrade validation should prove both platform health and workload health:

az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "{kubernetesVersion:currentKubernetesVersion,nodeResourceGroup:nodeResourceGroup,autoUpgradeProfile:autoUpgradeProfile}" \
    --output yaml

kubectl get nodes
kubectl get pods --all-namespaces
kubectl get events --all-namespaces --sort-by=.lastTimestamp

Validate at least:

• Node versions and node image labels match the intended end state.
• Core add-ons and critical DaemonSets returned to Ready.
• Ingress, DNS, storage, workload identity, and network-policy paths still work.
• Application probes, synthetic traffic, and business transactions pass.

Verification¶

• Cluster version, node versions, and node image rollout match the planned target.
• No cluster-critical add-on remains degraded after the upgrade window.
• Synthetic checks succeed for north-south traffic, east-west traffic, and Azure dependency access.
• The incident team can point to a concrete rollback path that does not rely on an in-place version reversal.

Rollback / Troubleshooting¶

• For high-risk production changes, treat rollback as traffic reversal or retained capacity, not as an in-place downgrade plan.
• If drains fail, start with Upgrade Blocked by Pod Disruption Budget.
• If the control plane refuses the target, start with Upgrade Blocked by Deprecated API.
• If nodes stall on image rollout, use Node Image Upgrade Stuck.
• If surge nodes fail because of subnet pressure, use Surge Upgrade IP Exhaustion.

See Also¶

• AKS Version Lifecycle
• Version Support
• Auto-Upgrade Channels
• Node OS Upgrades
• Maintenance Windows
• Blue-Green Upgrades
• Reliability

Sources¶

• Supported Kubernetes versions in AKS
• Upgrade options and recommendations for AKS clusters
• Automatically upgrade an AKS cluster
• Autoupgrade node OS images in AKS
• Use planned maintenance to schedule and control upgrades for AKS clusters
• AKS release tracker