GitOps 与 Argo CD 实战

摘要：本文面向要把"Git 作为集群唯一事实源"落地的平台/SRE 工程师。先厘清 GitOps 的 OpenGitOps 四原则，再以 Argo CD（2.x）为例拆解其架构与同步循环，给出 Application 实战示例，并对比 Argo CD 与 Flux 的取舍与常见失败模式。

适用版本与前提

Argo CD：2.x（CNCF Graduated，2022-12）
Flux：2.x（CNCF Graduated，2024-11）
Kubernetes：v1.25+
前提：已有一个存 YAML/Helm/Kustomize 的 Git 仓库

什么是 GitOps：OpenGitOps 四原则

"GitOps"一词由 Weaveworks 的 Alexis Richardson 于 2017 年提出，但长期被滥用为"CI 里跑 kubectl apply"。2021 年 CNCF 旗下的 OpenGitOps 工作组正式定义了四条原则，区分了真正的 GitOps 与传统 CI/CD：

Declarative（声明式）：系统期望状态用声明式描述（K8s YAML / Helm / Kustomize），而非命令式脚本。
Versioned and Immutable（版本化且不可变）：期望状态存于版本控制系统（如 Git），每次变更是 commit，可审计、可回滚。用 latest 这类浮动 tag 即破坏此原则。
Pulled Automatically（自动拉取）：集群内运行的 agent 自动从源拉取期望状态——这是与 push 模型（CI 调 kubectl apply）的根本区别。
Continuously Reconciled（持续调和）：agent 持续比对实际状态与期望状态，发现漂移（drift）自动纠正。

多数"GitOps"实现栽在第三条

只在 Git push 时触发 CI 去 apply，是"Git 触发的 CI/CD"，不是 GitOps——因为它依赖集群外的系统，且 CI 跑完后集群是否真的一致无人保证。真正 GitOps 是集群内 agent 主动 pull + 持续 reconcile。Argo CD / Flux 都是 pull 模型。

Argo CD 架构

Argo CD 是一个以 CRD 为核心的 Kubernetes 控制器，主要组件：

API Server / UI：提供 Web UI、CLI、API，展示资源树、diff、sync 状态。这是 Argo CD 的"杀手锏"特性。
Repository Server：拉取 Git 仓库、渲染 Helm/Kustomize/Ksonnet 成 manifest。
Application Controller：核心调和器，持续比对 Git（期望）与集群（实际），执行 sync。
Application（CRD）：定义一个应用 = 一个 Git 源 + 一个目标集群/命名空间 + 一个渲染工具。
AppProject（CRD）：多租户隔离单元，定义哪些 Git 源、集群、命名空间可被哪些 Application 使用，并配 RBAC/SSO。

持续调和（Reconciliation）循环

Argo CD 的心跳就是这个循环：周期性或被动触发地刷新 Git → 渲染 → diff → 必要时 sync → 上报 health。

关键状态分两类：Sync Status（Git 与集群是否一致）和 Health（应用是否真正健康运行，如 Deployment 的 Pod 是否 Ready）。两者独立——Synced 不代表 Healthy。

Application 实战示例

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: prod-api
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io   # 卸载时级联删除资源，防孤儿
spec:
  project: default
  source:
    repoURL: https://github.com/org/gitops-repo.git
    targetRevision: main
    path: apps/prod/api
    # 渲染工具：Kustomize 或 Helm 二选一
    kustomize:
      namePrefix: prod-
    # helm:
    #   valueFiles:
    #     - values-prod.yaml
  destination:
    server: https://kubernetes.default.svc   # 目标集群 API
    namespace: production
  syncPolicy:
    automated:
      prune: true          # 删除 Git 中已移除的资源
      selfHeal: true       # 集群被手动改动时自动纠正回 Git 状态
      allowEmpty: false
    syncOptions:
      - CreateNamespace=true
    retry:
      limit: 3

selfHeal: true 是 GitOps 精髓：有人手动 kubectl edit 改了副本数，Argo CD 会把它纠正回 Git 定义的值，杜绝配置漂移。prune: true 则保证 Git 删除的资源在集群也被删除（避免孤儿资源）。

生产危险

prune: true 会删除集群中"Git 已不再声明"的资源。若 Git 仓库误删了某条资源定义，Argo CD 会忠实地把生产中的对应资源删掉。务必开启 allowEmpty: false 并在 Git 侧做 MR 评审 + 保护分支，prune 前先在 Argo CD UI 确认 diff。

