部署舰队软件包

本页面介绍了如何使用 Config Sync 舰队软件包在注册到舰队的集群中部署 Kubernetes 资源。创建并部署舰队软件包后，当您向舰队添加新集群时，该舰队软件包会自动将 Git 仓库中的 Kubernetes 配置文件部署到新集群。

FleetPackage 是一种声明性 API，用于将 Kubernetes 原始清单部署到集群舰队。您要使用舰队软件包部署的所有 Kubernetes 资源都必须已完成水合 (WET)。

准备工作

创建 Git 仓库或确保您有权访问此仓库，其中包含您要在舰队中部署的 Kubernetes 资源。
安装并初始化 Google Cloud CLI，它提供了 gcloud 和 nomos 命令。如果您使用 Cloud Shell，则系统会预安装 Google Cloud CLI。如果您之前安装了 Google Cloud CLI，请运行 gcloud components update 以获取最新版本。

注意：对于现有 gcloud CLI 安装，请务必设置 compute/region 和 compute/zone 属性。通过设置默认位置，您可以避免 gcloud CLI 中出现以下错误：One of [--zone, --region] must be supplied: Please specify location。

启用 Config Sync (anthosconfigmanagement) API 和 ConfigDelivery API：

gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com

设置默认位置：
```
gcloud config set config_delivery/location us-central1
```
注意：ConfigDelivery API 唯一可用的位置是 us-central1。
设置默认项目：
```
gcloud config set project PROJECT_ID
```
将 PROJECT_ID 替换为舰队宿主项目的 ID。
确保集群已注册到舰队。
使用 Cloud Build 仓库创建与受支持的提供方（例如 GitHub 或 GitLab）的连接。使用舰队软件包时，您只需为每个要同步的仓库设置 Cloud Build 一次。

重要提示：Cloud Build 连接必须位于 us-central1 中，因为 Git 连接和 FleetPackage 必须位于同一区域。 ConfigDelivery API 仅在 us-central1 中提供。

查看集群要求

在集群上安装 Config Sync 之前，请查看集群配置建议和要求。

准备环境

如需为 Config Sync 舰队软件包准备环境，请向注册集群的用户授予所需的 IAM 角色。

安装 Config Sync

您可以使用 Google Cloud 控制台或 Google Cloud CLI 安装 Config Sync。

控制台

如需安装 Config Sync，所有集群都必须注册到舰队。在 Google Cloud 控制台中安装 Config Sync 时，选择个别集群会自动将这些集群注册到舰队。

在 Google Cloud 控制台中，前往功能部分下的配置页面。

转到“配置”

点击 安装 Config Sync。
在安装选项下，选择 Install Config Sync on entire fleet (recommended)。
点击 Install Config Sync（安装 Config Sync）。在设置标签页中，几分钟后，您应该会在舰队中集群的状态列中看到已启用。

gcloud

启用 ConfigManagement 舰队功能：

gcloud beta container fleet config-management enable

如需启用 Config Sync，请创建一个名为 apply-spec.yaml 且包含以下内容的文件：
```
applySpecVersion: 1
spec:
  configSync:
    enabled: true
```
应用 apply-spec.yaml 文件：
```
gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=apply-spec.yaml
```
将 MEMBERSHIP_NAME 替换为您在注册集群时选择的舰队成员资格名称。如需查找成员资格名称，请运行 gcloud container fleet memberships list 命令。

为 Cloud Build 创建服务账号

舰队软件包使用 Cloud Build 从 Git 仓库提取 Kubernetes 资源，并将其部署到集群。 Cloud Build 需要一个有权限运行此作业的服务账号。如需创建服务账号并授予所需的权限，请完成以下步骤：

创建服务账号：
```
gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
```
将 SERVICE_ACCOUNT_NAME 替换为服务账号的名称。该名称必须是介于 6 到 30 个字符之间的字母数字 ID，例如 my-service-account。在服务账号创建完毕后，无法再更改其名称。

为 Resource Bundle Publisher 角色添加 IAM 政策绑定：

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/configdelivery.resourceBundlePublisher'

如果系统提示，请选择 None 作为政策的条件。

为 Logs Writer 角色添加 IAM 政策绑定：

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/logging.logWriter'

