GitOps 与 Argo CD、Flux 生产交付、灾备及故障排查

GitOps 不是把 YAML 放进 Git 就结束。它是一套以 Git 中声明式期望状态为依据，由控制器持续对比并收敛实际环境的交付与治理模式。生产落地还需要仓库分层、权限、密钥、环境晋级、策略校验、漂移治理、回滚、灾备和审计。本文以 Argo CD 和 Flux 的共同理念为主，给出可执行的工程方法。

自动同步、自动 Prune 和自愈都可能快速扩大错误配置的影响范围。任何生产自动化上线前，应先建立预览、审批、策略、分批发布、暂停和回滚能力。

一、GitOps 的责任边界

GitOps 适合管理 Kubernetes 声明式资源、Helm/Kustomize 配置、部分基础设施声明和平台策略。它不应直接替代：

  • 数据库事务和业务数据迁移控制；
  • 密钥生成与明文保管；
  • 需要复杂交互判断的人工处置；
  • 缺少幂等性的脚本；
  • 无法声明和验证结果的外部操作。
开发提交代码
  ↓
CI 构建、测试、扫描、签名
  ↓
更新配置仓库中的镜像摘要/版本
  ↓
GitOps 控制器拉取期望状态
  ↓
集群收敛并报告健康状态

CI 负责产生可信制品，GitOps 控制器负责部署期望状态。不要让集群在运行时重新构建应用镜像。

二、仓库模型

常见模型包括单体仓库、应用仓库与环境仓库分离、每环境独立仓库。选择依据是权限边界、团队规模和审计需求，而不是追求目录形式统一。

推荐结构示意：

platform-config/
  clusters/
    prod-a/
    prod-b/
  apps/
    payment/
      base/
      overlays/dev/
      overlays/prod/
  policies/
  bootstrap/

生产配置的合并权限应严于开发环境；变更必须能识别“谁批准、修改什么、部署到哪里”。

三、Bootstrap 与信任根

GitOps 控制器、仓库凭证、项目权限和根 Application/Kustomization 组成信任根。Bootstrap 过程需要：

  • 固定仓库与分支；
  • 最小权限部署密钥；
  • 校验 SSH Host Key 或 TLS；
  • 限制允许部署的 Namespace、Cluster 和资源类型；
  • 控制器自身配置纳入版本控制；
  • 保留离线恢复说明和紧急只读副本。

不要让所有 Application 都拥有集群管理员权限。Argo CD Project 或 Flux 的 ServiceAccount/RBAC 应按团队和环境拆分。

四、Argo CD Application 与 ApplicationSet

Application 描述源仓库、目标集群、路径和同步策略。ApplicationSet 用于按集群、目录或清单批量生成 Application。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: payment-prod
  namespace: argocd
spec:
  project: production
  source:
    repoURL: ssh://git.example/config.git
    targetRevision: main
    path: apps/payment/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: payment
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

生产不应一开始就同时开启自动同步、Prune 和 SelfHeal。先观测 Diff，再逐步自动化。

五、Flux 对象链路

Flux 常通过 Source Controller 获取 Git/OCI/Helm 源，由 Kustomize Controller 或 Helm Controller 执行收敛，并由 Notification/Image Automation 等组件补充事件和版本更新。

排障时沿依赖链检查：

flux get sources git -A
flux get kustomizations -A
flux get helmreleases -A
kubectl -n flux-system logs deploy/source-controller
kubectl -n flux-system logs deploy/kustomize-controller

不要只看最终 Pod。源拉取失败、制品校验失败、依赖未 Ready、Helm 测试失败或 RBAC 不足都会阻止收敛。

六、同步顺序、Hook 与依赖

Argo CD 支持 Sync Phase、Hook 和 Sync Wave。较小 Wave 先执行，控制器通常等待该 Wave 资源健康后再继续。Flux 可通过 dependsOn 表达 Kustomization/HelmRelease 依赖。

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "-1"

可将 Namespace/CRD 放在前面，应用放中间，验证 Job 放后面。但同步顺序不是完整工作流引擎：若数据迁移不可回滚、耗时很长或与流量切换耦合，应使用专门发布编排和明确的恢复策略。

七、健康检查与卡在 Progressing

健康判断可能因 CRD 没有标准状态、DaemonSet 无法覆盖所有节点、Job 未结束或控制器状态滞后而卡住。处理顺序：

  1. 查看 Application/Kustomization 条件；
  2. 定位第一个不健康资源；
  3. 检查 Events、Controller Logs 和 CRD Status；
  4. 确认健康脚本或内置判断是否适配资源；
  5. 仅在明确风险后设置忽略或跳过健康检查。

跳过健康检查会让后续 Wave 继续执行，也可能使真实失败不再触发预期流程，不能作为通用修复。

八、Prune 与资源删除保护

Prune 会删除 Git 中已移除但集群仍存在的资源。危险点包括 PVC、Namespace、CRD、共享 Secret、集群级 RBAC 和多应用共同管理的对象。

