Skip to content

Node Image Upgrade Stuck

Symptom

The cluster or node pool remains on an older node image after the expected maintenance window, or some nodes move while others remain on the previous image version.

Possible Causes

  • The regional node image release has not landed yet.
  • The wrong node OS channel is configured.
  • The maintenance window did not allow enough time.
  • Workloads or platform conditions are slowing or blocking node replacement.

Diagnosis Steps

flowchart TD
    A[Node image not updating] --> B[Confirm regional release availability]
    B --> C[Check node OS channel and maintenance window]
    C --> D[Inspect node labels and workload health]

  1. Confirm the node OS channel and current upgrade profile.

    az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "autoUpgradeProfile" \
    --output yaml
    Command Purpose
    az aks show Show the cluster 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.

  2. Inspect node labels and node image versions.

    kubectl get nodes --show-labels

  3. Check whether the expected node image or security patch release is available in the cluster's region.

Resolution

  • Wait for the regional release if the tracker shows the image is not landed yet.
  • Correct the node OS channel if the cluster is using a different policy than intended.
  • Widen the maintenance window if the rollout consistently overruns the allowed time.
  • Resolve workload blockers before expecting the node image rollout to finish.

Prevention

  • Pair node OS channels with explicit maintenance windows.
  • Use the release tracker before declaring a rollout “stuck.”
  • Keep workload disruption budgets and readiness behavior compatible with node refresh events.

See Also

Sources