3. Argo CD 核心概念：Application、Project、Sync Policy、Sync Status、Health Status、Resource Customization
在深入监控与故障排查之前，必须牢固掌握 Argo CD 的六大核心概念。它们是理解制品同步状态、配置监控规则以及定位异常根因的基石。本章将逐一拆解这些概念，并建立它们之间的关联关系。
3.1 Application（应用）
Application 是 Argo CD 中管理部署单元的核心 CRD（Custom Resource Definition）。它定义了“从哪个 Git 仓库拉取清单”以及“部署到哪个目标集群/命名空间”。
| 字段 | 说明 | 示例值 |
|---|---|---|
| source | Git 仓库地址、目标路径、Helm/Kustomize 参数 | https://github.com/example/app.git |
| destination | 目标集群 URL 与命名空间 | https://kubernetes.default.svc / production |
| project | 所属 Project 名称（默认 default） | my-project |
| syncPolicy | 自动同步策略配置 | automated: { prune: true } |
监控关注点： Application 的
source 变更频率、destination 连通性、以及是否被意外删除或修改。
3.2 Project（项目）
Project 是 Argo CD 中的逻辑隔离单元，用于管理多个 Application 的访问权限、资源限制和部署目标约束。它类似于 Kubernetes 的 Namespace，但作用于 Argo CD 层面。
- 角色绑定： 控制哪些用户/组可以操作项目内的 Application。
- 源仓库白名单： 限制 Application 只能从指定的 Git 仓库拉取清单。
- 目标集群白名单： 限制 Application 只能部署到指定的目标集群。
- 资源配额： 限制项目内所有 Application 可使用的 Kubernetes 资源总量。
最佳实践： 按环境（dev/staging/prod）或团队划分 Project，避免跨项目权限混乱。监控时需关注 Project 的配额是否接近上限。
3.3 Sync Policy（同步策略）
Sync Policy 决定了 Argo CD 如何将 Git 仓库中的期望状态应用到目标集群。它分为两种模式：
| 策略类型 | 行为 | 适用场景 |
|---|---|---|
| Manual Sync（手动同步） | 需要人工点击“Sync”按钮或调用 API 触发 | 生产环境变更审批严格、需要手动确认 |
| Automated Sync（自动同步） | 检测到 Git 仓库变更后自动执行同步 | 开发/测试环境、CI/CD 流水线集成 |
自动同步策略包含两个关键子选项：
- Prune（修剪）： 自动删除集群中 Git 仓库已移除的资源。开启后需谨慎，避免误删。
- Self-Heal（自愈）： 当集群中资源被手动修改（偏离 Git 状态）时，自动回滚至 Git 定义的状态。
故障排查提示： 如果 Application 处于
OutOfSync 状态但未自动同步，首先检查 syncPolicy 是否配置了 automated。若未配置，需手动触发同步。
3.4 Sync Status（同步状态）
Sync Status 表示 Application 当前集群状态与 Git 仓库期望状态的一致性。这是监控中最核心的指标之一。
| 状态值 | 含义 | 监控告警建议 |
|---|---|---|
| Synced | 集群状态与 Git 完全一致 | 正常，无需告警 |
| OutOfSync | 集群状态与 Git 存在差异 | 立即告警，需排查差异原因 |
| Syncing | 正在执行同步操作 | 短暂过渡状态，若持续超过 5 分钟则告警 |
| Failed | 同步操作执行失败 | 严重告警，需立即介入 |
| Unknown | 无法获取同步状态（如集群不可达） | 告警，检查集群连通性 |
Grafana 监控指标： 使用
argocd_app_info 指标中的 sync_status 标签，可以按状态统计 Application 数量，并设置告警规则。
3.5 Health Status（健康状态）
Health Status 评估已部署资源是否正常运行，而不仅仅是与 Git 一致。它由 Argo CD 内置的健康检查逻辑或自定义 Lua 脚本判定。
| 状态值 | 含义 | 常见原因 |
|---|---|---|
| Healthy | 所有资源运行正常 | — |
| Progressing | 资源正在部署或更新中 | 滚动更新、Pod 启动中 |
| Degraded | 部分资源运行异常 | Pod CrashLoopBackOff、Service 无端点 |
| Suspended | 资源被暂停（如 HPA 缩容至 0） | 主动暂停部署 |
| Missing | 期望的资源在集群中不存在 | 资源被手动删除或同步失败 |
| Unknown | 健康检查无法执行 | 自定义资源缺少健康检查脚本 |
故障排查技巧： 当 Application 显示
Synced 但 Degraded 时，说明 Git 配置正确但应用本身运行异常。此时应查看 Pod 日志或 Events，而非 Git 差异。
3.6 Resource Customization（资源定制化）
Resource Customization 允许在同步过程中对 Kubernetes 资源进行动态修改，而无需更改 Git 仓库中的原始清单。常见场景包括：
- Config Management Plugins（CMP）： 使用自定义工具（如 Kustomize、Helm、Jsonnet）生成清单。
- Resource Hooks： 在同步前后执行 Job（如数据库迁移、预检查）。
- Ignore Differences： 忽略某些字段的差异（如
replicas被 HPA 自动修改）。 - Resource Overrides： 对特定资源类型应用全局修改（如添加
annotations）。
监控风险点： 过度使用
Ignore Differences 可能导致真正的配置漂移被忽略。建议在监控中增加对 resourceCustomizations 变更的审计日志告警。
3.7 核心概念关系图
下图展示了 Application、Project、Sync Policy 以及 Sync/Health 状态之间的协作关系：
3.8 状态组合与故障场景
理解 Sync Status 与 Health Status 的组合，是快速定位故障的关键。下表列出常见组合及其含义：
| Sync Status | Health Status | 典型场景 | 排查方向 |
|---|---|---|---|
| Synced | Healthy | 一切正常 | 无需操作 |
| Synced | Degraded | 配置正确但应用崩溃 | 查看 Pod 日志、Events、资源限制 |
| OutOfSync | Healthy | Git 有变更但未同步，当前集群仍健康 | 检查 Sync Policy 是否开启自动同步 |
| OutOfSync | Degraded | Git 变更导致集群状态异常 | 回滚 Git 或手动修复集群资源 |
| Failed | Missing | 同步失败且资源未创建 | 查看同步日志、检查 Git 仓库连通性 |
Grafana 面板设计建议： 在仪表盘中同时展示
sync_status 和 health_status 两个时间序列，并使用颜色编码（绿/黄/红）快速识别异常组合。例如，Synced + Degraded 应显示为橙色警告。