ArgoCD App of Apps 模式详解

App of Apps（应用之应用） 是 ArgoCD 实现大规模 GitOps 管理 的核心模式，其本质是用一个"根 Application"作为入口，批量管理集群内所有子 Application（包括业务应用、基础设施、甚至 ArgoCD 自身）。

这种模式的核心价值是：将集群的所有资源声明式地托管在 Git 中，实现"一键部署整个集群"，是多应用、多环境、多集群场景下的 GitOps 最佳实践。

一、核心原理

1. 模式架构

App of Apps 采用分层管理的思想，结构如下：

复制代码

Git 仓库
└── apps/
    ├── root-app.yaml       # 根 Application（App of Apps 入口）
    ├── infrastructure/     # 基础设施子应用（如 Cilium、Ingress Nginx）
    │   ├── cilium.yaml
    │   └── ingress-nginx.yaml
    ├── services/           # 业务服务子应用（如微服务、数据库）
    │   ├── user-service.yaml
    │   └── order-service.yaml
    └── argocd/             # ArgoCD 自管理子应用（可选）
        └── argocd-self.yaml

根 Application ：唯一需要手动 kubectl apply 到集群的资源，它的作用是同步 Git 仓库中所有子 Application 的清单。
子 Application：由根 Application 自动创建和管理，每个子 Application 对应一个具体的应用（如 Cilium、业务服务），负责同步自身的资源清单（Deployment、Service 等）。

2. 工作流程

手动部署根 Application：这是唯一的"手动操作"，目的是让 ArgoCD 发现 Git 仓库中的所有子应用。
根 Application 同步子 Application ：ArgoCD 会根据根 Application 中定义的 source.path，自动扫描 Git 仓库中的子 Application 清单，创建对应的 Application 资源。
子 Application 同步实际资源：每个子 Application 会根据自身配置，同步对应的业务/基础设施资源（如 Deployment、ConfigMap）。
全流程自动化 ：后续所有变更只需修改 Git 仓库中的清单，根 Application 会自动感知并同步子 Application，子 Application 再同步实际资源，实现完全声明式的集群管理。

二、核心优势

一键集群初始化 ：新集群只需 kubectl apply 根 Application，即可自动部署所有基础设施和业务应用，无需逐个配置。
分层管理，职责清晰 ：
- 基础设施团队维护 infrastructure/ 目录；
- 业务团队维护 services/ 目录；
- 平台团队维护根 Application，实现权限隔离。
支持多环境/多集群 ：通过 Git 分支（如 dev/test/prod）或目录区分环境，根 Application 可根据不同环境同步对应子应用。
与 ArgoCD 自管理无缝集成：可将 ArgoCD 自身的 Application 作为子应用，纳入 App of Apps 体系，实现"集群全资源 GitOps 化"。
故障快速恢复：集群故障时，只需重建集群并部署根 Application，即可一键恢复所有资源。

三、实现步骤（实战指南）

以下是基于 Git 仓库的 App of Apps 完整实现步骤，以部署基础设施+业务应用为例。

步骤1：规划 Git 仓库目录结构

推荐采用按功能分类的目录结构，便于维护：

复制代码

gitops-repo/
├── README.md
├── root-app.yaml          # 根 Application 清单
├── infrastructure/        # 基础设施应用
│   ├── cilium.yaml
│   ├── ingress-nginx.yaml
│   └── metrics-server.yaml
└── services/              # 业务服务应用
    ├── user-service.yaml  # 微服务1
    └── order-service.yaml # 微服务2

步骤2：编写子 Application 清单

每个子 Application 是一个标准的 ArgoCD Application 资源，负责同步自身的资源。

示例：基础设施子应用 `infrastructure/cilium.yaml`

yaml 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: cilium
  namespace: argocd
  # 关键：设置自动删除（当 Git 中删除该文件时，ArgoCD 自动删除 Application）
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://helm.cilium.io/  # Cilium Helm 仓库
    chart: cilium
    targetRevision: 1.14.3            # 固定版本
    helm:
      values: |
        hubble:
          enabled: true
  destination:
    server: https://kubernetes.default.svc  # 本地集群
    namespace: kube-system
  syncPolicy:
    automated:
      prune: true    # 自动删除 Git 中不存在的资源
      selfHeal: true # 自动修复手动修改的资源
    syncOptions:
      - CreateNamespace=true # 自动创建命名空间

示例：业务服务子应用 `services/user-service.yaml`

yaml 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: user-service
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/gitops-repo.git  # 业务代码 Git 仓库
    path: services/user-service/manifests                 # 资源清单目录
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

步骤3：编写根 Application 清单（核心）

