Back to Details

implementing-gitops

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitOps Workflows

GitOps工作流

Implement GitOps continuous delivery for Kubernetes using declarative, pull-based deployment models where Git serves as the single source of truth for infrastructure and application configuration.
为Kubernetes实现GitOps持续交付，采用声明式、基于拉取的部署模型，其中Git作为基础设施和应用配置的唯一可信源。

When to Use

适用场景

Use GitOps workflows for:
  • Kubernetes Deployments: Automating application and infrastructure deployments to Kubernetes clusters
  • Multi-Cluster Management: Managing deployments across development, staging, production, and edge clusters
  • Continuous Delivery: Implementing pull-based CD pipelines with automated reconciliation
  • Drift Detection: Automatically detecting and correcting configuration drift from desired state
  • Audit Requirements: Maintaining complete audit trails via Git commits for compliance
  • Progressive Delivery: Implementing canary, blue-green, or rolling deployment strategies
  • Disaster Recovery: Enabling rapid cluster recovery with GitOps bootstrap processes
Trigger keywords: "deploy to Kubernetes", "ArgoCD setup", "Flux bootstrap", "GitOps pipeline", "environment promotion", "multi-cluster deployment", "automated reconciliation"
GitOps工作流适用于：
  • Kubernetes部署： 自动化应用和基础设施到Kubernetes集群的部署
  • 多集群管理： 管理开发、预发布、生产和边缘集群的部署
  • 持续交付： 实现带有自动调和的基于拉取的CD流水线
  • 漂移检测： 自动检测并纠正配置与期望状态的偏差
  • 审计合规： 通过Git提交维护完整的审计轨迹以满足合规要求
  • 渐进式交付： 实现金丝雀、蓝绿或滚动发布策略
  • 灾难恢复： 通过GitOps引导流程实现快速集群恢复
触发关键词："部署到Kubernetes"、"ArgoCD配置"、"Flux引导"、"GitOps流水线"、"环境升级"、"多集群部署"、"自动调和"

Core GitOps Principles

GitOps核心原则

1. Git as Single Source of Truth

1. Git作为唯一可信源

All system configuration stored in Git repositories. No manual kubectl apply or cluster modifications. Declarative manifests (YAML) for all Kubernetes resources, environment-specific overlays, infrastructure configuration, and application deployments.
所有系统配置存储在Git仓库中。禁止手动执行kubectl apply或修改集群。所有Kubernetes资源、环境特定覆盖层、基础设施配置和应用部署均使用声明式清单（YAML）定义。

2. Pull-Based Deployment

2. 基于拉取的部署

Operators running inside clusters pull changes from Git and apply them automatically. Benefits include no cluster credentials in CI/CD pipelines, support for air-gapped environments, self-healing through continuous reconciliation, and simplified CI/CD.
运行在集群内部的Operator从Git拉取变更并自动应用。优势包括CI/CD流水线中无需存储集群凭证、支持离线环境、通过持续调和实现自修复、简化CI/CD流程。

3. Automated Reconciliation

3. 自动调和

GitOps operators continuously compare actual cluster state with desired state in Git and reconcile differences through a continuous loop: watch Git, compare live state, apply differences, report status, repeat.
GitOps Operator持续比较集群实际状态与Git中的期望状态，并通过循环实现调和：监听Git、对比实时状态、应用差异、报告状态、重复执行。

4. Declarative Configuration

4. 声明式配置

Use declarative Kubernetes manifests (not imperative scripts) to define desired state.
使用声明式Kubernetes清单（而非命令式脚本）定义期望状态。

Tool Selection

工具选择

ArgoCD vs Flux

ArgoCD vs Flux

Decision FactorChoose ArgoCDChoose Flux
Team PreferenceVisual management with web UICLI/API-first workflows
Learning CurveEasier onboarding with UISteeper but more flexible
ArchitectureMonolithic, stateful controllerModular, stateless controllers
Multi-TenancyBuilt-in RBAC and projectsKubernetes-native RBAC
Resource UsageHigher (includes UI components)Lower (minimal controllers)
Best ForTransitioning to GitOpsPlatform engineering
Hybrid Approach: Some teams use Flux for infrastructure and ArgoCD for applications.
For ArgoCD implementation patterns, see references/argocd-patterns.md For Flux implementation patterns, see references/flux-patterns.md For Kustomize overlay patterns, see references/kustomize-overlays.md
决策因素选择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