治理措施：

  • 关键资源使用删除确认或保护注解；
  • 一个资源只由一个 GitOps 应用负责；
  • 删除 CRD 前检查所有 CR；
  • 将状态数据与应用清单分离；
  • 对大范围删除设置人工审批窗口；
  • 预览 Diff 并检测资源数量异常变化。

九、漂移与 SelfHeal

SelfHeal 能纠正手工修改，但也可能覆盖事故中的临时止血措施。生产建议：

  • 默认禁止直接 kubectl edit；
  • 紧急操作建立 Break Glass 流程；
  • 事后把有效变更回写 Git；
  • 对 HPA、控制器自动写入字段等配置合理的 Diff Ignore；
  • 定期审计长期 OutOfSync 资源。

忽略差异应精确到字段，不能为消除红色状态而忽略整个 spec。

十、密钥管理

禁止将明文 Secret 提交 Git。常用方案：

  • External Secrets 从 Vault/KMS/云密钥服务同步；
  • Sealed Secrets 在集群内解密；
  • SOPS 加密文件并配合 KMS/PGP；
  • CSI Secret Store 挂载外部密钥。

密钥方案必须同时解决：密钥轮换、控制器高可用、审计、灾难恢复、离职账号回收和密钥材料备份。加密文件进入 Git 后，解密主密钥就是关键资产。

十一、镜像与供应链

不要使用漂移的 latest 标签。使用不可变标签或镜像摘要，并执行：

  • 构建来源记录；
  • 漏洞与恶意包扫描；
  • SBOM；
  • 镜像签名；
  • Admission 策略验证签名和仓库；
  • 生产晋级只改变可信版本引用。

自动镜像更新工具可生成提交或 PR，但不应绕过测试和审批直接修改生产。

十二、多环境晋级

推荐“同一制品逐级晋级”，而不是每个环境重新构建。开发、测试、预生产和生产之间通过 PR 或受控自动化变更镜像摘要。

环境差异只保留必要项：副本数、资源、域名、外部依赖和策略。若 Overlay 大量复制基础 YAML，环境将逐渐不可比较。

十三、回滚的真实含义

Git 回退能恢复声明配置，但不能自动撤销：

  • 已执行的数据库 DDL；
  • 已删除的数据；
  • 消息格式变化；
  • 外部 API 副作用；
  • 不兼容的持久卷内容。

发布设计应使用向后兼容 Schema、Expand/Contract、功能开关、双读写或蓝绿方案。回滚前确认旧版本能读取新数据。

十四、控制器灾备

Git 是期望状态的重要来源，但不是全部。灾备还需要：

  • 控制器安装和 Bootstrap 配置；
  • 仓库、部署密钥、签名与 KMS；
  • Argo CD 的集群注册、Projects、RBAC 和必要 Secret；
  • Flux 的源凭证与解密密钥；
  • 自定义健康检查与策略；
  • 仓库服务自身的备份与恢复。

建议定期在空集群演练：安装控制器、恢复凭证、拉取根配置、重建应用、验证流量和数据依赖。

十五、常见故障排查

仓库拉取失败

检查 DNS、代理、证书、SSH Host Key、部署密钥权限、分支和仓库限流。不要关闭证书校验作为永久方案。

OutOfSync 但看不出差异

查看 Server-Side Apply、默认字段、Mutating Webhook、资源版本和 Diff Ignore。控制器或 Operator 可能持续修改资源。

同步成功但业务不可用

GitOps 的 Synced 只表示期望状态已应用，不保证业务端到端可用。需结合 Readiness、合成探测、入口、DNS、数据库和消息队列验证。

删除卡住

检查 Finalizer、Admission、Namespace Terminating、CRD 控制器是否仍存在。不要盲目删除 Finalizer；先确认清理逻辑和外部资源。

十六、监控与审计

至少监控：同步结果和耗时、OutOfSync 数量、仓库拉取失败、控制器队列、资源健康、WebHook 延迟、Git 提交到生效的 Lead Time、回滚次数和 Break Glass 操作。

将事件发送到告警平台时附带应用、集群、Revision、变更人、Diff 与处置链接。仅提示“Sync failed”不足以行动。

十七、上线清单

  • 仓库、分支和环境权限隔离；
  • 控制器最小权限，不默认 cluster-admin；
  • 自动同步、Prune、SelfHeal 已分阶段验证；
  • 密钥不以明文进入 Git；
  • 镜像不可变且能追溯构建；
  • 发布含健康检查、流量验证和回滚边界；
  • 控制器与密钥完成空集群恢复演练；
  • 紧急变更能够暂停自动收敛并回写 Git。

参考资料

  • Argo CD Documentation：https://argo-cd.readthedocs.io/
  • Argo CD Sync Phases and Waves：https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/
  • Flux Documentation：https://fluxcd.io/flux/
  • OpenGitOps Principles：https://opengitops.dev/
Copyright © yan-jian.com 2023 - 2026 · Powered by GitBook更新时间： 2026-11-03 16:23:44

results matching ""

    No results matching ""