0
# Maintenance
1
2
Scheduled maintenance window management for AKS clusters including automated patching, upgrade scheduling, maintenance event coordination, and operational control over when disruptive operations can occur. This ensures predictable maintenance timing aligned with business requirements and minimizes operational impact.
3
4
## Capabilities
5
6
### Maintenance Configuration Management
7
8
Create, update, and manage maintenance configurations that define when maintenance operations can occur on AKS clusters.
9
10
```python { .api }
11
def create_or_update(
12
resource_group_name: str,
13
resource_name: str,
14
config_name: str,
15
parameters: MaintenanceConfiguration
16
) -> MaintenanceConfiguration:
17
"""
18
Creates or updates a maintenance configuration for the cluster.
19
20
Args:
21
resource_group_name: Azure resource group name
22
resource_name: Cluster name
23
config_name: Maintenance configuration name
24
parameters: Complete maintenance configuration
25
26
Returns:
27
MaintenanceConfiguration: Created or updated configuration
28
"""
29
30
def delete(
31
resource_group_name: str,
32
resource_name: str,
33
config_name: str
34
) -> None:
35
"""
36
Deletes a maintenance configuration.
37
38
Args:
39
resource_group_name: Azure resource group name
40
resource_name: Cluster name
41
config_name: Maintenance configuration name
42
"""
43
```
44
45
### Maintenance Configuration Discovery
46
47
List and retrieve maintenance configurations to understand current maintenance policies.
48
49
```python { .api }
50
def list_by_managed_cluster(
51
resource_group_name: str,
52
resource_name: str
53
) -> ItemPaged[MaintenanceConfiguration]:
54
"""
55
Lists maintenance configurations for the cluster.
56
57
Args:
58
resource_group_name: Azure resource group name
59
resource_name: Cluster name
60
61
Returns:
62
ItemPaged[MaintenanceConfiguration]: Paginated configuration list
63
"""
64
65
def get(
66
resource_group_name: str,
67
resource_name: str,
68
config_name: str
69
) -> MaintenanceConfiguration:
70
"""
71
Gets a specific maintenance configuration.
72
73
Args:
74
resource_group_name: Azure resource group name
75
resource_name: Cluster name
76
config_name: Maintenance configuration name
77
78
Returns:
79
MaintenanceConfiguration: Complete maintenance configuration
80
"""
81
```
82
83
## Core Types
84
85
```python { .api }
86
class MaintenanceConfiguration:
87
"""
88
Maintenance configuration defining maintenance windows and policies.
89
90
Attributes:
91
main_maintenance_window: Primary maintenance window schedule
92
not_allowed_time: Time periods when maintenance is not allowed
93
system_data: System metadata (read-only)
94
name: Configuration name (read-only)
95
type: Resource type (read-only)
96
id: Resource ID (read-only)
97
"""
98
main_maintenance_window: Optional[MaintenanceWindow]
99
not_allowed_time: Optional[List[TimeSpan]]
100
system_data: Optional[SystemData]
101
name: Optional[str]
102
type: Optional[str]
103
id: Optional[str]
104
105
class MaintenanceWindow:
106
"""
107
Maintenance window definition with scheduling parameters.
108
109
Attributes:
110
schedule: Maintenance schedule configuration
111
duration_hours: Duration of maintenance window in hours
112
utc_offset: UTC offset for maintenance window timing
113
start_date: Start date for maintenance schedule
114
start_time: Start time for maintenance operations
115
not_allowed_dates: Specific dates when maintenance is not allowed
116
"""
117
schedule: Schedule
118
duration_hours: int
119
utc_offset: Optional[str]
120
start_date: Optional[str]
121
start_time: Optional[str]
122
not_allowed_dates: Optional[List[DateSpan]]
123
124
class Schedule:
125
"""
126
Base schedule class for maintenance timing.
127
128
Note: This is a base class. Use specific schedule types:
129
- DailySchedule for daily maintenance
130
- WeeklySchedule for weekly maintenance
131
- AbsoluteMonthlySchedule for monthly (specific date)
132
- RelativeMonthlySchedule for monthly (relative day)
133
"""
134
pass
135
136
class DailySchedule(Schedule):
137
"""
138
Daily maintenance schedule.
139
140
Attributes:
141
interval_days: Interval between maintenance days
142
"""
143
interval_days: int
144
145
class WeeklySchedule(Schedule):
146
"""
147
Weekly maintenance schedule.
148
149
Attributes:
150
interval_weeks: Interval between maintenance weeks
151
day_of_week: Day of week for maintenance (Monday=1, Sunday=7)
152
"""
153
interval_weeks: int
154
day_of_week: int
155
156
class AbsoluteMonthlySchedule(Schedule):
157
"""
158
Monthly maintenance on specific date.
159
160
Attributes:
161
interval_months: Interval between maintenance months
162
day_of_month: Specific day of month (1-31)
163
"""
164
interval_months: int
165
day_of_month: int
166
167
class RelativeMonthlySchedule(Schedule):
168
"""
169
Monthly maintenance on relative day (e.g., first Monday).
170
171
Attributes:
172
interval_months: Interval between maintenance months
173
day_of_week: Day of week (Monday=1, Sunday=7)
174
week_index: Week of month (First=1, Last=5)
175
"""
176
interval_months: int
177
day_of_week: int
178
week_index: int
179
180
class TimeSpan:
181
"""
182
Time period when maintenance is not allowed.
183
184
Attributes:
185
start: Start time of blackout period
186
end: End time of blackout period
187
"""
188
start: str
189
end: str
190
191
class DateSpan:
192
"""
193
Date range when maintenance is not allowed.
194
195
Attributes:
196
start: Start date (YYYY-MM-DD format)
197
end: End date (YYYY-MM-DD format)
198
"""
199
start: str
200
end: str
201
```
202
203
## Usage Examples
204
205
### Basic Weekly Maintenance Window
206
207
```python
208
from azure.identity import DefaultAzureCredential
209
from azure.mgmt.containerservice import ContainerServiceClient
210
from azure.mgmt.containerservice.models import (
211
MaintenanceConfiguration,
212
MaintenanceWindow,
213
WeeklySchedule
214
)
215
216
credential = DefaultAzureCredential()
217
client = ContainerServiceClient(credential, subscription_id)
218
219
# Create weekly maintenance window (Sundays at 2 AM UTC, 4 hours duration)
220
maintenance_config = MaintenanceConfiguration(
221
main_maintenance_window=MaintenanceWindow(
222
schedule=WeeklySchedule(
223
interval_weeks=1,
224
day_of_week=7 # Sunday
225
),
226
duration_hours=4,
227
start_time="02:00",
228
utc_offset="+00:00"
229
)
230
)
231
232
result = client.maintenance_configurations.create_or_update(
233
"myResourceGroup",
234
"myCluster",
235
"default",
236
maintenance_config
237
)
238
print(f"Maintenance window created: {result.name}")
239
```
240
241
### Monthly Maintenance with Blackout Periods
242
243
```python
244
from azure.mgmt.containerservice.models import (
245
AbsoluteMonthlySchedule,
246
DateSpan,
247
TimeSpan
248
)
249
250
# Monthly maintenance on the 15th, with holiday blackouts
251
monthly_config = MaintenanceConfiguration(
252
main_maintenance_window=MaintenanceWindow(
253
schedule=AbsoluteMonthlySchedule(
254
interval_months=1,
255
day_of_month=15
256
),
257
duration_hours=6,
258
start_time="01:00",
259
utc_offset="-08:00", # PST
260
not_allowed_dates=[
261
DateSpan(start="2024-12-20", end="2024-01-05"), # Holiday season
262
DateSpan(start="2024-07-01", end="2024-07-07"), # July 4th week
263
]
264
),
265
not_allowed_time=[
266
TimeSpan(start="08:00", end="18:00") # No maintenance during business hours
267
]
268
)
269
270
result = client.maintenance_configurations.create_or_update(
271
"myResourceGroup",
272
"myCluster",
273
"monthly-maintenance",
274
monthly_config
275
)
276
```
277
278
### Daily Maintenance for Dev/Test
279
280
```python
281
from azure.mgmt.containerservice.models import DailySchedule
282
283
# Daily maintenance window for development cluster
284
dev_config = MaintenanceConfiguration(
285
main_maintenance_window=MaintenanceWindow(
286
schedule=DailySchedule(
287
interval_days=1
288
),
289
duration_hours=2,
290
start_time="03:00",
291
utc_offset="+00:00"
292
)
293
)
294
295
result = client.maintenance_configurations.create_or_update(
296
"devResourceGroup",
297
"devCluster",
298
"daily-maintenance",
299
dev_config
300
)
301
```
302
303
### Relative Monthly Schedule
304
305
```python
306
from azure.mgmt.containerservice.models import RelativeMonthlySchedule
307
308
# First Saturday of every month
309
relative_config = MaintenanceConfiguration(
310
main_maintenance_window=MaintenanceWindow(
311
schedule=RelativeMonthlySchedule(
312
interval_months=1,
313
day_of_week=6, # Saturday
314
week_index=1 # First week
315
),
316
duration_hours=8,
317
start_time="22:00", # 10 PM
318
utc_offset="-05:00" # EST
319
)
320
)
321
322
result = client.maintenance_configurations.create_or_update(
323
"myResourceGroup",
324
"myCluster",
325
"first-saturday",
326
relative_config
327
)
328
```
329
330
### Maintenance Configuration Management
331
332
```python
333
# List all maintenance configurations
334
configs = client.maintenance_configurations.list_by_managed_cluster(
335
"myResourceGroup",
336
"myCluster"
337
)
338
339
for config in configs:
340
print(f"Config: {config.name}")
341
if config.main_maintenance_window:
342
window = config.main_maintenance_window
343
print(f" Duration: {window.duration_hours} hours")
344
print(f" Start time: {window.start_time}")
345
346
if isinstance(window.schedule, WeeklySchedule):
347
print(f" Schedule: Weekly on day {window.schedule.day_of_week}")
348
elif isinstance(window.schedule, DailySchedule):
349
print(f" Schedule: Daily every {window.schedule.interval_days} days")
350
351
# Get specific configuration
352
config = client.maintenance_configurations.get(
353
"myResourceGroup",
354
"myCluster",
355
"default"
356
)
357
358
# Update existing configuration
359
if config.main_maintenance_window:
360
config.main_maintenance_window.duration_hours = 6 # Extend to 6 hours
361
362
updated = client.maintenance_configurations.create_or_update(
363
"myResourceGroup",
364
"myCluster",
365
"default",
366
config
367
)
368
369
# Delete configuration
370
client.maintenance_configurations.delete(
371
"myResourceGroup",
372
"myCluster",
373
"old-config"
374
)
375
```
376
377
### Complex Maintenance Scheduling
378
379
```python
380
# Production cluster with strict maintenance policies
381
production_config = MaintenanceConfiguration(
382
main_maintenance_window=MaintenanceWindow(
383
schedule=WeeklySchedule(
384
interval_weeks=2, # Bi-weekly
385
day_of_week=7 # Sunday
386
),
387
duration_hours=4,
388
start_time="01:00",
389
utc_offset="-05:00",
390
start_date="2024-01-07", # First Sunday after Jan 1
391
not_allowed_dates=[
392
# Block maintenance during critical business periods
393
DateSpan(start="2024-11-28", end="2024-12-02"), # Thanksgiving week
394
DateSpan(start="2024-12-23", end="2024-01-02"), # Holiday season
395
DateSpan(start="2024-03-15", end="2024-03-31"), # Quarter end
396
DateSpan(start="2024-06-15", end="2024-06-30"), # Quarter end
397
DateSpan(start="2024-09-15", end="2024-09-30"), # Quarter end
398
]
399
),
400
not_allowed_time=[
401
# Never during business hours
402
TimeSpan(start="06:00", end="22:00")
403
]
404
)
405
406
result = client.maintenance_configurations.create_or_update(
407
"prodResourceGroup",
408
"prodCluster",
409
"production-maintenance",
410
production_config
411
)
412
```
413
414
### Regional Maintenance Coordination
415
416
```python
417
# Coordinate maintenance across multiple regions
418
regions = ["eastus", "westus", "northeurope"]
419
maintenance_times = ["01:00", "04:00", "07:00"] # Staggered times
420
421
for i, region in enumerate(regions):
422
config = MaintenanceConfiguration(
423
main_maintenance_window=MaintenanceWindow(
424
schedule=WeeklySchedule(
425
interval_weeks=1,
426
day_of_week=7 # Sunday
427
),
428
duration_hours=3,
429
start_time=maintenance_times[i],
430
utc_offset="+00:00"
431
)
432
)
433
434
result = client.maintenance_configurations.create_or_update(
435
f"{region}-rg",
436
f"cluster-{region}",
437
"regional-maintenance",
438
config
439
)
440
print(f"Configured maintenance for {region} at {maintenance_times[i]} UTC")
441
```
442
443
## Error Handling
444
445
```python
446
from azure.core.exceptions import HttpResponseError, ResourceNotFoundError
447
448
try:
449
config = client.maintenance_configurations.get(
450
"myRG", "myCluster", "nonexistent"
451
)
452
except ResourceNotFoundError:
453
print("Maintenance configuration not found")
454
except HttpResponseError as e:
455
print(f"HTTP error: {e.status_code}")
456
457
# Validate maintenance window conflicts
458
try:
459
result = client.maintenance_configurations.create_or_update(
460
"myRG", "myCluster", "new-config", config
461
)
462
except HttpResponseError as e:
463
if e.status_code == 400:
464
print("Invalid maintenance configuration")
465
print(f"Error details: {e.message}")
466
```
467
468
## Best Practices
469
470
### Maintenance Scheduling Guidelines
471
472
```python
473
# Production: Conservative weekly schedule
474
prod_schedule = WeeklySchedule(
475
interval_weeks=1,
476
day_of_week=7 # Sunday
477
)
478
479
# Staging: More frequent for testing
480
staging_schedule = WeeklySchedule(
481
interval_weeks=1,
482
day_of_week=6 # Saturday
483
)
484
485
# Development: Daily for rapid iteration
486
dev_schedule = DailySchedule(
487
interval_days=1
488
)
489
490
# Consider time zones for global deployments
491
regional_configs = {
492
"eastus": "+00:00", # UTC
493
"westus": "-08:00", # PST
494
"westeurope": "+01:00", # CET
495
"eastasia": "+08:00" # CST
496
}
497
```
498
499
### Blackout Period Management
500
501
```python
502
# Common blackout periods for enterprise environments
503
common_blackouts = [
504
DateSpan(start="2024-11-28", end="2024-11-29"), # Thanksgiving
505
DateSpan(start="2024-12-24", end="2024-01-01"), # Winter holidays
506
DateSpan(start="2024-07-04", end="2024-07-04"), # Independence Day
507
DateSpan(start="2024-05-27", end="2024-05-27"), # Memorial Day
508
DateSpan(start="2024-09-02", end="2024-09-02"), # Labor Day
509
]
510
511
# Quarter-end blackouts for financial applications
512
quarter_ends = [
513
DateSpan(start="2024-03-29", end="2024-04-02"), # Q1 end
514
DateSpan(start="2024-06-28", end="2024-07-02"), # Q2 end
515
DateSpan(start="2024-09-27", end="2024-10-01"), # Q3 end
516
DateSpan(start="2024-12-27", end="2024-12-31"), # Q4 end
517
]
518
```