Quick Start

快速开始

ArgoCD Installation

ArgoCD安装

bash
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
Basic Application:
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
bash
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
基础应用示例：
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 Bootstrap

Flux引导

bash
flux bootstrap github \
  --owner=myorg \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production
Basic Kustomization:
yaml
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
For complete examples, see examples/argocd/ and examples/flux/
bash
flux bootstrap github \
  --owner=myorg \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production
基础Kustomization示例：
yaml
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/

Environment Promotion

环境升级

Branch-Based Strategy: dev branch → staging branch → main branch (prod) Kustomize-Based Strategy: k8s/base/ → k8s/overlays/{dev,staging,prod}/
Promotion Process:
  1. Merge code changes to main branch
  2. CI builds container image with tag
  3. Update image tag in environment overlay (Git commit)
  4. GitOps operator detects change and deploys
  5. Test in environment
  6. Promote to next environment by updating Git
For multi-environment ApplicationSet patterns, see references/argocd-patterns.md
基于分支的策略： dev分支 → staging分支 → main分支（生产） 基于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

Multi-Cluster Management

多集群管理

ArgoCD: Register external clusters with argocd CLI, use ApplicationSets to generate Applications per cluster, manage from single ArgoCD instance.
Flux: Bootstrap Flux per cluster, use same Git repo with cluster-specific paths, configure remote clusters via kubeConfig secrets.
For detailed multi-cluster patterns, see references/multi-cluster.md
ArgoCD： 使用argocd CLI注册外部集群，通过ApplicationSet为每个集群生成Application，从单个ArgoCD实例进行管理。
Flux： 为每个集群引导Flux，使用同一Git仓库的集群特定路径，通过kubeConfig配置文件的Secret管理远程集群。
详细多集群模式请参考references/multi-cluster.md

Progressive Delivery

渐进式交付

Canary Deployments: Gradually shift traffic to new version, monitor metrics during rollout, automated rollback on failures.
Blue-Green Deployments: Deploy new version alongside old, switch traffic atomically, instant rollback if issues detected.
ArgoCD: Use Argo Rollouts for progressive delivery Flux: Integrate Flagger for automated canary analysis
For progressive delivery strategies and Argo Rollouts examples, see references/progressive-delivery.md
金丝雀部署： 逐步将流量切换到新版本，在发布过程中监控指标，出现故障时自动回滚。
蓝绿部署： 在旧版本旁部署新版本，原子性切换流量，若检测到问题可立即回滚。
ArgoCD： 使用Argo Rollouts实现渐进式交付 Flux： 集成Flagger实现自动化金丝雀分析
渐进式交付策略和Argo Rollouts示例请参考references/progressive-delivery.md

Secret Management

密钥管理

GitOps requires storing configuration in Git, but secrets must be protected.
ToolApproachSecurityComplexity
Sealed SecretsEncrypt secrets for GitMediumLow
SOPSEncrypt files with KMSHighMedium
External SecretsReference external vaultsHighMedium
HashiCorp VaultCentral secret managementVery HighHigh
For secret management integration patterns, see references/secret-management.md
GitOps要求配置存储在Git中，但密钥必须受到保护。
工具实现方式安全性复杂度
Sealed Secrets加密密钥后存储到Git中等低
SOPS使用KMS加密文件高中等
External Secrets引用外部密钥库高中等
HashiCorp Vault集中式密钥管理极高高
密钥管理集成模式请参考references/secret-management.md

Drift Detection and Remediation

漂移检测与修复

GitOps operators continuously monitor for drift between Git (desired state) and cluster (actual state).
ArgoCD Automatic Self-Healing:
yaml
syncPolicy:
  automated:
    prune: true      # Remove resources not in Git
    selfHeal: true   # Revert manual changes
