配置维护窗口和排除项

使用维护窗口和维护排除项来控制可以和不可以在 Google Kubernetes Engine (GKE) 集群上进行自动集群维护（例如自动升级）的时间。在配置这些维护政策之前，请务必查看哪些更改会遵循和不遵循 GKE 维护政策。

准备工作

在开始之前，请确保您已执行以下任务：

• 启用 Google Kubernetes Engine API。
启用 Google Kubernetes Engine API
• 如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。 如果您之前安装了 gcloud CLI，请运行 gcloud components update 以获取最新版本。

配置维护期

如需配置维护窗口，请指定其开始时间、持续时长以及重复频率。例如，您可以配置每周重复的维护窗口（周一到周五，每天四小时）。

您可以使用 Google Cloud 控制台或 Google Cloud CLI 配置维护窗口。

配置维护窗口时的注意事项

配置维护窗口时，请遵循以下指南：

• 了解哪些类型的维护事件会遵循和不遵循 GKE 维护窗口。如需了解详情，请参阅遵循 GKE 维护政策的自动维护和不遵循 GKE 维护政策的自动维护。
• 您只能为一个集群配置一个维护窗口，配置新窗口会覆盖上一个窗口。
• 在 32 天的滚动期中，您必须至少留出 48 小时的维护时间，每次维护至少持续 4 小时。
• 使用 Google Cloud 控制台时，时间始终以本地时区显示。
• 系统始终根据世界协调时间 (UTC) 显示星期几。因此，我们建议您通过 gcloud CLI，完全以世界协调时间 (UTC) 设置涉及此类重复的维护窗口。虽然您可以在设置标志时使用当地时间，但系统不会存储该时区。例如，如果您所在的时区是 UTC+6，并且您希望维护窗口从您所在时区的星期三 02:00 开始，那么您可以指定星期二 20:00 的 UTC 值。如需了解详情，请参阅维护窗口的时区。

• 如果您的集群无法在计划维护窗口内完成节点升级，这可能会减慢升级速度。您可能需要使用配置进行实验，以便在速度和环境中断之间找到最佳平衡。可能影响升级速率的因素包括：

  • 维护可用性低（例如，较短的维护窗口）。
  • Standard 节点池比较大。
  • 优先考虑最少中断次数（而不是速度）的节点升级策略配置。
  • 某些 Pod 配置选项。如需了解详情，请参阅节点升级时长注意事项。

创建一个具有简单维护窗口的标准集群

您可以通过指定 --maintenance-window 标志在 gcloud CLI 中创建简单的维护窗口。通过此标志，您可以使用简化格式指定每日 4 小时的维护期。如需创建一个具有维护窗口的 Autopilot 集群，请使用 Google Cloud 控制台。

创建一个具有简单维护窗口的新标准集群

gcloud container clusters create CLUSTER_NAME \
    --maintenance-window START_TIME

替换以下内容：

• CLUSTER_NAME：新集群的名称。
• START_TIME：24 小时制 UTC 时间戳，例如 16:00。

维护窗口每天从指定的 START_TIME 开始，持续 4 个小时。

创建自定义维护窗口

您可以使用本部分中介绍的其他参数创建在一周或一个月内的某些时段执行的维护窗口。

例如，以下命令创建了一个名为 my-cluster 的集群，并于 2024 年 8 月 23 日星期五凌晨 2:00 UTC 开启维护窗口。此维护窗口在每周的周一和周五重复，30 小时后结束。维护窗口第一次出现从 8 月 23 日星期五凌晨 2:00 开始，到 8 月 24 日星期六上午 8:00 结束。您可以详细了解设置日期和时间格式。

gcloud container clusters create 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'

如需了解更多场景，请参阅维护窗口示例。

创建一个具有维护窗口的集群

您可以使用 gcloud CLI 或 Google Cloud 控制台创建具有维护窗口的新标准集群。如需创建一个具有维护期的新 Autopilot 集群，请使用 Google Cloud 控制台。

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

为现有集群配置维护窗口

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

手动完成未完成的维护

如果升级或其他自动维护需要比维护窗口更长的时间才能完成，GKE 会尝试停止正在进行的维护任务，并在下一个维护窗口继续这些任务。如果取消了自动升级，并且您已启用节点自动升级，则您的节点可能处于混合版本状态，但您的集群应该会正常运行。

如需手动升级您的集群，或者取消或回滚部分升级，请访问手动升级集群。

移除维护窗口

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

维护期示例

以下示例介绍了配置维护窗口的一些不同方法。示例仅显示相关标志，因为这些标志使用相同的语法来创建新集群或更新现有集群。

从 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)

此示例展示了如何设置每日维护期，同时跳过周末。此示例指定的是非 UTC 时区。

   --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 点，持续 8 小时 (UTC-7)

如果您没有为 --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 时区的工作日之间运行。在此示例中，该窗口从晚上 20:00 持续到次日凌晨 4:00。

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

配置维护排除项

如需为集群设置维护排除项，您需要指定以下各项：

• 名称：排除项的名称（可选）。
• 开始时间：排除期应开始的日期和时间。
• 结束时间：排除期应结束的日期和时间。请参阅下表，了解每个可用范围的排除期限长度的限制。
• 范围：要限制的自动升级的范围。请参阅列出可用排除范围的下表。

创建一个具有维护排除项的集群

您可以在使用 Google Cloud 控制台创建新集群时配置维护排除项。此任务无法在 gcloud CLI 中执行。

如需创建具有维护排除项的新集群，请执行以下操作：

1. 转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

   转到 Google Kubernetes Engine

2. 点击 add_box 创建。

3. 配置集群。

4. 在导航窗格的集群下，点击自动化。

5. 在维护排除项下，点击 add 添加维护排除项。

6. 选择范围、开始时间和结束时间。

7. 点击创建。

您可以查看黑色星期五的维护排除项示例。

为现有集群配置维护排除项

您可以使用 Google Cloud 控制台或 gcloud CLI 在现有集群上配置维护排除项。

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

移除维护排除项

您可以使用 Google Cloud 控制台或 gcloud CLI 移除维护排除项。

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

如需查看集群上的所有维护排除项，您可以查看集群的维护政策。

维护排除项示例

以下示例可避免在黑色星期五到网购星期一（一年内许多零售业务销量最高的时段）的四天内进行维护。此示例展示了如何防止在 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

问题排查

限制维护排除项的范围仅适用于发布渠道

在维护排除项中限制自动升级的范围时，必须在发布渠道中注册集群，否则您可能会遇到以下错误：

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).

后续步骤

• 详细了解集群和节点升级。
• 了解如何启用节点自动升级。
• 了解如何接收集群通知。