舰队软件包简介

本页面介绍了舰队软件包、FleetPackage API 以及它们与 Config Sync 的关系。

FleetPackage 是一种声明性 API，可让您管理整个舰队中的软件包。舰队软件包是一组用于定义集群配置的 Kubernetes YAML 清单。通过使用舰队软件包，您可以一次性或逐步向注册到舰队的集群部署软件包。

对于每个 FleetPackage 对象，您只需定义一次，之后便可使用新修订版本更新相应软件包。应用新修订版本时，舰队软件包服务会获取这些更改并将其部署到您的集群。

优势

使用舰队软件包向注册到舰队的所有集群部署 Kubernetes 资源。创建并应用舰队软件包后，该软件包会自动将 Git 代码库中的 Kubernetes 配置文件部署到新集群。舰队软件包基于 Config Sync 构建，除了 Config Sync 的优势（例如自动漂移校正）之外，还提供以下独特优势：

• 自动发布资源：设置舰队软件包后，舰队软件包服务会自动在所有集群上部署该软件包指向的 Kubernetes 资源。

• 自动配置新集群：如果您配置了舰队软件包，之后向舰队添加新集群，则舰队软件包定义的任何资源都会自动部署到该新集群。

• 大规模管理 Kubernetes 配置：使用舰队软件包将资源部署到整个集群舰队，而无需逐个管理集群。

• 最大限度降低错误更改造成的影响：选择一次性为尽可能多的集群部署资源。您可以密切监控每个集群的更改，确保错误的更改不会影响整个舰队。

• 简化 Config Sync 配置：舰队软件包使用 Cloud Build 向 Git 进行身份验证，这意味着您只需为每个项目进行一次身份验证，而无需为每个 RootSync 或 RepoSync 对象进行一次身份验证。

如果您的应用场景符合以下一项或多项描述，则您可能会更倾向于将 Config Sync 与 RootSync 或 RepoSync 对象搭配使用，而不是使用舰队软件包：

• 您管理的集群数量较少。

• 您需要对资源部署到集群的方式进行更精细的控制，而舰队软件包 API 通过标签和变体提供的控制功能无法满足您的需求。

要求和限制

• 配置舰队软件包时，仅支持将 Git 代码库作为可信来源。

• 存储在 Git 中的 Kubernetes 资源必须代表资源的最终状态。不支持用于转换存储在 Git 中的资源的其他叠加层。如需详细了解这些资源之间的差异，请参阅最佳实践：创建 WET 代码库。

• FleetPackage API 仅在 us-central1 区域提供。您仍然可以部署到其他区域中的集群，但必须在 us-central1 中设置 Cloud Build 并配置 gcloud CLI。

• 每个项目每个区域的舰队软件包数量上限为 300 个。

架构

您可以使用 FleetPackage API 将 Kubernetes 清单部署到集群舰队。FleetPackage API 使用 Cloud Build 从 Git 代码库同步和提取 Kubernetes 资源。然后，舰队软件包服务会将这些资源部署到您的集群。

变体的生成方式

舰队软件包使用变体系统，以便将不同的 Kubernetes 资源配置部署到舰队中的不同集群或集群组，但这些配置来自同一 Git 代码库。

FleetPackage 规范中有两个字段用于控制变体的行为：

1. resourceBundleSelector.cloudBuildRepository.variantsPattern：用于在 Git 代码库中查找文件和目录的 glob 模式（在指定的 path 下，如果省略 path，则在代码库根目录下）。此模式决定哪些文件或目录成为变体以及它们包含哪些内容。
2. variantSelector.variantNameTemplate：一个表达式，用于将舰队中的每个集群映射到 variantsPattern 生成的变体名称之一。此选择基于集群的舰队成员资格元数据。

variantsPattern 匹配

您 必须 指定 variantsPattern 字段，以说明如何从存储在代码库中的配置生成变体。匹配使用以下逻辑：

• 文件匹配 ：如果模式与 YAML 文件匹配，则会创建一个变体。

  • 变体名称： 不带扩展名的文件名（例如， prod-config.yaml 变为变体 prod-config）。
  • 变体内容 ：此单个文件的内容。

• 目录匹配 ：如果模式与目录匹配，则会创建一个变体。

  • 变体名称 ：目录名称（例如，目录 dev 变为变体 dev）。
  • 变体内容 ：在此目录及其所有子目录中递归找到的所有 YAML 文件的组合。

