此页面由 Cloud Translation API 翻译。

使用自定义阶段对集群升级的发布进行排序

Autopilot Standard

本文档介绍如何管理使用自定义阶段的发布顺序的 Google Kubernetes Engine (GKE) 集群升级。您可以使用整理到舰队中的集群组以及这些舰队中的可选集群子集来创建发布序列。您可以选择在一个组中完成集群升级后您所需的过渡测试时长（最多 30 天）。您可以同时包含 Autopilot 和 Standard 集群。如需详细了解此功能的工作原理，请参阅使用自定义阶段的发布顺序简介。

如果您要跨多个舰队管理发布，建议您使用专用项目来托管 RolloutSequence 对象。此项目充当序列中所有发布版本的父级和协调器。此项目通常不属于序列；也就是说，此项目不包含属于序列的舰队或集群。

准备工作

安装 Google Cloud CLI。安装完成后，运行以下命令来初始化 Google Cloud CLI：
```
gcloud init
```
如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 来获得最新版本。
确保您已有 Autopilot 或 Standard 集群。如需创建新集群，请参阅创建 Autopilot 集群。
（可选）如果您还没有专门用于托管 RolloutSequence 配置的 Google Cloud 项目，请使用 Google Cloud 控制台或其他方法创建一个。
确保您已启用舰队所需的 API。您必须在舰队宿主项目中启用这些 API，才能创建任何类型的发布序列。为发布序列宿主项目启用 gkehub.googleapis.com API。

所需的角色

如需创建项目，您需要拥有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予角色。

如需创建或修改发布序列，您必须在发布序列中的每个舰队宿主项目以及发布序列宿主项目中拥有 Fleet Editor IAM 角色 (roles/gkehub.editor)。此角色可提供以下权限：

gkehub.rolloutsequences.create
gkehub.rolloutsequences.get
gkehub.rolloutsequences.list
gkehub.rolloutsequences.update
gkehub.rolloutsequences.delete
gkehub.fleet.get

这些权限可让您创建、访问和修改 RolloutSequence 对象，以及在发布序列中使用舰队。

如果您需要向舰队注册或从舰队取消注册集群，则需要具备以下所有权限：

舰队宿主项目的集群注册权限。
对要注册的任何 GKE 集群的集群管理员权限。
对要注册到其他项目中的舰队的任何 GKE 集群的跨项目集群注册权限。

如需详细了解不同任务所需的最低权限 IAM 角色，请参阅在 Gemini 的协助下获取预定义角色建议。

配置发布顺序

如需创建发布序列，必须将您的集群整理到舰队组中。您还可以使用 Kubernetes 标签创建精细的阶段，以便将舰队中的特定集群子集作为目标。如需了解如何整理集群，请参阅社区银行示例。将集群分组并视需要为其添加标签后，您可以通过定义有序的阶段列表以及每个群组的过渡时间来创建发布序列。

将集群整理到舰队中

在发布序列中，我们建议在同一发布渠道中注册所有集群。如果集群未在同一渠道中注册，GKE 会从序列中最保守的渠道中选择一个版本。例如，如果集群同时在稳定渠道和常规渠道中注册，GKE 会选择稳定渠道中的版本。我们还建议所有集群运行相同的次要版本，以便符合条件并升级到相同的自动升级目标版本。

如果您已将集群整理到舰队中，则可以跳过以下步骤并继续执行创建集群子集部分。

将集群分组到舰队中。您可以按部署环境（例如测试、预演和生产环境）整理集群（推荐）。
根据您选择的分组向舰队注册每个集群。

创建集群子集（可选）

如需让发布序列中的某个阶段以特定集群为目标，您必须为这些集群添加标签。

例如，若要在全面推出之前先在一小部分集群上测试新版本，您可以为这些集群应用 canary 标签。如需使用 Google Cloud CLI 向集群添加值为 true 的 canary 标签，请运行以下命令：

gcloud container clusters update CLUSTER_NAME \
    --location=CLUSTER_LOCATION\
    --update-labels=canary=true

替换以下内容：

CLUSTER_NAME：现有集群的名称。
CLUSTER_LOCATION：集群的 Compute Engine 区域或可用区。

