使用計劃維護來排程並控制 Azure Kubernetes Service 叢集的升級

• 此文章假設您目前具有 AKS 叢集。 如果您沒有 AKS 叢集，請參閱建立 AKS 叢集。

• 一個有效的 Azure 訂閱。 如果你沒有Azure訂閱，請在開始前建立一個free帳號。

• 請用指令 az account set 設定你的訂閱上下文。 例如：

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

• Terraform 本地安裝。 安裝說明請參見 Install 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 and 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 組態，該組態將維護排定為在時區中 UTC 每週一凌晨 1：00 至凌晨 5：00 執行。 第二個範例新增 aksManagedAutoUpgradeSchedule 設定的命令，以排程在 UTC+5:30 時區的每隔三個星期五，午夜 12：00 到上午 8：00 之間執行一次維護。

# 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. 在 [升級] >[自動升級排程器] 下方，選取 [新增排程]。

   

4. 在 [新增維護排程] 窗格上，設定下列維護時段設定：

   • 重複：選取維護時段的頻率。 建議您選取 [每週]。
   • 頻率：選取維護時段排程在星期幾。 建議您選取 [星期日]。
   • 維護開始日期：選取維護時段的開始日期。
   • 維護開始時間：選取維護時段的開始時間。
   • UTC 時差：選取維護時段的 UTC 時差 預設值為 +00:00。

   

5. 選取 [儲存]。

您可以使用 JSON 檔案以建立維護設定，而不是使用參數。 使用此方法時，可以透過指定 notAllowedDatesdefault、 aksManagedAutoUpgradeSchedule、 和 aksManagedNodeOSUpgradeSchedule 配置，避免在某個日期範圍內進行維護。

1. 使用維護時段設定建立 JSON 檔案。

   下列範例會建立 default.json 檔案，將維護排程在 UTC 時區的每週二午夜 1:00 至 5:00。 從 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 檔案，其排程維護在 UTC-08 時區每三個月的第一天上午 9：00 至下午 1：00 之間執行。 從 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 維護配置，將維護排程安排在該時區每週六 UTC-04:00 凌晨2：00至6：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 配置，將維護排程安排為每週日凌晨1點至5點（時 UTC-04:00 區時間），自2026年4月20日起：

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
         }
       }
     }
   }
 }
}

Node OS 升級維護配置

以下範例建立維護 aksManagedNodeOSUpgradeSchedule 配置，將維護排程於每週一凌晨3點至7點（時 UTC-04:00 區）執行，時間自2026年4月21日起：

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 點至 6 點的維護工作。

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 入口網站中，導覽至 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 入口網站中，導覽至 AKS 叢集資源。

2. 從服務功能表中的 [設定] 底下，選取 [叢集設定]。

3. 在 [升級] >[自動升級排程器] 下方，選取 [編輯排程]。

   

4. 在 [編輯維護排程] 窗格上，選取 [移除排程]。

   

用指令 az aks maintenanceconfiguration delete 刪除 AKS 叢集中的維護設定視窗。

下列範例會刪除 autoUpgradeSchedule 維護設定：

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

要刪除維護設定，請從 Terraform 設定中移除對應的區塊，並用指令 terraform apply 套用變更。