Skip to content

GitOps:Argo CD 与声明式部署 ​

本篇要点:把「集群里跑的是什么」这件事的唯一事实源从人的记忆搬到 Git,并让偏离能被发现、能被纠正。前置文章:[《供应链安全:SBOM、签名与扫描》](/guide/cicd/supply-chain-security-sbom.html)解决了制品可信——镜像有签名、有 SBOM;这一章解决制品怎么进集群,以及进去之后怎么保证它和声明一致。

一、为什么需要它 ​

一个四人后端团队,Kubernetes 上跑十一个服务。2025 年 9 月的一个周五凌晨,订单服务 OOM,值班同学连进集群,kubectl edit deployment order-api 把内存限制从 512Mi 改成 1Gi,kubectl rollout restart,服务恢复,回家睡觉。

三个月后,新同事按流程发版,流水线跑完 kubectl apply -f k8s/,内存限制回到 512Mi。当晚同一时段,同一个服务,又 OOM 了一次。

这次事故里没有一行代码是错的。错的是「生产环境的真实状态」只存在于一次 kubectl edit 的操作历史里,而这份历史没有人能读到。文档里写的是 512Mi,Git 里是 512Mi,集群里是 1Gi,三者不一致,且没有任何机制会在不一致发生时发出声音。

同样的问题还有几种变体。安全审计问「谁能改生产」,答案是「有 kubeconfig 的十七个人,且没有操作记录」。回滚时发现上一个版本的 YAML 没人存,只能 kubectl rollout undo 赌一把。多集群时,三个集群的 ConfigMap 内容各不相同,没人说得清哪个是对的。

GitOps 要解决的就是这一类问题。它的主张很朴素:集群里的一切由 Git 里的声明决定,任何偏离都会被自动纠正。

二、核心概念 ​

2.1 四条原则,缺一条就退化成脚本 ​

OpenGitOps 项目(CNCF 下的一个工作组)把 GitOps 定义为四条原则,这四条是判断一个方案是不是 GitOps 的依据,不是口号。

原则含义少了它会怎样
声明式(declarative)描述「最终要什么状态」,不写「一步步怎么做」变成命令式脚本,重跑结果不一致
版本化且不可变(versioned and immutable)全部声明存在 Git,历史可回溯、可 diff回滚没有依据,只能靠记忆
自动拉取(pulled automatically)集群内的 agent 主动拉取,不由外部推入集群凭据必须散给 CI,攻击面变大
持续调和(continuously reconciled)循环比对期望与实际,不一致就纠正只部署一次,之后漂移无人管

表 8-1 GitOps 的四条原则与缺失后的后果

反例:写一个 Jenkins 任务,git pull 之后跑 kubectl apply -f .。它有版本控制、是声明式的,但只满足前两条。它不持续调和——apply 完就结束,之后的漂移不管;它也不自动拉取——CI 拿着集群的管理员凭据,那份 kubeconfig 存在 Jenkins 的凭据库里,任何一个能改 Jenkinsfile 的人都能拿到它。

2.2 Push 与 Pull:信任边界在哪 ​

图 8-1 Push 与 Pull 的信任边界差别

如图 8-1 所示,两种模式的分界线是「谁持有写集群的权限」。Push 模式下 CI 是特权方,CI 一旦被攻破,攻击者直接获得集群写权限;Pull 模式下 CI 只写镜像仓库,集群内的 agent 用本地 ServiceAccount 干活,外部没有任何可用的集群凭据。这也顺带解释了为什么 GitOps 特别适合多集群:加一个集群只需要在那个集群里装一个 agent,不需要把凭据集中到一处。

代价是反馈变慢。Pull 模式下部署发生在 agent 的下一个同步周期(默认 3 分钟),CI 里那句「部署成功」只能表示「镜像推上去了」。要做到端到端可见,得让 CI 反查 agent 的状态,或者让 agent 把结果回写到 commit status。

2.3 Argo CD 与 Flux 怎么选 ​

维度Argo CDFlux
部署形态自带 API Server、UI、CLI,一套完整应用一组控制器(source、kustomize、helm、notification),无内置 UI
声明单位Application CRD,一个应用一个对象GitRepository + Kustomization / HelmRelease 组合
可视化资源树、同步状态、diff 视图依赖 Weave GitOps 或 Grafana 看板
多环境ApplicationSet 按目录/集群生成Kustomization 分层 + FluxInstance
镜像自动更新需要 Argo CD Image Updater 单独装ImagePolicy + ImageAutomation 内置
学习曲线上手快,UI 能直接看懂概念多一层,脚本化更彻底

表 8-2 Argo CD 与 Flux 的能力对照(截至 2026 年 11 月,两者均为 CNCF 毕业项目)

