az aks maintenancewindow

Note

此參考是 Azure CLI(版本 2.85.0 或更高版本)的 aks-preview 擴充的一部分。 這個擴充功能會在你第一次執行 az aks maintenancewindow 指令時自動安裝。 深入了解擴充功能。

管理 MaintenanceWindow 對等 ARM 資源的指令。

MaintenanceWindow 是一個資源群組範圍的 ARM 資源,定義可重複使用的維護排程。 使用者可以透過 將此資源連結至既有的維護配置 maintenanceWindowId,使多個 managedCluster 維護設定共享同一個維護視窗,排程則集中於一處。

需要 Microsoft。ContainerService/AKSSharedMaintenanceWindowPreview 功能將註冊於訂閱中。 啟用自動核准: az feature register --namespace Microsoft.ContainerService --name AKSSharedMaintenanceWindowPreview。

命令

名稱 Description 類型 狀態
az aks maintenancewindow create

建立維護窗口。

Extension GA
az aks maintenancewindow delete

刪除一個維護視窗。

Extension GA
az aks maintenancewindow list

在資源群組中列出 MaintenanceWindows,或若省略 --resource-group 則跨訂閱。

Extension GA
az aks maintenancewindow show

顯示維護時段。

Extension GA
az aks maintenancewindow update

更新維護視窗。

Extension GA
az aks maintenancewindow wait

等待維護視窗達到期望狀態。

Extension GA

az aks maintenancewindow create

建立維護窗口。

需要 Microsoft。ContainerService/AKSSharedMaintenanceWindowPreview 功能將註冊於訂閱中。 註冊一次(自動核准): az feature register --namespace Microsoft.ContainerService --name AKSSharedMaintenanceWindowPreview。

az aks maintenancewindow create --name
                                --resource-group
                                [--acquire-policy-token]
                                [--change-reference]
                                [--config-file]
                                [--day-of-month]
                                [--day-of-week]
                                [--duration]
                                [--interval-days]
                                [--interval-months]
                                [--interval-weeks]
                                [--location]
                                [--no-wait]
                                [--schedule-type {AbsoluteMonthly, Daily, RelativeMonthly, Weekly}]
                                [--start-date]
                                [--start-time]
                                [--tags]
                                [--utc-offset]
                                [--week-index {First, Fourth, Last, Second, Third}]

範例

建立一個每週六的時段(典型的「製作週末」形式)。

az aks maintenancewindow create -g rg-maintenance -n production-weekends -l eastus \
  --schedule-type Weekly --day-of-week Saturday --interval-weeks 1 \
  --start-time "02:00" --duration 8 --utc-offset=-07:00 \
  --tags environment=production

從特定開始日期起,每兩天建立一個每日時段。

az aks maintenancewindow create -g rg-maintenance -n nightly -l eastus \
  --schedule-type Daily --interval-days 2 \
  --start-date 2026-06-01 --start-time "00:00" --duration 6 --utc-offset=-08:00

在15號設立絕對的每月時段。

az aks maintenancewindow create -g rg-maintenance -n monthly-15 -l eastus \
  --schedule-type AbsoluteMonthly --day-of-month 15 --interval-months 1 \
  --start-time "09:30" --duration 6 --utc-offset=+05:30

在最後一個星期五建立相對的每月時段。

az aks maintenancewindow create -g rg-maintenance -n last-friday -l eastus \
  --schedule-type RelativeMonthly --day-of-week Friday --week-index Last --interval-months 1 \
  --start-time "01:00" --duration 4 --utc-offset=+00:00

透過設定檔建立一個每週的黑名單視窗。

