Configure Node Disruption Policy in Azure Kubernetes Service (AKS) (Preview)

This article shows you how to configure and manage Node Disruption Policy to control when operations that require node reimage and trigger node redeployment are allowed in your Azure Kubernetes Service (AKS) cluster.

Prerequisites

• Review the Node Disruption Policy overview to learn how Node Disruption Policy works and the operations covered by Node Disruption Policy.
• Azure CLI version 2.76.0 or later installed and configured. To find your CLI version, run the az --version command. If you need to install or upgrade, see Install Azure CLI.
• An existing AKS cluster, or you can create a new one with Node Disruption Policy configured.
• Install the aks-preview Azure CLI extension and register the Node Disruption Policy preview feature.

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

• AKS support policies
• Azure support FAQ

Install the aks-preview Azure CLI extension

1. Install the aks-preview extension using the az extension add command.

   az extension add --name aks-preview
   

2. Update to the latest version of the extension using the az extension update command.

   az extension update --name aks-preview
   

Register the Node Disruption Policy preview feature

Register the Node Disruption Policy preview feature using the az feature register command.

az feature register --namespace "Microsoft.ContainerService" --name "NodeDisruptionProfile"

It takes a few minutes for the status to show as Registered.

Configure Node Disruption Policy on a new cluster

Create a new AKS cluster with Node Disruption Policy configured by using the az aks create command with the --node-disruption-policy parameter set to one of the following policy configurations: Allow (default), AllowDuringMaintenanceWindow, or Block.

Allow disruptive operations at any time (default)

az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-count 3 \
    --node-disruption-policy Allow \
    --generate-ssh-keys

Allow disruptive operations only during maintenance windows

az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-count 3 \
    --node-disruption-policy AllowDuringMaintenanceWindow \
    --generate-ssh-keys

Important

When you use AllowDuringMaintenanceWindow, ensure you configure an aksManagedNodeOSUpgradeSchedule maintenance window. Otherwise, disruptive operations are allowed indefinitely. For more information, see Use planned maintenance to schedule and control upgrades for your Azure Kubernetes Service cluster.

Block all disruptive operations

az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-count 3 \
    --node-disruption-policy Block \
    --generate-ssh-keys

Update Node Disruption Policy on an existing cluster

Update the Node Disruption Policy on an existing AKS cluster by using the az aks update command with the --node-disruption-policy parameter set to one of the following policy configurations: Allow (default), AllowDuringMaintenanceWindow, or Block.

Change policy to allow operations during maintenance windows

az aks update \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-disruption-policy AllowDuringMaintenanceWindow

Change policy to block all disruptive operations

az aks update \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-disruption-policy Block

Change policy back to allow operations at any time

az aks update \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-disruption-policy Allow

Verify Node Disruption Policy configuration

Verify the Node Disruption Policy configuration by using the az aks show command.

az aks show \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --query "nodeDisruptionProfile.nodeDisruptionPolicy" \
    --output tsv

The output shows the current policy setting, such as Allow, AllowDuringMaintenanceWindow, or Block.

Handle blocked operations

When the Node Disruption Policy blocks a disruptive operation, you can wait for the maintenance window or temporarily change the policy.

Wait for the maintenance window

If you're using AllowDuringMaintenanceWindow, schedule the operation to occur during the next maintenance window. You can view your configured maintenance windows by using the az aks maintenanceconfiguration list command.

az aks maintenanceconfiguration list \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster

Temporarily change the policy

1. Update the policy to Allow by using the az aks update command with --node-disruption-policy set to Allow.

   az aks update \
       --resource-group myResourceGroup \
       --name myAKSCluster \
       --node-disruption-policy Allow
   

2. Perform your disruptive operation. The following example updates the custom CA certificates by using the az aks update command:

   az aks update \
       --resource-group myResourceGroup \
       --name myAKSCluster \
       --custom-ca-trust-certificates <path-to-certificate-file>
   

3. Restore the original policy by using the az aks update command. The following example restores --node-disruption-policy to Block:

   az aks update \
       --resource-group myResourceGroup \
       --name myAKSCluster \
       --node-disruption-policy Block
   

Operations that require manual node pool upgrade

Some operations that Node Disruption Policy doesn't control require a manual node pool upgrade after any configuration changes. These operations include:

• SSH configuration changes, such as changing SSH access methods or updating SSH public keys.
• IMDS restriction changes, such as enabling or disabling IMDS restriction.
• Bootstrap profile ACR name changes for network isolated clusters.
• Outbound type changes, such as changing cluster egress routing.

For these operations, you must manually run the az aks nodepool upgrade command after making the configuration change. For example:

az aks nodepool upgrade \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --name <nodepool-name> \
    --node-image-only

For more information about operations covered by Node Disruption Policy, see the Node Disruption Policy overview.

Troubleshoot Node Disruption Policy issues

Operation blocked unexpectedly

If an operation is blocked unexpectedly, use the following steps to troubleshoot the issue:

1. Check the current policy setting by using the az aks show command.

   az aks show \
       --resource-group myResourceGroup \
       --name myAKSCluster \
       --query "nodeDisruptionProfile.nodeDisruptionPolicy" \
       --output tsv
   

2. If you're using AllowDuringMaintenanceWindow, verify the maintenance window configuration by using the az aks maintenanceconfiguration show command.

   az aks maintenanceconfiguration show \
       --resource-group myResourceGroup \
       --cluster-name myAKSCluster \
       --name aksManagedNodeOSUpgradeSchedule
   

3. Check if the current time falls within the maintenance window.

No maintenance window configured

If you set the policy to AllowDuringMaintenanceWindow but don't configure a maintenance window, all disruptive operations are allowed.

Configure a maintenance window by using the az aks maintenanceconfiguration add command.

az aks maintenanceconfiguration add \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --name aksManagedNodeOSUpgradeSchedule \
    --schedule-type Weekly \
    --day-of-week Sunday \
    --interval-weeks 1 \
    --duration 4 \
    --start-hour 2

Related content

• Node Disruption Policy overview
• Use planned maintenance to schedule and control upgrades for your Azure Kubernetes Service cluster