設定維護期間和排除項目

自動駕駛 標準

使用維護期間和維護排除項目，控管 Google Kubernetes Engine (GKE) 叢集自動維護作業 (例如自動升級) 的執行時間。設定這些維護政策前，請務必先瞭解哪些變更會遵守 GKE 維護政策，哪些不會。

事前準備

開始之前，請確認您已完成下列工作：

• 啟用 Google Kubernetes Engine API。
啟用 Google Kubernetes Engine API
• 如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update 指令，取得最新版本。較舊的 gcloud CLI 版本可能不支援執行本文件中的指令。
  注意：如果是現有的 gcloud CLI 安裝項目，請務必設定 compute/region 屬性。如果您主要使用區域叢集，請改為設定 compute/zone。設定預設位置後，即可避免 gcloud CLI 發生下列錯誤：One of [--zone, --region] must be supplied: Please specify location。如果叢集位置與您設定的預設位置不同，您可能需要在特定指令中指定位置。

• 請確認您有現有的 Autopilot 或 Standard 叢集。如需叢集，請建立 Autopilot 叢集。

設定維護期間

如要設定維護期間，請指定開始時間、持續時間和重複頻率。舉例來說，您可以設定維護時段，每週一到週五每天重複四小時。

您可以使用 Google Cloud 控制台或 Google Cloud CLI 設定維護時段。

設定維護期間的注意事項

設定維護期間時，請遵循下列指引：

• 瞭解哪些類型的維護事件會遵守 GKE 維護期間，哪些不會。詳情請參閱「自動維護作業會遵守 GKE 維護政策」和「自動維護作業不會遵守 GKE 維護政策」。
• 每個叢集只能設定一個維護期間，且設定新維護期間會覆寫先前的設定。
• 在每個連續 32 天的區間內，至少必須安排 48 小時執行維護作業，而且每次作業時間至少須持續四小時。
• 使用 Google Cloud 控制台時，系統一律會以當地時區顯示時間。
• 每週重複的日期一律以世界標準時間為準。因此，建議您透過 gcloud CLI，以 UTC 設定涉及這類週期性事件的維護期間。設定旗標時可以使用當地時間，但系統不會儲存時區。舉例來說，如果您的時區是 UTC+6，且希望維護期間在您時區的星期三凌晨 2 點開始，請指定星期二 20:00 的 UTC 值。詳情請參閱「維護時段的時區」。

設定維護期間

您可以使用Google Cloud 控制台或 gcloud CLI，在現有叢集上設定維護期間。

gcloud

為現有叢集建立或更新維護期間：

gcloud container clusters update CLUSTER_NAME \
    --maintenance-window-start START_TIME \
    --maintenance-window-end END_TIME \
    --maintenance-window-recurrence RRULE

更改下列內容：

• CLUSTER_NAME：叢集名稱。
• START_TIME：啟用週期性維護時段的日期和時間，以 RFC-5545 DTSTART 值表示。之後，維護期間會根據 RRULE 重複。START_TIME 也會提供維護時段的開始時間。
• END_TIME：計算維護期間長度的結束時間，以 START_TIME 後的時間量表示，格式相同。END_TIME 的值必須是未來時間，相對於 START_TIME。這項操作只會計算維護期間的長度，不會設定維護期間的週期性停止時間。維護期間移除後，系統才會停止重複執行。
• RRULE：維護期間的重複次數，以 RFC-5545 RRULE 表示。這個彈性格式提供多種指定週期性規則的方式，可決定維護時段的開始日期。舉例來說，您可以指定每週或每月重複特定次數。如果END_TIME日期晚於START_TIME日期，維護期間會跨越多天。舉例來說，如果維護期間從週日開始，就會持續到週一。

重要事項： GKE 會使用 START_TIME 計算維護期長度，以及維護期開始重複的時間。GKE 只會使用 END_TIME 計算維護時段的持續時間，不會使用這個變數指定維護時段停止重複的時間。維護期間會持續重複，直到您移除維護期間為止。

