基于 ArgoCD 与 Flux 的 Kubernetes GitOps 工作流实战指南（gitops-workflow Skill 详解）

本指南以本仓库 plugins/kubernetes-operations/skills/gitops-workflow/SKILL.md 为骨架，系统讲解如何在 Kubernetes 集群中落地声明式、以 Git 为唯一事实来源的持续交付（GitOps）工作流。你将掌握 OpenGitOps 四大原则、ArgoCD 与 Flux CD 的完整安装与配置、仓库结构设计、自动化同步策略、渐进式发布（Canary / Blue-Green）、GitOps 下的密钥管理，以及排障与最佳实践，是一份可直接照抄运行的生产级操作手册。

这个 Skill 在仓库中的定位

gitops-workflow 是 kubernetes-operations 插件下的核心技能之一，与同目录下的 k8s-manifest-generator（生成生产级清单）、helm-chart-scaffolding（Helm 打包模板）以及 k8s-security-policies（安全策略）构成"清单生成 → 打包 → 安全加固 → GitOps 自动交付"的完整链路。

从仓库结构看，该 Skill 采用统一的三层组织方式（SKILL.md + references/ 参考文档）：

• SKILL.md：面向 Agent 的主技能文件，含 YAML 前置元数据（name、description 触发条件）与全部实战步骤；
• references/argocd-setup.md：ArgoCD 的安装、UI/CLI、SSO、RBAC 深入配置；
• references/sync-policies.md：同步策略、健康检查、同步选项的完整参数说明。

该技能由 kubernetes-architect Agent 主动调用（其描述明确声明 "Use PROACTIVELY for K8s architecture, GitOps implementation"），适用于：为集群搭建 GitOps、从 Git 自动化部署应用、实施渐进式交付、管理多集群部署、配置自动化同步策略、在 GitOps 中管理密钥等场景。

OpenGitOps 四大原则

GitOps 并非某一款工具的专利，而是一套以 OpenGitOps 规范 为基准的方法论。该 Skill 明确定义的四个核心原则是理解后续所有配置的前提：

1. 声明式（Declarative）：整个系统的期望状态都以声明式清单描述，不依赖命令式操作；
2. 版本化且不可变（Versioned and Immutable）：期望状态存放在 Git 中，拥有完整版本历史，可随时回滚；
3. 自动拉取（Pulled Automatically）：由软件 Agent（如 ArgoCD / Flux 的 controller）主动从 Git 拉取期望状态，而非 CI 推送；
4. 持续调谐（Continuously Reconciled）：Agent 持续观察集群实际状态，并将其向期望状态收敛。

注意区分第 3 点与经典 CI/CD 的关键差异：GitOps 采用"拉取模型"，Git 是状态源，集群侧的 controller 是执行者，CI 只负责把变更写入 Git，不再直接操作集群。kubernetes-architect 同样将这四个原则列为知识基石，并在实践建议中强调"从项目立项之初就引入 GitOps，而不是事后补充"。

ArgoCD 搭建与仓库结构设计

1. 安装 ArgoCD

SKILL.md 给出的最小安装流程：

# 创建命名空间
kubectl create namespace argocd

# 安装 ArgoCD（stable 清单）
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 获取初始 admin 密码
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

references/argocd-setup.md 提供了三种安装方式的对比：

方式	命令	适用场景
标准安装	上述 kubectl apply 清单	快速验证、小型集群
高可用安装	kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml	生产环境多副本
Helm 安装	helm repo add argo https://argoproj.github.io/argo-helm && helm install argocd argo/argo-cd -n argocd --create-namespace	与 Helm 生态统一管理

安装后访问 UI 与 CLI 的初始化步骤：

# Port-forward 访问 UI（https://localhost:8080）
kubectl port-forward svc/argocd-server -n argocd 8080:443

# 或直接取初始密码
argocd admin initial-password -n argocd

# CLI 登录
argocd login argocd.example.com --username admin

2. GitOps 仓库结构

SKILL.md 推荐的环境隔离式目录布局：