文件匹配模式具有以下限制：

• 没有递归（双）通配符。不支持 ** 模式。
• 如果模式包含点 (.) 字符，则后面必须跟一个字母数字字符。
• 模式不能包含单引号 (')。
• 变体名称必须是唯一的。如果您的模式与多个同名文件（例如 app1/deploy.yaml 和 app2/deploy.yaml）匹配，则两者都会尝试创建一个名为 deploy 的变体，从而导致名称冲突。

例如，假设有一个具有以下结构的代码库：

repo-root/
└── FleetPackages/
    └── clusters/
        ├── common-ingress.yaml
        ├── us-central1-a/
        │   ├── gke-1/
        │   │   ├── deployment.yaml
        │   │   └── service.yaml
        │   └── gke-2/
        │       ├── deployment.yaml
        │       └── service.yaml
        └── us-central1-b/
            ├── gke-1.yaml
            └── blue-green.yaml

您可以根据在舰队软件包规范中定义的文件或目录匹配类型，匹配不同的文件并将其同步到集群，例如：

• variantsPattern: "*"：与 common-ingress.yaml、us-central1-a 和 us-central1-b 匹配。生成变体：

  • common-ingress（来自文件）
  • us-central1-a（合并该文件夹中的所有 YAML 文件）
  • us-central1-b（合并该文件夹中的所有 YAML 文件）

• variantsPattern: "*.yaml"：与 common-ingress.yaml 匹配。生成变体：

  • common-ingress

• variantsPattern: "us-*"：与 us-central1-a 和 us-central1-b 匹配。 生成变体：

  • us-central1-a
  • us-central1-b

• variantsPattern: "us-central1-b/*.yaml"：与 us-central1-b/gke-1.yaml 和 us-central1-b/blue-green.yaml 匹配。生成变体：

  • gke-1
  • blue-green

variantNameTemplate 匹配

定义变体后，variantSelector 部分中的 variantNameTemplate 字段会确定将哪个变体应用于每个集群。 该模板可以使用变量来访问以下舰队成员资格元数据：

• ${membership.name}：集群的舰队成员资格名称。
• ${membership.location}：舰队成员资格位置。
• ${membership.project}：舰队成员资格项目。
• ${membership.labels['KEY']}：舰队成员资格上标签 KEY 的值。

例如，假设以下场景使用标签来匹配变体：

• variantNameTemplate: "${membership.labels['env']}"：带有 标签 env: prod 的集群会同步到名为 prod 的变体。
• variantNameTemplate: "${membership.location}"：集群会同步到 与其位置匹配的变体（例如 us-central1-a）。
• variantNameTemplate: "default"：集群会同步到名为 default的变体。如果省略 variantSelector，这是默认行为。如果您的代码库不包含名为 default.yaml 的文件或名为 default 的目录，则不会同步任何内容。

组合使用 variantsPattern 和 variantNameTemplate

如需成功部署，您必须确保 variantsPattern 生成的变体名称是集群可以通过匹配 variantNameTemplate 同步到的名称。

例如，如需根据环境标签部署到集群，您可以将 Git 代码库的结构设置为包含 dev、staging 和 prod 等目录。然后，您可以使用以下舰队软件包规范：

resourceBundleSelector:
  cloudBuildRepository:
    # ... other fields
    path: "manifests"
    variantsPattern: "*" # Matches dev, staging, prod directories
variantSelector:
  variantNameTemplate: "${membership.labels['env']}"

使用此配置，带有标签 env: staging 的集群会接收 manifests/staging/ 目录的内容。

部署策略

您可以使用舰队软件包将资源从 Git 代码库部署到整个集群舰队。您还可以配置舰队软件包，以控制部署资源的方式、位置和类型。

以下部分展示了不同的 FleetPackage 配置示例。如需详细了解如何应用舰队软件包，请参阅部署舰队软件包。

部署到舰队中的所有集群

以下 FleetPackage 使用滚动策略一次性将 Kubernetes 资源部署到三个集群，并且后续会部署到舰队中的所有集群：

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3
variantSelector:
  variantNameTemplate: deployment # matches a file named deployment.yaml

部署到部分集群

以下 FleetPackage 使用标签选择器将 Kubernetes 资源 仅部署到舰队中成员资格标签 country 与 "us" 匹配的集群：

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

后续步骤

部署舰队软件包