舉例來說，下列指令會編輯名為 my-cluster 的叢集，並在 2024 年 8 月 23 日星期五的 UTC 上午 2 點啟用維護期間。這個維護時段每週一和週五都會重複，並在 30 小時後結束。第一個維護期間從 8 月 23 日 (星期五) 凌晨 2 點開始，到 8 月 24 日 (星期六) 上午 8 點結束。如要進一步瞭解如何設定日期和時間格式，請參閱這篇文章。

gcloud container clusters update my-cluster \
    --maintenance-window-start 2024-08-23T02:00:00Z \
    --maintenance-window-end 2024-08-24T08:00:00Z \
    --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,FR'

如需更多情境，請參閱維護期間範例。

控制台

如要為現有叢集建立或修改維護期間：

1. 前往 Google Cloud 控制台的「Google Kubernetes Engine」頁面。

   前往「Google Kubernetes Engine」

2. 在叢集清單中，按一下您要修改的叢集名稱。

3. 在「Automation」(自動化) 下，按一下「Maintenance window」(維護時段) 欄位旁的「Edit maintenance policy」(編輯維護政策)。

4. 勾選「啟用維護期間」核取方塊。

5. 選取開始時間和長度，然後選取維護期間的星期幾。如要直接編輯 RRule，請選取「自訂編輯器」。

6. 按一下 [儲存變更]。

手動完成未完成的維護作業

如果升級或其他自動維護作業所需時間超出維護期間，GKE 會嘗試停止進行中的維護工作，並在下個維護期間繼續執行。如果自動升級已取消，且您已啟用節點自動升級功能，節點的版本可能會不一致，但叢集應能正常運作。

如要手動升級叢集，或取消或復原部分升級，請參閱「手動升級叢集」。

移除維護期間

gcloud

從叢集移除維護期間：

gcloud container clusters update CLUSTER_NAME --clear-maintenance-window

將 CLUSTER_NAME 替換為現有叢集的名稱。

控制台

如要移除維護期間：

1. 前往 Google Cloud 控制台的「Google Kubernetes Engine」頁面。

   前往「Google Kubernetes Engine」

2. 在叢集清單中，按一下您要修改的叢集名稱。

3. 在「Automation」(自動化) 下，按一下「Maintenance window」(維護時段) 欄位旁的「Edit maintenance policy」(編輯維護政策)。

4. 取消勾選「啟用維護期間」核取方塊。

5. 按一下 [儲存變更]。

維護期間範例

以下範例說明設定維護期間的幾種不同方式。系統只會顯示相關的旗標，因為旗標使用相同的語法來建立新叢集或更新現有叢集。

2026 年 8 月 22 日起，週末

在這個範例中，開始和結束時間戳記之間相差整整兩天，因此維護期間會涵蓋整個週末，也就是週六和週日。如要將回溯期設為 48 小時以外的時間長度，請修改 -start 來變更回溯期開始時間，或修改 -end 來變更回溯期總長度。

  --maintenance-window-start 2026-08-22T00:00:00Z \
  --maintenance-window-end 2026-08-24T00:00:00Z \
  --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=SA'

平日每天 9:00 至 17:00 (UTC-4)

本例說明如何設定每日維護時段，但略過週末。 這個範例指定了非世界標準時間的時區。

   --maintenance-window-start 2026-09-02T09:00:00-04:00 \
   --maintenance-window-end 2026-09-02T17:00:00-04:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR'

每週下午 4 點 (UTC-7) 進行 8 小時

如果沒有為 --maintenance-window-start 指定時區，系統會使用 Google Cloud 帳戶中設定的當地時間。 Google Cloud 控制台一律使用當地時間。

   --maintenance-window-start 2026-08-13T16:00:00-7:00 \
   --maintenance-window-end 2026-08-14T00:00:00-7:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY'

平日夜間

這個範例顯示在 UTC-7 時區，於工作日之間的夜間執行每日維護作業。在這個範例中，時間範圍為晚上 8 點到隔天凌晨 4 點。

   --maintenance-window-start 2026-08-15T20:00:00-7:00 \
   --maintenance-window-end 2026-08-16T04:00:00-7:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH'

