Argo CD ApplicationSet怎么用：多集群GitOps应用分发实践

本文定位：面向已经使用 Argo CD 管理应用、正在把发布范围扩展到多环境或多集群的平台工程团队。

Argo CD ApplicationSet 的价值，是用一套生成规则批量创建和维护多个 Argo CD Application，而不是让团队为每个集群、每个环境手工复制一份配置。它适合多集群 GitOps 应用分发，但前提是你已经想清楚仓库结构、集群标签、环境差异和回滚边界。

在多集群场景里，真正难的不是写出第一个 ApplicationSet，而是避免“生成很多 Application 后没人能解释”。本文不把它写成 YAML 片段堆砌，而是从分发模型、生成器选择、仓库组织、校验和回退路径来讲。

图1：Argo CD ApplicationSet 多集群分发

ApplicationSet 适合解决什么问题

Argo CD 的 Application 描述一个应用从 Git 仓库同步到目标集群和命名空间的关系。ApplicationSet 则用于根据模板和生成器批量生成多个 Application。Argo CD 官方文档将 ApplicationSet 作为 Argo CD 的控制器能力之一，具体对象和字段应以 ApplicationSet 官方文档为准[2]。

它通常适合这些问题：

• 同一个应用要分发到多个集群。
• 同一套平台组件要按环境、区域或租户生成多份 Application。
• 团队希望通过 Git 中的目录、列表或集群标签驱动分发范围。
• 运维不希望手工复制 Application 后再逐个维护差异。
• 发布流程需要把“分发到哪里”变成可审查的配置变更。

它不适合替代发布设计。如果团队还没有明确环境命名、仓库目录、集群标签和权限边界，ApplicationSet 只会把混乱批量化。

先设计分发模型，再选择生成器

ApplicationSet 的生成器很多，常见包括 List、Cluster、Git、Matrix、Merge 等。不同生成器对应不同分发模型，官方生成器说明可作为选择依据[3]。

生成器选择要反映组织边界

如果你的组织边界是“每个业务团队维护自己的应用目录”，Git 生成器往往更自然；如果边界是“平台团队统一把基础组件装到所有生产集群”，Cluster 生成器更适合；如果只是少量固定环境，List 生成器反而更清晰。

不要因为 Matrix 强大就优先使用 Matrix。它很适合表达组合关系，但也容易把 5 个应用、6 个集群、3 个环境组合成难以审查的 90 个 Application。只有当组合关系是业务真实需求，并且有明确排除规则时，才适合使用。

一种可维护的仓库结构

多集群 GitOps 应用分发的仓库结构，应让读者能从路径判断应用、环境、集群和差异来源。不要把所有环境差异都塞进一个巨大的 values 文件，也不要把每个集群都复制一份完整目录。

推荐从三类目录开始：

1. 应用基线目录：保存通用 Helm values、Kustomize base 或原始 manifests。
2. 环境覆盖目录：表达 dev、staging、prod 等环境差异。
3. 集群绑定目录：表达应用要分发到哪些集群，以及目标命名空间、项目和同步策略。

例如，一个团队可以使用这样的逻辑结构：

apps/
  payment-api/
    base/
    overlays/
      dev/
      prod/
platform/
  ingress-controller/
  observability-agent/
clusters/
  cn-prod-01/
    apps.yaml
  cn-prod-02/
    apps.yaml
applicationsets/
  platform-components.yaml
  business-apps.yaml

这只是组织方式示例，不代表唯一最佳结构。更重要的是：路径语义要稳定，差异层级要可解释，权限边界要能落到仓库审查流程。

图2：GitOps 仓库结构与 ApplicationSet

ApplicationSet 配置要关注 4 个边界

写 ApplicationSet 时，平台团队最容易关注模板是否能生成 Application，却忽略治理边界。Application 会定义 source、destination、project、syncPolicy 等关键配置[4]，这些字段直接影响分发范围和同步行为。

建议重点检查：

• 目标边界：destination 的集群和命名空间是否来自可信集群标签或明确列表。
• 项目边界：project 是否限制了允许的仓库、目标集群和命名空间。
• 同步边界：自动同步、自动修剪和自愈策略是否适合当前环境。
• 差异边界：哪些值允许按环境覆盖，哪些值必须保持全局一致。

示例：用 List 生成少量环境 Application

