Node image updates for node auto-provisioning (NAP) in Azure Kubernetes Service (AKS)

This article provides an overview of node image updates for node auto-provisioning (NAP) in Azure Kubernetes Service (AKS), including how it works, recommended maintenance windows, and examples to get started.

How do node image updates work for node auto-provisioning nodes?

By default, NAP node pool virtual machines (VMs) are automatically updated when a new image version is available. You can configure an AKS-managed node operating system (OS) upgrade schedule maintenance window to control when new images are picked up and applied to your NAP nodes, or use Karpenter Node Disruption Budgets and Pod Disruption Budgets to control how and when disruption occurs during upgrades.

Note

NAP forces the latest image version to be picked up if the existing node image version is older than 90 days. This bypasses any existing maintenance window.

Node OS upgrade maintenance windows for NAP

You can use the AKS planned maintenance feature with a node OS auto-upgrade channel to configure a aksManagedNodeOSUpgradeSchedule maintenance window that controls when to perform node OS security patching scheduled by your designated node OS auto-upgrade channel.

Node OS upgrade maintenance window behavior and considerations

Keep the following information in mind when configuring a node OS upgrade maintenance window for NAP:

  • The aksManagedNodeOSUpgradeSchedule maintenance configuration determines the window during which NAP picks up a new image. This configuration doesn't necessarily determine when existing nodes are disrupted.
  • The upgrade mechanism and decision criteria are specific to NAP/Karpenter and are evaluated by NAP's drift logic. NAP respects Karpenter Node Disruption Budgets and Pod Disruption Budgets. For more information about drift, see the Karpenter drift documentation.
  • These NAP upgrade decisions are separate from the cluster NodeImage and SecurityPatch channels. However, the aksManagedNodeOSUpgradeSchedule maintenance configuration applies them as well.
  • We recommend using a maintenance window of four hours or more for reliable operation.
  • If no maintenance configuration exists, AKS might use a fallback schedule to pick up new images, which can cause images to be picked up at unexpected times. You can avoid unexpected timing of new images and upgrades by defining an explicit aksManagedNodeOSUpgradeSchedule.
  • Allow at least 30 minutes between creating or updating a maintenance configuration and the scheduled start time to ensure AKS has time to reconcile the new configuration.

We recommend the following schedule pattern for NAP-managed nodes:

  • Weekly cadence: Recommended for routine node image roll outs (for example: Every week on Sunday).

Create a node OS maintenance schedule example

The following sections show you how to create a weekly maintenance window for NAP-managed nodes using the Azure CLI and a JSON configuration file and how to update, view, list, and delete the maintenance configuration.

Create a maintenance configuration

  1. Create a JSON file named nodeosMaintenance.json with a weekly maintenance window (for example: Sunday at 01:00 UTC for 4 hours).

    {
  "properties": {
    "maintenanceWindow": {
      "durationHours": 4,
      "schedule": {
        "weekly": {
          "intervalWeeks": 1,
          "dayOfWeek": "Sunday"
        }
      },
      "startDate": "2025-01-01",
      "startTime": "01:00",
      "utcOffset": "+00:00"
    }
  }
}

  2. Add the maintenance configuration to your cluster using the az aks maintenanceconfiguration add command.

    az aks maintenanceconfiguration add \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name aksManagedNodeOSUpgradeSchedule \
  --config-file ./nodeosMaintenance.json

Update, view, list, or delete a maintenance configuration

You can use the following commands to update, view, list, or delete a maintenance configuration for NAP-managed nodes:

  • Update a maintenance configuration by modifying the JSON file and then running the az aks maintenanceconfiguration update command.

    az aks maintenanceconfiguration update \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name aksManagedNodeOSUpgradeSchedule \
  --config-file ./nodeosMaintenance.json

  • View the details of a maintenance configuration using the az aks maintenanceconfiguration show command.

    az aks maintenanceconfiguration show \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name aksManagedNodeOSUpgradeSchedule

  • List all maintenance configurations for your cluster using the az aks maintenanceconfiguration list command.

    az aks maintenanceconfiguration list \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME

  • Delete a maintenance configuration using the az aks maintenanceconfiguration delete command.

    az aks maintenanceconfiguration delete \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name aksManagedNodeOSUpgradeSchedule

For complete details, examples, and advanced scenarios, see Use Planned Maintenance to schedule maintenance windows for your AKS cluster.

Karpenter Node Disruption Budgets and Pod Disruption Budgets for NAP

For more information on configuring Karpenter Node Disruption Budgets and Pod Disruption Budgets for NAP, see the following resources from the official Karpenter documentation:

Next steps

For more information on node auto-provisioning in AKS, see the following articles:

  • Last updated on