--update-labels=canary=true 标志指示 GKE 将 canary 标签应用于集群。

如需详细了解如何为集群添加标签，请参阅为现有集群添加或更新标签。

创建具有自定义阶段的发布序列

发布序列使用阶段来定义升级顺序。如需创建发布序列，您必须先创建一个定义阶段的 YAML 文件，然后创建一个 RolloutSequence。

为确保序列捕获所有集群，每个舰队都必须包含一个全捕获阶段（没有标签选择器的阶段）。此全方位阶段会捕获 GKE 在之前阶段未选择的所有剩余集群。如果您在单个 RolloutSequence 内将单个集群分配给多个阶段，为解决冲突，GKE 会隐式地将该集群仅分配给最早的阶段。

以下示例配置会创建三个阶段：

第一阶段的目标是 dev 舰队中的所有集群。升级完成后，会有 7 天的过渡时间（值为 604800 秒）。
第二阶段的目标是 prod 舰队中具有 canary=true 标签的集群。升级完成后，需要 7 天的浸泡时间。
第三阶段针对 prod 舰队中的其余集群。升级完成后，会有 7 天的浸泡时间。

将以下清单保存为 rollout-sequence.yaml：
```
- stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: resource.labels.canary=='true'
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
```
请注意以下几点：
- stage：包括舰队或舰队中的部分集群。在序列进入下一阶段之前，必须先将早期阶段的集群完全升级并浸泡。不过，如果集群在升级过程开始 30 天后仍未完成升级，GKE 会开始过渡期。
- fleet-projects：从中选择此阶段的集群的舰队列表。每个阶段最多可引用一个舰队。舰队由托管该舰队的项目标识。如果舰队包含跨项目成员资格，则此项目可以与集群所在的项目不同。指定舰队项目的格式为 projects/PROJECT_ID。
- label-selector（可选）：从指定的舰队中选择一部分集群。此字段使用通用表达式语言 (CEL) 语法，并且必须以 resource.labels 开头。
- soak-duration：在升级前一阶段中的所有集群后，等待多长时间再继续下一阶段。以秒为单位。
如需创建您在 rollout-sequence.yaml 清单中定义的发布序列，请运行以下命令：
```
gcloud beta container fleet rolloutsequences create ROLLOUT_SEQUENCE_NAME \
    --display-name=DISPLAY_NAME \
    --stage-config=rollout-sequence.yaml
```
替换以下内容：
- ROLLOUT_SEQUENCE_NAME：符合 RFC-1034 规范的不可变标识符，例如 test-rollout-sequence。
- DISPLAY_NAME：用于发布序列的人类可读字符串。

检查发布状态

配置发布顺序后，系统会自动创建 Rollout 对象来管理升级。您可以使用 Google Cloud CLI 命令来观察和跟踪这些对象的进度。

列出发布

如需列出发布序列宿主项目中的所有有效和历史发布，请运行以下命令：

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

将 HOST_PROJECT_ID 替换为您的发布序列宿主项目的 ID。

如果您已位于托管发布序列的项目中，则可以省略 --project=HOST_PROJECT_ID 标志。

输出类似于以下内容：

NAME                                              STATE      CREATE_TIME
05eb251e4f19269e23-node-1-33-5-gke-1201000-t7mqd  COMPLETED  2025-10-30T20:07:46
05eb251e4f19269e23-kcp-1-33-5-gke-1201000-djwst   COMPLETED  2025-10-30T18:07:06
05eb251e4f19269e23-node-1-33-5-gke-1125000-6bxvu  COMPLETED  2025-10-23T17:46:54
05eb251e4f19269e23-kcp-1-33-5-gke-1125000-2f6ct   RUNNING    2025-10-23T16:41:33

在上述输出中，包含 kcp 的发布版本名称是指控制平面升级，而包含 node 的名称是指节点升级。kcp 或 node 之后的发布版本名称段派生自 GKE 版本。

描述发布

如需获取有关特定发布的详细信息，包括目标版本、状态以及已升级的集群，请使用 describe 命令，并提供从上一个命令中获取的发布 ID：

gcloud beta container fleet rollouts describe ROLLOUT_ID \
  --project=HOST_PROJECT_ID

替换以下内容：