选择的实际依据通常不是功能,是团队。有平台团队、要给业务方开自助界面,选 Argo CD;团队小、偏好「一切皆 CRD」、不想多维护一个 API Server,选 Flux。两个都支持 Helm 与 Kustomize,都能做多集群,差别在运维成本和习惯。

2.4 多环境靠目录,不靠分支 ​

常见做法是三个环境三个分支:dev、staging、main。它的第一个问题是合并方向混乱——从 main 往 staging 合,等于把生产改动带到预发;第二个问题是 diff 只在同一分支内可见,跨分支比较要另开工具;第三个问题是「哪个 commit 部署到了哪个环境」需要拼三份历史。

更好的组织是单分支多目录:

text
deploy/
├── base/                    # 共用:Deployment、Service、HPA
│   ├── kustomization.yaml
│   └── deployment.yaml
├── overlays/
│   ├── dev/                 # 副本 1、镜像 tag 用 digest、资源 256Mi
│   ├── staging/             # 副本 2、资源 512Mi
│   └── prod/                # 副本 4、资源 1Gi、加 PDB
└── clusters/
    ├── cn-east/             # 引用 overlays/prod
    └── us-west/             # 引用 overlays/prod,改 region 相关配置

一个 commit 同时描述三个环境的变化,git log deploy/overlays/prod 就是这个环境的发布历史。跨环境对比退化成 diff 两个目录,回滚退化成一次 git revert。

2.5 漂移检测:慢三分钟,但一定会到 ​

漂移(drift)指集群实际状态偏离 Git 声明。Argo CD 把状态分成 Synced 和 OutOfSync,检测靠周期性比对(默认每 3 分钟一次,可用 timeout.reconciliation 调整)。

有两种处理姿态。selfHeal: true 让 agent 发现漂移后自动改回去;不开则只标红,等人点「Sync」。生产上还有一个中间态:对 Deployment 的 replicas 开 selfHeal,这样 HPA 扩容之后不会被拉回原值——这是最常见的一类「假漂移」。

比这更麻烦的是「合法漂移」:Service 的 clusterIP、由 cert-manager 注入的 caBundle、Istio 注入的 sidecar 容器,这些字段是集群或其它控制器写的,Git 里本来就没有。它们会被算成 OutOfSync,然后 selfHeal 会把它们删掉,把服务搞坏。解决办法是 ignoreDifferences 按 JSON Pointer 排除这些路径,而不是关掉 selfHeal。

2.6 Secrets:加密后进 Git 只是及格线 ​

明文 Secret 提交进 Git,历史里永远删不干净。三种常见做法:

方案怎么工作Git 里存什么轮换成本
Sealed Secrets控制器持私钥,kubeseal 用公钥加密加密后的 SealedSecret CRD中,要重新 seal
SOPS + age文件级加密,只有指定 age 公钥能解加密的 YAML,明文键可见低,改文件重加密
External Secrets Operator从 Vault/AWS SM 拉取,同步成 K8s Secret只有引用路径,无密文最低,改源头即可

表 8-3 三种 Secrets 管理方式的取舍

三者的区别在「密钥材料放在哪」。前两种,解密能力在集群里;第三种,真实数据在外部密钥管理系统,集群只在启动时取一次。团队有 Vault 就用第三种,没有就先用 SOPS——它不需要额外控制器,sops -e 一条命令就能把文件加密。

反例是把密钥 seal 进 Git 就以为结束了:Sealed Secrets 的加密绑定 namespace 和 name,改名之后解不开;私钥一旦丢失,所有历史密文全部作废,所以控制器的私钥必须备份,而且不能备份在同一个集群里。

三、动手实践 ​

三步:装 Argo CD、用 Application 接一个仓库、然后手工制造一次漂移看它被纠正。

3.1 安装并接入一个应用 ​

bash
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 初始管理员密码存在这个 Secret 里
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d
yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: order-api-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/acme/deploy.git
    targetRevision: main
    path: overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: order-api
  syncPolicy:
    automated:
      prune: true        # Git 里删掉的资源,集群里也删
      selfHeal: true     # 漂移自动改回
    syncOptions:
      - CreateNamespace=true
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers: ["/spec/replicas"]   # 交给 HPA

prune: true 是最需要想清楚的一项。它会把 Git 里不存在的资源从集群删掉——包括别人手工创建的、还没纳入 Git 的东西。新接入一个已有集群时,先只开 selfHeal,prune 等资源全部纳入 Git 之后再开。

运行结果:

text
$ argocd app get order-api-prod
Name:               argocd/order-api-prod
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          order-api
URL:                https://argocd.example.com/applications/order-api-prod
Source:
- Repo:             https://github.com/acme/deploy.git
  Target:           main
  Path:             overlays/prod
SyncWindow:         Sync Allowed
Sync Policy:        Automated (Prune)
Sync Status:        Synced to main (7c1f0a2)
Health Status:      Healthy