gitops-repo/
├── apps/
│   ├── production/
│   │   ├── app1/
│   │   │   ├── kustomization.yaml
│   │   │   └── deployment.yaml
│   │   └── app2/
│   └── staging/
├── infrastructure/
│   ├── ingress-nginx/
│   ├── cert-manager/
│   └── monitoring/
└── argocd/
    ├── applications/
    └── projects/

要点：

• apps/ 按环境（staging / production）再按应用组织，每个应用目录内含 Kustomize 基准与覆盖；
• infrastructure/ 集中管理集群级基础设施组件；
• argocd/ 存放 ArgoCD 自身的 Application 与 Project 定义（自托管、可版本化）。

3. 创建第一个 Application

# argocd/applications/my-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/gitops-repo
    targetRevision: main
    path: apps/production/my-app
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true      # 删除 Git 中已不存在的资源
      selfHeal: true   # 把集群中的手动改动收敛回期望状态
    syncOptions:
      - CreateNamespace=true

字段解析：source 声明"从哪个 Git 仓库的哪个分支/路径取期望状态"，destination 声明"部署到哪个集群的哪个命名空间"，syncPolicy.automated 开启自动同步（prune 负责清理、selfHeal 负责漂移修复），syncOptions.CreateNamespace=true 允许在目标命名空间不存在时自动创建。

也可通过 CLI 创建等价应用：

argocd app create my-app \
  --repo https://github.com/org/repo \
  --path apps/my-app \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace production

4. App of Apps 模式

当应用数量增多时，推荐"应用的聚合应用"（App of Apps）模式：先定义一个管理型 Application，指向 argocd/applications/ 目录，该目录下再放置各业务应用的 Application 清单，从而让"ArgoCD 管理自身"也进入 Git 版本控制。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: applications
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/gitops-repo
    targetRevision: main
    path: argocd/applications
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated: {}

该模式也是 kubernetes-architect 明确支持的仓库组织策略（App-of-apps、单仓 vs 多仓、环境提升策略），适合团队协作与多集群场景。对于多集群，references/argocd-setup.md 进一步建议使用 ApplicationSet 管理跨集群应用。

5. 生产加固：Ingress、SSO 与 RBAC

references/argocd-setup.md 提供了从"能跑"到"生产可用"的关键配置：

Ingress（HTTPS 直通，配合 cert-manager）：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: nginx
  rules:
    - host: argocd.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: argocd-server
                port:
                  number: 443
  tls:
    - hosts:
        - argocd.example.com
      secretName: argocd-secret

GitHub OAuth SSO（写入 argocd-cm ConfigMap）：

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  url: https://argocd.example.com
  dex.config: |
    connectors:
      - type: github
        id: github
        name: GitHub
        config:
          clientID: $GITHUB_CLIENT_ID
          clientSecret: $GITHUB_CLIENT_SECRET
          orgs:
          - name: my-org