az aks maintenancewindow create -g rg-maintenance -n weekly-with-holidays -l eastus \
  --config-file ./mw-body.json
  The contents of mw-body.json:
  {
    "properties": {
      "schedule": { "weekly": { "intervalWeeks": 1, "dayOfWeek": "Saturday" } },
      "startTime": "02:00",
      "durationHours": 8,
      "utcOffset": "-07:00",
      "notAllowedDates": [
        { "start": "2026-12-23", "end": "2027-01-05" },
        { "start": "2026-07-04", "end": "2026-07-05" }
      ]
    }
  }

必要參數

--name -n

維修時段名稱。

--resource-group -g

資源群組的名稱。 您可以使用 az configure --defaults group=<name> 來設定預設群組。

選擇性參數

下列參數是選擇性參數,但視內容而定,命令可能需要一或多個參數才能成功執行。

--acquire-policy-token

自動取得 Azure 原則 令牌以進行此資源操作。

屬性 值
參數群組: Global Policy Arguments
--change-reference

相關變更的 ID 是為此資源操作所參考的。

屬性 值
參數群組: Global Policy Arguments
--config-file

指向描述 MaintenanceWindow 主體的 JSON 檔案路徑。 當你需要設定沒有專用標記的欄位(例如 notAllowedDates / Blackout 日期範圍)時,請使用。

--day-of-month

維護的月份會進行。 例如15。 僅限 AbsoluteMonthly 排班。

--day-of-week

維護工作在星期幾進行。 例如星期一。 僅限每週或每月的排班。

--duration

維修時段的長度(以小時計)。 距離4-24。

--interval-days

兩次發生之間的天數。 僅限每日行程。

--interval-months

兩次發生之間的月數。 僅限 AbsoluteMonthly 或 RelativeMonthly 排班。

--interval-weeks

兩次發生之間的間隔。 僅限每週排班。

--location -l

維護窗口的位置。 省略時預設為資源群組的位置。

--no-wait

請勿等候長時間執行的作業完成。

屬性 值
預設值: False
--schedule-type

週期類型。 每日、每週、絕對每月或相對每月。

屬性 值
接受的值: AbsoluteMonthly, Daily, RelativeMonthly, Weekly
--start-date

維護期間啟動的日期。 例如:2026-06-01。 若未特別指定,視窗會立即啟動。

--start-time

維護時段的開始時間。 接受的值是從 『00:00』 到 『23:59』。 --UTC-offset 適用於此欄位。

--tags

以空格分隔的標記:key[=value] [key[=value] ...]。使用 「清除現有的標記」。

--utc-offset

格式為 +/-HH:mm 的 UTC 位移。 例如,印度標準時間(IST)為「+05:30」,太平洋標準時間(PST)為「-07:00」。 預設值為「+00:00」。

--week-index

維護發生的星期幾(第一、第二、第三、第四、最後)。 僅限 RelativeMonthly 排程。

屬性 值
接受的值: First, Fourth, Last, Second, Third
全域參數
--debug

提高日誌詳細程度以顯示所有調試日誌。

屬性 值
預設值: False
--help -h

顯示此說明訊息並結束。

--only-show-errors

只顯示錯誤,隱藏警告。

屬性 值
預設值: False
--output -o

輸出格式。

屬性 值
預設值: json
接受的值: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath 查詢字串。 如需詳細資訊和範例,請參閱 http://jmespath.org/。

--subscription

訂用帳戶的名稱或識別碼。 您可以使用 az account set -s NAME_OR_ID 設定預設訂用帳戶。

--verbose

增加記錄的詳細程度。 針對完整偵錯記錄使用 --debug。

屬性 值
預設值: False

az aks maintenancewindow delete

刪除一個維護視窗。

az aks maintenancewindow delete --name
                                --resource-group
                                [--acquire-policy-token]
                                [--change-reference]
                                [--no-wait]
                                [--yes]

必要參數

--name -n

維修時段名稱。

--resource-group -g

資源群組的名稱。 您可以使用 az configure --defaults group=<name> 來設定預設群組。

選擇性參數

下列參數是選擇性參數,但視內容而定,命令可能需要一或多個參數才能成功執行。

