Skip to content

Node OS Upgrades

Cluster version policy and node OS policy are different decisions. Kubernetes minor and patch upgrades control API and control-plane behavior; node OS channels control how quickly AKS applies security and image-level fixes to the machines that actually run your workloads.

Prerequisites

  • Decide whether the environment prioritizes fastest security response or broader bug-fix uptake.
  • Confirm the cluster has an explicit maintenance schedule for production.
  • Verify add-ons, custom DaemonSets, and workload startup paths tolerate node reimage events.

When to Use

  • Defining the default node update posture for AKS Standard clusters.
  • Aligning security-patch urgency with maintenance and workload resilience.
  • Replacing the legacy node-image cluster auto-upgrade habit with the dedicated node OS policy.

Procedure

flowchart TD
    A[Choose node OS policy] --> B{Need fully manual node patch ownership?}
    B -->|Yes| C[None]
    B -->|No| D{Need OS-native unmanaged patching?}
    D -->|Yes| E[Unmanaged]
    D -->|No| F{Prioritize fastest security response?}
    F -->|Yes| G[SecurityPatch]
    F -->|No| H[NodeImage]

Channel comparison

Channel What it does Trade-off Best fit
None No automatic node security updates. Full operator ownership and highest drift risk. Exceptional environments only.
Unmanaged Uses OS-native patching behavior. AKS does not control update timing; reboot handling is on you. Estates with their own OS patch orchestration model.
SecurityPatch Applies AKS-tested security patches and can avoid full reimage when live patching is sufficient. Focuses on security fixes, not broader bug-fix payloads. Security-first environments that want faster CVE response.
NodeImage Reimages nodes to a newly patched VHD with security fixes and bug fixes on a weekly cadence. More disruptive than live patching, but simpler and broader in payload. Recommended default for most AKS Standard production clusters.

Decision guidance

  • Choose SecurityPatch when the primary objective is fast security remediation and you accept the channel's narrower scope.
  • Choose NodeImage when you want the cleanest fully managed weekly node refresh with both security and bug fixes.
  • Choose Unmanaged only if your operating model already owns reboot timing and patch orchestration.
  • Avoid None for long-lived production clusters unless a separate, enforced node-patching process exists.

Configure the node OS channel

az aks update \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --node-os-upgrade-channel NodeImage

az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "autoUpgradeProfile" \
    --output yaml
Command Purpose
az aks update Set the node OS auto-upgrade channel.
--resource-group Resource group that contains the AKS cluster.
--name Name of the AKS cluster.
--node-os-upgrade-channel Node OS 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.

CVE response and operational cadence

For production planning, the important difference is usually:

  • SecurityPatch is the faster security-only path.
  • NodeImage is the broader weekly image-refresh path.

Use the AKS release tracker to confirm which node image or security patch release has landed in the cluster's region before you assume the fix is available.

Verification

az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "autoUpgradeProfile.nodeOsUpgradeChannel" \
    --output tsv

kubectl get nodes --show-labels
Command Purpose
az aks show Show the node OS upgrade channel.
--resource-group Resource group that contains the AKS cluster.
--name Name of the AKS cluster.
--query Selects the node OS upgrade channel.
--output Output format for the result.
kubectl get nodes List nodes with labels to confirm image state.
  • Confirm the cluster shows the intended nodeOsUpgradeChannel value.
  • Confirm node labels reflect the expected image version after rollout.
  • Confirm the maintenance configuration for aksManagedNodeOSUpgradeSchedule exists in production.

Rollback / Troubleshooting

  • If node refreshes are too disruptive, revisit workload readiness, PDBs, and maintenance timing before changing the channel.
  • If the cluster needs quicker security reaction, move from NodeImage to SecurityPatch rather than disabling automation.
  • If node reimage rollout stalls, use Node Image Upgrade Stuck.

See Also

Sources