3. Argo CD 核心概念：Application、Project、Sync Policy、Sync Wave、Hook 机制详解
Argo CD 作为声明式 GitOps 引擎，其核心抽象模型围绕 Application（应用）、Project（项目）、Sync Policy（同步策略）、Sync Wave（同步波次）和 Hook（钩子）构建。理解这五个概念是掌握 Argo CD 平台工程能力的基础。
3.1 Application：GitOps 的最小部署单元
Application 是 Argo CD 中最核心的 CRD（Custom Resource Definition），它定义了“从哪个 Git 仓库拉取什么清单”以及“部署到哪个目标集群/命名空间”。
| 字段 | 说明 | 示例值 |
|---|---|---|
spec.source.repoURL |
Git 仓库地址 | https://github.com/example/app-config.git |
spec.source.path |
仓库内清单目录路径 | environments/prod |
spec.destination.server |
目标 Kubernetes API Server 地址 | https://kubernetes.default.svc |
spec.destination.namespace |
目标命名空间 | production |
spec.project |
所属 Project 名称 | default |
关键原则：Application 遵循“声明式最终一致”模型。Argo CD 持续对比 Git 中的期望状态与集群中的实时状态，当出现偏差时，根据同步策略自动或手动纠正。
3.2 Project：多租户隔离与权限边界
Project 是 Argo CD 实现多租户隔离的顶层逻辑分组。一个 Project 可以包含多个 Application，并统一约束其行为。
- 源仓库白名单：限制 Application 只能从指定的 Git 仓库拉取清单。
- 目标集群/命名空间白名单：限制 Application 只能部署到特定的集群和命名空间。
- 资源类型黑名单/白名单：控制 Project 内允许或禁止创建的 Kubernetes 资源类型（如禁止创建 ClusterRole）。
- 同步窗口：定义允许或禁止自动同步的时间段。
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: platform-team
spec:
sourceRepos:
- 'https://github.com/platform-*'
destinations:
- namespace: 'team-*'
server: 'https://kubernetes.default.svc'
clusterResourceWhitelist:
- group: ''
kind: 'Namespace'
- group: 'rbac.authorization.k8s.io'
kind: 'ClusterRole'
3.3 Sync Policy：同步行为的自动化控制
Sync Policy 定义了 Application 在检测到 Git 与集群状态不一致时的响应行为。它分为自动同步和手动同步两种模式。
| 策略类型 | 子选项 | 行为描述 |
|---|---|---|
| 自动同步 | prune: true |
自动删除集群中 Git 中已不存在的资源 |
selfHeal: true |
自动修复集群中被手动修改的资源，使其回归 Git 状态 | |
allowEmpty: true |
允许 Git 目录为空时清空目标命名空间 | |
| 手动同步 | — | 仅当用户通过 UI/CLI 触发时执行同步，适合生产环境审批流程 |
平台工程建议：生产环境推荐使用手动同步 + 自动自愈（selfHeal: true），既保留人工审批环节，又能防止集群状态被意外篡改。
3.4 Sync Wave：资源部署的顺序编排
Sync Wave 解决了 Kubernetes 资源部署时的依赖顺序问题。Argo CD 允许为每个资源设置 argocd.argoproj.io/sync-wave 注解，数值越小，部署优先级越高。
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
annotations:
argocd.argoproj.io/sync-wave: "1" # 在 ConfigMap 之后部署
spec:
...
---
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
annotations:
argocd.argoproj.io/sync-wave: "0" # 优先部署
data:
...
3.5 Hook 机制：同步生命周期的精细化干预
Hook 允许在同步流程的特定阶段执行 Job 或 Pod，用于完成数据库迁移、预检查、通知等任务。Argo CD 通过资源注解 argocd.argoproj.io/hook 来识别 Hook 资源。
| Hook 类型 | 触发时机 | 典型用途 |
|---|---|---|
PreSync |
在 Sync Wave 执行之前 | 数据库 Schema 校验、前置依赖检查 |
Sync |
在 Sync Wave 执行期间 | 执行数据迁移脚本、初始化缓存 |
PostSync |
在所有 Sync Wave 执行完成后 | 发送部署通知、更新 CMDB、触发集成测试 |
SyncFail |
同步失败时 | 回滚数据库、发送告警、清理临时资源 |
apiVersion: batch/v1
kind: Job
metadata:
name: db-migration
annotations:
argocd.argoproj.io/hook: PreSync # 在同步前执行
argocd.argoproj.io/hook-delete-policy: HookSucceeded # 成功后自动删除 Job
spec:
template:
spec:
containers:
- name: migration
image: myapp/migration:latest
command: ["/bin/sh", "-c", "flyway migrate"]
restartPolicy: Never
注意事项：Hook 资源默认不会出现在 Application 的最终状态中。如果 Hook 执行失败，Argo CD 会阻止后续同步流程。建议为关键 Hook 设置合理的超时和重试机制。