Flux Automatic Reconciliation:
yaml
spec:
  interval: 10m    # Check every 10 minutes
  prune: true      # Remove resources not in Git
  force: true      # Force apply on conflicts
Manual Operations:
bash
undefined
GitOps Operator持续监控Git（期望状态）与集群（实际状态）之间的配置漂移。
ArgoCD自动自修复：
yaml
syncPolicy:
  automated:
    prune: true      # 删除Git中不存在的资源
    selfHeal: true   # 还原手动变更
Flux自动调和：
yaml
spec:
  interval: 10m    # 每10分钟检查一次
  prune: true      # 删除Git中不存在的资源
  force: true      # 冲突时强制应用
手动操作：
bash
undefined

ArgoCD

ArgoCD

argocd app get myapp # View sync status argocd app diff myapp # Show differences argocd app sync myapp # Manually trigger sync
argocd app get myapp # 查看同步状态 argocd app diff myapp # 显示差异 argocd app sync myapp # 手动触发同步

Flux

Flux

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

For drift detection strategies and troubleshooting, see references/drift-remediation.md
flux get kustomizations # 查看同步状态 flux reconcile kustomization myapp # 强制立即调和 flux logs # 查看控制器日志

漂移检测策略与故障排查请参考references/drift-remediation.md

Sync Hooks and Lifecycle

同步钩子与生命周期

Execute operations before/after syncs using hooks.
PreSync Hook (Database Migration):
yaml
apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
PostSync Hook (Smoke Test):
yaml
apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/hook: PostSync
For complete sync hook examples, see examples/argocd/sync-hooks.yaml
使用钩子在同步前后执行操作。
PreSync钩子（数据库迁移）：
yaml
apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
PostSync钩子（冒烟测试）：
yaml
apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/hook: PostSync
完整同步钩子示例请查看examples/argocd/sync-hooks.yaml

Monitoring and Observability

监控与可观测性

Key Metrics

关键指标

  • Sync Status: OutOfSync, Synced, Unknown
  • Sync Frequency: How often reconciliation occurs
  • Drift Detection: Time to detect configuration drift
  • Sync Duration: Time to apply changes
  • Failure Rate: Failed syncs and causes
ArgoCD Metrics: Exposed at 
/metrics
endpoint (
argocd_app_sync_total
, 
argocd_app_info
) Flux Metrics: From controllers (
gotk_reconcile_condition
, 
gotk_reconcile_duration_seconds
)
  • 同步状态： OutOfSync、Synced、Unknown
  • 同步频率： 调和执行的频次
  • 漂移检测： 检测配置漂移的时间
  • 同步时长： 应用变更所需的时间
  • 失败率： 同步失败的次数及原因
ArgoCD指标： 在
/metrics
端点暴露（
argocd_app_sync_total
、
argocd_app_info
） Flux指标： 来自控制器（
gotk_reconcile_condition
、
gotk_reconcile_duration_seconds
）

Troubleshooting

故障排查

Common Issues

常见问题

Sync Stuck/OutOfSync:
  • Check Git repository accessibility
  • Verify manifests are valid YAML
  • Review sync logs for errors
  • Check resource finalizers
Self-Heal Not Working:
  • Verify selfHeal enabled in syncPolicy
  • Check operator has write permissions
  • Review resource ownership labels
Secrets Not Decrypting:
  • Verify SOPS/ESO controllers installed
  • Check KMS/Vault credentials
  • Review encryption key configuration
同步停滞/OutOfSync：
  • 检查Git仓库的可访问性
  • 验证清单是否为有效的YAML格式
  • 查看同步日志中的错误信息
  • 检查资源的终结器（Finalizer）
自修复功能不生效：
  • 验证syncPolicy中是否启用了selfHeal
  • 检查Operator是否有写入权限
  • 查看资源的所有权标签
密钥无法解密：
  • 验证SOPS/ESO控制器是否已安装
  • 检查KMS/密钥库的凭证
  • 查看加密密钥配置

CLI Quick Reference

CLI快速参考

ArgoCD Commands

ArgoCD命令