設定維護作業排除時段

如要為叢集設定維護排除項目，請指定下列項目：

• 名稱：排除條件的名稱 (選填)。
• 開始時間：排除期開始的日期和時間。開始時間必須是現在或未來。
• 結束時間：排除期結束的日期和時間。 請參閱下表，瞭解各適用範圍的排除期間長度限制。
• 範圍：要限制自動升級的範圍。請參閱下表，瞭解可用的排除範圍。

範圍	說明	排除時間長度上限
不升級 (預設)	排除所有修補程式和次要升級。避免升級作業導致叢集控制層和節點的 VM 中斷。	不得超過 30 天。
不執行任何次要升級作業	不包括所有次要升級。修補程式升級作業可能會導致叢集的控制層和節點發生 VM 中斷情形。	如果叢集註冊於 Rapid、Regular 或 Stable 版本，則無法延長超過標準支援服務結束日期。如果叢集已註冊延長版，則無法延長子版本的延長支援期限。
不執行任何次要或節點升級作業	排除所有次要升級和節點升級作業。避免升級導致叢集節點的 VM 中斷。不過，控制層可能會發生中斷情形。	如果叢集註冊於 Rapid、Regular 或 Stable 版本，則無法延長超過標準支援服務結束日期。如果叢集已註冊延長版，則無法延長子版本的延長支援期限。

注意： 建議將維護排除條件的長度限制在六個月以下。如果長期排除維護作業，系統就會延後子版本升級，導致 GKE 需要多次升級子版本，確保叢集持續執行支援的版本。

設定維護作業排除時段

您可以使用Google Cloud 控制台或 gcloud CLI，在現有叢集上設定維護作業排除項目。

gcloud

為現有叢集設定維護作業排除時段：

gcloud container clusters update CLUSTER_NAME \
    --add-maintenance-exclusion-name EXCLUSION_NAME \
    --add-maintenance-exclusion-start START_DATE_TIME \
    --add-maintenance-exclusion-end END_DATE_TIME \
    --add-maintenance-exclusion-scope SCOPE

更改下列內容：

• CLUSTER_NAME：叢集名稱。
• EXCLUSION_NAME：排除的維護時間名稱。
• START_DATE_TIME：排除項目的開始日期和時間。
• END_DATE_TIME：排除項目的結束日期和時間。
• SCOPE：要排除的升級範圍，可以是下列其中一個值：no_upgrades、no_minor_upgrades 或 no_minor_or_node_upgrades。

如要查看支援的日期和時間格式，請執行 gcloud topic datetimes。

主控台

如要為現有叢集設定維護作業排除時段，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Google Kubernetes Engine」頁面。

   前往「Google Kubernetes Engine」

2. 在叢集清單中，按一下您要修改的叢集名稱。

3. 在「Automation」(自動化) 下方，按一下「Maintenance exclusions」(維護排除條件) 欄位旁的 「Edit maintenance exclusions」(編輯維護排除條件)。

4. 在「排除的維護時間」下方，按一下 「新增排除的維護時間」。

5. 選取「範圍」、「開始時間」和「結束時間」。

6. 按一下 [儲存變更]。

移除排除的維護時間

您可以使用 Google Cloud 控制台或 gcloud CLI 移除維護排除項目。

gcloud

移除現有的排除維護時間：

gcloud container clusters update CLUSTER_NAME \
    --remove-maintenance-exclusion EXCLUSION_NAME

更改下列內容：

• CLUSTER_NAME：現有叢集的名稱。
• EXCLUSION_NAME：要移除的維護排除項目名稱。

控制台

如要從現有叢集移除維護排除項目：

1. 前往 Google Cloud 控制台的「Google Kubernetes Engine」頁面。

   前往「Google Kubernetes Engine」

2. 在叢集清單中，按一下您要修改的叢集名稱。

3. 在「Automation」(自動化) 下方，按一下「Maintenance exclusions」(維護排除條件) 欄位旁的 「Edit maintenance exclusions」(編輯維護排除條件)。