Argo CD 与 Flux 的差异

两者都是 CNCF Graduated 的 pull 模型 GitOps 工具，但哲学与体验不同：

维度	Argo CD	Flux
UI	自带富 Web UI（资源树/diff/sync 历史）	无原生 UI（社区有第三方面板）
架构	集中式 server + API，一个控制面管多集群	分布式控制器，每集群各自一套 CRD
多租户	AppProject + RBAC + SSO（OIDC/LDAP/SAML）	原生 K8s RBAC + ServiceAccount 隔离
Helm	渲染 Chart 成 manifest 后 apply	原生 `HelmRelease` CRD，带自动升级/回滚
镜像自动化	需 Argo CD Image Updater 组件	内置 Image Reflector + Automation 控制器
上手	UI 直观，新团队秒懂	学习曲线陡，但更 K8s-native

何时选谁（经验判断）

需要可视化总览、多团队差异化权限、SSO 集成的平台团队，选 Argo CD（UI 是决定性优势）；追求极简、Kubernetes-native、强组合性的团队，选 Flux。二者能力逐步趋同，最终取决于组织偏好与现有栈。

生产实践

Git 仓库分层：apps/<env>/<app> 放各环境 overlay，Argo CD 只读；变更走 MR + 评审 + 保护分支。
AppProject 做隔离：不同团队/环境用不同 project，限制其可写的集群与命名空间。
syncPolicy 渐进开启：先手动 sync 验证，再开 automated，最后才开 prune/selfHeal。
Webhook 加速：配 Git webhook 触发 refresh，避免纯靠轮询（默认 3 分钟）的延迟。
finalizers 防孤儿：关键 Application 加 resources-finalizer，删除 Application 时级联清理集群资源。

故障排查

OutOfSync 但无变化：可能是 last-applied-configuration 注解或 status 字段被算入 diff，检查 ignoreDifferences 配置。
Sync 卡在 Progressing：资源未进入 Ready（如镜像拉取失败、探针不通），查对应 Pod 事件，而非 Argo CD 本身。
selfHeal 反复抖动：说明有外部控制器或人在持续改集群，需找到"真凶"而不是靠 selfHeal 掩盖。
Webhook 不触发：核对 webhook secret 与 Argo CD 侧 argocd-cm 配置是否匹配。

失败模式

Secrets 进 Git：GitOps 要求状态入 Git，但 Secret 明文入仓是大忌。应配合 sealed-secrets / SOPS / External Secrets，而非裸 Secret。
PR 合并即生产变更：缺乏环境级审批闸门，错误配置直接进 prod。应对：多环境用不同分支/目录 + 保护分支 + 人工审批。
repo 服务器权限过大：Argo CD 的 ServiceAccount 若拥有集群管理员权限，一旦 Git 被攻破即集群沦陷。遵循最小权限，用 AppProject 收窄。

版本相关

Argo CD 2.x 的 spec.source 字段在 2.3+ 对 OCI Helm 仓库、2.4+ 对 namePrefix 等支持有差异。生产前以目标 Argo CD 版的 upgrade notes 为准。

FAQ

Q：Argo CD 自己怎么部署？它不是也该 GitOps 化吗？ A：可以用 Argo CD 管理 Argo CD（bootstrap / "App of Apps" 模式），但初始安装通常还是手工或 GitOps 引擎（如用 Flux 管 Argo CD，避免"鸡生蛋"）。生产常见做法是单独一个 bootstrap 仓库。

Q：Argo CD 能管多集群吗？ A：可以。通过 argocd cluster add 注册外部集群的 kubeconfig，Application 的 destination.server 指向对应集群 API，一个 Argo CD 控制面即可编排多集群。

参考资料

Argo CD Core Concepts（官方文档），访问日期：2026-10-08。
OpenGitOps 1.0 声明与四原则，访问日期：2026-10-08。
CNCF Application Delivery TAG / OpenGitOps，访问日期：2026-10-08（GitOps 工作组归属）。
GitOps in Practice: ArgoCD vs Flux（实践对比），访问日期：2026-10-08。

GitOps 与 Argo CD 实战 ​

适用版本与前提 ​

什么是 GitOps：OpenGitOps 四原则 ​

Argo CD 架构 ​

持续调和（Reconciliation）循环 ​

Application 实战示例 ​

Argo CD 与 Flux 的差异 ​

生产实践 ​

故障排查 ​

失败模式 ​

FAQ ​

参考资料 ​