Skip to content

Commit d66938e

Browse files
v-regandownerv-regandowner
authored
Merge pull request #224177 from Nickomang/aks-autoupgrade-schedule
Auto Upgrade Schedule maintenance window
2 parents 59d85d3 + b48af8c commit d66938e

File tree

1 file changed

+183
-115
lines changed

1 file changed

+183
-115
lines changed

‎articles/aks/planned-maintenance.md

Lines changed: 183 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,14 @@ titleSuffix: Azure Kubernetes Service
44
description: Learn how to use Planned Maintenance in Azure Kubernetes Service (AKS).
55
services: container-service
66
ms.topic: article
7-
ms.date: 03/03/2021
7+
ms.date: 01/17/2023
88
ms.author: qpetraroia
99
author: qpetraroia
10-
1110
---
1211

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

15-
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 that will update your control plane as well as your kube-system pods on a VMSS instance, and minimize workload impact. Once scheduled, all your maintenance will occur during the window you selected. You can schedule one or more weekly windows on your cluster by specifying a day or time range on a specific day. Maintenance Windows are configured using the Azure CLI.
14+
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.
1615

1716
## Before you begin
1817

@@ -30,7 +29,7 @@ When you use Planned Maintenance, the following restrictions apply:
3029

3130
### Install aks-preview CLI extension
3231

33-
You also need the *aks-preview* Azure CLI extension version 0.5.4 or later. Install the *aks-preview* Azure CLI extension by using the [az extension add][az-extension-add] command. Or install any available updates by using the [az extension update][az-extension-update] command.
32+
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][az-extension-add] command. Or install any available updates by using the [az extension update][az-extension-update] command.
3433

3534
```azurecli-interactive
3635
# Install the aks-preview extension
@@ -40,163 +39,237 @@ az extension add --name aks-preview
4039
az extension update --name aks-preview
4140
```
4241

43-
## Allow maintenance on every Monday at 1:00am to 2:00am
42+
## Understanding maintenance window configuration types
43+
44+
There are currently two available configuration types: `default` and `aksManagedAutoUpgradeSchedule`:
45+
46+
- `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][release-tracker].
47+
48+
- `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][aks-upgrade].
49+
50+
### Choosing between configuration types
51+
52+
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.
53+
54+
> [!NOTE]
55+
> When using auto-upgrade, to ensure proper functionality, use a maintenance window with a duration of four hours or more.
56+
57+
## Creating a maintenance window
58+
59+
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.
60+
61+
Planned Maintenance windows are specified in Coordinated Universal Time (UTC).
62+
63+
A `default` maintenance window has the following properties:
4464

45-
To add a maintenance window, you can use the `az aks maintenanceconfiguration add` command.
65+
|Name|Description|Default value|
66+
|--|--|--|
67+
|`timeInWeek`|In a `default` configuration, this property contains the `day` and `hourSlots` values defining a maintenance window|N/A|
68+
|`timeInWeek.day`|The day of the week to perform maintenance in a `default` configuration|N/A|
69+
|`timeInWeek.hourSlots`|A list of hour-long time slots to perform maintenance on a given day in a `default` configuration|N/A|
70+
|`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|
71+
72+
An `aksManagedAutoUpgradeSchedule` has the following properties:
73+
74+
|Name|Description|Default value|
75+
|--|--|--|
76+
|`utcOffset`|Used to determine the timezone for cluster maintenance|`+00:00`|
77+
|`startDate`|The date on which the maintenance window will begin to take effect|The current date at creation time|
78+
|`startTime`|The time for maintenance to begin, based on the timezone determined by `utcOffset`|N/A|
79+
|`schedule`|Used to determine frequency. Three types are available: `Weekly`, `AbsoluteMonthly`, and `RelativeMonthly`|N/A|
80+
|`intervalWeeks`|The interval in weeks for maintenance runs|N/A|
81+
|`intervalMonths`|The interval in months for maintenance runs|N/A|
82+
|`dayOfWeek`|The specified day of the week for maintenance to begin|N/A|
83+
|`durationHours`|The duration of the window for maintenance to run|N/A|
84+
|`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|
85+
86+
### Understanding schedule types
87+
88+
There are currently three available schedule types: `Weekly`, `AbsoluteMonthly`, and `RelativeMonthly`. These schedule types are only applicable to `aksManagedClusterAutoUpgrade` configurations.
89+
90+
#### Weekly schedule
91+
92+
A `Weekly` schedule may look like *"every two weeks on Friday"*:
93+
94+
```json
95+
"schedule": {
96+
"weekly": {
97+
"intervalWeeks": 2,
98+
"dayOfWeek": "Friday"
99+
}
100+
}
101+
```
46102