--acquire-policy-token

自動取得 Azure 原則 令牌以進行此資源操作。

屬性 值
參數群組: Global Policy Arguments
--change-reference

相關變更的 ID 是為此資源操作所參考的。

屬性 值
參數群組: Global Policy Arguments
--no-wait

請勿等候長時間執行的作業完成。

屬性 值
預設值: False
--yes -y

不提示確認。

屬性 值
預設值: False
全域參數
--debug

提高日誌詳細程度以顯示所有調試日誌。

屬性 值
預設值: False
--help -h

顯示此說明訊息並結束。

--only-show-errors

只顯示錯誤,隱藏警告。

屬性 值
預設值: False
--output -o

輸出格式。

屬性 值
預設值: json
接受的值: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath 查詢字串。 如需詳細資訊和範例,請參閱 http://jmespath.org/。

--subscription

訂用帳戶的名稱或識別碼。 您可以使用 az account set -s NAME_OR_ID 設定預設訂用帳戶。

--verbose

增加記錄的詳細程度。 針對完整偵錯記錄使用 --debug。

屬性 值
預設值: False

az aks maintenancewindow list

在資源群組中列出 MaintenanceWindows,或若省略 --resource-group 則跨訂閱。

az aks maintenancewindow list [--resource-group]

選擇性參數

下列參數是選擇性參數,但視內容而定,命令可能需要一或多個參數才能成功執行。

--resource-group -g

資源群組的名稱。 您可以使用 az configure --defaults group=<name> 來設定預設群組。

全域參數
--debug

提高日誌詳細程度以顯示所有調試日誌。

屬性 值
預設值: False
--help -h

顯示此說明訊息並結束。

--only-show-errors

只顯示錯誤,隱藏警告。

屬性 值
預設值: False
--output -o

輸出格式。

屬性 值
預設值: json
接受的值: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath 查詢字串。 如需詳細資訊和範例,請參閱 http://jmespath.org/。

--subscription

訂用帳戶的名稱或識別碼。 您可以使用 az account set -s NAME_OR_ID 設定預設訂用帳戶。

--verbose

增加記錄的詳細程度。 針對完整偵錯記錄使用 --debug。

屬性 值
預設值: False

az aks maintenancewindow show

顯示維護時段。

az aks maintenancewindow show --name
                              --resource-group

必要參數

--name -n

維修時段名稱。

--resource-group -g

資源群組的名稱。 您可以使用 az configure --defaults group=<name> 來設定預設群組。

全域參數
--debug

提高日誌詳細程度以顯示所有調試日誌。

屬性 值
預設值: False
--help -h

顯示此說明訊息並結束。

--only-show-errors

只顯示錯誤,隱藏警告。

屬性 值
預設值: False
--output -o

輸出格式。

屬性 值
預設值: json
接受的值: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath 查詢字串。 如需詳細資訊和範例,請參閱 http://jmespath.org/。

--subscription

訂用帳戶的名稱或識別碼。 您可以使用 az account set -s NAME_OR_ID 設定預設訂用帳戶。

--verbose

增加記錄的詳細程度。 針對完整偵錯記錄使用 --debug。

屬性 值
預設值: False

az aks maintenancewindow update

更新維護視窗。

讀-修改-寫語意匹配 az aks update 和 az aks nodepool update:取出現有的 MW,你提供的欄位合併到該區域,然後 PUT 回去。 你沒提供的欄位會被保留 as-is(現有標籤、現有排程標量、現有的黑名單日期等)。

當你提供排程 arg(--schedule-type / --interval-* / --day-of-week / --day-of month / --week-index)時,排程形狀會從你的 args 端到端重建(你不能部分混合 Daily + Weekly 欄位——選擇一種排程類型並提供所需的 arg)。

--tags 遵循 aks update 慣例:傳遞 --tags 會取代整個標籤的字典;省略 --tags 以保留現有標籤。

