本页面介绍了如何在 Google Distributed Cloud connected 环境中使用 Config Sync 舰队软件包。舰队软件包是一种工具，它使用 Git 代码库作为集群配置的单一可信来源。
Distributed Cloud connected 中的舰队软件包与标准 Google Kubernetes Engine 集群使用相同的底层技术和命令。GKE 文档的 部署舰队软件包页面介绍了如何创建和管理舰队 软件包。 本页面介绍了如何针对您的 Distributed Cloud connected 环境调整该指南。
以下部分介绍了您需要针对 Distributed Cloud connected 执行哪些不同的操作，以及您可以直接按照 GKE 文档中的哪些步骤操作。
要求
在 Distributed Cloud connected 中使用 Config Sync 舰队软件包有以下要求：
- 由于发布控制器位于云端，因此您的 Git 代码库必须可通过公共互联网访问。不支持未公开的内部或本地 Git 服务器。
- Distributed Cloud connected 仅支持使用舰队 工作负载身份联合来向 Google Cloud 服务进行身份验证。您的集群与版本化软件包代码库之间的连接不支持其他 Config Sync 身份验证方法，例如 SSH 密钥或 Cookie。如需了解详情，请参阅 Workload Identity 集群身份验证。
- 舰队中的所有集群都必须位于同一项目中。 Distributed Cloud connected 不支持将多个项目中的集群注册到单个中央项目以进行舰队管理。
- 您的 Kubernetes 清单必须符合 Distributed Cloud connected 工作负载限制。 违反这些限制的清单会被集群准入控制器屏蔽。
- 舰队软件包需要 Config Sync 1.16.0 或更高版本。
系统行为
Distributed Cloud connected 中的舰队软件包具有以下行为：
- 舰队软件包会将您的 Kubernetes 清单转换为版本化的 OCI 映像。这些映像存储在名为
fleet-packages的受管 Artifact Registry 代码库中，该代码库会在您的项目中自动创建。您的集群会直接从该代码库拉取这些映像，以确保交付的一致性和可靠性。 - 舰队软件包继承了 Config Sync 的漂移校正行为。对集群上的资源所做的手动更改会自动被覆盖，以与版本化的 OCI 软件包保持一致。
- 如果 Distributed Cloud connected 集群进入 生存模式， Config Sync 代理会继续在本地强制执行上次成功同步的 配置。但是，任何新的发布或对舰队软件包的更新都会暂停，直到云连接恢复为止。
- 舰队软件包继承了 Config Sync 的自动资源剪除行为。当您在 Git 代码库中创建新标记并使用新标记更新舰队软件包配置以启动同步时，如果您从 Git 代码库中移除清单，Config Sync 代理会从集群中删除相应的资源。
- 如果多个舰队软件包管理同一资源，则会发生所有权冲突。如果您尝试删除处于所有权冲突状态的舰队软件包，删除操作可能会停滞。如需解决此问题，请修改其中一个冲突的舰队软件包，以移除冲突的资源，然后再尝试删除该软件包。
Distributed Cloud connected 前提条件
在按照 部署舰队软件包中的步骤操作之前， 请确保您的 Distributed Cloud connected 环境和用户 权限已正确配置。
网络和安全
您的网络环境必须满足以下要求：
- VPC Service Controls 。如果您的项目受到 VPC 服务边界的保护，请确保您的 Cloud Build 和 Config Delivery 服务代理（例如
service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.com）已获授权跨越边界并从 Artifact Registry 拉取映像。 如需了解详情，请参阅 配置 VPC Service Controls 集成。 - 出站流量访问权限 。您的 Distributed Cloud connected 集群必须具有对
us-central1-docker.pkg.dev的出站流量访问权限。舰队软件包会将您的清单软件包存储为 Artifact Registry 中的 OCI 映像。集群必须能够直接从 Artifact Registry 拉取这些映像。
代码库设置
包含清单软件包的 Artifact Registry 代码库必须与舰队软件包位于同一项目中，并且必须位于 us-central1 中。
所需权限
如需完成 Distributed Cloud connected 环境中的步骤，您必须对项目拥有以下 IAM 角色：
- Config Delivery 管理员 (
roles/configdelivery.admin)：创建和管理舰队软件包及发布时需要此角色 - Developer Connect 管理员 (
roles/developerconnect.admin)：创建和管理代码库连接时需要此角色 - Project IAM 管理员 (
roles/resourcemanager.projectIamAdmin)：向服务帐号授予必要角色时需要此角色
如需详细了解如何授予角色，请参阅 授予、更改和撤消对资源的访问权限。
必需的 API
您需要为代码库连接启用 API，并与 Distributed Cloud connected 集群进行安全通信。如需启用必需的 API，请运行
以下
gcloud services enable
命令：
gcloud services enable anthosconfigmanagement.googleapis.com \
configdelivery.googleapis.com \
cloudbuild.googleapis.com \
connectgateway.googleapis.com \
developerconnect.googleapis.com \
artifactregistry.googleapis.com
以下组件需要这些 API：
anthosconfigmanagement.googleapis.com：管理集群上的 Config Sync 代理configdelivery.googleapis.com：协调在集群舰队中发布 Kubernetes 资源cloudbuild.googleapis.com：从 Git 中提取 Kubernetes 清单并将其打包到版本化的软件包中connectgateway.googleapis.com：在 Config Delivery 服务与 Distributed Cloud connected 集群之间提供安全连接developerconnect.googleapis.com：支持与外部 Git 代码库主机建立安全连接artifactregistry.googleapis.com：将版本化的软件包存储为项目中的 OCI 映像
默认环境设置
舰队软件包的 Config Delivery API 仅在 us-central1 中受支持。如需确保命令正确路由，请使用
gcloud config set命令设置您的
默认项目和位置：
设置默认项目：
gcloud config set project PROJECT_ID
将
PROJECT_ID替换为您的 Google Cloud 项目 ID。设置舰队软件包的默认位置。与舰队软件包搭配使用的所有 Cloud Build 代码库连接都必须位于
us-central1区域中。gcloud config set config_delivery/location us-central1
过程差异
请参阅下表，了解如何将 部署舰队软件包 中的步骤应用于您的 Distributed Cloud connected 环境。
| 标准步骤 | Distributed Cloud connected 调整 |
|---|---|
| 将集群注册到舰队 | 跳过此步骤。Distributed Cloud connected 集群在创建时会自动 注册到项目中的舰队。 |
| 安装 Config Sync | 按照标准步骤操作，但我们建议使用
在整个舰队中安装（舰队默认） 方法。在控制台的 Google Cloud **中心** 或**舰队** 设置中配置此
方法。
此实现可确保您可用区中的任何现有或未来的
Distributed Cloud connected 节点都会自动
接收 Config Sync 代理。 对于身份验证成员类型，您必须选择 Workload Identity。 您用于 Workload Identity 的服务账号必须 对项目拥有 roles/artifactregistry.reader 角色，以便 Config Sync 代理可以从
受管 fleet-packages 代码库拉取清单软件包。 |
| 创建服务账号 | 按照说明为 Cloud Build 创建服务帐号并授予所需的权限。服务账号必须与舰队软件包位于同一项目中。我们建议您使用以下命令：
|
| 确定成员资格名称 | 当命令要求提供 MEMBERSHIP_NAME 时，请使用 Distributed Cloud connected 集群的名称。您可以通过运行 gcloud container fleet memberships list 命令找到集群名称。 |
| 确定集群 | 在您使用舰队软件包定位集群之前，如果您的工作负载
需要主机级网络配置（例如 HugePages 或 SR-IOV），
请在集群中的每个节点上应用并验证
NodeSystemConfigUpdate
资源。
|
| 确定 Git 标记 | 发布控制器要求 Git 标记采用完整的语义
版本格式 (major.minor.patch)。例如，v1.0.0 是有效的，而 v1 无效。 |
| 定位特定集群 | 虽然集群会自动注册，但如果您想使用标签选择器定位集群子集，则必须 手动向集群成员资格添加标签 。 |
| 部署策略 | 使用标签和变体定位特定集群。对于
Distributed Cloud connected，变体模板中使用的成员资格元数据变量（
例如项目和位置）是指与
Distributed Cloud
connected 集群关联的云端资源。 以下 Distributed Cloud 特有的成员资格元数据可在 变体模板中使用：
|
共享过程
对于以下操作任务，Distributed Cloud connected 和标准 GKE 的命令语法和服务行为是相同的。按照这些说明操作时，请使用本文档 过程差异部分中的表格中定义的设置和 值。
- 创建舰队软件包：
定义
FleetPackage资源以提取和部署配置。 - 更新舰队软件包： 修改软件包以发布更改或更新设置。
- 管理舰队软件包发布： 暂停、恢复或中止活跃发布。
- 检查资源软件包和发布:
调试变体生成和版本控制。资源软件包是配置的容器，而发布是这些软件包的版本化实例。如需验证是否已成功交付到您的
Distributed Cloud connected 硬件，请使用
gcloud container fleet memberships get-credentials命令 获取对集群的访问权限， 然后使用kubectl检查集群上的RootSync状态。 - 删除舰队软件包:
移除舰队软件包及其受管资源。为确保彻底移除，请验证与舰队软件包关联的受管
RootSync对象是否已从集群中移除。
监控和问题排查
如需更有效地监控部署，请将 --format 标志与 gcloud 命令搭配使用，以便在发布期间获取详细的状态消息。
例如，运行以下
gcloud container fleet packages rollouts describe
命令，以查看舰队中每个集群的详细状态消息：
gcloud container fleet packages rollouts describe ROLLOUT_NAME \
--fleet-package=FLEET_PACKAGE_NAME \
--format=json
替换以下值：
ROLLOUT_NAME：发布的名称。FLEET_PACKAGE_NAME：舰队软件包的名称。
如果 build 失败或停滞，您可以在流式日志
中找到指向 Cloud Build 作业的链接，该日志位于
gcloud container fleet packages list
命令的输出中。如果发布仍处于 PENDING 或 STALLED 状态，请检查您的
Distributed Cloud connected 硬件连接，如
排查 Distributed Cloud connected中所述。
如需详细了解如何诊断与 Cloud Build 相关的错误，请参阅 排查 build 错误。
验证集群内同步状态
如需验证集群是否已成功与舰队软件包同步，请检查集群上的 RootSync 资源。集群上的 RootSync 对象的名称与您为软件包选择的 FLEET_PACKAGE_NAME 相同。
如需检查状态，请运行以下命令：
kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system
成功同步会显示 SYNCED 状态。如果您看到 Error 状态，如需了解更多详细信息，请运行以下命令：
kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system
如需了解详情，请参阅 GKE 文档中的监控 RootSync 和 RepoSync 对象 。
如需帮助解码输出中的特定错误代码，请参阅 Config Sync 错误参考。