Scheduling and Controlling Upgrades in Azure Kubernetes Service with Planned Maintenance

Maintaining and upgrading your Azure Kubernetes Service (AKS) cluster can be a critical but complex task. Fortunately, AKS provides a powerful feature called Planned Maintenance that enables you to schedule and control cluster and node image upgrades. This article will guide you through the ins and outs of using Planned Maintenance to streamline your AKS cluster upgrades.

Understanding Planned Maintenance

Your AKS cluster undergoes regular maintenance automatically, which can be divided into two types:

  1. AKS-initiated Maintenance: This involves the weekly releases that AKS performs to keep your cluster up to date with the latest features and fixes.
  2. User-initiated Maintenance: This includes [cluster auto-upgrades][aks-upgrade] and [node operating system (OS) automatic security updates][node-image-auto-upgrade].

The Planned Maintenance feature in AKS allows you to run both types of maintenance on a schedule of your choosing, helping minimize the impact on your workloads. With Planned Maintenance, you can specify when automatic upgrades should occur, though enabling or disabling Planned Maintenance itself does not enable or disable the automatic upgrades.

Configuring Planned Maintenance

Planned Maintenance in AKS offers three configuration types:

  1. default: This is a basic configuration for controlling AKS weekly releases. These releases can take up to two weeks to roll out to all regions due to Azure’s safe deployment practices. Use the default configuration to schedule these updates in a way that is least disruptive for your needs, and monitor the status of ongoing releases using the [weekly release tracker][release-tracker].

  2. aksManagedAutoUpgradeSchedule: This configuration controls when cluster upgrades scheduled by your auto-upgrade channel are performed. It allows for more granular control over the cadence and recurrence settings compared to the default configuration. For more information on cluster auto-upgrades, see [Automatically upgrade an Azure Kubernetes Service cluster][aks-upgrade].

  3. aksManagedNodeOSUpgradeSchedule: This configuration controls when node OS security patching scheduled by your node OS auto-upgrade channel is performed. Again, it offers more fine-grained control over the schedule than the default configuration. For details on node OS auto-upgrades, see [Automatically patch and update AKS cluster node images][node-image-auto-upgrade].

We recommend using the aksManagedAutoUpgradeSchedule configuration for all cluster upgrade scenarios and the aksManagedNodeOSUpgradeSchedule configuration for all node OS security patching scenarios. The default configuration is intended solely for AKS weekly releases, and you can switch between it and the other two configurations using the az aks maintenanceconfiguration update command.

Creating a Maintenance Window

Planned Maintenance windows are specified in Coordinated Universal Time (UTC). The available schedule types for the aksManagedAutoUpgradeSchedule and aksManagedNodeOSUpgradeSchedule configurations are:

  • Weekly: Schedule maintenance to run on a specific day of the week, at a recurring interval.
  • AbsoluteMonthly: Schedule maintenance to run on a specific day of the month, at a recurring interval.
  • RelativeMonthly: Schedule maintenance to run on a specific day of the week, in a specific week of the month, at a recurring interval.

For the aksManagedNodeOSUpgradeSchedule configuration, you can also use a Daily schedule to perform maintenance at a specific interval of days.

Here are some example maintenance window configurations:

# Weekly schedule
"schedule