使用计划内维护来计划和控制Azure Kubernetes 服务群集的升级

• 本文假定你拥有现有的 AKS 群集。 如果还没有 AKS 群集，请参阅创建 AKS 群集。

• 一个有效的 “Azure” 订阅。 如果没有 Azure 订阅，可在开始前创建一个试用帐户。

• 使用 az account set 命令设置订阅上下文。 例如：

  az account set --subscription "00000000-0000-0000-0000-000000000000"
  

• 在本地安装 Terraform。 有关安装说明，请参阅 安装 Terraform。

创建 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

1. 在 Azure 门户中，进入您的 AKS 群集资源。

2. 在服务菜单中的 “设置”下，选择“ 升级”。

3. 在“升级”“自动升级计划程序”下，选择“添加计划”>。

   截图显示在 Azure 门户中添加计划的选项。

4. 在“添加维护计划”窗格上，配置以下维护时段设置：

   • 重复：选择维护时段的频率。 我们建议选择“每周”。
   • 频率：为维护时段选择一周中的某一天。 我们建议选择“周日”。
   • 维护开始日期：选择维护时段开始日期。
   • 维护开始时间：选择维护时段开始时间。
   • 选择维护时段的 UTC 偏移量。 默认值为+00:00。

   此截图显示了 Azure 门户中用于添加维护计划的窗格。

5. 选择“保存”。

可以使用 JSON 文件而不是参数来创建维护配置。 使用此方法时，可以通过为 notAllowedDates、default 和 aksManagedAutoUpgradeSchedule 配置指定 aksManagedNodeOSUpgradeSchedule 来防止在某个日期范围内进行维护。

1. 使用维护窗口设置创建 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"
               }
           ]
       }
     }
   }
   

2. 使用 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

1. 在Azure portal中，导航到 AKS 群集资源。

2. 在服务菜单中的 “设置”下，选择“ 升级”。

3. 在“升级”“自动升级计划程序”下，选择“编辑计划”>。

   

4. 在“编辑维护计划”窗格中，根据需要更新维护窗口设置。

5. 选择“保存”。

1. 使用新的维护时段设置更新配置 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"
               }
           ]
       }
     }
   }
   

2. 使用 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 delete 命令删除 AKS 群集中的维护配置窗口。

以下示例删除 autoUpgradeSchedule 维护配置：

az aks maintenanceconfiguration delete --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name autoUpgradeSchedule

1. 在Azure portal中，导航到 AKS 群集资源。

2. 在服务菜单中的“设置”下，选择“群集配置”。

3. 在“升级”“自动升级计划程序”下，选择“编辑计划”>。

   

4. 在“编辑维护计划”窗格上，选择“删除计划”。

   在 Azure 门户中，屏幕截图显示用于编辑维护窗口的窗格及用于删除计划的按钮。

使用 az aks maintenanceconfiguration delete 命令删除 AKS 群集中的维护配置窗口。

以下示例删除 autoUpgradeSchedule 维护配置：

az aks maintenanceconfiguration delete --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name autoUpgradeSchedule

若要删除维护配置，请从 Terraform 配置中删除相应的块，并使用 terraform apply 命令应用更改。