4. 在「維護排除項目」下方，找出要移除的排除項目，然後按一下「結束時間」欄位旁邊的「刪除項目」圖示 。

5. 按一下 [儲存變更]。

如要查看叢集的所有維護排除條件，請查看叢集的維護政策。

維護作業排除時段範例

以下範例可避免在黑色星期五到網購星期一這四天進行維護，因為對許多零售業來說，這段期間的銷售量是全年最高。以下範例說明如何避免在 2021 年黑色星期五 (2021 年 11 月 26 日) 到 2021 年網路星期一 (2021 年 11 月 29 日) 期間，從美東時間 (UTC-5) 午夜到太平洋時間 (UTC-8) 23:59:59 發生維護時段。

gcloud container clusters update sample-cluster \
    --add-maintenance-exclusion-name black-friday \
    --add-maintenance-exclusion-start 2021-11-26T00:00:00-05:00 \
    --add-maintenance-exclusion-end 2021-11-29T23:59:59-08:00 \
    --add-maintenance-exclusion-scope no_upgrades

查看叢集的維護政策

如要查看叢集的維護政策，包括是否有維護期間和所有維護排除項目，請使用下列指令：

gcloud container clusters describe CLUSTER_NAME

找出未設定維護期間的叢集

GKE 會找出您尚未設定維護期間的叢集，方便您選擇定期維護期間，讓 GKE 執行叢集維護作業。建議您設定維護期間，確保 GKE 在最適合叢集環境的時間，執行自動升級和其他叢集維護作業 (遵守維護政策)。

GKE 會透過 Recommender 服務，以深入分析結果和建議的形式提供這項指引。如要進一步瞭解如何管理 Recommender 的深入分析和建議，請參閱「運用深入分析和建議，最佳化 GKE 使用量」。

如要找出未設定維護期間的叢集，可以使用下列其中一種方式：

• 使用 Google Cloud 控制台。
• 使用 gcloud CLI 或 Recommender API，並指定 CLUSTER_MAINTENANCE_WINDOW_AND_EXCLUSIONS recommender subtype。

如需操作說明，請參閱這篇文章。

如要實作這項建議，請設定維護時段。

疑難排解

請參閱下列資訊，排解維護期間和排除時段的常見問題。

維護期間導致節點更新無法完成

如果叢集無法在排定的維護期間內完成節點更新 (例如節點版本升級)，升級速度可能會變慢，或節點變更作業可能會延遲完成。您可能需要嘗試調整設定，在環境的速度和中斷之間取得最佳平衡。可能影響升級率的因素包括：

• 維護時間較短，例如維護期間較短。
• 大型標準節點集區。
• 節點升級策略：設定優先考量是將中斷時間降到最低，還是升級速度。
• 部分 Pod 設定選項。詳情請參閱「節點升級時間注意事項」。

限制維護排除時段的範圍只能套用至發布管道

在維護排除項目中限制自動升級範圍時，叢集必須在發布管道中註冊，否則可能會遇到下列錯誤：

ERROR: (gcloud.container.clusters.update) INVALID_ARGUMENT: Cannot update to
STATIC channel since following maintenancePolicy.maintenanceExclusions can only
apply to release channels. Please remove those maintenance exclusions.

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=MaintenancePolicy.maintenanceExclusions["no"] could not apply to cluster
in STATIC channel, only no_upgrades exclusions are allowed in STATIC channel.

排除的維護時間超出上限

您最多只能指定 3 個維護排除時段，排除所有升級作業 (也就是「不執行任何升級作業」的範圍)，否則會收到下列錯誤訊息：

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of active maintenance exclusions exceeds limit (3).

您最多只能指定 20 個維護排除項目，否則會收到下列錯誤訊息：

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of total maintenance exclusions exceeds limit (20).

後續步驟

• 進一步瞭解叢集和節點升級。
• 瞭解如何啟用節點自動升級功能。
• 瞭解叢集通知。
• 進一步瞭解 GKE 發布時間表。