RBAC（写入 argocd-rbac-cm，默认只读、按团队授权）：

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly
  policy.csv: |
    p, role:developers, applications, *, */dev, allow
    p, role:operators, applications, *, */*, allow
    g, my-org:devs, role:developers
    g, my-org:ops, role:operators

该参考文档还总结了生产建议：启用 SSO、实施 RBAC、按团队划分 Project、开启审计日志、配置通知、使用 ApplicationSet 管理多集群、实现资源 hooks、配置健康检查、用同步窗口（sync windows）做维护、用 Prometheus 指标监控。

Flux CD 搭建

1. 安装与引导（Bootstrap）

# 安装 Flux CLI
curl -s https://fluxcd.io/install.sh | sudo bash

# Bootstrap：一次性完成 GitHub 仓库创建、密钥注入与集群组件安装
flux bootstrap github \
  --owner=org \
  --repository=gitops-repo \
  --branch=main \
  --path=clusters/production \
  --personal

flux bootstrap 是 Flux 的差异化优势：一条命令即可在指定 GitHub 仓库的 clusters/production 路径下生成 flux-system 组件清单，并把部署密钥写回仓库，实现"用 GitOps 安装 GitOps"。

2. 创建 GitRepository（源）

Flux 把"源管理"与"部署"拆成两层 CRD。第一层是 GitRepository，负责按 interval 轮询拉取 Git 仓库内容：

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/org/my-app
  ref:
    branch: main

references/sync-policies.md 补充了 timeout: 60s 可选项，控制单次拉取的超时上限。

3. 创建 Kustomization（部署）

第二层是 Kustomization，消费上面的源，按 interval 周期性地把指定路径渲染并应用到集群：

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  path: ./deploy
  prune: true
  sourceRef:
    kind: GitRepository
    name: my-app

同步策略详解

"自动同步"不等于"无脑同步"，references/sync-policies.md 给出了完整的策略参数体系。

ArgoCD 自动同步与重试

syncPolicy:
  automated:
    prune: true          # 删除 Git 中已移除的资源
    selfHeal: true       # 调谐（覆盖）集群内手动改动
    allowEmpty: false    # 禁止空同步（防止误清空）
  retry:
    limit: 5             # 最多重试 5 次
    backoff:
      duration: 5s       # 初始退避 5 秒
      factor: 2          # 指数退避倍数 2
      maxDuration: 3m    # 最大退避 3 分钟

手动同步（生产推荐）

syncPolicy:
  syncOptions:
    - PrunePropagationPolicy=foreground   # 等待被删资源真正删除
    - CreateNamespace=true                # 自动创建命名空间

同步窗口（Sync Windows）

用于在维护窗口内禁止或放行同步：

syncWindows:
  - kind: allow
    schedule: "0 8 * * *"   # 每天 8 点允许
    duration: 1h
    applications:
      - my-app
  - kind: deny
    schedule: "0 22 * * *"  # 每天 22 点起拒绝 8 小时
    duration: 8h
    applications:
      - "*"

Flux 同步参数

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
spec:
  interval: 5m
  prune: true
  wait: true          # 等待资源就绪再继续
  timeout: 5m         # 单次应用超时
  retryInterval: 1m   # 失败后重试间隔
  force: false        # 是否强制替换（含冲突资源）

常用同步选项速查

选项	含义
PrunePropagationPolicy=foreground	等待被剪除资源完成删除
CreateNamespace=true	自动创建目标命名空间
Validate=false	跳过 kubectl 校验（慎用）
PruneLast=true	先同步再剪除
RespectIgnoreDifferences=true	尊重 ignoreDifferences 配置
ApplyOutOfSyncOnly=true	只应用不同步的资源

同步策略的核心取舍是：非生产环境用全自动（prune + selfHeal），生产环境要求手动审批、配合同步窗口、谨慎使用 prune。

自定义健康检查

对自定义 CRD，可借助 ArgoCD 的资源自定义健康检查（Lua 脚本）判断资源真实健康状态：

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  resource.customizations.health.MyCustomResource: |
    hs = {}
    if obj.status ~= nil then
      if obj.status.conditions ~= nil then
        for i, condition in ipairs(obj.status.conditions) do
          if condition.type == "Ready" and condition.status == "False" then
            hs.status = "Degraded"
            hs.message = condition.message
            return hs
          end
          if condition.type == "Ready" and condition.status == "True" then
            hs.status = "Healthy"
            hs.message = condition.message
            return hs
          end
        end
      end
    end
    hs.status = "Progressing"
    hs.message = "Waiting for status"
    return hs

逻辑解析：遍历 status.conditions，按 Ready 条件的真假映射为 Degraded / Healthy，否则返回 Progressing。这保证 ArgoCD 的同步状态判断与真实业务就绪状态一致。

渐进式交付（Progressive Delivery）

Canary 部署（ArgoCD Rollouts）

Argo Rollouts 用 Rollout 替代 Deployment，通过流量权重阶梯式放量，逐步放大新版本：

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: my-app
spec:
  replicas: 5
  strategy:
    canary:
      steps:
        - setWeight: 20            # 先放 20% 流量
        - pause: { duration: 1m }  # 观察 1 分钟
        - setWeight: 50            # 放到 50%
        - pause: { duration: 2m }  # 再观察 2 分钟
        - setWeight: 100           # 全量

Blue-Green 部署

strategy:
  blueGreen:
    activeService: my-app           # 当前服务
    previewService: my-app-preview  # 预览服务
    autoPromotionEnabled: false     # 关闭自动切换，人工确认

autoPromotionEnabled: false 意味着新版就绪后需要人工触发切换，适合高风险应用。这与 kubernetes-architect 中"渐进式交付与安全部署实践"（Argo Rollouts、Flagger、canary、blue/green、A/B）的能力定位一致。

GitOps 下的密钥管理

Git 中不应存放明文密钥，SKILL.md 给出了两条主流路径：

方案一：External Secrets Operator（推荐，密钥不入 Git）

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: db-credentials
spec:
  refreshInterval: 1h              # 每小时刷新一次
  secretStoreRef:
    name: aws-secrets-manager      # 指向 SecretStore
    kind: SecretStore
  target:
    name: db-credentials           # 生成的 Kubernetes Secret 名
  data:
    - secretKey: password          # 目标 Secret 的键
      remoteRef:
        key: prod/db/password      # 外部存储中的键

原理：明文只存在于外部密钥存储（AWS Secrets Manager、Vault 等），Git 仓库中仅保存"引用关系"，由 controller 周期性拉取并生成集群内 Secret。SKILL.md 的最佳实践明确要求"把密钥排除在 Git 之外（使用 External Secrets）"。

方案二：Sealed Secrets（加密后入 Git）

# 用集群公钥加密 secret
kubeseal --format yaml < secret.yaml > sealed-secret.yaml

# 把 sealed-secret.yaml 提交到 Git（明文永不出现在仓库）

kubeseal 使用集群内私钥在控制器侧解密，仓库中只保存加密后的 SealedSecret，兼顾"Git 可审计"与"密钥安全"。

最佳实践清单

SKILL.md 归纳的 10 条实践：

1. 不同环境使用独立仓库或分支；
2. 为 Git 仓库实施 RBAC；
3. 为同步失败开启通知；
4. 为自定义资源配置健康检查；
5. 生产环境实施审批门禁；
6. 密钥不入 Git（使用 External Secrets）；
7. 使用 App of Apps 模式组织应用；
8. 发布打标签（Tag），便于快速回滚；
9. 用告警监控同步状态；
10. 先在 staging 验证再上生产。

references/sync-policies.md 额外强调：非生产用自动同步、生产要求手动审批、用同步窗口做维护、为自定义资源实现健康检查、大应用使用选择性同步、配置合理的重试策略、用告警监控同步失败、生产环境谨慎使用 prune、先在 staging 验证同步策略、向团队文档化同步行为。

排障指南

同步失败：

argocd app get my-app
argocd app sync my-app --prune

状态不一致（Out of sync）：

argocd app diff my-app
argocd app sync my-app --force

排查思路：先 get 查看同步/健康状态，diff 定位漂移差异，--prune 处理废弃资源，--force 用于强制收敛（慎用，会直接覆盖集群差异）。配合前文的通知告警，可以第一时间发现同步异常。

与相邻技能的协作

本 Skill 的 Related Skills 指向仓库内的两个兄弟技能，构成完整流水线：

• k8s-manifest-generator：负责生成生产级 Deployment / Service / ConfigMap / Secret 清单——GitOps 仓库的"原料"；
• helm-chart-scaffolding：负责 Helm chart 的模板化与打包，其 SKILL 中同样将 gitops-workflow 列为自动化部署的后续步骤。

此外，k8s-security-policies 负责集群安全加固，其 SKILL 也将 gitops-workflow 列为"策略的自动化部署通道"。实际落地时，通常先用 manifest-generator 产出清单，再用 helm-chart-scaffolding 打包，最后统一交给本 Skill 的 ArgoCD / Flux 自动交付。

小结

本文完整继承了 gitops-workflow Skill 的实操骨架，并借助 references/argocd-setup.md 与 references/sync-policies.md 补齐了安装方式对比、Ingress / SSO / RBAC 生产加固、同步窗口、健康检查 Lua 脚本等纵深细节。按上述步骤操作，即可在集群中落地一套"Git 声明期望状态 → controller 自动拉取 → 持续调谐 → 渐进式放量 → 密钥安全托管"的完整 GitOps 体系。