--位置不可更改(TrackedResource 語意學 — ARM 在 PUT 時拒絕位置變更)。 若提供與現有位置不同的數值,則會被忽略並發出警告。

--config-file:提供後,JSON 檔案的 properties 區塊會直接替換現有 properties 的。 這是現今唯一能改變 notAllowedDates / Blackout 日期範圍的方法。 此路徑忽略個別排程旗標;標籤遵循與 un --config-file 相同的 --tags 規則。

az aks maintenancewindow update --name
                                --resource-group
                                [--acquire-policy-token]
                                [--change-reference]
                                [--config-file]
                                [--day-of-month]
                                [--day-of-week]
                                [--duration]
                                [--interval-days]
                                [--interval-months]
                                [--interval-weeks]
                                [--location]
                                [--no-wait]
                                [--schedule-type {AbsoluteMonthly, Daily, RelativeMonthly, Weekly}]
                                [--start-date]
                                [--start-time]
                                [--tags]
                                [--utc-offset]
                                [--week-index {First, Fourth, Last, Second, Third}]

範例

只更新標籤(現有排程仍保留)。

az aks maintenancewindow update -g rg-maintenance -n production-weekends --tags environment=staging

只需更新排程的星期幾(保留現有時長/開始時間/標籤)。

az aks maintenancewindow update -g rg-maintenance -n production-weekends \
  --schedule-type Weekly --day-of-week Sunday --interval-weeks 1

僅更改時長(保留現有排程格式)。

az aks maintenancewindow update -g rg-maintenance -n production-weekends --duration 6

透過設定檔替換黑名單日期(保留標籤和位置)。

az aks maintenancewindow update -g rg-maintenance -n production-weekends --config-file ./mw-body.json
  The contents of mw-body.json should include a complete properties block, e.g.:
  {
    "properties": {
      "schedule": { "weekly": { "intervalWeeks": 1, "dayOfWeek": "Saturday" } },
      "startTime": "02:00",
      "durationHours": 8,
      "utcOffset": "-07:00",
      "notAllowedDates": [ { "start": "2026-12-23", "end": "2027-01-05" } ]
    }
  }

必要參數

--name -n

維修時段名稱。

--resource-group -g

資源群組的名稱。 您可以使用 az configure --defaults group=<name> 來設定預設群組。

選擇性參數

下列參數是選擇性參數,但視內容而定,命令可能需要一或多個參數才能成功執行。

--acquire-policy-token

自動取得 Azure 原則 令牌以進行此資源操作。

屬性 值
參數群組: Global Policy Arguments
--change-reference

相關變更的 ID 是為此資源操作所參考的。

屬性 值
參數群組: Global Policy Arguments
--config-file

指向描述 MaintenanceWindow 主體的 JSON 檔案路徑。 當 JSON 提供時,會完整定義建立資源,或在更新時替換現有 properties 區塊。 這是唯一能設定欄位且不需專用旗標(notAllowedDates 等)的路徑。

--day-of-month

維護會在 AbsoluteMonthly 排班的月份進行。

--day-of-week

維護工作以週或相對月的時間表進行。

--duration

維修時段的長度(以小時計)。 距離4-24。

--interval-days

每日排程中每組事件之間的天數。

--interval-months

AbsoluteMonthly 或 RelativeMonthly 排程中,每組事件之間的月數。

--interval-weeks

每週排程中每組事件之間的週數。

--location -l

Location. 值的來源:az account list-locations。 您可以使用 az configure --defaults location=<location>來設定預設位置。

--no-wait

請勿等候長時間執行的作業完成。

屬性 值
預設值: False
--schedule-type

復發類型:每日、每週、絕對每月或相對每月。

屬性 值
接受的值: AbsoluteMonthly, Daily, RelativeMonthly, Weekly
--start-date

維護期間啟動的日期。 例如:2026-06-01。

--start-time

