implementing-gitops

GitOps 工作流

使用声明式、拉取式部署模型为 Kubernetes 实现 GitOps 持续交付，其中 Git 是基础设施和应用配置的唯一事实来源。

适用场景

在以下场景中使用 GitOps 工作流：

• Kubernetes 部署： 自动将应用和基础设施部署到 Kubernetes 集群
• 多集群管理： 管理开发、预发布、生产和边缘集群中的部署
• 持续交付： 实现具有自动协调功能的拉取式 CD 流水线
• 漂移检测： 自动检测并纠正与期望状态不一致的配置漂移
• 审计要求： 通过 Git 提交保留完整审计跟踪，以满足合规要求
• 渐进式交付： 实现 Canary、蓝绿或滚动部署策略
• 灾难恢复： 通过 GitOps 引导流程实现集群快速恢复

触发关键词：“部署到 Kubernetes”、“ArgoCD 设置”、“Flux 引导”、“GitOps 流水线”、“环境晋级”、“多集群部署”、“自动协调”

GitOps 核心原则

1. Git 是唯一事实来源

所有系统配置都存储在 Git 仓库中。不手动运行 kubectl apply，也不直接修改集群。使用声明式清单（YAML）定义所有 Kubernetes 资源、特定环境的覆盖配置、基础设施配置和应用部署。

2. 拉取式部署

在集群内运行的 Operator 从 Git 拉取变更并自动应用。其优势包括：CI/CD 流水线中无需存放集群凭据、支持隔离网络环境、通过持续协调实现自我修复，以及简化 CI/CD。

3. 自动协调

GitOps Operator 持续比较集群的实际状态与 Git 中的期望状态，并通过持续循环协调差异：监视 Git、比较实时状态、应用差异、报告状态，然后重复。

4. 声明式配置

使用声明式 Kubernetes 清单（而不是命令式脚本）定义期望状态。

工具选择

ArgoCD 与 Flux

决策因素	选择 ArgoCD	选择 Flux
团队偏好	通过 Web UI 进行可视化管理	以 CLI/API 为先的工作流
学习曲线	借助 UI 更容易上手	学习门槛较高，但更灵活
架构	单体、有状态控制器	模块化、无状态控制器
多租户	内置 RBAC 和项目	Kubernetes 原生 RBAC
资源使用量	较高（包含 UI 组件）	较低（控制器精简）
最适合	过渡到 GitOps	平台工程

混合方式： 一些团队使用 Flux 管理基础设施，使用 ArgoCD 管理应用。

ArgoCD 实现模式请参见 references/argocd-patterns.md Flux 实现模式请参见 references/flux-patterns.md Kustomize 覆盖配置模式请参见 references/kustomize-overlays.md

快速入门

安装 ArgoCD

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

基础应用：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/repo.git
    targetRevision: HEAD
    path: k8s/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Flux 引导

flux bootstrap github \
  --owner=myorg \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production

基础 Kustomization：

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: myapp
  namespace: flux-system
spec:
  interval: 10m
  path: "./k8s/prod"
  prune: true
  sourceRef:
    kind: GitRepository
    name: myapp

完整示例请参见 examples/argocd/ 和 examples/flux/

环境晋级

基于分支的策略： dev 分支 → staging 分支 → main 分支（prod） 基于 Kustomize 的策略： k8s/base/ → k8s/overlays/{dev,staging,prod}/

晋级流程：

1. 将代码变更合并到 main 分支
2. CI 构建带有标签的容器镜像
3. 更新环境覆盖配置中的镜像标签（Git 提交）
4. GitOps Operator 检测到变更并进行部署
5. 在环境中测试
6. 通过更新 Git 晋级到下一个环境

多环境 ApplicationSet 模式请参见 references/argocd-patterns.md

多集群管理

ArgoCD： 使用 argocd CLI 注册外部集群，使用 ApplicationSets 为每个集群生成 Application，并通过单个 ArgoCD 实例进行管理。

Flux： 在每个集群中引导 Flux，使用同一个 Git 仓库并为各集群配置专属路径，通过 kubeConfig 密钥配置远程集群。

多集群模式详见 references/multi-cluster.md

渐进式交付

金丝雀部署： 逐步将流量切换到新版本，在发布期间监控指标，并在发生故障时自动回滚。

蓝绿部署： 与旧版本并行部署新版本，原子性地切换流量，并在检测到问题时立即回滚。

ArgoCD： 使用 Argo Rollouts 实现渐进式交付 Flux： 集成 Flagger 进行自动化金丝雀分析

渐进式交付策略和 Argo Rollouts 示例详见 references/progressive-delivery.md

密钥管理

GitOps 要求将配置存储在 Git 中，但必须保护密钥。

工具	方式	安全性	复杂度
Sealed Secrets	为 Git 中的密钥加密	中	低
SOPS	使用 KMS 加密文件	高	中
External Secrets	引用外部保险库	高	中
HashiCorp Vault	集中管理密钥	很高	高