47-
> [!IMPORTANT]
48-
> At this time, you must set `default` as the value for `--name`. Using any other name will cause your maintenance window to not run.
49-
>
50-
> Planned Maintenance windows are specified in Coordinated Universal Time (UTC).
103+
#### AbsoluteMonthly schedule
104+
105+
An `AbsoluteMonthly` schedule may look like *"every three months, on the first day of the month"*:
106+
107+
```json
108+
"schedule": {
109+
"absoluteMonthly": {
110+
"intervalMonths": 3,
111+
"dayOfMonth": 1
112+
}
113+
}
114+
```
115+
116+
#### RelativeMonthly schedule
117+
118+
A `RelativeMonthly` schedule may look like *"every two months, on the last Monday"*:
119+
120+
```json
121+
"schedule": {
122+
"relativeMonthly": {
123+
"intervalMonths": 2,
124+
"dayOfWeek": "Monday",
125+
"weekIndex": "Last"
126+
}
127+
}
128+
```
129+
130+
## Add a maintenance window configuration with Azure CLI
131+
132+
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:
51133

52134
```azurecli-interactive
53-
az aks maintenanceconfiguration add -g MyResourceGroup --cluster-name myAKSCluster --name default --weekday Monday --start-hour 1
135+
az aks maintenanceconfiguration add -g myResourceGroup --cluster-name myAKSCluster --name default --weekday Monday --start-hour 1
54136
```
55137

56-
The following example output shows the maintenance window from 1:00am to 2:00am every Monday.
138+
> [!NOTE]
139+
> When using a `default` configuration type, to allow maintenance anytime during a day omit the `--start-time` parameter.
140+
141+
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:
142+
143+
```azurecli-interactive
144+
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
145+
```
146+
147+
## Add a maintenance window configuration with a JSON file
148+
149+
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.
150+
151+
Create a `default.json` file with the following contents:
57152

58153
```json
59154
{
60-
"id": "/subscriptions/<subscriptionID>/resourcegroups/MyResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster/maintenanceConfigurations/default",
61-
"name": "default",
62-
"notAllowedTime": null,
63-
"resourceGroup": "MyResourceGroup",
64-
"systemData": null,
65155
"timeInWeek": [
66156
{
67-
"day": "Monday",
68-
"hourSlots": [
69-
1
157+
"day": "Tuesday",
158+
"hour_slots": [
159+
1,
160+
2
161+
]
162+
},
163+
{
164+
"day": "Wednesday",
165+
"hour_slots": [
166+
1,
167+
6
70168
]
71169
}
72170
],
73-
"type": null
171+
"notAllowedTime": [
172+
{
173+
"start": "2021-05-26T03:00:00Z",
174+
"end": "2021-05-30T12:00:00Z"
175+
}
176+
]
74177
}
75178
```
76179

77-
To allow maintenance anytime during a day, omit the *start-hour* parameter. For example, the following command sets the maintenance window for the full day every Monday:
78-
79-
```azurecli-interactive
80-
az aks maintenanceconfiguration add -g MyResourceGroup --cluster-name myAKSCluster --name default --weekday Monday
81-
```
82-
83-
## Add a maintenance configuration with a JSON file
180+
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.
84181

85-
You can also use a JSON file create a maintenance window instead of using parameters. Create a `test.json` file with the following contents:
182+
Create an `autoUpgradeWindow.json` file with the following contents:
86183

87184
```json
88-
{
89-
"timeInWeek": [
90-
{
91-
"day": "Tuesday",
92-
"hour_slots": [
93-
1,
94-
2
95-
]
96-
},
97-
{
98-
"day": "Wednesday",
99-
"hour_slots": [
100-
1,
101-
6
102-
]
103-
}
104-
],
105-
"notAllowedTime": [
106-
{
107-
"start": "2021-05-26T03:00:00Z",
108-
"end": "2021-05-30T12:00:00Z"
109-
}
185+
{
186+
"properties": {
187+
"maintenanceWindow": {
188+
"schedule": {
189+
"absoluteMonthly": {
190+
"intervalMonths": 3,
191+
"dayOfMonth": 1
192+
}
193+
},
194+
"durationHours": 4,
195+
"utcOffset": "-08:00",
196+
"startTime": "09:00",
197+
"notAllowedDates": [
198+
{
199+
"start": "2023-12-23",
200+
"end": "2024-01-05"
201+
}
110202
]
203+
}
204+
}
111205
}
112206
```
113207

114-
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. 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. The following command adds the maintenance windows from `test.json`.
208+
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.
209+
210+
The following command adds the maintenance windows from `default.json` and `autoUpgradeWindow.json`:
115211

116212
```azurecli-interactive
117-
az aks maintenanceconfiguration add -g MyResourceGroup --cluster-name myAKSCluster --name default --config-file ./test.json
213+
az aks maintenanceconfiguration add -g myResourceGroup --cluster-name myAKSCluster --name default --config-file ./test.json
214+
215+
az aks maintenanceconfiguration add -g myResourceGroup --cluster-name myAKSCluster --name aksManagedAutoUpgradeSchedule --config-file ./autoUpgradeWindow.json
118216
```
119217

120218
## Update an existing maintenance window
121219

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

124222
```azurecli-interactive
125-
az aks maintenanceconfiguration update -g MyResourceGroup --cluster-name myAKSCluster --name default --weekday Monday --start-hour 1
223+
az aks maintenanceconfiguration update -g myResourceGroup --cluster-name myAKSCluster --name default --weekday Monday --start-hour 2
126224
```
127225