如果系统提示，请选择 None 作为政策的条件。

为 ArtifactRegistry Writer 角色添加 IAM 政策绑定：

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/artifactregistry.writer'

如果系统提示，请选择 None 作为政策的条件。

创建舰队软件包

如需创建舰队软件包，您需要定义 FleetPackage 规范，该规范指向包含您连接到 Cloud Build 的 Kubernetes 资源的代码库。然后应用 FleetPackage 资源，该资源会从 Git 提取资源并将其部署到舰队。

创建一个名为 fleetpackage-spec.yaml 的文件，其中包含以下内容：
```
resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
# set the state to SUSPENDED to pause new rollouts
# set the state back to ACTIVE to resume rollouts
# state: SUSPENDED
```
替换以下内容：
- CONNECTION_NAME：您在将 Git 主机连接到 Cloud Build 时选择的名称。您可以通过运行 gcloud builds connections list 或打开 Google Cloud 控制台中的仓库页面来查看所有 Cloud Build 连接：
  
  打开“代码库”页面
- REPOSITORY_NAME：代码库的名称。此值必须与您在设置 Cloud Build 连接时输入的值完全相同。
- TAG：仓库的 Git 标记。格式必须是包含主要版本号、次要版本号和补丁号的完整语义版本。例如，v1.0.0 是有效的标记，而 v1 或 v1.0 是无效的标记。
- CONFIG_FILE_PATH：仓库中 Kubernetes 资源的路径。如果文件位于仓库的根目录中，您可以省略此字段。
- MAX_CLUSTERS：一次部署 Kubernetes 资源的集群数量上限。例如，如果您将此值设置为 1，则资源包一次只会部署到一个集群。
  
  如需查看您可以配置的所有字段的完整列表，请参阅 FleetPackage 参考文档。

创建舰队软件包：

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

将 FLEET_PACKAGE_NAME 替换为舰队软件包发布的名称。

验证是否已创建舰队软件包：
```
gcloud container fleet packages list
```
输出将列出构建触发器的状态。几秒钟后，MESSAGE 字段会更新，输出类似于以下内容：
```
MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
```
您可以点击所提供的链接以查看 Cloud Build 作业的流式日志。Cloud Build 可能需要几分钟时间来处理构建触发器。

如果构建触发器成功，舰队软件包会开始在舰队中发布 Kubernetes 资源。

当构建触发器成功完成时，gcloud container fleet packages list 的输出类似于以下内容：

NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621

舰队软件包开始在舰队中发布 Kubernetes 资源。

现在，您已部署舰队软件包，当您向舰队添加新集群时，舰队软件包中定义的 Kubernetes 资源会自动部署到新集群。

更新舰队软件包

您可以更新舰队软件包，以更改设置或更改舰队软件包部署的资源，如以下示例所示：

通过更改 maxConcurrent 字段的值来更改发布策略。
通过设置 state: SUSPENDED 暂停舰队软件包。当舰队软件包被暂停时，任何正在进行的发布都会继续。在您将状态更改回 ACTIVE 之前，系统不会创建或安排任何新的发布。
通过更新 tag 字段以从其他 Git 标记进行拉取，从而更新舰队软件包部署的 Kubernetes 资源。

如需更新舰队软件包，请完成以下步骤：

使用您的更改更新 FleetPackage 规范。

更新舰队软件包：

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

系统可能需要几分钟时间才能获取更改并开始向集群发布。

管理舰队软件包发布

您可以监控舰队软件包部署的进度并管理有效发布。当舰队软件包更改时，系统会自动创建新的发布。以下命令可帮助您获取有关发布的详细信息。例如，如果您需要调试部署问题，可以检查发布详细信息，并根据需要暂停或取消发布。

列出发布可让您查看与软件包关联的所有发布的状态，包括可能导致发布失败的错误。如需列出发布并查看其状态，请运行以下命令：

gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME

输出将类似以下内容：

ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED

描述发布可为您提供有关特定发布的详细信息，包括每个目标集群的状态和任何特定于集群的错误。如需描述发布，请运行以下命令：

gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

将 ROLLOUT_NAME 替换为发布的名称。您可以从上一步中的 list 命令获取完整的发布名称。