維護時段的開始時間。 例如09:30。

--tags

以空格分隔的標記:key[=value] [key[=value] ...]。使用 「清除現有的標記」。

--utc-offset

格式為 +/-HH:mm 的 UTC 位移。 例如:-08:00 或 +05:30。

--week-index

在 --day of week-day 中指定的工作日實例,維護會發生在 RelativeMonthly 排程中。

屬性 值
接受的值: First, Fourth, Last, Second, Third
全域參數
--debug

提高日誌詳細程度以顯示所有調試日誌。

屬性 值
預設值: False
--help -h

顯示此說明訊息並結束。

--only-show-errors

只顯示錯誤,隱藏警告。

屬性 值
預設值: False
--output -o

輸出格式。

屬性 值
預設值: json
接受的值: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath 查詢字串。 如需詳細資訊和範例,請參閱 http://jmespath.org/。

--subscription

訂用帳戶的名稱或識別碼。 您可以使用 az account set -s NAME_OR_ID 設定預設訂用帳戶。

--verbose

增加記錄的詳細程度。 針對完整偵錯記錄使用 --debug。

屬性 值
預設值: False

az aks maintenancewindow wait

等待維護視窗達到期望狀態。

如果維護視窗上的操作被中斷或以 --no-wait開始,請使用此指令等待其完成。

az aks maintenancewindow wait --name
                              --resource-group
                              [--acquire-policy-token]
                              [--change-reference]
                              [--created]
                              [--custom]
                              [--deleted]
                              [--exists]
                              [--interval]
                              [--timeout]
                              [--updated]

範例

等待建立一個維護視窗。

az aks maintenancewindow wait -g rg-maintenance -n production-weekends --created

必要參數

--name -n

維修時段名稱。

--resource-group -g

資源群組的名稱。 您可以使用 az configure --defaults group=<name> 來設定預設群組。

選擇性參數

下列參數是選擇性參數,但視內容而定,命令可能需要一或多個參數才能成功執行。

--acquire-policy-token

自動取得 Azure 原則 令牌以進行此資源操作。

屬性 值
參數群組: Global Policy Arguments
--change-reference

相關變更的 ID 是為此資源操作所參考的。

屬性 值
參數群組: Global Policy Arguments
--created

請等候在 'Succeeded' 使用 'provisioningState' 建立。

屬性 值
參數群組: Wait Condition Arguments
預設值: False
--custom

等到條件符合自定義 JMESPath 查詢為止。 例如 provisioningState!='InProgress', instanceView.statuses[?code=='PowerState/running']。

屬性 值
參數群組: Wait Condition Arguments
--deleted

等到刪除為止。

屬性 值
參數群組: Wait Condition Arguments
預設值: False
--exists

等候資源存在。

屬性 值
參數群組: Wait Condition Arguments
預設值: False
--interval

輪詢間隔以秒為單位。

屬性 值
參數群組: Wait Condition Arguments
預設值: 30
--timeout

以秒為單位的等候上限。

屬性 值
參數群組: Wait Condition Arguments
預設值: 3600
--updated

等到 provisioningState 更新為 'Succeeded'。

屬性 值
參數群組: Wait Condition Arguments
預設值: False
全域參數
--debug

提高日誌詳細程度以顯示所有調試日誌。

屬性 值
預設值: False
--help -h

顯示此說明訊息並結束。

--only-show-errors

只顯示錯誤,隱藏警告。

屬性 值
預設值: False
--output -o

輸出格式。

屬性 值
預設值: json
接受的值: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath 查詢字串。 如需詳細資訊和範例,請參閱 http://jmespath.org/。

--subscription

訂用帳戶的名稱或識別碼。 您可以使用 az account set -s NAME_OR_ID 設定預設訂用帳戶。

--verbose

增加記錄的詳細程度。 針對完整偵錯記錄使用 --debug。

屬性 值
預設值: False