az aks maintenancewindow

Note

This reference is part of the aks-preview extension for the Azure CLI (version 2.76.0 or higher). The extension will automatically install the first time you run an az aks maintenancewindow command. Learn more about extensions.

Commands to manage MaintenanceWindow peer ARM resources.

MaintenanceWindow is a resource-group-scoped ARM resource that defines a reusable maintenance schedule. Users can link this resource to a pre-existing maintenanceConfiguration via maintenanceWindowId, so multiple managedCluster maintenance configurations share a single MaintenanceWindow and the schedule lives in one place.

Requires the Microsoft.ContainerService/AKSSharedMaintenanceWindowPreview feature to be registered on the subscription. Auto-approval is enabled: az feature register --namespace Microsoft.ContainerService --name AKSSharedMaintenanceWindowPreview.

Commands

Name	Description	Type	Status
az aks maintenancewindow create	Create a MaintenanceWindow.	Extension	GA
az aks maintenancewindow delete	Delete a MaintenanceWindow.	Extension	GA
az aks maintenancewindow list	List MaintenanceWindows in a resource group, or across the subscription if --resource-group is omitted.	Extension	GA
az aks maintenancewindow show	Show a MaintenanceWindow.	Extension	GA
az aks maintenancewindow update	Update a MaintenanceWindow.	Extension	GA
az aks maintenancewindow wait	Wait for a MaintenanceWindow to reach a desired state.	Extension	GA

az aks maintenancewindow create

Create a MaintenanceWindow.

Requires the Microsoft.ContainerService/AKSSharedMaintenanceWindowPreview feature to be registered on the subscription. Register once (auto-approved): az feature register --namespace Microsoft.ContainerService --name AKSSharedMaintenanceWindowPreview.

az aks maintenancewindow create --name
                                --resource-group
                                [--acquire-policy-token]
                                [--change-reference]
                                [--config-file]
                                [--day-of-month]
                                [--day-of-week]
                                [--duration]
                                [--interval-days]
                                [--interval-months]
                                [--interval-weeks]
                                [--location]
                                [--no-wait]
                                [--schedule-type {AbsoluteMonthly, Daily, RelativeMonthly, Weekly}]
                                [--start-date]
                                [--start-time]
                                [--tags]
                                [--utc-offset]
                                [--week-index {First, Fourth, Last, Second, Third}]

Examples

Create a weekly Saturday window (the canonical "production weekends" shape).

az aks maintenancewindow create -g rg-maintenance -n production-weekends -l eastus \
  --schedule-type Weekly --day-of-week Saturday --interval-weeks 1 \
  --start-time "02:00" --duration 8 --utc-offset=-07:00 \
  --tags environment=production

Create a daily window every 2 days from a specific start date.

az aks maintenancewindow create -g rg-maintenance -n nightly -l eastus \
  --schedule-type Daily --interval-days 2 \
  --start-date 2026-06-01 --start-time "00:00" --duration 6 --utc-offset=-08:00

Create an absolute monthly window on the 15th.

az aks maintenancewindow create -g rg-maintenance -n monthly-15 -l eastus \
  --schedule-type AbsoluteMonthly --day-of-month 15 --interval-months 1 \
  --start-time "09:30" --duration 6 --utc-offset=+05:30

Create a relative monthly window on the last Friday.

az aks maintenancewindow create -g rg-maintenance -n last-friday -l eastus \
  --schedule-type RelativeMonthly --day-of-week Friday --week-index Last --interval-months 1 \
  --start-time "01:00" --duration 4 --utc-offset=+00:00

Create a weekly window with blackout dates via a config file.

az aks maintenancewindow create -g rg-maintenance -n weekly-with-holidays -l eastus \
  --config-file ./mw-body.json
  The contents of mw-body.json:
  {
    "properties": {
      "schedule": { "weekly": { "intervalWeeks": 1, "dayOfWeek": "Saturday" } },
      "startTime": "02:00",
      "durationHours": 8,
      "utcOffset": "-07:00",
      "notAllowedDates": [
        { "start": "2026-12-23", "end": "2027-01-05" },
        { "start": "2026-07-04", "end": "2026-07-05" }
      ]
    }
  }