bash
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
bash
argocd app create <name>          # 创建应用
argocd app get <name>              # 查看状态
argocd app sync <name>             # 触发同步
argocd app diff <name>             # 显示漂移
argocd app list                    # 列出所有应用

Flux Commands

Flux命令

bash
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
bash
flux create source git <name>      # 创建Git源
flux create kustomization <name>   # 创建Kustomization
flux get all                       # 查看所有资源
flux reconcile <kind> <name>       # 强制调和
flux logs                          # 查看控制器日志

Kustomize Commands

Kustomize命令

bash
kustomize build k8s/overlays/prod  # Preview generated YAML
kubectl apply -k k8s/overlays/prod # Apply directly
kubectl diff -k k8s/overlays/prod  # Show differences
bash
kustomize build k8s/overlays/prod  # 预览生成的YAML
kubectl apply -k k8s/overlays/prod # 直接应用
kubectl diff -k k8s/overlays/prod  # 显示差异

Installation Scripts

安装脚本

Use the provided installation scripts for quick setup:
bash
undefined
使用提供的安装脚本快速搭建环境：
bash
undefined

Install ArgoCD

安装ArgoCD

./scripts/install-argocd.sh
./scripts/install-argocd.sh

Bootstrap Flux

引导Flux

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

Check for drift

检查漂移

./scripts/check-drift.sh
./scripts/check-drift.sh

Promote environment

升级环境

./scripts/promote-env.sh dev staging
undefined
./scripts/promote-env.sh dev staging
undefined

Example Files

示例文件

Complete working examples provided in examples/ directory:
ArgoCD Examples:
  • examples/argocd/application.yaml - Basic Application
  • examples/argocd/applicationset.yaml - Multi-environment ApplicationSet
  • examples/argocd/progressive-rollout.yaml - Progressive rollout strategy
  • examples/argocd/sync-hooks.yaml - PreSync/PostSync hooks
Flux Examples:
  • examples/flux/gitrepository.yaml - Git source configuration
  • examples/flux/kustomization.yaml - Kustomization controller
  • examples/flux/helmrelease.yaml - Helm release management
  • examples/flux/ocirepository.yaml - OCI artifact source
Kustomize Examples:
  • examples/kustomize/base/ - Base configuration
  • examples/kustomize/overlays/{dev,staging,prod}/ - Environment overlays
Rollout Examples:
  • examples/rollouts/canary.yaml - Canary deployment with Argo Rollouts
  • examples/rollouts/blue-green.yaml - Blue-green deployment strategy
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}/ - 环境覆盖层
发布示例：
  • examples/rollouts/canary.yaml - 使用Argo Rollouts的金丝雀部署
  • examples/rollouts/blue-green.yaml - 蓝绿部署策略

Related Skills

相关技能

  • kubernetes-operations: Kubernetes fundamentals and resource management
  • infrastructure-as-code: Provisioning clusters that GitOps deploys to
  • building-ci-pipelines: CI builds images, GitOps deploys them
  • secret-management: Vault/ESO integration with GitOps
  • deploying-applications: GitOps as the deployment mechanism
  • kubernetes-operations： Kubernetes基础与资源管理
  • infrastructure-as-code： 为GitOps部署提供集群的基础设施即代码
  • building-ci-pipelines： CI构建镜像，GitOps负责部署
  • secret-management： 密钥库/ESO与GitOps的集成
  • deploying-applications： 将GitOps作为部署机制

Summary

总结

GitOps provides automated, declarative continuous delivery for Kubernetes with Git as the single source of truth. Choose ArgoCD for UI-driven workflows or Flux for CLI/API-first approaches. Implement automated reconciliation, drift detection, and progressive delivery for reliable deployments at scale. Integrate secret management, multi-cluster orchestration, and disaster recovery for production-grade GitOps workflows.
GitOps为Kubernetes提供了自动化、声明式的持续交付能力，以Git作为唯一可信源。UI驱动的工作流选择ArgoCD，CLI/API优先的场景选择Flux。实现自动调和、漂移检测和渐进式交付，以实现大规模的可靠部署。集成密钥管理、多集群编排和灾难恢复，构建生产级别的GitOps工作流。