配置维护窗口和排除项

Autopilot Standard

---

使用维护窗口和维护排除项来控制可以和不可以在 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 安装，请务必设置 compute/region 和 compute/zone 属性。通过设置默认位置，您可以避免 gcloud CLI 中出现以下错误：One of [--zone, --region] must be supplied: Please specify location。

配置维护期

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

您可以使用 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 的集群，并于 2026 年 8 月 19 日星期三凌晨 2:00 UTC 启用了维护窗口。此维护窗口从星期一和星期五开始，到 30 小时后结束。维护窗口第一次执行从 8 月 21 日星期五凌晨 2:00 开始，到 8 月 22 日星期六上午 8:00 结束。您可以详细了解设置日期和时间格式。

gcloud container clusters create my-cluster \
    --maintenance-window-start 2026-08-19T02:00:00Z \
    --maintenance-window-end 2026-08-20T08:00:00Z \
    --maintenance-window-recurrence 'FREQ=WEEKLY:BYDAY=MO,FR'

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

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

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

gcloud

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

gcloud container clusters create 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 日期，则维护窗口会跨越多天。例如，从星期日开始的维护窗口将持续到星期一。

控制台

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

   转到 Google Kubernetes Engine

2. 点击 创建。

3. 配置集群。

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

5. 选中启用维护期复选框。

6. 选择开始时间和时长，然后选择在一周中的哪几天安排维护期。如需直接修改重复规则规范 (RRule)，请选择自定义编辑器。

7. 点击创建。

为现有集群配置维护窗口

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 日期，则维护窗口会跨越多天。例如，从星期日开始的维护窗口将持续到星期一。

控制台

如需为现有集群创建或修改维护期，请执行以下操作：

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

   前往 Google Kubernetes Engine

2. 在集群列表中，点击您要修改的集群的名称。

3. 在自动化下，点击维护期字段旁边的 修改维护政策。

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. 在自动化下，点击维护期字段旁边的 修改维护政策。

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)

此示例展示了如何设置每日维护期，同时跳过周末。此示例指定的是非 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'

配置维护排除项

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

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

范围	说明	排除长度上限
无升级（默认）	不包括所有补丁程序和次要升级。避免集群控制层面和节点由于升级而发生虚拟机中断。	不能超过 30 天。
无次要升级	不包括所有次要升级。由于补丁程序升级，集群的控制层面和节点可能会发生虚拟机中断。	不能在排除项创建日期后超过 180 天结束，也不能超过次要版本的服务终止日期。
无次要升级或节点升级	不包括所有次要升级和节点升级。避免集群节点由于升级而发生虚拟机中断。但是，控制层面可能会发生中断。	不能在排除项创建日期后超过 180 天结束，也不能超过次要版本的服务终止日期。

如需了解次要版本和补丁程序版本的定义，请参阅版本控制方案。

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

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

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

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

   转到 Google Kubernetes Engine

2. 点击 创建。

3. 配置集群。

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

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

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

7. 点击创建。

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

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

您可以使用 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. 在自动化下方的维护排除项字段旁边，点击 修改维护排除项。

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. 在自动化下方的维护排除项字段旁边，点击 修改维护排除项。

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

问题排查

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

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

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

后续步骤

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