Required Parameters

--name -n

The maintenance window name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--config-file

Path to a JSON file describing the MaintenanceWindow body. Use when you need to set fields without dedicated flags (e.g. notAllowedDates / blackout date ranges).

--day-of-month

Day of month the maintenance occurs. e.g. 15. AbsoluteMonthly schedule only.

--day-of-week

Day of week the maintenance occurs. e.g. Monday. Weekly or RelativeMonthly schedules only.

--duration

The length of the maintenance window in hours. Range 4-24.

--interval-days

Number of days between occurrences. Daily schedule only.

--interval-months

Number of months between occurrences. AbsoluteMonthly or RelativeMonthly schedules only.

--interval-weeks

Number of weeks between occurrences. Weekly schedule only.

--location -l

Location for the MaintenanceWindow. Defaults to the resource group's location when omitted.

--no-wait

Do not wait for the long-running operation to finish.

Property	Value
Default value:	False

--schedule-type

Recurrence type. One of Daily, Weekly, AbsoluteMonthly or RelativeMonthly.

Property	Value
Accepted values:	AbsoluteMonthly, Daily, RelativeMonthly, Weekly

--start-date

The date the maintenance window activates. e.g. 2026-06-01. If not specified, the window activates immediately.

--start-time

The start time of the maintenance window. Accepted values are from '00:00' to '23:59'. --utc-offset applies to this field.

--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

--utc-offset

The UTC offset in format +/-HH:mm. For example, '+05:30' for IST or '-07:00' for PST. Default is '+00:00'.

--week-index

Instance of the day-of-week the maintenance occurs (First, Second, Third, Fourth, Last). RelativeMonthly schedule only.

Property	Value
Accepted values:	First, Fourth, Last, Second, Third

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az aks maintenancewindow delete

Delete a MaintenanceWindow.

az aks maintenancewindow delete --name
                                --resource-group
                                [--acquire-policy-token]
                                [--change-reference]
                                [--no-wait]
                                [--yes]

Required Parameters

--name -n

The maintenance window name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--no-wait

Do not wait for the long-running operation to finish.

Property	Value
Default value:	False

--yes -y

Do not prompt for confirmation.

Property	Value
Default value:	False

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az aks maintenancewindow list

List MaintenanceWindows in a resource group, or across the subscription if --resource-group is omitted.

az aks maintenancewindow list [--resource-group]

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az aks maintenancewindow show

Show a MaintenanceWindow.

az aks maintenancewindow show --name
                              --resource-group

Required Parameters

--name -n

The maintenance window name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az aks maintenancewindow update

Update a MaintenanceWindow.

Read-modify-write semantics matching az aks update and az aks nodepool update: the existing MW is fetched, your supplied fields are merged onto it, and the resulting body is PUT back. Fields you do not supply are preserved as-is (existing tags, existing schedule scalars, existing blackout dates, etc.).

When you do supply a schedule arg (--schedule-type / --interval-* / --day-of-week / --day-of-month / --week-index), the schedule shape is re-built end-to-end from your args (you cannot partially mix Daily + Weekly fields — pick one schedule type and supply its required args).

--tags follows aks update convention: passing --tags replaces the whole tags dictionary; omit --tags to keep the existing tags.

--location cannot be changed (TrackedResource semantics — ARM rejects location changes on PUT). If supplied with a different value than the existing location it is ignored with a warning.

--config-file: when supplied, the JSON file's properties block replaces the existing properties wholesale. This is the only way today to mutate notAllowedDates / blackout date ranges. Individual schedule flags are ignored on this path; tags follow the same --tags rule as without --config-file.

az aks maintenancewindow update --name
                                --resource-group
                                [--acquire-policy-token]
                                [--change-reference]
                                [--config-file]
                                [--day-of-month]
                                [--day-of-week]
                                [--duration]
                                [--interval-days]
                                [--interval-months]
                                [--interval-weeks]
                                [--location]
                                [--no-wait]
                                [--schedule-type {AbsoluteMonthly, Daily, RelativeMonthly, Weekly}]
                                [--start-date]
                                [--start-time]
                                [--tags]
                                [--utc-offset]
                                [--week-index {First, Fourth, Last, Second, Third}]