根 Application 是 App of Apps 的入口，它的 source.path 指向 Git 仓库中子 Application 所在的目录 ，通过 directory.recurse: true 递归扫描所有子 Application 清单。

根 Application 清单 `root-app.yaml`

yaml 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root-app
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/gitops-repo.git  # GitOps 仓库地址
    targetRevision: main                                   # 分支/标签
    path: .                                                # 指向仓库根目录（包含 infrastructure/ 和 services/）
    directory:
      recurse: true                                        # 关键：递归扫描所有子目录下的 Application 清单
      # 可选：只包含特定目录，过滤无关文件
      include: '*.yaml'
      # 可选：排除不需要的文件
      exclude: 'README.md'
  destination:
    server: https://kubernetes.default.svc  # 本地集群（多集群时可指定其他集群）
    namespace: argocd
  syncPolicy:
    automated:
      prune: true    # 当 Git 中删除子 Application 清单时，自动删除集群中的 Application
      selfHeal: true # 自动修复根 Application 的配置漂移
    syncOptions:
      - CreateNamespace=true
      - ApplyOutOfSyncOnly=true  # 仅同步不同步的资源，提升效率

步骤4：部署并验证 App of Apps

部署根 Application ：这是唯一的手动操作
bash 复制代码
```
kubectl apply -f root-app.yaml
```
查看根 Application 状态
bash 复制代码
```
argocd app get root-app
```
正常情况下，根 Application 会显示 Synced 状态，且 Children 字段会列出所有子 Application。

查看子 Application 状态

bash 复制代码

# 列出所有 Application
argocd app list
# 查看某个子应用的同步状态
argocd app get cilium

验证资源是否同步

bash 复制代码

# 查看基础设施资源
kubectl get pods -n kube-system -l app=cilium
# 查看业务服务资源
kubectl get pods -n default -l app=user-service

四、关键配置详解

1. `directory.recurse: true`

这是 App of Apps 的核心配置，必须开启 ，表示 ArgoCD 会递归扫描 source.path 目录下的所有子目录，识别所有 kind: Application 的清单并创建对应的资源。

2. `finalizers` 配置

yaml 复制代码

finalizers:
  - resources-finalizer.argocd.argoproj.io

作用是：当 Git 中删除 Application 清单时，ArgoCD 会自动删除集群中的对应 Application 及其管理的所有资源，实现"Git 中删除即集群中删除"的声明式管理。

3. `syncPolicy.automated.prune: true`

对根 Application：当 Git 中删除子 Application 清单时，自动删除集群中的子 Application。
对子 Application：当 Git 中删除资源清单时，自动删除集群中的对应资源。

注意：生产环境需谨慎开启，建议先在测试环境验证，避免误删重要资源。

4. 多环境/多集群适配

方式1：按 Git 分支区分环境

dev 分支：部署开发环境的子应用；
test 分支：部署测试环境的子应用；
prod 分支：部署生产环境的子应用。

根 Application 只需修改 targetRevision 即可切换环境：

yaml 复制代码

spec:
  source:
    targetRevision: prod  # 切换到生产环境

方式2：按目录区分环境

Git 仓库目录结构：

复制代码

gitops-repo/
├── root-app-dev.yaml
├── root-app-prod.yaml
├── dev/
│   ├── infrastructure/
│   └── services/
└── prod/
    ├── infrastructure/
    └── services/

根 Application 只需修改 source.path 即可切换环境：

yaml 复制代码

# 生产环境根 Application
spec:
  source:
    path: prod  # 指向 prod 目录

方式3：多集群部署

根 Application 的 destination.server 可以指定不同的集群（需提前将集群添加到 ArgoCD）：

yaml 复制代码

# 部署到 prod-cluster 集群
spec:
  destination:
    server: https://prod-cluster-api-server:6443
    namespace: argocd

五、与 ArgoCD 自管理集成

App of Apps 可以无缝集成 ArgoCD 自管理，将 ArgoCD 自身的 Application 作为子应用纳入管理，实现集群全资源的 GitOps 化。

步骤1：将 ArgoCD 自管理的 Application 放入 Git 仓库

在 Git 仓库中创建 argocd/argocd-self.yaml（即之前提到的 ArgoCD 自管理 Application 清单）。

步骤2：根 Application 扫描 ArgoCD 子应用

修改根 Application 的 source.path，确保包含 argocd/ 目录：

yaml 复制代码

spec:
  source:
    path: .  # 包含 infrastructure/、services/、argocd/
    directory:
      recurse: true

步骤3：部署根 Application

此时，根 Application 会自动创建 ArgoCD 自管理的子 Application，实现 "根 Application 管理 ArgoCD，ArgoCD 管理自身，ArgoCD 管理所有子应用" 的闭环。

六、生产环境最佳实践