ROLLOUT_ID：您在列出发布版本时获得的发布版本 ID。
HOST_PROJECT_ID：您的发布序列所托管到的项目 ID。

例如：

gcloud beta container fleet rollouts describe 927e9a989930cf3b55-kcp-1-32-4-gke-1106006 \
  --project=my-hostfleet

输出类似于以下内容：

createTime: '2025-05-26T11:47:29.909959672Z'
membershipStates:
  projects/dev-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T12:20:55.601542481Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-1234567890-abcdefg-hijklm-nopqrst
      state: SUCCEEDED
    stageAssignment: 1
  projects/dev-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T12:22:57.151203493Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-2
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-987654321-ghijkl-mno-pqr-stu-vwxyz
      state: SUCCEEDED
    stageAssignment: 1
  projects/prod-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T13:03:34.134308942Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-567891234-efghij-klm-nopq-rstu-vwxyz
      state: SUCCEEDED
    stageAssignment: 2
  projects/prod-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T13:06:34.025261641Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-765432198-01a7b896-67c2-523-6fjjh4-icmdydh
      state: SUCCEEDED
    stageAssignment: 2
name: projects/user-hostfleet/locations/global/rollouts/05eb251e4f19269e23-kcp-1-32-4-gke-1106006
rolloutSequence: projects/project-id/locations/global/rolloutSequences/my-sequence
state: COMPLETED
updateTime: '2025-07-22T07:36:51.052691989Z'
versionUpgrade:
  desiredVersion: 1.32.4-gke.1106006
  type: TYPE_CONTROL_PLANE
stages:
- state: COMPLETED
  endTime: '2025-05-26T12:22:28.828506491Z'
  stageNumber: 1
  startTime: '2025-05-26T11:48:28.772658427Z'
  soakDuration: 600s
- state: COMPLETED
  endTime: '2025-05-26T13:06:20.026390832Z'
  stageNumber: 2
  startTime: '2025-05-26T12:32:38.419372153Z'
  soakDuration: 600s

发布的状态信息

描述发布时，输出的 stages 和 membershipStates 字段分别提供每个阶段以及该阶段内每个集群的进度状态。

下表列出了阶段的潜在状态：

状态	说明
`PENDING`	此阶段的升级尚未开始。
`RUNNING`	此阶段的升级正在进行中。如果您为阶段中的集群配置了维护窗口，则 GKE 会等待窗口打开，然后再升级集群。
`SOAKING`	此阶段中的所有集群均已完成升级，并且该阶段处于配置的过渡期。
`FORCED_SOAKING`	升级所用时间超过了最长升级时间（30 天），因此 GKE 强制启动了过渡阶段。升级仍会在任何剩余集群上继续进行。
`COMPLETED`	阶段已完成浸泡，发布作业将继续进入下一阶段。

下表列出了序列中集群的潜在状态：

状态	说明
`PENDING`	此集群上的升级处于待处理状态。
`INELIGIBLE`	此集群不符合升级条件，可能是由于版本不一致。输出中提供了不符合条件的原因。
`RUNNING`	此集群正在升级。
`SUCCEEDED`	此集群已成功完成升级。
`FAILED`	此集群上的升级失败。失败的目标会在其阶段处于有效状态（处于 `RUNNING` 或 `FORCED_SOAKING` 状态）时无限期重试。

管理发布序列

您可以采用多种方式通过发布序列控制自动集群升级，如以下部分所述。

列出发布序列

如需列出宿主项目中的所有发布序列，请运行以下命令：

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

将 HOST_PROJECT_ID 替换为您的发布序列宿主项目的 ID。

描述发布序列

如需查看特定发布序列的详细信息，请运行以下命令：

gcloud beta container fleet rolloutsequences describe ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

替换以下内容：

ROLLOUT_SEQUENCE_NAME：发布序列的名称。
HOST_PROJECT_ID：发布序列宿主项目的 ID。

输出类似于以下内容：

createTime: '2025-10-23T16:40:16.403871189Z'
displayName: my-display-name
name: projects/HOST_PROJECT_ID/locations/global/rolloutSequences/ROLLOUT_SEQUENCE_NAME
stages:
- clusterSelector:
    labelSelector: resource.labels.canary=='true'
  fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 600s
- fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 300s
uid: 5c5b2ac8-9d76-45f9-92ca-5e6bd3fbcaef
updateTime: '2025-10-23T17:11:57.285678399Z'

修改发布序列

您可以修改定义了现有发布序列的 YAML 配置文件，从而修改该序列。例如，您可以更新某个阶段的浸泡时间，也可以更新阶段来更改升级顺序。修改完文件后，应用更改。

例如，如果您在名为 rollout-sequence.yaml 的文件中定义了原始的发布序列，请根据需要修改该文件。然后，运行以下命令：

gcloud beta container fleet rolloutsequences update test-rollout-sequence \
  --display-name="My Updated Rollout Sequence" \
  --stage-config=rollout-sequence.yaml

删除发布序列

如需删除发布序列，请运行以下命令：

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

替换以下内容：

将 ROLLOUT_SEQUENCE_NAME 替换为发布序列的名称。
将 HOST_PROJECT_ID 替换为您的发布序列宿主项目的 ID。

删除发布序列后，该序列中正在进行的所有发布都会被取消。属于该序列的集群会恢复为其注册的发布渠道的默认自动升级行为。

迁移现有发布序列以使用自定义阶段

如果您使用的是基于舰队的发布序列化（正式版），则可以创建引用现有舰队的新 RolloutSequence，从而迁移到使用自定义阶段的序列。

在迁移序列之前，我们建议您先复制当前的发布序列配置。

如需迁移发布序列，请完成以下步骤：

创建一个专用 Google Cloud 项目来托管发布序列。此项目通常不属于序列；也就是说，该项目不包含属于序列的舰队或集群。
如果您希望发布序列包含舰队中的特定集群，请向这些集群添加标签。这是可选步骤。

按照创建具有自定义阶段的发布序列中的说明操作。

例如，以下名为 rollout-sequence-migrate.yaml 的清单引用了之前发布序列中的现有舰队。此清单描述了三个阶段，包括 prod 舰队中的 canary 阶段：

- stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: canary=true
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

在您为舰队定义新的 RolloutSequence 后，GKE 会立即开始按照新顺序升级舰队，并移除之前的配置。

将具有自定义阶段的发布序列迁移到之前的发布序列

本部分介绍了如何从具有自定义阶段的发布序列恢复为基于舰队的正式版序列模型。此过程涉及删除新的 RolloutSequence 并恢复基于车队的原始配置。

防止在迁移期间发生升级顺序错误

为避免在重新配置序列时发生意外或无序升级，请为生产集群应用维护排除项。此步骤会暂时暂停这些集群上的所有自动升级。例如，您可以在生产集群上配置类型为 no upgrades 的维护排除项。

删除发布序列

删除用于管理集群的 RolloutSequence 对象。此删除操作会停用自定义阶段功能。

如需删除 RolloutSequence，请运行以下命令：

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

将 ROLLOUT_SEQUENCE_NAME 替换为发布序列的名称。

恢复之前的发布序列配置（不含自定义阶段）

删除 RolloutSequence 后，您可以恢复基于舰队的原始配置。此过程涉及使用原始参数重新创建 clusterupgrade 功能，包括序列中每个舰队的 upstreamFleet 链接和浸泡时间。如需了解详情，请参阅创建发布顺序。

移除维护排除项

恢复基于舰队的原始发布序列配置后，移除您在本部分的第一步中应用的维护排除对象。GKE 会恢复自动升级，现在由您恢复的基于舰队的序列来管理。

后续步骤

详细了解使用发布序列的集群升级。

使用自定义阶段对集群升级的发布进行排序 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

配置发布顺序

将集群整理到舰队中

创建集群子集（可选）

创建具有自定义阶段的发布序列

检查发布状态

列出发布

描述发布

发布的状态信息

管理发布序列

列出发布序列

描述发布序列

修改发布序列

删除发布序列

迁移现有发布序列以使用自定义阶段

将具有自定义阶段的发布序列迁移到之前的发布序列

防止在迁移期间发生升级顺序错误

删除发布序列

恢复之前的发布序列配置（不含自定义阶段）

移除维护排除项

后续步骤

使用自定义阶段对集群升级的发布进行排序