AKS Node Disruption Policy is Now in Preview: Control When Your Nodes Get Reimaged

Reading Time: 5 minutes

If you have ever watched a routine cluster configuration change silently reimage your node pools mid-business-hours and wondered why you had no say in the matter, this feature is for you.

Two PRs landed in the azure-cli-extensions repo recently that bring a new preview capability to the aks-preview CLI extension. PR #9893 added --node-disruption-policy to az aks update. PR #9960 completed the picture by wiring the same flag into az aks create. Together they give you cluster-level control over whether AKS is allowed to reimage your nodes when it needs to apply certain changes.

What Problem Does This Solve?

Certain operations on an AKS cluster trigger node reimaging. This is expected behaviour, but the timing is not always welcome. Things like updating your HTTP proxy configuration, adding or removing CA certificates, rotating managed identity credentials, or switching network policies all require AKS to reimage affected nodes to apply the change.

By default, AKS will proceed immediately. If you have workloads that are sensitive to node disruption, that is a problem. You might have maintenance windows configured, you might be mid-incident, or you might simply want more predictable change management than “AKS will do it when it wants to.”

Node Disruption Policy introduces a cluster-level property on nodeDisruptionProfile that lets you tell AKS how to handle these situations.

The Three Policy Values

The flag accepts one of three values, and it is worth understanding what each actually does before you reach for one.

Allow is the default behaviour. AKS reimages nodes immediately when an operation requires it. Nothing changes from what you have today.

Block rejects any operation that would trigger a node reimage. When you attempt a change that requires reimaging, the API call fails with an error message and nothing is applied. To actually make the change, you need to temporarily switch the policy to Allow, apply the update, then switch back to Block. This gives you full control over when disruptive changes can happen, but it is a hard gate, not a queue-and-apply-later mechanism. Use it during critical periods or incident response, not as a long-term default.

AllowDuringMaintenanceWindow is the middle ground. AKS will hold reimage operations and execute them only when the cluster’s configured maintenance window is active. If you already use planned maintenance on your clusters, this is probably the option you want. This policy specifically requires an aksManagedNodeOSUpgradeSchedule maintenance window to be configured. If no such window exists, AKS falls back to allowing the operations immediately rather than blocking them indefinitely.

Prerequisites

This is a preview feature. You need the aks-preview CLI extension and the NodeDisruptionProfile feature flag registered on your subscription.

Install or update the extension:

Register the feature flag:

Wait for the registration to complete:

Once it shows Registered, propagate the change to the resource provider:

Setting the Policy at Create Time

You can set the policy when creating a new cluster:

If you are using AllowDuringMaintenanceWindow, you also need to configure an aksManagedNodeOSUpgradeSchedule maintenance window. This is a separate step after the cluster is created:

Without this, AKS has no window to reference and will fall back to allowing reimage operations immediately, which defeats the purpose of the policy.

Updating an Existing Cluster

For existing clusters, use az aks update:

You can change the policy at any time. Switching from Block back to Allow will not retroactively trigger any previously blocked operations, but it will allow future reimage-triggering operations to proceed immediately.

Operations Covered by Node Disruption Policy

Not every cluster change triggers a node reimage, and not every reimage is subject to the policy. Here is the full breakdown.

Cluster-level operations

These affect all node pools in the cluster when triggered.

Network policy and CNI changes: Switching to or from Azure Network Policy, Calico, or upgrading from Azure CNI to Azure CNI Overlay requires networking components to be installed and network rules reconfigured on every node. Note: switching between Azure and Calico (when one is already enabled) does not require a reimage.

Node OS upgrade channel changes: Each channel uses different OS patching infrastructure that cannot be modified on running nodes. Changing from Unmanaged to any other channel, or from any channel back to Unmanaged, triggers a reimage. Switching between SecurityPatch, NodeImage, and None channels does not.

IPv6 dual-stack enablement: Adding IPv6 to a previously IPv4-only cluster requires both IP configurations and nftables rules to be updated at the OS level.

Cilium data plane changes: Enabling or disabling Cilium installs or removes eBPF programs at the kernel level. Switching between no Cilium and Cilium in either direction triggers a reimage.

HTTP proxy configuration: All node components (containerd, kubelet, system services) require the proxy configuration applied system-wide. Any modification to httpProxy, httpsProxy, noProxy, or trustedCa, as well as enabling, disabling, or re-enabling the proxy, triggers a cluster-wide reimage of all node pools.

Custom CA certificates: Adding, removing, or updating CA certificates requires the OS trust store to be updated on every node.

Kubelet identity changes: Updating the managed identity or user-assigned managed identity for the kubelet, including initial assignment, identity updates, and service principal profile resets.

Private DNS zone changes: Modifying the private DNS zone configuration on a private cluster requires DNS resolver settings to be updated on all nodes.

API Server VNet Integration enablement: Enabling API Server VNet Integration on an existing cluster requires nodes to be reconfigured to communicate with the API server through the internal load balancer IP projected into the delegated subnet.

eBPF host routing changes: Enabling or disabling BpfVeth acceleration mode installs or removes eBPF programs for high-performance packet forwarding.

Node pool-level operations

These trigger a rolling reimage within only the affected node pool.

Local DNS profile updates: Changes to DNS caching daemon configuration and forwarding rules must be applied at the node level.

Trusted Launch security changes: Enabling or disabling vTPM (virtual Trusted Platform Module) or Secure Boot requires VM firmware and boot process settings to be changed, which cannot be done on running VMs.

Artifact streaming changes: Enabling or disabling artifact streaming installs or removes the components that handle on-demand image layer streaming.

Windows GMSA profile updates: Modifications to GMSA configurations on Windows node pools require new settings, DNS server configuration, and domain join credentials to be applied.

Capacity Reservation Group attachment: Attaching a Capacity Reservation Group (CRG) to an existing node pool that does not already have one requires the underlying VMs to be recreated so they are allocated from the reserved capacity.

Operations not yet covered

The following changes require a node reimage but are not yet subject to Node Disruption Policy. After making these changes, you must manually run az aks nodepool upgrade --node-image-only to apply them to your nodes.

• SSH configuration changes: Changing SSH access methods or updating SSH public keys.
• IMDS restriction changes: Enabling or disabling Instance Metadata Service restriction for pod access.
• Bootstrap profile changes: Switching the artifactSource between Direct and Cache, or changing the container registry used for bootstrap profiles in network-isolated clusters.
• Outbound type changes: Modifying the cluster’s outbound connectivity type (loadBalancer, userDefinedRouting, managedNATGateway, or userAssignedNATGateway).

Operations the policy never controls

These operations always proceed regardless of your policy setting.

Upgrade operations: Node image version updates and Kubernetes version upgrades (whether manual or via an auto-upgrade channel) are intentionally excluded. These are operations you or AKS schedule deliberately, not side effects of configuration changes.

Recovery operations: Node pool rollback after a failed upgrade, admin cluster restore operations performed by Azure support, and periodic node identity credential rotation by AKS for security compliance will always proceed when needed to maintain cluster health.

Wrapping Up

Node Disruption Policy fills a real gap. The most predictable use case is pairing AllowDuringMaintenanceWindow with an existing planned maintenance configuration. You get the change applied without manual intervention, but it happens at a time you have already pre-approved. Block is the right choice if your change management process requires a human to explicitly trigger node maintenance after a config change. Just remember it is a hard block, not a deferral, so plan for the policy toggle when you need to apply the change.

It is a preview feature, so not for production yet. But the design is clean and the implementation is straightforward. If you are managing clusters where node disruption has caused you pain in the past, it is worth registering the feature flag now and getting familiar with how it works.