你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
本文介绍如何使用计划内维护来计划和控制Azure Kubernetes 服务 (AKS)中的群集和节点映像升级。
对 AKS 群集的定期维护是自动进行的。 有两种类型的维护操作：
- AKS 发起的维护涉及 AKS 执行的用于使群集与最新功能和修补程序保持一致的每周发布。
- 用户发起的维护包括群集自动升级和节点操作系统 (OS) 自动安全更新。
使用 AKS 中的计划内维护功能时，可以按照自己选择的节奏运行两种类型的维护，以最大程度地减少工作负荷影响。
注意
可以使用计划内维护来计划自动升级的时间，但启用或禁用计划内维护不会启用或禁用自动升级。
开始之前
- 本文假定你拥有现有的 AKS 群集。 如果还没有 AKS 群集，请参阅创建 AKS 群集。
- 如果使用 Azure CLI，请使用
az upgrade命令升级到最新版本。
一个有效的 Azure 订阅。 如果没有Azure订阅，请在开始前创建 free 帐户。
使用
az account set命令设置订阅上下文。 例如：az account set --subscription "00000000-0000-0000-0000-000000000000"在本地安装 Terraform。 有关安装说明，请参阅 安装 Terraform。
注意事项
使用计划内维护时，以下注意事项适用：
- 对于紧急或关键的计划外、反应性维护操作，AKS 保留在计划内维护时段外进行操作的权利。 这些维护操作甚至可以在配置中定义的
notAllowedTime或notAllowedDates期间运行。 - 我们会尽最大努力执行维护操作，但不保证在指定时段内执行。
计划内维护的计划配置类型
计划内维护可使用三种计划配置类型：
default是用于管理 AKS 版本的基本配置，包括控制层组件和系统加载项升级。 由于 Azure 安全部署做法，这些发布可能需要长达两周的时间才能推出到所有区域（从最初的发布时间算起）。选择
default可安排这些更新，使其对你造成的影响最小。 可使用每周发布跟踪器按区域监视正在进行的 AKS 发布的状态。aksManagedAutoUpgradeSchedule控制何时执行由指定的自动升级通道计划的群集升级。 与default配置相比，使用此配置可以更精细地控制频率和定期设置。 有关群集自动升级的详细信息，请参阅 自动升级 Azure Kubernetes 服务 群集。aksManagedNodeOSUpgradeSchedule控制何时执行由节点 OS 自动升级通道计划的节点 OS 安全修补。 与default配置相比，使用此配置可以更精细地控制频率和定期设置。 有关节点 OS 自动升级通道的详细信息，请参阅自动修补和更新 AKS 群集节点映像。
建议对所有群集 Kubernetes 版本升级方案使用 aksManagedAutoUpgradeSchedule，对所有节点 OS 安全修补方案使用 aksManagedNodeOSUpgradeSchedule。
default 专用于 AKS 每周发布。 如果要控制 AKS 控制平面组件（如 API 服务器、ETCD 等）和加载项（如 CoreDNS、Metrics Server 等）的升级计划，请使用 default。
所有三种类型的配置都可以共存。
创建维护时段
注意
使用自动升级时，为了确保正常运行，请使用持续时间为 4 小时或 4 小时以上的维护时段。
注意
从 2023-05-01 API 版本开始，请使用下表中的属性进行 default 配置。
从 2023-05-01 API 版本开始，aksManagedAutoUpgradeSchedule 或 aksManagedNodeOSUpgradeSchedule 维护时段和 default 配置具有以下属性：
| 名称 | 说明 | 默认值 |
|---|---|---|
utcOffset |
群集维护的时区。 | +00:00 |
startDate |
维护时段开始生效的日期。 | 创建时的当前日期 |
startTime |
维护开始的时间，基于由 utcOffset 确定的时区。 |
不适用 |
schedule |
升级频率。 提供三种类型：Weekly、AbsoluteMonthly 和 RelativeMonthly。 |
不适用 |
intervalDays |
维护运行的间隔（以天为单位）。 它仅适用于 aksManagedNodeOSUpgradeSchedule。 |
不适用 |
intervalWeeks |
维护运行的间隔（以周为单位）。 | 不适用 |
intervalMonths |
维护运行的间隔（以月为单位）。 | 不适用 |
dayOfWeek |
要开始维护的一周中的指定某一天。 | 不适用 |
durationHours |
要运行维护的时段的持续时间。 | 不适用 |
notAllowedDates |
维护无法运行的日期范围，由 start 和 end 子属性确定。 仅当你使用配置文件创建维护时段时，它才适用。 |
不适用 |
已弃用的属性
注意
如果使用以下已弃用的属性创建 default 配置，它会自动迁移到上表中所示的新属性。
[已弃用]default维护时段具有以下旧属性：
| 名称 | 说明 | 默认值 |
|---|---|---|
timeInWeek |
在 default 配置中，此属性包含定义维护时段的 day 和 hourSlots 值。 |
不适用 |
timeInWeek.day |
default 配置中要执行维护的一周中的某一天。 |
不适用 |
timeInWeek.hourSlots |
default 配置中要在特定的一天执行维护的小时长的时间槽列表。 |
不适用 |
notAllowedTime |
维护无法运行的日期范围，由 start 和 end 子属性确定。 仅当你使用配置文件创建维护时段时，此属性才适用。 |
不适用 |
计划类型
支持四种计划类型： Daily、 Weekly、 AbsoluteMonthly和 RelativeMonthly。
下表显示了每种维护配置选项可用的类型：
| 计划类型 | default |
aksManagedClusterAutoUpgradeSchedule |
aksManagedNodeOSUpgradeSchedule |
|---|---|---|---|
| Daily | 不受支持的 ❌ | ✅ 支持（2025 年 6 月之后） | 支持✅ |
| Weekly | 支持✅ | 支持✅ | 支持✅ |
| AbsoluteMonthly | 不受支持的 ❌ | 支持✅ | 支持✅ |
| RelativeMonthly | 不受支持的 ❌ | 支持✅ | 支持✅ |
为每个计划类型显示的所有字段都是必填字段。
Daily 计划可能类似于“每三天一次”：
"schedule": {
"daily": {
"intervalDays": 3
}
}
Weekly 计划可能类似于“每两周一次，在星期五进行”：
"schedule": {
"weekly": {
"intervalWeeks": 2,
"dayOfWeek": "Friday"
}
}
AbsoluteMonthly 计划可能类似于“每三个月一次，在当月的第一天进行”：
"schedule": {
"absoluteMonthly": {
"intervalMonths": 3,
"dayOfMonth": 1
}
}
RelativeMonthly 计划可能类似于“每两个月一次，在最后一个星期一进行”：
"schedule": {
"relativeMonthly": {
"intervalMonths": 2,
"dayOfWeek": "Monday",
"weekIndex": "Last"
}
}
weekIndex 的有效值包括 First、Second、Third、Fourth 和 Last。
创建 Terraform 配置文件
Terraform 配置文件定义 Terraform 创建和管理的基础结构。
创建名为 main.tf 的文件，并添加以下代码以定义 Terraform 版本并指定Azure提供程序：
terraform {
required_providers {
azurerm = {
source = "hashicorp/azurerm"
version = "~>4.0"
}
azapi = {
source = "azure/azapi"
version = "~>2.0"
}
}
}
provider "azurerm" {
features {}
}
provider "azapi" {}
创建资源组
将以下代码添加到 main.tf，以创建Azure资源组。 请更新 location 和 name 值以匹配您的环境。
resource "azurerm_resource_group" "rg" {
name = "aks-maintenance-rg"
location = "East US"
}
创建 AKS 群集
添加以下代码到 main.tf 创建 AKS 集群。 根据需要更新任何值以匹配环境。
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"
}
}
添加维护时段配置
使用 az aks maintenanceconfiguration add 命令将维护窗口配置添加到 AKS 群集。
第一个示例添加了一个新的 default 配置，该配置安排每周一凌晨1:00到5:00在UTC时区进行维护。 第二个示例添加一个新的 aksManagedAutoUpgradeSchedule 配置，该配置计划的维护每三周进行一次，在星期五的凌晨 0:00 到上午 8:00 之间运行（UTC+5:30 时区）。
# 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
在 Azure 门户中，导航到 AKS 群集资源。
在服务菜单中的 “设置”下，选择“ 升级”。
在“升级”“自动升级计划程序”下，选择“添加计划”>。
在“添加维护计划”窗格上，配置以下维护时段设置：
- 重复：选择维护时段的频率。 我们建议选择“每周”。
- 频率：为维护时段选择一周中的某一天。 我们建议选择“周日”。
- 维护开始日期：选择维护时段开始日期。
- 维护开始时间：选择维护时段开始时间。
- UTC 时差：选择维护时段 UTC 时差。 默认值为 +00:00。
选择“保存”。
可以使用 JSON 文件而不是参数来创建维护配置。 使用此方法时，可以通过为 notAllowedDates、default 和 aksManagedAutoUpgradeSchedule 配置指定 aksManagedNodeOSUpgradeSchedule 来防止在某个日期范围内进行维护。
使用维护时段设置创建 JSON 文件。
以下示例创建一个
default.json文件，该文件计划的维护在每星期二从凌晨 1:00 运行到凌晨 5:00（UTC时区）。 此外，从2021-05-26到2021-05-30是一个例外时段，即使该时段与维护时段重叠，也不允许在该时段进行维护。{ "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" } ] } } }以下示例创建一个
autoUpgradeWindow.json文件，该文件计划的维护每三个月运行一次，在当月第一天的上午 9:00 到下午 1:00 之间运行（UTC-08时区）。 此外，从2023-12-23到2024-01-05是一个例外时段，即使该时段与维护时段重叠，也不允许在该时段进行维护。{ "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" } ] } } }配合使用
az aks maintenanceconfiguration add命令和--config-file参数添加维护时段配置。第一个示例使用
default文件添加一个新的default.json配置。 第二个示例使用aksManagedAutoUpgradeSchedule文件添加一个新的autoUpgradeWindow.json配置。# 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
使用 main.tf 资源将维护窗口配置添加到 azapi_resource。
默认维护配置
以下示例创建一个 default 维护配置，该配置将维护计划从凌晨 2：00 到上午 6：00（每周六）在 UTC-04:00 时区中运行：
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"
}
}
}
}
自动升级维护配置
以下示例创建一个 aksManagedAutoUpgradeSchedule 维护配置，该配置计划从 2026 年 4 月 20 日开始，每个星期日凌晨 1:00 到 5:00 在 UTC-04:00 时区内运行维护。
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
}
}
}
}
}
}
节点 OS 升级维护配置
以下示例创建一个 aksManagedNodeOSUpgradeSchedule 维护配置，计划从 2026 年 4 月 21 日起，每周一在 UTC-04:00 时区的上午 3:00 到 7:00 之间进行维护。
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
}
}
}
}
}
}
更新现有的维护时段
使用 az aks maintenanceconfiguration update 命令更新现有维护配置。
以下示例将 default 配置更新为安排每周五凌晨 2:00 到 6:00 进行的维护操作：
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
在Azure门户中，导航到 AKS 群集资源。
在服务菜单中的 “设置”下，选择“ 升级”。
在“升级”“自动升级计划程序”下，选择“编辑计划”>。
在“编辑维护计划”窗格上，根据需要更新维护时段设置。
选择“保存”。
使用新的维护时段设置更新配置 JSON 文件。
以下示例将
default.json的 文件更新为让计划的维护在每星期一从凌晨 2:00 运行到凌晨 6:00：{ "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" } ] } } }配合使用
az aks maintenanceconfiguration update命令和--config-file参数更新维护时段配置：az aks maintenanceconfiguration update --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name default --config-file ./default.json
如果您已有一个由 Terraform 管理的 AKS 群集，可以通过修改 Terraform 配置文件并使用 terraform apply 命令应用更改来更新维护窗口配置。
初始化 Terraform
使用main.tf命令在包含terraform init文件的目录中初始化 Terraform。 此命令将下载使用 Terraform 管理 Azure 资源所需的 Azure 提供程序。
terraform init
创建 Terraform 执行计划
使用 terraform plan 命令创建 Terraform 执行计划。 此命令显示 Terraform 将在Azure订阅中创建或修改的资源。
terraform plan
应用 Terraform 配置
查看并确认执行计划后，使用 terraform apply 命令应用 Terraform 配置。 此命令创建或修改Azure订阅中main.tf文件中定义的资源。
terraform apply
在现有群集中列出所有维护时段
使用 az aks maintenanceconfiguration list 以下命令列出 AKS 群集中的当前维护配置窗口：
az aks maintenanceconfiguration list --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME
显示现有群集中的特定维护配置时段
使用带有参数的 az aks maintenanceconfiguration show 命令 --name 在 AKS 群集中查看特定的维护配置窗口：
az aks maintenanceconfiguration show --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name aksManagedAutoUpgradeSchedule
以下示例输出显示了 aksManagedAutoUpgradeSchedule 的维护时段：
{
"id": "/subscriptions/<subscription>/resourceGroups/myResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster/maintenanceConfigurations/aksManagedAutoUpgradeSchedule",
"maintenanceWindow": {
"durationHours": 4,
"notAllowedDates": [
{
"end": "2024-01-05",
"start": "2023-12-23"
}
],
"schedule": {
"absoluteMonthly": {
"dayOfMonth": 1,
"intervalMonths": 3
},
"daily": null,
"relativeMonthly": null,
"weekly": null
},
"startDate": "2023-01-20",
"startTime": "09:00",
"utcOffset": "-08:00"
},
"name": "aksManagedAutoUpgradeSchedule",
"notAllowedTime": null,
"resourceGroup": "myResourceGroup",
"systemData": null,
"timeInWeek": null,
"type": null
}
删除现有群集中的维护配置时段
使用 az aks maintenanceconfiguration delete 命令删除 AKS 群集中的维护配置窗口。
以下示例删除 autoUpgradeSchedule 维护配置：
az aks maintenanceconfiguration delete --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name autoUpgradeSchedule
在Azure门户中，导航到 AKS 群集资源。
在服务菜单中的“设置”下，选择“群集配置”。
在“升级”“自动升级计划程序”下，选择“编辑计划”>。
在“编辑维护计划”窗格上，选择“删除计划”。
使用 az aks maintenanceconfiguration delete 命令删除 AKS 群集中的维护配置窗口。
以下示例删除 autoUpgradeSchedule 维护配置：
az aks maintenanceconfiguration delete --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name autoUpgradeSchedule
若要删除维护配置，请从 Terraform 配置中删除相应的块，并使用 terraform apply 命令应用更改。
常见问题 (FAQ)
如何检查群集中的现有维护配置？
使用 az aks maintenanceconfiguration show 命令。
计划外、反应性维护是否也能在 notAllowedDates 期间进行？
是的。 对于紧急或关键的计划外/反应性维护操作，AKS 保留在这些时段外进行操作的权利。
如何判断是否发生了维护事件？
对于发布，请检查群集的区域并在每周发布中查找信息，看它是否与维护计划匹配。 若要查看自动升级的状态，请在群集上查找活动日志。 还可查找升级 AKS 群集中所述的与升级相关的特定事件。
AKS 还会发出与升级相关的 Azure 事件网格 事件。 要了解详细信息，请参阅充当事件网格源的 AKS。
是否可以同时使用多种维护配置？
是的，可以同时运行所有三种配置：default、aksManagedAutoUpgradeSchedule 和 aksManagedNodeOSUpgradeSchedule。 如果时段重叠，AKS 会决定运行顺序。
我配置了维护时段，但升级没有进行。 为什么？
考虑到维护时段，AKS 自动升级需要一定的时间（通常不超过 15 分钟）。 建议在创建或更新维护配置与计划启动时间之间至少间隔 15 分钟。
此外，请确保在计划内维护时段开始时启动群集。 如果群集已停止，则会解除其控制平面的分配，不允许执行任何操作。
为什么我的代理池之一在维护时段之外进行了升级？
AKS 仅在配置的维护时段内启动与升级相关的操作。 如果某个操作在窗口关闭之前开始，它可以继续运行，直到完成，即使此操作超出了窗口结束时间。
窗口关闭时，AKS 不会启动任何新的升级操作。 任何剩余的升级工作将推迟到未来的合格时段。
示例：如果维护窗口为 08:00-12:00，并且 12:00 之前开始的群集或节点池升级在 12:15 仍在进行中，则 AKS 会让正在进行的工作完成。 但是，AKS 在 12：00 后不会启动新的升级工作。
对于维护配置，是否有任何最佳做法？
如果你使用的是 通道，建议将NodeImage计划设置为每周一次，因为每周都会发布一个新的节点映像。 也可选择使用 SecurityPatch 通道来接收每日安全更新.
可以将 自动升级 计划设置为每月节奏，以随时了解 Kubernetes N-2 支持策略。
有关升级最佳做法和其他注意事项的详细讨论，请参阅 AKS 补丁和升级指导。
是否可以将单个订阅中的所有群集配置为使用相同的维护配置？
不建议对单个订阅中的多个群集使用相同的维护配置，因为这样做可能会导致 ARM 限制错误，从而导致群集升级失败。 相反，我们建议错开每个群集的维护时段，以避免这些错误。
为什么在同一维护时段内，节点池升级了两次？
如果在维护时段内提供较新版本的节点映像，AKS 将执行第二次升级，以确保节点池正在运行最新版本。 此行为正常，并不指示问题。
Azure是否可以使用 AKS 计划内维护时段来对底层 VMSS 进行平台维护？
不。 AKS 计划内维护时段专门用于计划和控制 Azure Kubernetes 服务 中的 AKS 群集和节点映像升级。 它不适用于托管 AKS 节点池的基础 VMSS 上的Azure平台级维护。 它们独立运行，且它们之间没有直接依赖关系。
Azure定期执行平台更新，以提高虚拟机的基础主机基础结构的可靠性、性能和安全性。 这些更新可能包括修补软件组件、升级网络基础结构或解除硬件授权。 平台维护可以是无重启的，也可以需要重新启动。
对于需要重新启动的维护事件，客户会提前通过维护通知接到通知，通知中包括一个通常持续长达四周的维护期self‑service phase。
相关内容
若要开始升级 AKS 群集，请参阅 AKS 群集的升级选项。