4. ApplicationSet 基础：控制器原理与 Generators 类型概览

在 Argo CD 多环境与多租户场景中，手动为每个环境或每个租户创建独立的 Application 对象会带来巨大的维护负担。ApplicationSet 控制器正是为解决这一规模化问题而设计的——它通过模板与生成器（Generators）的组合，实现 Application 对象的批量声明式管理。

4.1 ApplicationSet 控制器原理

ApplicationSet 是 Argo CD 的一个子控制器，它监听一个名为 ApplicationSet 的自定义资源（CRD）。其核心工作流程分为三个步骤：

1. 生成参数集：控制器根据 ApplicationSet 中定义的 Generators 生成一组键值对参数（例如：cluster、env、team）。
2. 渲染模板：将生成的参数注入到 ApplicationSet 的 template 字段中，渲染出完整的 Application 对象定义。
3. 同步与调和：控制器将渲染后的 Application 对象提交到 Argo CD，并持续调和，确保实际 Application 状态与 ApplicationSet 定义一致。

4.2 Generators 类型概览

Generators 是 ApplicationSet 的核心扩展点，决定了如何生成参数集。Argo CD 内置了多种 Generator 类型，覆盖从简单列表到复杂 Git 仓库的多种场景。

4.3 核心 Generator 详解

4.3.1 List Generator

List Generator 是最简单的生成器，直接在 ApplicationSet 定义中内联一个元素列表。每个元素会生成一组参数，用于渲染模板。

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook-list
spec:
  generators:
  - list:
      elements:
        - cluster: dev
          url: https://kubernetes.default.svc
        - cluster: staging
          url: https://staging-cluster.example.com
        - cluster: prod
          url: https://prod-cluster.example.com
  template:
    metadata:
      name: '{{cluster}}-guestbook'
    spec:
      project: default
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps.git
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{url}}'
        namespace: guestbook

4.3.2 Cluster Generator

Cluster Generator 自动读取 Argo CD 中注册的所有集群（通过 argocd cluster add 或集群 Secret），并为每个集群生成一个 Application。它支持通过 selector 字段按标签过滤集群。

spec:
  generators:
  - clusters:
      selector:
        matchLabels:
          environment: production
  template:
    metadata:
      name: '{{name}}-app'  # name 来自集群 Secret 的 label
    spec:
      source:
        repoURL: https://github.com/example/app.git
        targetRevision: HEAD
        path: '{{name}}'    # 按集群名选择目录
      destination:
        server: '{{server}}'
        namespace: app

4.3.3 Git Generator

Git Generator 是 GitOps 场景中最灵活的生成器。它扫描 Git 仓库中的目录或文件，根据目录结构或文件内容生成参数。有两种模式：

• 目录模式（Directories）：为仓库中的每个子目录生成一个 Application。
• 文件模式（Files）：读取指定路径下的 JSON/YAML 文件，将文件内容作为参数。

spec:
  generators:
  - git:
      repoURL: https://github.com/example/environments.git
      revision: HEAD
      directories:
      - path: 'environments/*'   # 匹配 environments/ 下的所有子目录
  template:
    metadata:
      name: '{{path.basename}}-app'
    spec:
      source:
        repoURL: https://github.com/example/app.git
        targetRevision: HEAD
        path: '{{path.basename}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{path.basename}}'

4.4 高级 Generator：Matrix 与 Merge

当单一 Generator 无法满足复杂映射关系时，可以使用 Matrix 和 Merge 生成器组合多个 Generator 的输出。

# Matrix 示例：集群 × 环境
spec:
  generators:
  - matrix:
      generators:
        - clusters: {}                    # 生成所有集群
        - list:
            elements:
              - env: dev
              - env: prod
  # 结果：每个集群 × 每个环境 = N*2 个 Application

# Merge 示例：基础配置 + 环境覆盖
spec:
  generators:
  - merge:
      generators:
        - list:
            elements:
              - env: dev
                replicas: 1
                image: nginx:latest
              - env: prod
                replicas: 3
                image: nginx:stable
        - list:
            elements:
              - env: prod
                image: nginx:1.25  # 覆盖 prod 的镜像版本
  # 结果：dev 使用默认值，prod 使用覆盖后的镜像版本

4.5 Generator 选择决策树

在实际项目中，选择合适的 Generator 可以大幅降低维护成本。以下决策树可以帮助快速判断：

• 环境数量少且固定 → List Generator
• 需要自动发现集群 → Cluster Generator（配合标签选择器）
• 环境配置存储在 Git 目录中 → Git Generator（目录模式）
• 需要从 Git 文件读取动态参数 → Git Generator（文件模式）
• 需要为每个 PR 创建预览环境 → Pull Request Generator
• 需要多维度组合（如集群 × 环境） → Matrix Generator
• 需要分层配置覆盖 → Merge Generator