Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster (preview)

Your AKS cluster has regular maintenance performed on it automatically. By default, this work can happen at any time. Planned Maintenance allows you to schedule weekly maintenance windows to perform updates and minimize workload impact. Once scheduled, maintenance will occur only during the window you selected.

Before you begin

This article assumes that you have an existing AKS cluster. If you need an AKS cluster, see the AKS quickstart using the Azure CLI, using Azure PowerShell, or using the Azure portal.

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:

Limitations

When you use Planned Maintenance, the following restrictions apply:

  • AKS reserves the right to break these windows for unplanned/reactive maintenance operations that are urgent or critical.
  • Currently, performing maintenance operations are considered best-effort only and are not guaranteed to occur within a specified window.
  • Updates cannot be blocked for more than seven days.

Install aks-preview CLI extension

You also need the aks-preview Azure CLI extension version 0.5.124 or later. Install the aks-preview Azure CLI extension by using the az extension add command. Or install any available updates by using the az extension update command.

# Install the aks-preview extension
az extension add --name aks-preview

# Update the extension to make sure you have the latest version installed
az extension update --name aks-preview

Understanding maintenance window configuration types

There are currently two available configuration types: default and aksManagedAutoUpgradeSchedule:

  • default corresponds to a basic configuration that will update your control plane and your kube-system pods on a virtual machine scale sets instance. It is a legacy configuration that is mostly suitable for basic scheduling of weekly releases.

  • aksManagedAutoUpgradeSchedule is a more complex configuration that controls when upgrades scheduled by your designated auto-upgrade channel are performed. More finely controlled cadence and recurrence settings are possible.¬†For more information on cluster auto-upgrade, see Automatically an Azure Kubernetes Service (AKS) cluster.

Choosing between configuration types

We recommend using aksManagedAutoUpgradeSchedule for all maintenance and upgrade scenarios, while default is meant exclusively for weekly releases. You can port default configurations to aksManagedAutoUpgradeSchedule configurations via the az aks maintenanceconfiguration update command.

Note

When using auto-upgrade, to ensure proper functionality, use a maintenance window with a duration of four hours or more.

Creating a maintenance window

To create a maintenance window, you can use the az aks maintenanceconfiguration add command using the --name value default or aksManagedAutoUpgradeSchedule. The name value should reflect the desired configuration type. Using any other name will cause your maintenance window not to run.

Planned Maintenance windows are specified in Coordinated Universal Time (UTC).

A default maintenance window has the following properties:

Name Description Default value
timeInWeek In a default configuration, this property contains the day and hourSlots values defining a maintenance window N/A
timeInWeek.day The day of the week to perform maintenance in a default configuration N/A
timeInWeek.hourSlots A list of hour-long time slots to perform maintenance on a given day in a default configuration N/A
notAllowedTime Specifies a range of dates that maintenance cannot run, determined by start and end child properties. Only applicable when creating the maintenance window using a config file N/A

An aksManagedAutoUpgradeSchedule has the following properties:

Name Description Default value
utcOffset Used to determine the timezone for cluster maintenance +00:00
startDate The date on which the maintenance window will begin to take effect The current date at creation time
startTime The time for maintenance to begin, based on the timezone determined by utcOffset N/A
schedule Used to determine frequency. Three types are available: Weekly, AbsoluteMonthly, and RelativeMonthly N/A
intervalWeeks The interval in weeks for maintenance runs N/A
intervalMonths The interval in months for maintenance runs N/A
dayOfWeek The specified day of the week for maintenance to begin N/A
durationHours The duration of the window for maintenance to run N/A
notAllowedDates Specifies a range of dates that maintenance cannot run, determined by start and end child properties. Only applicable when creating the maintenance window using a config file N/A

Understanding schedule types

There are currently three available schedule types: Weekly, AbsoluteMonthly, and RelativeMonthly. These schedule types are only applicable to aksManagedClusterAutoUpgrade configurations.

Note

All of the fields shown for each respective schedule type are required.

Weekly schedule

A Weekly schedule may look like "every two weeks on Friday":

"schedule": {
    "weekly": {
        "intervalWeeks": 2,
        "dayOfWeek": "Friday"
    }
}

AbsoluteMonthly schedule

An AbsoluteMonthly schedule may look like "every three months, on the first day of the month":

"schedule": {
    "absoluteMonthly": {
        "intervalMonths": 3,
        "dayOfMonth": 1
    }
}

RelativeMonthly schedule

A RelativeMonthly schedule may look like "every two months, on the last Monday":

"schedule": {
    "relativeMonthly": {
        "intervalMonths": 2,
        "dayOfWeek": "Monday",
        "weekIndex": "Last"
    }
}

Valid values for weekIndex are First, Second, Third, Fourth, and Last.

Add a maintenance window configuration with Azure CLI

The following example shows a command to add a new default configuration that schedules maintenance to run from 1:00am to 2:00am every Monday:

az aks maintenanceconfiguration add -g myResourceGroup --cluster-name myAKSCluster --name default --weekday Monday --start-hour 1

Note

When using a default configuration type, to allow maintenance anytime during a day omit the --start-time parameter.

The following example shows a command to add a new aksManagedAutoUpgradeSchedule configuration that schedules maintenance to run every third Friday between 12:00 AM and 8:00 AM in the UTC+5:30 timezone:

az aks maintenanceconfiguration add -g myResourceGroup --cluster-name myAKSCluster -n aksManagedAutoUpgradeSchedule --schedule-type Weekly --day-of-week Friday --interval-weeks 3 --duration 8 --utc-offset +05:30 --start-time 00:00

Add a maintenance window configuration with a JSON file

You can also use a JSON file create a maintenance configuration instead of using parameters. This method has the added benefit of allowing maintenance to be prevented during a range of dates, specified by notAllowedTimes for default configurations and notAllowedDates for aksManagedAutoUpgradeSchedule configurations.

Create a default.json file with the following contents:

{
  "timeInWeek": [
    {
      "day": "Tuesday",
      "hour_slots": [
        1,
        2
      ]
    },
    {
      "day": "Wednesday",
      "hour_slots": [
        1,
        6
      ]
    }
  ],
  "notAllowedTime": [
    {
      "start": "2021-05-26T03:00:00Z",
      "end": "2021-05-30T12:00:00Z"
    }
  ]
}

The above JSON file specifies maintenance windows every Tuesday at 1:00am - 3:00am and every Wednesday at 1:00am - 2:00am and at 6:00am - 7:00am in the UTC timezone. There is also an exception from 2021-05-26T03:00:00Z to 2021-05-30T12:00:00Z where maintenance isn't allowed even if it overlaps with a maintenance window.

Create an autoUpgradeWindow.json file with the following contents:

{
  "properties": {
    "maintenanceWindow": {
        "schedule": {
            "absoluteMonthly": {
                "intervalMonths": 3,
                "dayOfMonth": 1
            }
        },
        "durationHours": 4,
        "utcOffset": "-08:00",
        "startTime": "09:00",
        "notAllowedDates": [
            {
                "start": "2023-12-23",
                "end": "2024-01-05"
            }
        ]
    }
  }
}

The above JSON file specifies maintenance windows every three months on the first of the month between 9:00 AM - 1:00 PM in the UTC-08 timezone. There is also an exception from 2023-12-23 to 2024-01-05 where maintenance isn't allowed even if it overlaps with a maintenance window.

The following command adds the maintenance windows from default.json and autoUpgradeWindow.json:

az aks maintenanceconfiguration add -g myResourceGroup --cluster-name myAKSCluster --name default --config-file ./test.json

az aks maintenanceconfiguration add -g myResourceGroup --cluster-name myAKSCluster --name aksManagedAutoUpgradeSchedule --config-file ./autoUpgradeWindow.json

Update an existing maintenance window

To update an existing maintenance configuration, use the az aks maintenanceconfiguration update command.

az aks maintenanceconfiguration update -g myResourceGroup --cluster-name myAKSCluster --name default --weekday Monday  --start-hour 2

List all maintenance windows in an existing cluster

To see all current maintenance configuration windows in your AKS cluster, use the az aks maintenanceconfiguration list command.

az aks maintenanceconfiguration list -g myResourceGroup --cluster-name myAKSCluster

Show a specific maintenance configuration window in an AKS cluster

To see a specific maintenance configuration window in your AKS Cluster, use the az aks maintenanceconfiguration show command.

az aks maintenanceconfiguration show -g myResourceGroup --cluster-name myAKSCluster --name aksManagedAutoUpgradeSchedule

The following example output shows the maintenance window for aksManagedAutoUpgradeSchedule:

{
  "id": "/subscriptions/<subscription>/resourceGroups/myResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster/maintenanceConfigurations/aksManagedAutoUpgradeSchedule",
  "maintenanceWindow": {
    "durationHours": 4,
    "notAllowedDates": [
      {
        "end": "2024-01-05",
        "start": "2023-12-23"
      }
    ],
    "schedule": {
      "absoluteMonthly": {
        "dayOfMonth": 1,
        "intervalMonths": 3
      },
      "daily": null,
      "relativeMonthly": null,
      "weekly": null
    },
    "startDate": "2023-01-20",
    "startTime": "09:00",
    "utcOffset": "-08:00"
  },
  "name": "aksManagedAutoUpgradeSchedule",
  "notAllowedTime": null,
  "resourceGroup": "myResourceGroup",
  "systemData": null,
  "timeInWeek": null,
  "type": null
}

Delete a certain maintenance configuration window in an existing AKS Cluster

To delete a certain maintenance configuration window in your AKS Cluster, use the az aks maintenanceconfiguration delete command.

az aks maintenanceconfiguration delete -g MyResourceGroup --cluster-name myAKSCluster --name autoUpgradeSchedule

Next steps