密钥管理集成模式详见 references/secret-management.md

漂移检测与修复

GitOps 运算符会持续监控 Git（期望状态）与集群（实际状态）之间的漂移。

ArgoCD 自动自我修复：

syncPolicy:
  automated:
    prune: true      # Remove resources not in Git
    selfHeal: true   # Revert manual changes

Flux 自动协调：

spec:
  interval: 10m    # Check every 10 minutes
  prune: true      # Remove resources not in Git
  force: true      # Force apply on conflicts

手动操作：

# ArgoCD
argocd app get myapp           # View sync status
argocd app diff myapp          # Show differences
argocd app sync myapp          # Manually trigger sync

# Flux
flux get kustomizations              # View sync status
flux reconcile kustomization myapp   # Force immediate sync

漂移检测策略和故障排查详见 references/drift-remediation.md

同步钩子与生命周期

使用钩子在同步前后执行操作。

PreSync 钩子（数据库迁移）：

apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded

PostSync 钩子（冒烟测试）：

apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/hook: PostSync

完整的同步钩子示例请参阅 examples/argocd/sync-hooks.yaml

监控与可观测性

关键指标

• 同步状态： OutOfSync、Synced、Unknown
• 同步频率： 协调发生的频率
• 漂移检测： 检测到配置漂移所需的时间
• 同步时长： 应用更改所需的时间
• 故障率： 同步失败次数及原因

ArgoCD 指标： 在 /metrics 端点公开（argocd_app_sync_total、argocd_app_info） Flux 指标： 来自控制器（gotk_reconcile_condition、gotk_reconcile_duration_seconds）

故障排查

常见问题

同步卡住/OutOfSync：

• 检查是否可以访问 Git 仓库
• 验证清单是否为有效 YAML
• 查看同步日志中的错误
• 检查资源终结器

自我修复不起作用：

• 验证 syncPolicy 中已启用 selfHeal
• 检查运算符是否具有写入权限
• 查看资源所有权标签

密钥无法解密：

• 验证是否已安装 SOPS/ESO 控制器
• 检查 KMS/Vault 凭据
• 查看加密密钥配置

CLI 快速参考

ArgoCD 命令

argocd app create <name>          # Create application
argocd app get <name>              # View status
argocd app sync <name>             # Trigger sync
argocd app diff <name>             # Show drift
argocd app list                    # List all applications

Flux 命令

flux create source git <name>      # Create Git source
flux create kustomization <name>   # Create kustomization
flux get all                       # View all resources
flux reconcile <kind> <name>       # Force reconciliation
flux logs                          # View controller logs

Kustomize 命令

kustomize build k8s/overlays/prod  # Preview generated YAML
kubectl apply -k k8s/overlays/prod # Apply directly
kubectl diff -k k8s/overlays/prod  # Show differences

安装脚本

使用提供的安装脚本快速完成设置：

# Install ArgoCD
./scripts/install-argocd.sh

# Bootstrap Flux
export GITHUB_TOKEN=<token>
export GITHUB_OWNER=<org>
export GITHUB_REPO=fleet-infra
./scripts/install-flux.sh

# Check for drift
./scripts/check-drift.sh

# Promote environment
./scripts/promote-env.sh dev staging

示例文件

examples/ 目录中提供了可运行的完整示例：

ArgoCD 示例：

• examples/argocd/application.yaml - 基本应用
• examples/argocd/applicationset.yaml - 多环境 ApplicationSet
• examples/argocd/progressive-rollout.yaml - 渐进式发布策略
• examples/argocd/sync-hooks.yaml - PreSync/PostSync 钩子

Flux 示例：

• examples/flux/gitrepository.yaml - Git 源配置
• examples/flux/kustomization.yaml - Kustomization 控制器
• examples/flux/helmrelease.yaml - Helm 发布管理
• examples/flux/ocirepository.yaml - OCI 制品源

Kustomize 示例：

• examples/kustomize/base/ - 基础配置
• examples/kustomize/overlays/{dev,staging,prod}/ - 环境覆盖配置

Rollout 示例：

• examples/rollouts/canary.yaml - 使用 Argo Rollouts 的金丝雀部署
• examples/rollouts/blue-green.yaml - 蓝绿部署策略

相关技能

• kubernetes-operations： Kubernetes 基础知识和资源管理
• infrastructure-as-code： 预配 GitOps 部署到的集群
• building-ci-pipelines： CI 构建镜像，GitOps 部署镜像
• secret-management： 将 Vault/ESO 与 GitOps 集成
• deploying-applications： 将 GitOps 用作部署机制

总结

GitOps 以 Git 为唯一真实来源，为 Kubernetes 提供自动化、声明式的持续交付。可根据需求选择 ArgoCD（以 UI 驱动的工作流）或 Flux（以 CLI/API 为先）。实施自动协调、漂移检测和渐进式交付，实现可靠的大规模部署。集成密钥管理、多集群编排和灾难恢复，构建生产级 GitOps 工作流。