下面示例只用于说明结构，不建议直接复制到生产。实际字段和版本差异应以 Argo CD 官方文档为准[1]。

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: payment-api-envs
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: dev
            cluster: https://kubernetes.default.svc
            namespace: payment-dev
          - env: prod
            cluster: https://kubernetes.default.svc
            namespace: payment-prod
  template:
    metadata:
      name: 'payment-api-{{env}}'
    spec:
      project: payment
      source:
        repoURL: https://github.com/example/platform-gitops.git
        targetRevision: main
        path: apps/payment-api/overlays/{{env}}
      destination:
        server: '{{cluster}}'
        namespace: '{{namespace}}'
      syncPolicy:
        automated:
          prune: false
          selfHeal: true

这个例子有意把 `prune` 设为 `false`，不是因为生产环境都应如此，而是提醒团队：自动修剪会删除 Git 中不再声明的资源，使用前必须明确删除策略、审查流程和回退方式。

从单集群扩展到多集群的步骤

ApplicationSet 的落地顺序，建议从小范围、低风险、强可观测开始。

可以按 5 步推进：

1. 梳理现有 Application。先找出重复配置、环境差异、手工修改和命名不一致问题。
2. 定义集群标签体系。例如 region、env、tier、owner、network-zone，不要让标签随意增长。
3. 选择一个低风险组件试点。优先选择配置稳定、回滚简单、跨集群一致性强的组件。
4. 把生成结果纳入审查。每次变更前确认会新增、修改或删除哪些 Application。
5. 建立回退路径。保留原 Application 或保留可回退的 Git commit，避免分发失败后无法快速恢复。

图3：ApplicationSet 多集群发布校验与回退路线图

多集群场景要特别防止误分发

误分发通常不是 ApplicationSet 本身的问题，而是分发条件过宽。例如，Cluster 生成器基于标签选择目标集群，如果新集群注册时继承了错误标签，就可能被自动纳入发布范围。

上线前建议增加三类检查：

• 生成结果检查：确认即将生成的 Application 数量和目标集群符合预期。
• 权限检查：确认 AppProject 限制了允许的仓库、目标集群和命名空间。
• 同步策略检查：确认自动同步、修剪和自愈策略与环境风险匹配。

如果团队已经采用 GitOps 作为平台交付主路径，可以把 ApplicationSet 作为多集群分发能力的上层抽象，而不是让每个业务团队直接维护复杂模板。

常见反模式：配置能生成，但不可治理

ApplicationSet 的反模式通常不是语法错误，而是治理失控。

可治理性优先于模板技巧

一个可治理的 ApplicationSet，应该让评审者回答三个问题：这次会影响哪些集群？哪些应用会被修改？失败后怎么回退？如果评审者只能看到一段复杂模板，却看不出影响范围，那么模板技巧已经超过了团队治理能力。

小结

Argo CD ApplicationSet 适合把多集群 GitOps 应用分发从手工复制升级为规则生成。它的关键不在“能生成多少 Application”，而在生成规则是否可审查、集群选择是否可解释、环境差异是否可维护、失败后是否能回退。

落地时建议先从低风险组件试点，明确仓库结构和集群标签，再逐步扩大到业务应用。对平台团队来说，ApplicationSet 是分发治理工具，不是绕过发布审查的快捷方式。

参考资料

• [1] Argo CD Documentation
• [2] Argo CD ApplicationSet
• [3] Argo CD ApplicationSet Generators
• [4] Argo CD Application Specification

常见问题

1. Argo CD ApplicationSet 和 Application 有什么区别？

Application 描述一个应用同步关系，ApplicationSet 用模板和生成器批量生成多个 Application。简单场景下直接写 Application 更清晰；当你需要跨多个集群、环境、租户或目录批量分发时，ApplicationSet 才能减少重复配置并提升一致性。

2. 多集群 GitOps 一定要使用 ApplicationSet 吗？

不一定。如果只有少量集群和少量应用，手工维护 Application 也可以接受。ApplicationSet 更适合目标数量增长后仍希望保持规则化分发的团队。判断标准不是集群数量本身，而是重复配置、环境漂移和审查成本是否已经影响发布效率。

3. ApplicationSet 的自动同步安全吗？

自动同步本身不是不安全，风险来自同步范围、权限边界和删除策略不清。生产环境可以按应用等级分层：低风险组件启用自动同步，高风险业务先保留人工确认；自动修剪和自愈策略需要结合审查、告警和回退机制使用。

4. Git 生成器和 Cluster 生成器应该怎么选？

如果分发范围由仓库目录决定，例如每个应用目录声明自己要部署到哪里，Git 生成器更自然。如果分发范围由集群属性决定，例如所有 prod 集群都安装同一组平台组件，Cluster 生成器更清晰。复杂场景可以组合，但要避免组合结果不可审查。