I picked this one up via the AKS Docs Tracker I run here. A new PR landed in the azure-aks-docs repo adding documentation for Shared Maintenance Windows, and it caught my attention straight away.
If you’ve ever managed planned maintenance across more than a handful of AKS clusters, you’ll know the problem. You set up a maintenance window for control plane upgrades on one cluster, a separate one for node OS upgrades, and then you do the same thing on the next cluster. And the next. Over time those schedules drift. Someone updates one but not the others. Environments that are supposed to follow the same governance end up on completely different windows without anyone noticing until something breaks during an upgrade.
Shared Maintenance Windows fix that by turning the maintenance schedule into a standalone resource you can define once and link across as many clusters as you want.
Why this matters
Planned maintenance in AKS has always been per-cluster. You set aksManagedAutoUpgradeSchedule or aksManagedNodeOSUpgradeSchedule inline on each cluster and manage those schedules individually. That’s fine for one or two clusters but it doesn’t scale cleanly when a platform team is responsible for upgrade governance across many.
The new model introduces a shared maintenance window as a first-class AKS resource. You create it once, get a resource ID, and then link that ID into maintenance configurations on as many clusters as you need. When you want to change the window, you update one resource and everything pointing at it picks up the change.
For teams running fleet-scale AKS or operating under change management policies that require consistent upgrade windows, this is a meaningful step forward.
A couple of things to know upfront. This is currently in preview, support starts from AKS API version 2026-05-02-preview, and the Azure portal and Terraform don’t support this feature yet. You’ll need the Azure CLI or REST API.
How to set it up
You’ll need the aks-preview extension and the AKSSharedMaintenanceWindowPreview feature flag registered on your subscription before you can use this. The feature registration is subscription-scoped, so you only need to do it once.
|
1 2 3 4 5 |
az extension add --upgrade --name aks-preview az feature register \ --namespace Microsoft.ContainerService \ --name AKSSharedMaintenanceWindowPreview |
Wait until az feature show returns Registered before continuing. Then refresh the provider registration.
|
1 2 3 4 5 6 7 |
az feature show \ --namespace Microsoft.ContainerService \ --name AKSSharedMaintenanceWindowPreview \ --query properties.state \ --output tsv az provider register --namespace Microsoft.ContainerService |
Once that’s done, create the shared window resource. This example sets up a weekly schedule every Friday from 01:00 to 05:00 UTC.
|
1 2 3 4 5 6 7 8 9 |
az aks maintenancewindow create \ --resource-group $RESOURCE_GROUP \ --name mySharedWindow \ --schedule-type Weekly \ --day-of-week Friday \ --interval-weeks 1 \ --duration 4 \ --utc-offset +00:00 \ --start-time 01:00 |
If your change management process runs on a monthly cadence, you can also use a relative monthly schedule instead. This one runs on the last Sunday of every month.
|
1 2 3 4 5 6 7 8 9 10 |
az aks maintenancewindow create \ --resource-group $RESOURCE_GROUP \ --name mySharedWindow \ --schedule-type RelativeMonthly \ --day-of-week Sunday \ --week-index Last \ --interval-months 1 \ --duration 4 \ --utc-offset +00:00 \ --start-time 01:00 |
With the window resource created, grab its resource ID and link it to a maintenance configuration on a cluster.
|
1 2 3 4 5 6 7 |
MAINTENANCE_WINDOW_ID="/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ContainerService/maintenanceWindows/mySharedWindow" az aks maintenanceconfiguration add \ --resource-group $RESOURCE_GROUP \ --cluster-name $CLUSTER_NAME \ --name aksManagedAutoUpgradeSchedule \ --maintenance-window-id $MAINTENANCE_WINDOW_ID |
You can do the same for node OS upgrades, or update an existing maintenance configuration to point at the shared window.
|
1 2 3 4 5 |
az aks maintenanceconfiguration update \ --resource-group $RESOURCE_GROUP \ --cluster-name $CLUSTER_NAME \ --name aksManagedNodeOSUpgradeSchedule \ --maintenance-window-id $MAINTENANCE_WINDOW_ID |
Once linked, both configurations follow the schedule defined in the shared window. If you want to unlink a cluster later, update the configuration with an inline schedule and omit --maintenance-window-id. That converts it back to a standard inline configuration and doesn’t affect anything else pointing at the shared window.
One important thing to watch for is that you can’t combine --maintenance-window-id with inline schedule flags like --schedule-type or --day-of-week in the same command. The two approaches are mutually exclusive. The same applies if you’re using a JSON config file — set maintenanceWindowId in the file instead of mixing it with --config-file and a command-line window ID.
Also worth knowing is that you can’t delete a shared maintenance window while any maintenance configuration still references it. You’ll need to unlink everything pointing at it first. Removing a link doesn’t delete the window though, so other clusters using it are unaffected.
Wrapping up
I’ve managed enough AKS clusters to know that maintenance schedule drift is one of those problems that seems minor until it causes a production incident. This feature doesn’t solve every upgrade governance problem, but it does address the specific pain of keeping schedules consistent across a fleet without manual coordination.
It’s still preview, so I wouldn’t rely on it for production upgrade windows just yet. But I’d absolutely test it now, especially if you’re already dealing with drift across environments. Start with a non-production cluster, link a couple of maintenance configurations to the same shared window, and validate that upgrades fire when expected.
If this reaches GA with the same model, it’ll become a standard part of how I set up AKS at platform scale. If you try it, let me know how it goes.
0 Comments