使用 ArgoCD 项目（Project）做权限隔离
- 创建 infrastructure-project：仅允许同步基础设施资源；
- 创建 services-project：仅允许同步业务服务资源；
- 不同团队只能操作自己的 Project，避免越权修改。

开启资源健康检查

在子 Application 中开启健康检查，确保资源部署成功后才标记为 Healthy：

yaml 复制代码

syncPolicy:
  automated:
    prune: true
    selfHeal: true
  healthChecks:
    - apiGroup: apps
      kind: Deployment
      name: user-service
      namespace: default

配置同步波次（Sync Waves）

对于有依赖关系的应用（如先部署数据库，再部署业务服务），可以通过同步波次控制部署顺序：

yaml 复制代码

# 数据库 Application，波次 0（先部署）
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"
# 业务服务 Application，波次 1（后部署）
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"

波次数值越小，部署优先级越高。

定期备份 Git 仓库

Git 仓库是集群的"唯一可信源"，需定期备份，避免仓库丢失导致集群无法恢复。
避免循环依赖

不要让子应用依赖根 Application，或 ArgoCD 自管理的应用依赖其他子应用，避免同步死循环。

七、常见问题与排障

问题1：根 Application 同步成功，但子 Application 未创建

原因：
1. directory.recurse: true 未开启；
2. 子 Application 清单的 kind 不是 Application；
3. 子 Application 清单的 YAML 语法错误。
解决：
1. 检查根 Application 的 directory.recurse 配置；
2. 验证子 Application 清单的语法：kubectl apply --dry-run=client -f <sub-app.yaml>；
3. 查看 ArgoCD 控制器日志：kubectl logs -n argocd deployment/argocd-application-controller | grep -i error。

问题2：子 Application 显示 `OutOfSync`，但 Git 中配置正确

原因：子 Application 的同步策略未开启 selfHeal: true，或资源被手动修改。
解决：
1. 在子 Application 中开启 syncPolicy.automated.selfHeal: true；
2. 手动触发硬同步：argocd app sync <sub-app-name> --hard。

问题3：删除 Git 中的子 Application 清单，但集群中仍存在该 Application

原因：未配置 finalizers 或 syncPolicy.automated.prune: true。
解决：
1. 为子 Application 添加 finalizers 配置；
2. 开启根 Application 的 syncPolicy.automated.prune: true；
3. 手动删除：argocd app delete <sub-app-name> --cascade。

八、总结

App of Apps 是 ArgoCD 规模化管理集群的标准模式 ，其核心是通过一个根 Application 批量管理所有子 Application，实现集群资源的全生命周期 GitOps 化。

这种模式的优势在于：

一键集群初始化：新集群快速部署所有资源；
分层管理：职责清晰，便于多团队协作；
声明式变更：所有修改通过 Git 提交，可追溯、可回滚；
无缝集成自管理：实现 ArgoCD 自身的 GitOps 管理。

生产环境中，建议结合 ArgoCD 项目、同步波次、健康检查等特性，构建稳定、高效的 GitOps 流水线。

需要我帮你生成一份可直接复用的 App of Apps 模板清单（包含根应用、基础设施子应用、业务子应用）吗？

ArgoCD App of Apps 模式详解

一、核心原理

1. 模式架构

2. 工作流程

二、核心优势

三、实现步骤（实战指南）

步骤1：规划 Git 仓库目录结构

步骤2：编写子 Application 清单

示例：基础设施子应用 infrastructure/cilium.yaml

示例：业务服务子应用 services/user-service.yaml

步骤3：编写根 Application 清单（核心）

根 Application 清单 root-app.yaml

步骤4：部署并验证 App of Apps

四、关键配置详解

1. directory.recurse: true

2. finalizers 配置

3. syncPolicy.automated.prune: true

4. 多环境/多集群适配

方式1：按 Git 分支区分环境

方式2：按目录区分环境

方式3：多集群部署

五、与 ArgoCD 自管理集成

步骤1：将 ArgoCD 自管理的 Application 放入 Git 仓库

步骤2：根 Application 扫描 ArgoCD 子应用

步骤3：部署根 Application

六、生产环境最佳实践

七、常见问题与排障

问题1：根 Application 同步成功，但子 Application 未创建

问题2：子 Application 显示 OutOfSync，但 Git 中配置正确

问题3：删除 Git 中的子 Application 清单，但集群中仍存在该 Application

八、总结

示例：基础设施子应用 `infrastructure/cilium.yaml`

示例：业务服务子应用 `services/user-service.yaml`

根 Application 清单 `root-app.yaml`

1. `directory.recurse: true`

2. `finalizers` 配置

3. `syncPolicy.automated.prune: true`

问题2：子 Application 显示 `OutOfSync`，但 Git 中配置正确