输出将类似以下内容：

CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists

您可以通过运行以下命令来管理有效发布：
- 暂停发布会将正在进行的发布置于 SUSPENDED 状态。所有正在进行的软件包更新都会继续，并且不会安排进一步的软件包更新。如需暂停发布，请运行以下命令：
```
gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- 恢复发布更改会将 SUSPENDED 发布更改回 IN_PROGRESS 状态。软件包更新会按计划部署到目标集群。如需恢复发布，请运行以下命令：
```
gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- 取消正在进行的发布作业会立即终止发布，并将其置于 ABORTED 状态。所有计划作为发布一部分的待处理软件包更新都会被取消。如需取消发布，请运行以下命令：
```
gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```

使用标签部署到不同集群

标签是附加到对象的键值对。舰队软件包仅支持舰队成员资格标签。不支持 GKE 集群标签。

您可以使用标签将舰队软件包部署到舰队中的部分集群。

添加成员资格标签

如需添加成员资格标签，请完成以下步骤：

获取舰队中的成员资格列表：

gcloud container fleet memberships list

为成员资格添加标签：
```
gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE
```
替换以下内容：
- MEMBERSHIP_NAME：已注册到舰队的集群的名称。
- KEY 和 VALUE：要添加到成员资格的标签。如果标签已存在，则系统会修改其值。否则，系统会创建新标签。键必须以小写字符开头，并且只能包含连字符 (-)、下划线 (_)、小写字符和数字。值只能包含连字符 (-)、下划线 (_)、小写字符和数字。
针对要为其添加标签的每个成员资格重复执行此命令。

部署到部分集群

您可以通过使用键值对指定 target.fleet.selector.matchLabels 字段来部署到部分集群。例如，如果您将 matchLabels 设置为 country: "us"，则舰队软件包服务仅会将资源部署到标签 country 与 "us" 匹配的集群。

如需将舰队软件包部署到部分集群，请完成以下步骤：

使用标签选择器创建或更新 FleetPackage 规范：

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
    selector:
      matchLabels:
        KEY: "VALUE"
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS

创建或更新舰队软件包：

创建舰队软件包

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

更新舰队软件包

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

将变体资源部署到集群

变体是资源的不同版本。这些资源的值可能会因集群的位置、项目或名称而不同。您可以通过指定 variantsPattern 和 variantNameTemplate 字段，将变体资源部署到不同的集群。

您可以使用成员资格标签或其他成员资格元数据（例如位置、项目或名称）来匹配变体。

如需部署包含变体的舰队软件包，请完成以下步骤：

使用变体详细信息创建或更新 FleetPackage 规范：

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    variantsPattern: VARIANT_PATTERN
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
target:
  fleet:
    project: projects/PROJECT_ID
 variantSelector:
  variantNameTemplate: VARIANT_NAME_TEMPLATE

替换以下内容：

VARIANT_PATTERN：变体的模式，例如 "variants/*.yaml" 或 "us-*"。
VARIANT_NAME_TEMPLATE ：一个模板字符串，指的是包含集群成员资格元数据（如位置、项目、名称或标签）的变量，用于确定目标集群变体的名称。如需查看更多示例，请参阅 FleetPackage 参考文档。

创建或更新舰队软件包：

创建舰队软件包

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

更新舰队软件包

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

删除舰队软件包

删除舰队软件包还会删除以下资源：

集群上部署的 Kubernetes 资源
舰队软件包发布历史记录

如需删除舰队软件包，请运行以下命令：

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

问题排查

如需查找诊断和解决与 Cloud Build 相关的错误的方法，请参阅排查构建错误。

后续步骤

请参阅 FleetPackage 字段参考页面

部署舰队软件包 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

查看集群要求

准备环境

安装 Config Sync

控制台

gcloud

为 Cloud Build 创建服务账号

创建舰队软件包

更新舰队软件包

管理舰队软件包发布

使用标签部署到不同集群

添加成员资格标签

部署到部分集群

创建舰队软件包

更新舰队软件包

将变体资源部署到集群

创建舰队软件包

更新舰队软件包

删除舰队软件包

问题排查

后续步骤

部署舰队软件包