web

第54章｜Argo CD 入门：应用模型、同步、漂移与回滚

若把集群比作乐谱上的演奏，kubectl apply 像即兴改几个音符——好听一时，却难复现。 Argo CD 把 Git 当作唯一乐谱，持续比较「谱面」与「现场」，直到二者收敛（reconcile）。 本章厘清 Application、Sync、Health、Drift 与回滚，让你敢在事故夜按下“回到上一版”。

App model

Desired state

  • source · revision
  • destination cluster/ns
  • AppProject guardrails
Sync

Converge

  • prune · selfHeal
  • retry · hooks
  • sync windows
Reality

Drift & rollback

  • OutOfSync vs Degraded
  • hard refresh
  • history & rollback

1. Argo CD 在 GitOps 里扮演什么？

Pull-based GitOps：控制器主动从 Git 拉取声明，再对集群做 apply；人的默认动作是合并 PR，而不是登录生产执行 kubectl。 Argo CD 的核心循环：发现差异 → 可选自动同步 → 观测资源健康 → 写回 Application 状态。 它与第 53 章的渐进发布工具（Rollouts / Flagger）可组合：Git 管期望 YAML，Rollouts 管流量与步骤。

Reconciliation plane (conceptual) Git manifests · Helm · Kustomize commit SHA = source of truth Argo CD application controller · repo-server · api-server compare desired vs live manifest render · diff · sync Application / AppProject CRDs status · health · sync UI · CLI · API observe same status Cluster live resources Deployment Service · CM · Secret eventually matches Git
图 1：Git 是“谱”；Argo CD 是“指挥”；集群是“乐团”——三者节拍靠持续对拍校准。

2. Application：把“交付单元”说清楚

一个 Application 绑定：从哪拉（source：仓库 URL、路径、插件）、落到哪（destination：集群地址与命名空间）、怎么同步（syncPolicy）。 多环境常见做法：同一 chart，多 Application 指向不同 values 或 overlay；或用 ApplicationSet 从列表/集群生成一批 Application（进阶话题，本章点到为止）。 

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: payments-api
  namespace: argocd
spec:
  project: team-payments
  source:
    repoURL: https://git.example.com/org/payments.git
    targetRevision: main
    path: deploy/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: payments-prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

3. AppProject：边界与准入

AppProject 定义哪些仓库可被引用、哪些集群/命名空间可部署、允许创建哪些 API 资源类型（防止 Application 变成“集群 root 后门”）。 多团队场景下，把项目隔离与RBAC绑在一起：开发者能改自己仓库的 Application，但不能把应用指到别人的 namespace。

4. Sync、Health 与三者关系

Sync status：Git 渲染结果与集群是否一致（Synced / OutOfSync）。Health：工作负载是否就绪、是否失败（Healthy / Progressing / Degraded / Suspended）。 典型误区：看到 Synced 就以为万事大吉——若 Deployment 镜像拉取失败，可能仍是 Degraded。反过来，OutOfSync 也不一定“坏了”，可能只是有人改了集群（漂移）。

信号 问的是什么 常见下一步
OutOfSync Git 与 live manifest 有差异 diff · sync · 或接受 drift（不推荐长期）
Progressing 滚动更新 / Job 运行中 等待 · 看 events · 调超时
Degraded 就绪失败、CrashLoop 等 logs · rollback revision · fix chart
Drift: who moved the furniture? Argo CD compares rendered manifests from Git against live objects in the cluster. Git (desired) replicas: 3 image: v1.4.2 Live (cluster) replicas: 5 ← manual scale? image: v1.4.2 Diff view highlight: replica mismatch sync restores Git truth (if policy allows)
图 2：OutOfSync 常常是“人动了集群”或“别的控制器写了字段”——先读懂 diff，再决定同步还是修 Git。

5. 同步策略：自动化、修剪与自愈

prune: true：Git 里删掉的资源，同步时从集群删除——双刃剑，务必配合评审流程。 selfHeal: true：集群被手动改坏时自动拉回 Git；运维临时 kubectl scale 可能被瞬间“纠正”，团队要约定紧急变更是否先改 Git。 Sync waves 与 hooks（Job / PreSync）能编排顺序依赖；sync windows 限制变更时段，降低与业务高峰重叠的风险。

底线：生产开启 automated + prune 前，确认不会误删共享资源，且回滚路径（历史 revision）可访问；否则一次错误合并可能变成级联删除。

6. 资源树与 Helm/Kustomize

UI 中的 Resource tree 展示 Application 展开后的对象图：Deployment、ReplicaSet、Service、Ingress、HPA 等。Helm chart 经 repo-server 渲染；Kustomize 走 build 管道。 版本问题多在缓存的 commit与helm dependency build——遇到“本地 helm template 与 Argo 不一致”，优先检查 targetRevision 与 values 来源。

Resource tree (simplified) Application Deployment ReplicaSet Pods ×N Service selector → pods Ingress host / tls Config / Secret mounted env · files health bubbles up
图 3：树不是摆设——它帮你定位“卡在 Deployment 还是 Ingress”。

7. 回滚与历史：让“上一版”可点击

Argo CD 记录每次同步的 revision（Git commit 或 chart version）。回滚即把 Application 指回历史 revision 并同步——本质是 GitOps 的“时间旅行”，前提是历史仍存在于仓库（不要 force-push 掉救命的 tag）。 与镜像回滚配合时，注意 数据库迁移是否不可逆——YAML 回去了，schema 可能回不去。 

# CLI examples (illustrative)
argocd app get payments-api
argocd app diff payments-api
argocd app sync payments-api --prune
argocd app rollback payments-api <id>

8. 多集群与 App of Apps

多集群：在 destination.server 注册外部集群凭据；每个环境一个 Application 或 ApplicationSet。App of Apps：一个“根” Application 的 path 里全是子 Application manifest，用于引导整片平台（ingress、监控、策略控制器）。 复杂度上升时，把仓库分层（平台层 vs 业务层）与RBAC写进设计文档，避免“根 App 一同步，全员屏住呼吸”。

App of Apps & multi-cluster (schematic) root Application repo: platform-gitops child: observability Prometheus stack child: ingress controllers · certs child: workloads per-team Applications child: policies OPA · network policy destination clusters prod-a · prod-b · DR — each mapped via cluster secrets + destination in child Apps
图 4：根 App 像“乐团总谱”；子 App 是分谱——分谱错了，总谱再美也听不见对和声。

9. 本章清单

  1. 画一张表：每个业务系统的 Application、AppProject、目标集群/命名空间与同步策略。
  2. 在测试环境演练：OutOfSync（故意改集群）→ diff → sync 或修 Git；打开 selfHeal 观察行为。
  3. 为生产定义 prune 与 sync window 的边界；明确紧急变更先改仓库的纪律。
  4. 验证回滚：从历史 revision 恢复，并检查依赖（DB 迁移、CRD 版本）。
  5. 下一章对比 Flux：Source、Kustomization、HelmRelease 的另一条 GitOps 路线。
← 上一章：渐进交付 下一章：Flux 入门 →