2. Argo CD 核心概念深度解析

在深入多集群 GitOps 流水线之前，必须透彻理解 Argo CD 的六大核心模型：Application、Project、Repository、Cluster Secret、Sync Policy 和 Health Status。这些模型构成了 Argo CD 声明式配置与自动化调谐的基石。

2.1 核心模型总览

下表从职责、作用域和关键属性三个维度对比六大模型，帮助建立全局认知：

核心模型 职责 作用域 关键属性
Application 定义“从哪个仓库、同步到哪个集群、如何同步”的完整单元 命名空间级 source, destination, syncPolicy, syncStatus
Project 逻辑隔离与权限边界，约束 Application 的行为 集群级 sourceRepos, destinations, roles, syncWindows
Repository 存储 Git 仓库连接凭证与元数据 集群级 url, type, sshPrivateKey, password
Cluster Secret 存储目标集群的 kubeconfig 或 API 端点凭证 集群级 server, config, name, namespaces
Sync Policy 控制同步触发方式、自动行为与资源修剪策略 Application 内嵌 automated, syncOptions, retry
Health Status 评估已部署资源是否处于预期健康状态 Application 内嵌 status, message, resources.health
实践要点：在单集群场景中，Project 和 Cluster Secret 通常使用默认值；但在多集群架构下，必须显式管理 Cluster Secret 和 Project 的 RBAC 约束，否则极易出现配置泄露或越权同步。

2.2 Application：GitOps 的最小部署单元

Application 是 Argo CD 中最核心的 CRD（Custom Resource Definition）。它完整描述了一个部署单元的“三要素”：

  • Source：Git 仓库路径、Helm Chart 或 Kustomize 目录。
  • Destination：目标集群 API Server 地址 + 目标命名空间。
  • Sync Policy：自动/手动同步、修剪策略、重试机制。

一个典型的 Application YAML 示例如下：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook-prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ApplyOutOfSyncOnly=true
关键字段解读：
syncPolicy.automated.prune：当 Git 中删除资源时，自动从集群中删除对应资源。
syncPolicy.automated.selfHeal：当集群资源被手动修改时，自动回滚到 Git 中的期望状态。
syncOptions.ApplyOutOfSyncOnly：仅同步状态不一致的资源，大幅提升大规模集群的同步效率。

2.3 Project：多租户隔离与安全边界

Project 是 Argo CD 中实现多团队、多环境隔离的核心机制。它限制了 Application 可以引用的仓库、目标集群和命名空间，并支持细粒度的 RBAC 角色绑定。

Project 的典型约束维度：

约束类型 字段 示例值
允许的仓库 spec.sourceRepos https://github.com/team-a/*
允许的目标集群 spec.destinations server: https://cluster-prod.example.com
允许的命名空间 spec.destinations.namespace team-a-*
同步窗口 spec.syncWindows kind: deny, schedule: "0 0 * * 1-5"
常见陷阱：Project 的 destinations 支持通配符 *，但生产环境应避免使用。始终为每个环境（dev/staging/prod）定义独立的 Project，并明确列出允许的集群和命名空间。

2.4 Repository 与 Cluster Secret：凭证管理模型

Repository 和 Cluster Secret 是 Argo CD 连接 Git 和 Kubernetes 集群的“桥梁”。它们都以 Kubernetes Secret 的形式存储敏感信息，但用途截然不同。

Repository 存储 Git 仓库的访问凭证：

  • 支持 HTTPS（用户名+密码/）和 SSH（私钥）两种认证方式。
  • 通过 argocd repo add 命令或 UI 添加后，Argo CD 会将其加密存储。
  • 多集群场景下，所有 Argo CD 实例共享同一套 Repository 配置（通过 ConfigMap 分发）。

Cluster Secret 存储目标 Kubernetes 集群的连接信息：

  • 核心字段：server（API Server 地址）、config（kubeconfig 或 bearer ）。
  • 命名规范：Secret 名称必须包含 cluster- 前缀，且位于 Argo CD 安装的命名空间。
  • 多集群管理时，每个目标集群对应一个独立的 Cluster Secret。
# 查看已注册的集群
argocd cluster list

# 输出示例
SERVER                          NAME        STATUS  MESSAGE
https://kubernetes.default.svc  in-cluster  Successful
https://prod-cluster:6443       prod        Successful
https://staging-cluster:6443    staging     Successful
最佳实践：使用 argocd cluster add 命令自动生成 Cluster Secret，避免手动编写 kubeconfig。对于跨云场景，优先使用 bearer 而非完整的 kubeconfig 文件，以降低凭证泄露风险。

2.5 Sync Policy：同步行为控制引擎