128226
## List all maintenance windows in an existing cluster
129227

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

132230
```azurecli-interactive
133-
az aks maintenanceconfiguration list -g MyResourceGroup --cluster-name myAKSCluster
134-
```
135-
136-
In the output below, you can see that there are two maintenance windows configured for myAKSCluster. One window is on Mondays at 1:00am and another window is on Friday at 4:00am.
137-
138-
```json
139-
[
140-
{
141-
"id": "/subscriptions/<subscriptionID>/resourcegroups/MyResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster/maintenanceConfigurations/default",
142-
"name": "default",
143-
"notAllowedTime": null,
144-
"resourceGroup": "MyResourceGroup",
145-
"systemData": null,
146-
"timeInWeek": [
147-
{
148-
"day": "Monday",
149-
"hourSlots": [
150-
1
151-
]
152-
}
153-
],
154-
"type": null
155-
},
156-
{
157-
"id": "/subscriptions/<subscriptionID>/resourcegroups/MyResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster/maintenanceConfigurations/testConfiguration",
158-
"name": "testConfiguration",
159-
"notAllowedTime": null,
160-
"resourceGroup": "MyResourceGroup",
161-
"systemData": null,
162-
"timeInWeek": [
163-
{
164-
"day": "Friday",
165-
"hourSlots": [
166-
4
167-
]
168-
}
169-
],
170-
"type": null
171-
}
172-
]
231+
az aks maintenanceconfiguration list -g myResourceGroup --cluster-name myAKSCluster
173232
```
174233

175234
## Show a specific maintenance configuration window in an AKS cluster
176235

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

179238
```azurecli-interactive
180-
az aks maintenanceconfiguration show -g MyResourceGroup --cluster-name myAKSCluster --name default
239+
az aks maintenanceconfiguration show -g myResourceGroup --cluster-name myAKSCluster --name aksManagedAutoUpgradeSchedule
181240
```
182241

183-
The following example output shows the maintenance window for *default*:
242+
The following example output shows the maintenance window for *aksManagedAutoUpgradeSchedule*:
184243

185244
```json
186245
{
187-
"id": "/subscriptions/<subscriptionID>/resourcegroups/MyResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster/maintenanceConfigurations/default",
188-
"name": "default",
246+
"id": "/subscriptions/<subscription>/resourceGroups/myResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster/maintenanceConfigurations/aksManagedAutoUpgradeSchedule",
247+
"maintenanceWindow": {
248+
"durationHours": 4,
249+
"notAllowedDates": [
250+
{
251+
"end": "2024-01-05",
252+
"start": "2023-12-23"
253+
}
254+
],
255+
"schedule": {
256+
"absoluteMonthly": {
257+
"dayOfMonth": 1,
258+
"intervalMonths": 3
259+
},
260+
"daily": null,
261+
"relativeMonthly": null,
262+
"weekly": null
263+
},
264+
"startDate": "2023-01-20",
265+
"startTime": "09:00",
266+
"utcOffset": "-08:00"
267+
},
268+
"name": "aksManagedAutoUpgradeSchedule",
189269
"notAllowedTime": null,
190-
"resourceGroup": "MyResourceGroup",
270+
"resourceGroup": "myResourceGroup",
191271
"systemData": null,
192-
"timeInWeek": [
193-
{
194-
"day": "Monday",
195-
"hourSlots": [
196-
1
197-
]
198-
}
199-
],
272+
"timeInWeek": null,
200273
"type": null
201274
}
202275
```
@@ -206,16 +279,9 @@ The following example output shows the maintenance window for *default*:
206279
To delete a certain maintenance configuration window in your AKS Cluster, use the `az aks maintenanceconfiguration delete` command.
207280

208281
```azurecli-interactive
209-
az aks maintenanceconfiguration delete -g MyResourceGroup --cluster-name myAKSCluster --name default
282+
az aks maintenanceconfiguration delete -g MyResourceGroup --cluster-name myAKSCluster --name autoUpgradeSchedule
210283
```
211284

212-
## Using Planned Maintenance with Cluster Auto-Upgrade
213-
214-
Planned Maintenance will detect if you are using Cluster Auto-Upgrade and schedule your upgrades during your maintenance window automatically. For more details on about Cluster Auto-Upgrade, see [Upgrade an Azure Kubernetes Service (AKS) cluster][aks-upgrade].
215-
216-
> [!NOTE]
217-
> To ensure proper functionality, use a maintenance window of four hours or more.
218-
219285
## Next steps
220286

221287
- To get started with upgrading your AKS cluster, see [Upgrade an AKS cluster][aks-upgrade]
@@ -233,3 +299,5 @@ Planned Maintenance will detect if you are using Cluster Auto-Upgrade and schedu
233299
[az-aks-install-cli]: /cli/azure/aks#az_aks_install_cli
234300
[az-provider-register]: /cli/azure/provider#az_provider_register
235301
[aks-upgrade]: upgrade-cluster.md
302+
[release-tracker]: release-tracker.md
303+
[auto-upgrade]: auto-upgrade-cluster.md

0 commit comments

Comments
 (0)