Examples

Update only tags (existing schedule is preserved).

az aks maintenancewindow update -g rg-maintenance -n production-weekends --tags environment=staging

Update only the schedule's day-of-week (existing duration / start-time / tags preserved).

az aks maintenancewindow update -g rg-maintenance -n production-weekends \
  --schedule-type Weekly --day-of-week Sunday --interval-weeks 1

Change duration only (existing schedule shape preserved).

az aks maintenancewindow update -g rg-maintenance -n production-weekends --duration 6

Replace blackout dates via a config file (preserves tags, location).

az aks maintenancewindow update -g rg-maintenance -n production-weekends --config-file ./mw-body.json
  The contents of mw-body.json should include a complete properties block, e.g.:
  {
    "properties": {
      "schedule": { "weekly": { "intervalWeeks": 1, "dayOfWeek": "Saturday" } },
      "startTime": "02:00",
      "durationHours": 8,
      "utcOffset": "-07:00",
      "notAllowedDates": [ { "start": "2026-12-23", "end": "2027-01-05" } ]
    }
  }

Required Parameters

--name -n

The maintenance window name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--config-file

Path to a JSON file describing the MaintenanceWindow body. When supplied, the JSON wholly defines the resource on create, or replaces the existing properties block on update. This is the only path that can set fields without dedicated flags (notAllowedDates, etc.).

--day-of-month

Day of month the maintenance occurs for AbsoluteMonthly schedule.

--day-of-week

Day of week the maintenance occurs for Weekly or RelativeMonthly schedule.

--duration

The length of the maintenance window in hours. Range 4-24.

--interval-days

The number of days between each set of occurrences for Daily schedule.

--interval-months

The number of months between each set of occurrences for AbsoluteMonthly or RelativeMonthly schedule.

--interval-weeks

The number of weeks between each set of occurrences for Weekly schedule.

--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--no-wait

Do not wait for the long-running operation to finish.

Property	Value
Default value:	False

--schedule-type

Recurrence type: Daily, Weekly, AbsoluteMonthly or RelativeMonthly.

Property	Value
Accepted values:	AbsoluteMonthly, Daily, RelativeMonthly, Weekly

--start-date

The date the maintenance window activates. e.g. 2026-06-01.

--start-time

The start time of the maintenance window. e.g. 09:30.

--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

--utc-offset

The UTC offset in format +/-HH:mm. e.g. -08:00 or +05:30.

--week-index

Instance of the weekday specified in --day-of-week the maintenance occurs for RelativeMonthly schedule.

Property	Value
Accepted values:	First, Fourth, Last, Second, Third

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az aks maintenancewindow wait

Wait for a MaintenanceWindow to reach a desired state.

If an operation on a MaintenanceWindow was interrupted or was started with --no-wait, use this command to wait for it to complete.

az aks maintenancewindow wait --name
                              --resource-group
                              [--acquire-policy-token]
                              [--change-reference]
                              [--created]
                              [--custom]
                              [--deleted]
                              [--exists]
                              [--interval]
                              [--timeout]
                              [--updated]

Examples

Wait for a MaintenanceWindow to be created.

az aks maintenancewindow wait -g rg-maintenance -n production-weekends --created

Required Parameters

--name -n

The maintenance window name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--created

Wait until created with 'provisioningState' at 'Succeeded'.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	False

--custom

Wait until the condition satisfies a custom JMESPath query. E.g. provisioningState!='InProgress', instanceView.statuses[?code=='PowerState/running'].

Property	Value
Parameter group:	Wait Condition Arguments

--deleted

Wait until deleted.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	False

--exists

Wait until the resource exists.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	False

--interval

Polling interval in seconds.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	30

--timeout

Maximum wait in seconds.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	3600

--updated

Wait until updated with provisioningState at 'Succeeded'.

Property	Value
Parameter group:	Wait Condition Arguments
Default value:	False

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False