Sync Policy 决定了 Argo CD 如何将 Git 中的期望状态应用到目标集群。它不是一个独立的 CRD，而是内嵌在 Application 的 spec.syncPolicy 字段中。

同步策略的核心维度：

策略维度 可选值 说明
同步模式 automated / manual 自动模式：Argo CD 定期检测差异并自动同步；手动模式：需人工触发
修剪策略 prune: true/false 是否允许删除集群中 Git 已移除的资源
自愈策略 selfHeal: true/false 是否自动修复集群中被手动修改的资源
同步选项 syncOptions 如 CreateNamespace=true、ApplyOutOfSyncOnly=true、PruneLast=true
重试策略 retry 失败重试次数、间隔和回退因子
生产环境推荐配置：
automated.prune: true —— 确保集群状态与 Git 完全一致。
automated.selfHeal: true —— 防止配置漂移。
syncOptions[0]: CreateNamespace=true —— 自动创建目标命名空间。
syncOptions[1]: ApplyOutOfSyncOnly=true —— 减少不必要的 API 调用。
retry.limit: 5 —— 网络抖动时自动重试。

2.6 Health Status：资源健康评估体系

Argo CD 不仅关注“同步状态”（Synced/OutOfSync），还关注“健康状态”（Healthy/Progressing/Degraded）。健康状态评估是 GitOps 自动化运维的核心能力。

健康状态分为三个层级：

  • Application 级别：status.health.status，取值 Healthy、Progressing、Degraded、Suspended、Missing。
  • 资源级别：status.resources[].health，每个 Kubernetes 资源独立评估。
  • 自定义健康检查：通过 resource.customizations 扩展对 CRD 的健康评估逻辑。

常见资源的健康判定逻辑：

资源类型 Healthy 条件 Degraded 条件
Deployment 可用副本数 ≥ 期望副本数 可用副本数 < 期望副本数，且持续超过阈值
StatefulSet Ready 副本数 = 期望副本数 Ready 副本数 < 期望副本数
Service 存在 Endpoints 无 Endpoints 或 LoadBalancer 挂起
Ingress Admitted 状态为 True Admitted 状态为 False
Job Complete Failed 或 Active 超时
注意：对于自定义 CRD（如 Prometheus Operator 的 ServiceMonitor、Istio 的 VirtualService），Argo CD 默认无法评估健康状态。必须通过 argocd.argoproj.io/health 注解或全局 resource.customizations 配置自定义 Lua 脚本。

2.7 核心模型关系图

下图展示了六大核心模型之间的依赖与数据流关系：

Argo CD 核心模型关系图 Argo CD 核心模型关系图 Git 仓库层 Repository 凭证 + URL + 类型 Argo CD 控制面 Application Source + Destination + Policy Project RBAC + 约束 + 隔离 Sync Policy 自动/手动 + 修剪 + 重试 Health Status Healthy / Degraded / Progressing 目标集群层 Cluster Secret kubeconfig / 读取清单 连接目标 约束 内嵌 驱动 核心数据流 1. Application 从 Repository 读取 Git 清单（Source） 2. Application 通过 Cluster Secret 连接目标集群（Destination） 3. Sync Policy 控制同步行为，Health Status 反馈部署结果

2.8 多集群场景下的模型协同

在多集群 GitOps 架构中，上述模型需要协同工作才能实现“一次配置，多集群生效”。典型的协同模式如下：

  1. Repository 共享：所有集群共用同一个 Git 仓库，通过不同目录或分支区分环境。
  2. Cluster Secret 独立：每个目标集群有独立的 Cluster Secret，Argo CD 通过 argocd cluster add 管理。
  3. Project 隔离：每个团队或环境使用独立的 Project，限制其可操作的集群和命名空间。
  4. Application 模板化：使用 ApplicationSet 生成器（如 Cluster Generator）为每个集群自动生成 Application。
  5. Sync Policy 差异化：生产集群启用 prune: true 和 selfHeal: true，开发集群可关闭自愈以允许临时调试。
  6. Health Status 聚合：通过 Argo CD 的 status.health 字段，在控制面统一查看所有集群的部署健康度。
多集群协同示例：
假设有 3 个集群（dev、staging、prod），每个集群对应一个 Cluster Secret。通过一个 ApplicationSet 和 Cluster Generator，Argo CD 会自动为每个集群创建一个 Application，这些 Application 共享同一个 Project（如 team-a）和 Repository，但 Destination 指向不同的 Cluster Secret。当 Git 仓库中的清单更新时，所有集群的 Application 会按照各自的 Sync Policy 执行同步。
← 上一章 📖 返回目录 下一章 →