GROUP  KIND        NAMESPACE  NAME       STATUS  HEALTH
apps   Deployment  order-api  order-api  Synced  Healthy
       Service     order-api  order-api  Synced  Healthy

Synced to main (7c1f0a2) 里的 commit 号是关键信息:它让「线上跑的是哪一版」有了唯一答案。

3.2 制造一次漂移 ​

bash
kubectl -n order-api scale deployment order-api --replicas=9
sleep 200
kubectl -n order-api get deployment order-api \
  -o jsonpath='{.spec.replicas}{"\n"}'

上面这段故意用 scale 而不是改镜像,因为镜像改动会触发 Pod 重建,而副本数不会,观察起来干净。

运行结果:

text
9                       # scale 之后立刻查
...(约 3 分钟内 Argo CD 完成一次调和)
4                       # selfHeal 生效后回到 Git 声明的值

中间那三分钟是真实存在的窗口。漂移检测不是实时的,它是轮询的;想要更快可以开 webhook(Git 侧变化秒级触发),但那只能加速「Git 变了要同步」,不能加速「集群被手改了」——后者只能靠轮询周期缩短,代价是 API Server 负载。

3.3 用 ApplicationSet 铺开多集群 ​

yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: order-api-all-clusters
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            tier: production
  template:
    metadata:
      name: 'order-api-{{name}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/acme/deploy.git
        targetRevision: main
        path: 'overlays/prod'
      destination:
        server: '{{server}}'
        namespace: order-api
      syncPolicy:
        automated: {prune: true, selfHeal: true}

运行结果(集群打了 tier=production 标签的前提下):

text
$ kubectl -n argocd get applicationset order-api-all-clusters -o wide
NAME                     AGE
order-api-all-clusters   12d

$ kubectl -n argocd get applications -l tier=production
NAME                  SYNC STATUS   HEALTH STATUS
order-api-cn-east     Synced        Healthy
order-api-us-west     Synced        Healthy

新集群打上同一个标签,agent 会自动生成对应的 Application,不需要改任何 Git 文件。这也是 GitOps 与「集群清单写在 Terraform 里」的差别:后者加集群要跑一次 apply,前者只是改个标签。

四、常见误解 ​

很多人以为 GitOps 就是「用 Git 存 YAML」,实际上缺了自动拉取和持续调和,它只是把 kubectl apply 换了个地方执行。判断标准是 2.1 节那四条,尤其是后两条——没有持续调和,漂移就永远没人管。

很多人以为开了 selfHeal 就不用管了,实际上合法漂移会被它改成故障。HPA 改的副本数、cert-manager 注入的 caBundle、Istio 注入的 sidecar,这些都该进 ignoreDifferences。selfHeal 配错的典型症状是「服务刚起来好好的,三分钟后开始 503」,因为某个被注入的字段被删了。

很多人以为 Secret 加密后进 Git 就安全了,实际上加密只保护了「静止状态」。密文进了 Git,解密密钥在集群里,那么任何能读那个 Secret 的人都能拿到明文;而轮换密钥意味着重新 seal 所有文件。真正需要区分的是「谁能解密」和「多久换一次」,这两件事在选型时比加密算法更重要。

五、小结 ​

[《供应链安全:SBOM、签名与扫描》](/guide/cicd/supply-chain-security-sbom.html)保证了制品可信,这一章保证了部署行为可追溯、集群状态可复现。

  • GitOps 的四条原则里,自动拉取与持续调和是分水岭;只做到前两条,等于把脚本搬进 Git。
  • Pull 模式把集群凭据从 CI 里拿走,这是它相对 Push 的核心收益,代价是反馈延迟和状态回传要多做一步。
  • 多环境用单分支多目录加 Kustomize overlay,不用多分支;一个 commit 描述全部环境,回滚就是一次 revert。
  • 漂移检测是轮询的,通常有几分钟窗口;selfHeal 必须配合 ignoreDifferences 处理合法漂移,否则会主动制造故障。
  • Secrets 的选型看「解密能力放在哪」,不看加密算法;没有 Vault 时 SOPS + age 是成本最低的起点。

六、相关文章 ​

GitOps 把「部署」变成了「提交一个 commit」,这带来一个新问题:一个 commit 合进去,四个副本全部换成新版本,出错就是全量出错。中间缺的那一层是发布节奏——先给 5% 的流量、看指标、没问题再放大,指标崩了自动退回。[《渐进式交付:金丝雀与自动回滚》](/guide/cicd/k8s-progressive-delivery.html)就用 Argo Rollouts 把这条路径自动化,它复用这一章的 Application 与 Git 声明,只是把 Deployment 换成能按比例调权重的 Rollout。

继续阅读:[《渐进式交付:金丝雀与自动回滚》 渐进式交付:金丝雀与自动回滚](/guide/cicd/k8s-progressive-delivery.html)