Use planned maintenance to schedule and control upgrades for your Azure Kubernetes Service cluster

• This article assumes that you have an existing AKS cluster. If you don't have an AKS cluster, see Create an AKS cluster.

• An active Azure subscription. If you don't have an Azure subscription, create a free account before you begin.

• Set your subscription context using the az account set command. For example:

  az account set --subscription "00000000-0000-0000-0000-000000000000"
  

• Terraform installed locally. For installation instructions, see Install Terraform.

Create the Terraform configuration file

Terraform configuration files define the infrastructure that Terraform creates and manages.

Create a file named main.tf and add the following code to define the Terraform version and specify the Azure provider:

terraform {
 required_providers {
   azurerm = {
     source  = "hashicorp/azurerm"
     version = "~>4.0"
   }
   azapi = {
     source  = "azure/azapi"
     version = "~>2.0"
   }
 }
}
provider "azurerm" {
 features {}
}
provider "azapi" {}

Create a resource group

Add the following code to main.tf to create an Azure resource group. Update the location and name values to match your environment.

resource "azurerm_resource_group" "rg" {
 name     = "aks-maintenance-rg"
 location = "East US"
}

Create an AKS cluster

Add the following code to main.tf to create an AKS cluster. Update any values as needed to match your environment.

resource "azurerm_kubernetes_cluster" "aks" {
 name                = "aks-maintenance-cluster"
 location            = azurerm_resource_group.rg.location
 resource_group_name = azurerm_resource_group.rg.name
 dns_prefix          = "aksmaintenance"
 default_node_pool {
   name       = "nodepool1"
   node_count = 1
   vm_size    = "Standard_DS2_v2"
 }
 identity {
   type = "SystemAssigned"
 }
}

Add a maintenance window configuration to an AKS cluster using the az aks maintenanceconfiguration add command.

The first example adds a new default configuration that schedules maintenance to run from 1:00 AM to 5:00 AM every Monday in the UTC time zone. The second example adds 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 time zone.

# Add a new default configuration
az aks maintenanceconfiguration add --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name default --schedule-type Weekly --day-of-week Monday --interval-weeks 1 --duration 4 --utc-offset +00:00 --start-time 01:00

# Add a new aksManagedAutoUpgradeSchedule configuration
az aks maintenanceconfiguration add --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name aksManagedAutoUpgradeSchedule --schedule-type Weekly --day-of-week Friday --interval-weeks 3 --duration 8 --utc-offset +05:30 --start-time 00:00

1. In the Azure portal, go to your AKS cluster resource.

2. From the service menu, under Settings, select Upgrades.

3. Under Upgrade > Automatic upgrade scheduler, select Add schedule.

   

4. On the Add maintenance schedule pane, configure the following maintenance window settings:

   • Repeats: Select the frequency for the maintenance window. We recommend selecting Weekly.
   • Frequency: Select the day of the week for the maintenance window. We recommend selecting Sunday.
   • Maintenance start date: Select the start date for the maintenance window.
   • Maintenance start time: Select the start time for the maintenance window.
   • UTC offset: Select the UTC offset for the maintenance window. The default is +00:00.

   

5. Select Save.

You can use a JSON file to create a maintenance configuration instead of using parameters. When you use this method, you can prevent maintenance during a range of dates by specifying notAllowedDates for default, aksManagedAutoUpgradeSchedule, and aksManagedNodeOSUpgradeSchedule configurations.

1. Create a JSON file with the maintenance window settings.

   The following example creates a default.json file that schedules maintenance to run from 1:00 AM to 5:00 AM every Tuesday in the UTC time zone. There's also an exception from 2021-05-26 to 2021-05-30 where maintenance isn't allowed, even if it overlaps with a maintenance window.

   {
     "properties": {
       "maintenanceWindow": {
           "schedule": {
               "weekly": {
                   "intervalWeeks": 1,
                   "dayOfWeek": "Tuesday"
               }
           },
           "durationHours": 4,
           "utcOffset": "+00:00",
           "startTime": "01:00",
           "notAllowedDates": [
               {
                   "start": "2021-05-26",
                   "end": "2021-05-30"
               }
           ]
       }
     }
   }
   

   The following example creates an autoUpgradeWindow.json file that schedules maintenance to run every three months on the first of the month between 9:00 AM and 1:00 PM in the UTC-08 time zone. There's also an exception from 2023-12-23 to 2024-01-05 where maintenance isn't allowed, even if it overlaps with a maintenance window.

   {
     "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"
               }
           ]
       }
     }
   }
   

2. Add the maintenance window configuration using the az aks maintenanceconfiguration add command with the --config-file parameter.

   The first example adds a new default configuration by using the default.json file. The second example adds a new aksManagedAutoUpgradeSchedule configuration by using the autoUpgradeWindow.json file.

   # Add a new default configuration
   az aks maintenanceconfiguration add --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name default --config-file ./default.json
   
   # Add a new aksManagedAutoUpgradeSchedule configuration
   az aks maintenanceconfiguration add --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name aksManagedAutoUpgradeSchedule --config-file ./autoUpgradeWindow.json
   

Add the maintenance window configuration to main.tf using the azapi_resource resource.

Default maintenance configuration

The following example creates a default maintenance configuration that schedules maintenance to run from 2:00 AM to 6:00 AM every Saturday in the UTC-04:00 time zone:

resource "azapi_resource" "default_maintenance" {
 type      = "Microsoft.ContainerService/managedClusters/maintenanceConfigurations@2025-10-01"
 name      = "default"
 parent_id = azurerm_kubernetes_cluster.aks.id
 schema_validation_enabled = false
 body = {
   properties = {
     maintenanceWindow = {
       schedule = {
         weekly = {
           dayOfWeek     = "Saturday"
           intervalWeeks = 1
         }
       }
       durationHours = 4
       startTime     = "02:00"
       utcOffset     = "-04:00"
     }
   }
 }
}

Autoupgrade maintenance configuration

The following example creates an aksManagedAutoUpgradeSchedule maintenance configuration that schedules maintenance to run every Sunday from 1:00 AM to 5:00 AM in the UTC-04:00 time zone, starting on April 20, 2026:

resource "azapi_resource" "auto_upgrade" {
 type      = "Microsoft.ContainerService/managedClusters/maintenanceConfigurations@2025-10-01"
 name      = "aksManagedAutoUpgradeSchedule"
 parent_id = azurerm_kubernetes_cluster.aks.id
 schema_validation_enabled = false
 body = {
   properties = {
     maintenanceWindow = {
       startDate     = "2026-04-20"
       startTime     = "01:00"
       durationHours = 4
       utcOffset     = "-04:00"
       schedule = {
         weekly = {
           dayOfWeek     = "Sunday"
           intervalWeeks = 1
         }
       }
     }
   }
 }
}

Node OS upgrade maintenance configuration

The following example creates an aksManagedNodeOSUpgradeSchedule maintenance configuration that schedules maintenance to run every Monday from 3:00 AM to 7:00 AM in the UTC-04:00 time zone, starting on April 21, 2026:

resource "azapi_resource" "node_os_upgrade" {
 type      = "Microsoft.ContainerService/managedClusters/maintenanceConfigurations@2025-10-01"
 name      = "aksManagedNodeOSUpgradeSchedule"
 parent_id = azurerm_kubernetes_cluster.aks.id
 schema_validation_enabled = false
 body = {
   properties = {
     maintenanceWindow = {
       startDate     = "2026-04-21"
       startTime     = "03:00"
       durationHours = 4
       utcOffset     = "-04:00"
       schedule = {
         weekly = {
           dayOfWeek     = "Monday"
           intervalWeeks = 1
         }
       }
     }
   }
 }
}

Update an existing maintenance configuration using the az aks maintenanceconfiguration update command.

The following example updates the default configuration to schedule maintenance to run from 2:00 AM to 6:00 AM every Friday:

az aks maintenanceconfiguration update --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name default --schedule-type Weekly --day-of-week Friday --interval-weeks 1 --duration 4 --utc-offset +00:00 --start-time 02:00

1. In the Azure portal, navigate to your AKS cluster resource.

2. From the service menu, under Settings, select Upgrades.

3. Under Upgrade > Automatic upgrade scheduler, select Edit schedule.

   

4. On the Edit maintenance schedule pane, update the maintenance window settings as needed.

5. Select Save.

1. Update the configuration JSON file with the new maintenance window settings.

   The following example updates the default.json file from the previous section to schedule maintenance to run from 2:00 AM to 6:00 AM every Monday:

   {
     "properties": {
       "maintenanceWindow": {
           "schedule": {
               "weekly": {
                   "intervalWeeks": 1,
                   "dayOfWeek": "Monday"
               }
           },
           "durationHours": 4,
           "utcOffset": "+00:00",
           "startTime": "02:00",
           "notAllowedDates": [
               {
                   "start": "2021-05-26",
                   "end": "2021-05-30"
               }
           ]
       }
     }
   }
   

2. Update the maintenance window configuration using the az aks maintenanceconfiguration update command with the --config-file parameter:

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

If you already have an existing AKS cluster managed by Terraform, you can update the maintenance window configuration by modifying the Terraform configuration file and applying the changes using the terraform apply command.

Initialize Terraform

Initialize Terraform in the directory containing your main.tf file using the terraform init command. This command downloads the Azure provider required to manage Azure resources with Terraform.

terraform init

Create a Terraform execution plan

Create a Terraform execution plan using the terraform plan command. This command shows you the resources that Terraform will create or modify in your Azure subscription.

terraform plan

Apply the Terraform configuration

After reviewing and confirming the execution plan, apply the Terraform configuration using the terraform apply command. This command creates or modifies the resources defined in your main.tf file in your Azure subscription.

terraform apply

Delete a maintenance configuration window in your AKS cluster using the az aks maintenanceconfiguration delete command.

The following example deletes the autoUpgradeSchedule maintenance configuration:

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

1. In the Azure portal, navigate to your AKS cluster resource.

2. From the service menu, under Settings, select Cluster configuration.

3. Under Upgrade > Automatic upgrade scheduler, select Edit schedule.

   

4. On the Edit maintenance schedule pane, select Remove schedule.

   

Delete a maintenance configuration window in your AKS cluster using the az aks maintenanceconfiguration delete command.

The following example deletes the autoUpgradeSchedule maintenance configuration:

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

To delete a maintenance configuration, remove the corresponding block from your Terraform configuration and apply the changes using the terraform apply command.