【K8S 运维实战】32-GitOps实践ArgoCD

GitOps 实践:ArgoCD 持续交付 从手工 kubectl apply到Git 驱动、自动同步、可回滚的部署体系写在前面你可能还在用 Jenkins/GitLab CI 构建镜像,然后一个kubectl apply -f deployment.yaml推到集群。这叫 CI 驱动部署——流水线推着集群走。问题很明显:谁改了集群配置没人知道,回滚靠人脑记 Git commit,多环境手动操作出错率高。GitOps 是另一条路:集群的状态永远由 Git 仓库定义,ArgoCD 自动拉取并同步。你改 Git,ArgoCD 改集群;集群有人偷偷 kubectl edit,ArgoCD 会自动拉回来(自愈)。这篇文章从 GitOps 四原则出发,带你落地 ArgoCD 多环境管理、渐进式交付(Argo Rollouts)、通知和 SSO,让部署从手工活变成Git 驱动的自动化闭环。核心问题部署怎么从手工 kubectl进化到Git 驱动、自动同步、可回滚的持续交付体系?一、原理剖析1.1 GitOps 四原则GitOps 不是把 kubectl 命令写进 CI pipeline那么简单,它有四个核心原则,缺一个就不完整:┌──────────────────────────────────────────────────────────────┐ │ GitOps 四原则 │ ├──────────────────┬───────────────────────────────────────────┤ │ 1. 声明式 │ 集群期望状态用声明式描述(YAML/Helm/Kust) │ │ │ 不写脚本,不写 kubectl 命令 │ ├──────────────────┼───────────────────────────────────────────┤ │ 2. 版本化 │ 所有声明存入 Git,每次变更都是一个 commit │ │ │ 回滚 git revert,审计 git log │ ├──────────────────┼───────────────────────────────────────────┤ │ 3. 自动拉取 │ 自动化系统(ArgoCD)持续拉取 Git, │ │ │ 发现差异后自动同步到集群 │ ├──────────────────┼───────────────────────────────────────────┤ │ 4. 自愈 │ 集群被手动修改后,ArgoCD 检测到 │ │ │ OutOfSync 状态,自动拉回 Git 定义的状态 │ └──────────────────┴───────────────────────────────────────────┘对比传统 CI Push 模型:传统 CI Push: Git → CI Pipeline → 构建镜像 → kubectl apply → 集群 问题: 集群状态 ≠ Git 状态;没有自愈;回滚靠人 GitOps Pull: Git → ArgoCD 拉取 → 对比集群状态 → 自动/手动同步 → 集群 优势: 集群状态 Git 状态;自愈;回滚 git revert1.2 ArgoCD 架构┌─────────────────────┐ │ Git Repositories │ │ (Helm/Kust/YAML) │ └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ Repo Server │ │ (拉取Git渲染模板) │ └──────────┬──────────┘ │ 渲染后的目标清单 ┌──────────▼──────────┐ │ Application Ctrl │◄── UI/API/CLI │ (对比目标vs实际状态) │ │ OutOfSync → Sync │ └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ Kubernetes Cluster │ │ (实际运行状态) │ └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ Notification Ctrl │ │ (Sync结果/健康变化 │ │ → Slack/Email/Webhook) │ └─────────────────────┘核心组件:Application Controller: 核心,持续对比 Git 目标状态与集群实际状态,发现差异触发 SyncRepo Server: 从 Git 仓库拉取配置,渲染 Helm/Kustomize,输出最终 YAML 清单API Server / UI: 用户交互入口,查看状态、手动同步、管理 ApplicationNotification Controller: 监听 Application 状态变化,发送通知(Slack/Email/Webhook)关键概念:Application: ArgoCD 的核心资源,定义一个 Git 仓库的某个路径 → 同步到集群的某个 namespaceSource: Git 仓库地址路径分支revision,可指定 Helm values 覆盖Project: 资源隔离边界,控制哪些 namespace/cluster/仓库可以被使用Sync Policy:auto(自动同步) /manual(手动审批) /autoprune(自动同步自动删除不在 Git 里的资源)1.3 多环境管理:App of Apps 与 ApplicationSet当你的环境从 1 个变成 5 个(dev/staging/prod 2 个区域),每个环境都要定义 Application,手动管理太痛了。App of Apps 模式:Git: argocd-apps/ ├── apps/ │ ├── dev.yaml # dev 環境的 Application 列表 │ ├── staging.yaml # staging 環境 │ └── prod.yaml # prod 環境 │ └── root.yaml # App of Apps——引用上面三个root.yaml:apiVersion:argoproj.io/v1alpha1kind:Applicationmetadata:name:root-appnamespace:argocdspec:source:repoURL:https://git.internal/argocd-appspath:appstargetRevision:maindestination:server:https://kubernetes.default.svcnamespace:argocdsyncPolicy:automated:prune:trueselfHeal:trueApplicationSet 模式(推荐):ApplicationSet 用模板生成器批量创建 Application,比 App of Apps 更灵活:ApplicationSet 工作原理: Generator(生成目标列表) Template(Application模板) 多个 Application ┌─────────────┐ ┌──────────────┐ │ Generator │ ───► │ Template │ ───► 生成 N 个 Application │ (集群列表/ │ │ (Application │ │ Git目录/ │ │ 定义模板) │ │ 環境列表) │ └──────────────┘ └─────────────┘1.4 Argo Rollouts:渐进式交付ArgoCD 负责同步,Argo Rollouts 负责怎么安全地推进新版本。Rollouts 是 Deployment 的替代品,支持金丝雀/蓝绿/渐进式发布自动化分析。Argo Rollouts 金丝雀流程: Stable (v1) ──► Canary (v2, 10%流量) │ ├─ AnalysisTemplate: 检查错误率/延迟 │ ├─ Pass → 增加到 30% 流量 │ ├─ Fail → 自动回滚到 v1 │ └─ Continue → 等待下一步 │ ├─ 30% → Analysis again → Pass │ ├─ 60% → Analysis again → Pass │ └─ 100% → Promote, v2 成为 Stable 关键组件: - Rollout: 替代 Deployment 的 CRD,定义发布策略 - AnalysisTemplate: 定义指标检查条件(Prometheus/Web/Job) - AnalysisRun: 一次实际的分析执行 - Experiment: 可在金丝雀期间运行并行实验二、实战操作2.1 ArgoCD 安装# 安装 ArgoCD(K8s 1.30 兼容版本 v2.12)kubectl create namespace argocd kubectl apply-nargocd-fhttps://raw.githubusercontent.com/argoproj/argo-cd/v2.12.0/stable/install.yaml# 获取初始 admin 密码kubectl-nargocd get secret argocd-initial-admin-secret\-ojsonpath{.data.password}|base64-d# 安装 argocd CLIcurl-sLOhttps://github.com/argoproj/argo-cd/releases/download/v2.12.0/argocd-linux-amd64chmodx argocd-linux-amd64mvargocd-linux-amd64 /usr/local/bin/argocd# 访问 UI(端口转发)kubectl port-forward svc/argocd-server-nargocd8080:443# 浏览器访问 https://localhost:8080# 登录argocd login localhost:8080--usernameadmin--password上面获取的密码2.2 ApplicationSet 多环境方案cluster-appset.yaml— 按集群生成 Application:apiVersion:argoproj.io/v1alpha1kind:ApplicationSetmetadata:name:myapp-clustersnamespace:argocdspec:generators:-list:elements:-cluster:dev-clusterurl:https://dev.k8s.internalenv:devvalues:replicaCount:1imageTag:latest-cluster:staging-clusterurl:https://staging.k8s.internalenv:stagingvalues:replicaCount:2imageTag:v2.4.1-rc1-cluster:prod-clusterurl:https://prod.k8s.internalenv:prodvalues:replicaCount:3imageTag:v2.4.1template:metadata:name:myapp-{{env}}labels:env:{{env}}spec:project:defaultsource:repoURL:https://git.internal/platform/myapp-deploytargetRevision:mainpath:helm/myapphelm:valueFiles:-values.yaml-values-{{env}}.yamlparameters:-name:replicaCountvalue:{{values.replicaCount}}-name:image.tagvalue:{{values.imageTag}}destination:server:{{url}}namespace:myappsyncPolicy:automated:prune:trueselfHeal:truesyncOptions:-CreateNamespacetrue-ServerSideApplytrueGit 目录模式生成器— 每个环境一个目录:apiVersion:argoproj.io/v1alpha1kind:ApplicationSetmetadata:name:myapp-git-dirnamespace:argocdspec:generators:-git:repoURL:https://git.internal/platform/myapp-deployrevision:maindirectories:-path:envs/*# 匹配 envs/dev、envs/staging、envs/prodtemplate:metadata:name:myapp-{{path.basename}}spec:project:defaultsource:repoURL:https://git.internal/platform/myapp-deploytargetRevision:mainpath:{{path}}destination:server:https://kubernetes.default.svcnamespace:myapp-{{path.basename}}syncPolicy:automated:prune:trueselfHeal:trueGit 仓库结构:myapp-deploy/ ├── envs/ │ ├── dev/ │ │ └── kustomization.yaml │ │ └── patch-replicas.yaml # replicas: 1 │ ├── staging/ │ │ └── kustomization.yaml │ │ └── patch-replicas.yaml # replicas: 2 │ └── prod/ │ │ └── kustomization.yaml │ │ └── patch-replicas.yaml # replicas: 3 │ │ └── patch-resources.yaml # 更大的资源限制2.3 Argo Rollouts 金丝雀发布先安装 Argo Rollouts:kubectl create namespace argo-rollouts kubectl apply-nargo-rollouts-fhttps://raw.githubusercontent.com/argoproj/argo-rollouts/v2.37.0/stable/install.yaml# 安装 kubectl argo-rollouts 插件curl-sLOhttps://github.com/argoproj/argo-rollouts/releases/download/v2.37.0/kubectl-argo-rollouts-linux-amd64chmodx ./kubectl-argo-rollouts-linux-amd64mv./kubectl-argo-rollouts-linux-amd64 /usr/local/bin/kubectl-argo-rolloutsrollout.yaml— 金丝雀发布策略:apiVersion:argoproj.io/v1alpha1kind:Rolloutmetadata:name:myapp-rolloutnamespace:myappspec:replicas:5strategy:canary:canaryService:myapp-canary# 金丝雀 ServicestableService:myapp-stable# 稳定版 ServicetrafficRouting:istio:virtualService:name:myapp-vsvcroutes:-primarydestinationRules:name:myapp-drsteps:-setWeight:10# 10% 流量到金丝雀-pause:{duration:5m}# 观察 5 分钟-analysis:templates:-templateName:error-rate-checkargs:-name:service-namevalue:myapp-canary.default.svc.cluster.local-setWeight:30# 分析通过,30% 流量-pause:{duration:5m}-analysis:templates:-templateName:latency-check-setWeight:60-pause:{duration:2m}-setWeight:100# 全量发布revisionHistoryLimit:3selector:matchLabels:app:myapptemplate:metadata:labels:app:myappspec:containers:-name:myappimage:registry.internal/company/myapp:v2.4.1ports:-containerPort:8080resources:requests:cpu:100mmemory:128MiAnalysisTemplate— 基于 Prometheus 的自动化分析:apiVersion:argoproj.io/v1alpha1kind:AnalysisTemplatemetadata:name:error-rate-checknamespace:myappspec:args:-name:service-namemetrics:-name:error-rateinterval:30scount:6# 6 次采样 3 分钟successLimit:5# 至少 5 次通过failureLimit:2# 2 次失败就中止金丝雀provider:prometheus:address:http://prometheus.monitoring:9090query:sum(rate(http_requests_total{status_code~5.., app{{args.service-name}}}[1m])) / sum(rate(http_requests_total{app{{args.service-name}}[1m]))successCondition:result[0] 0.01# 错误率 1%failureCondition:result[0] 0.05# 错误率 5%apiVersion:argoproj.io/v1alpha1kind:AnalysisTemplatemetadata:name:latency-checknamespace:myappspec:metrics:-name:p99-latencyinterval:30scount:4successLimit:3failureLimit:2provider:prometheus:address:http://prometheus.monitoring:9090query:histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket{appmyapp-canary}[1m])) by (le))successCondition:result[0] 2# P99 2秒failureCondition:result[0] 5# P99 5秒Istio VirtualService DestinationRule 配合金丝雀流量分割:apiVersion:networking.istio.io/v1beta1kind:VirtualServicemetadata:name:myapp-vsvcnamespace:myappspec:hosts:-myapp.company.comgateways:-myapp-gatewayhttp:-name:primaryroute:-destination:host:myapp-stableweight:100-destination:host:myapp-canaryweight:0apiVersion:networking.istio.io/v1beta1kind:DestinationRulemetadata:name:myapp-drnamespace:myappspec:host:myapp-stabletrafficPolicy:connectionPool:http:h2UpgradePolicy:DEFAULT操作命令:# 查看发布状态kubectl argo-rollouts get rollout myapp-rollout-nmyapp# 手动推进金丝雀(如果设了 pause)kubectl argo-rollouts promote myapp-rollout-nmyapp# 手动回滚kubectl argo-rollouts undo myapp-rollout-nmyapp# 查看分析结果kubectl argo-rollouts list analysisruns-nmyapp2.4 ArgoCD SSO/OIDC 认证生产环境不能用 admin 账号,必须接 SSO。argocd-cm.yaml— OIDC 配置(以公司内部 IdP 为例):apiVersion:v1kind:ConfigMapmetadata:name:argocd-cmnamespace:argocddata:url:https://argocd.company.comoidc.config:|name: CompanySSO issuer: https://idp.company.com/realms/platform clientID: argocd-prod clientSecret: $oidc.company.clientSecret # 引用 argocd-secret 中的值 requestedScopes: [openid, profile, email, groups] requestedIDTokenClaims: {groups: {essential: true}}RBAC 配置—argocd-rbac-cm.yaml:apiVersion:v1kind:ConfigMapmetadata:name:argocd-rbac-cmnamespace:argocddata:policy.csv:|# 管理员组:全局读写 g, platform-admins, role:admin # 开发组:只能操作 dev 環境的 Application g, dev-team, role:dev-developer # 定义自定义角色 p, role:dev-developer, applications, get, dev/*, allow p, role:dev-developer, applications, sync, dev/*, allow p, role:dev-developer, applications, create, dev/*, allow # 生产组:只能查看,不能自动同步 g, prod-team, role:prod-viewer p, role:prod-viewer, applications, get, prod/*, allow p, role:prod-viewer, applications, sync, prod/*, denypolicy.default:role:readonly2.5 通知配置argocd-notification-cm.yaml:apiVersion:v1kind:ConfigMapmetadata:name:argocd-notifications-cmnamespace:argocddata:template.app-deployed:|email: subject: [ArgoCD] {{ .app.metadata.name }} deployed to {{ .app.spec.destination.namespace }} slack: blocks: - type: section text: type: mrkdwn text: :white_check_mark: **{{ .app.metadata.name }}** synced to **{{ .app.spec.destination.namespace }}** - type: context elements: - type: mrkdwn text: Revision: {{ .app.status.operationState.syncResult.revision }} webhook: myapp-deployed: method: POST path: /deployments body: | {app: {{ .app.metadata.name }}, env: {{ .app.spec.destination.namespace }}, revision: {{ .app.status.operationState.syncResult.revision }}}trigger.on-deployed:|- description: Application deployed oncePer: app.metadata.name send: - template.app-deployed when: app.status.operationState.phase in [Succeeded]trigger.on-sync-failed:|- description: Sync failed send: - template.app-sync-failed when: app.status.operationState.phase in [Failed, Error]service.slack:|apiUrl: https://slack.com/api/chat.postMessage token: $slack-token channels: - name: argocd-deploymentsservice.email:|host: smtp.company.com port: 587 from: argocdcompany.com username: argocdcompany.com password: $email-password给 Application 添加通知订阅:apiVersion:argoproj.io/v1alpha1kind:Applicationmetadata:name:myappnamespace:argocdannotations:notifications.argoproj.io/subscribe.on-deployed.slack:argocd-deploymentsnotifications.argoproj.io/subscribe.on-sync-failed.slack:argocd-deploymentsnotifications.argoproj.io/subscribe.on-deployed.email:dev-teamcompany.comspec:# ... (Application 定义)三、踩坑与排查踩坑 1:ArgoCD Sync 成功但 Application 状态一直 Progressing现象:argocd app get myapp显示Sync Status: Synced,但Health Status: Progressing,永远不变成 Healthy。原因: ArgoCD 的 Health Check 不仅看资源是否创建成功,还看资源是否就绪。Deployment 必须所有 Pod Ready;Pod 必须所有 Container Running;Job 必须 Completed。如果你的 Pod 因为 readinessProbe 不通过而一直 Not Ready,Health 就卡在 Progressing。# 查看 ArgoCD 的健康判断逻辑kubectl get deploy myapp-nmyapp-ojsonpath{.status.conditions}# 常见问题:replicas3,availableReplicas2,updatingReplicas1解决:# 方法 1:检查 Pod 状态kubectl get pods-nmyapp-lappmyapp kubectl describe podpod-name-nmyapp|grep-A5Readiness# 方法 2:如果 Probe 配置合理但 ArgoCD 仍不识别,自定义 Health Check# argocd-cm 中添加自定义健康规则:apiVersion:v1kind:ConfigMapmetadata:name:argocd-cmnamespace:argocddata:resource.customizations.health.apps_Deployment:|hs {} if obj.status ~ nil then if obj.status.readyReplicas obj.status.replicas then hs.status Healthy hs.message All replicas ready else hs.status Progressing hs.message Waiting for replicas: .. obj.status.readyReplicas .. / .. obj.status.replicas end end return hs蹈坑 2:SelfHeal 把紧急手动修复又拉回了错误状态现象: 生产出了严重 bug,运维手动kubectl scale deployment myapp --replicas10应急,ArgoCD 检测到 OutOfSync,5 分钟后自动把 replicas 拉回 Git 里的 3,应急措施失效。原因:selfHeal: true会让 ArgoCD 在检测到任何偏差时自动同步。这在平时是好事(防止手动修改漂移),但在紧急场景下会 Undo你的应急操作。解决:# 方法 1:临时关闭自愈(推荐)# 在 Application 上加 annotation:annotations:argocd.argoproj.io/sync-options:SelfHealfalse# 方法 2:先改 Git 再让 ArgoCD 同步(最安全)# kubectl scale 后,立即在 Git 仓库改 values-prod.yaml 的 replicaCount10# ArgoCD 同步后集群状态和 Git 一致# 方法 3:使用 ArgoCD 的 Sync Window 限制自愈时间# 只在非工作时间自愈:apiVersion:argoproj.io/v1alpha1kind:AppProjectmetadata:name:defaultnamespace:argocdspec:syncWindows:-kind:allowschedule:10 1 * * *# 每天凌晨 1:10 允许同步duration:8h# 持续 8 小时applications:-name:myapp-prodmanualSync:true# 其他时间只允许手动同步踩坑 3:Argo Rollouts 金丝雀 AnalysisTemplate 查不到 Prometheus 数据现象: 金丝雀到 analysis 步骤时,AnalysisRun 一直Running不出结果,最终金丝雀超时回滚。原因: AnalysisTemplate 的 Prometheus query 写错了 service-name 变量,或者 Prometheus 在另一个集群,Argo Rollouts 网络不通。# 查看 AnalysisRun 详细状态kubectl get analysisrun-nmyapp-lrolloutsmyapp-rollout kubectl describe analysisrunanalysisrun-name-nmyapp# 常见错误: failed to query prometheus: connection refused解决:# 1. 验证 Prometheus 可达kubectl run curl-test--rm-it--restartNever--imagecurlimages/curl\--curl-shttp://prometheus.monitoring:9090/api/v1/query?queryup# 2. 验证 query 语法(在 Prometheus UI 先试)# 把 AnalysisTemplate 里的 query 拿到 Prometheus Graph 页面跑一遍# 3. 确保 args 替换正确# AnalysisTemplate 中 {{args.service-name}} 必须与 Rollout 的 analysis.args 匹配# Rollout 定义:# analysis:# templates:# - templateName: error-rate-check# args:# - name: service-name# value: myapp-canary.myapp.svc.cluster.local # 完整 DNS 名称踩坑 4:ApplicationSet 生成太多 Application 导致 ArgoCD 性能下降现象: ArgoCD UI 加载缓慢,argocd app list响应慢,Application Controller CPU 持续高。原因: ApplicationSet 的 List Generator 有 30 个集群 × 20 个应用 600 个 Application,ArgoCD 每个都要持续对比 Git 状态,API Server 扛不住。解决:# 方法 1:减少对比频率(降低 reconcile 循环)# argocd-cm:data:timeout.reconciliation:300s# 从默认 180s 改为 300s# 方法 2:用 Git Directory Generator 替代 List Generator# 让 Git 仓库结构决定 Application 数量,而不是硬编码# 方法 3:按环境拆分多个 ApplicationSet# 不要一个 AppSet 生成所有环境,每个环境一个 AppSet:# prod-appset.yaml (只管 prod)apiVersion:argoproj.io/v1alpha1kind:ApplicationSetmetadata:name:myapp-prodnamespace:argocdspec:generators:-clusters:selector:matchLabels:env:prod# 只选择 prod 集群template:# ...四、最佳实践ArgoCD 生产部署清单项目建议说明HA 部署Application Controller 3 replicas生产必须 HARedis用外部 Redis(HA)不用内置单节点 RedisRepo Server2 replicasGit 仓库压力大时需要资源限制Controller 2CPU/2Gi,Repo 1CPU/1Gi防止 OOMSSO必须接 OIDC不用 admin 密码RBAC精细到 projectnamespacedev 不能操作 prod自愈prod 环境建议 manual sync紧急修改不被 Undo通知必须配置 Slack/Email同步失败第一时间知道Git 分支prod 用 main 分支,dev 用 develop分支与环境对应资源跟踪使用 annotation-based tracking防止命名冲突Secret 管理用 Sealed Secrets / SOPSSecret 不裸放 GitGitOps 仓库结构推荐platform-deploy/ ├── argocd/ │ ├── appsets/ # ApplicationSet 定义 │ │ ├── dev.yaml │ │ ├── staging.yaml │ │ └── prod.yaml │ ├── projects/ # AppProject 定义 │ └── notifications/ # 通知模板 ├── envs/ │ ├── dev/ │ │ ├── myapp/ │ │ │ ├── kustomization.yaml │ │ │ └── patch.yaml │ ├── staging/ │ │ ├── myapp/ │ ├── prod/ │ │ ├── myapp/ ├── base/ # Kustomize 基础(所有环境共享) │ ├── myapp/ │ │ ├── deployment.yaml │ │ ├── service.yaml │ │ ├── kustomization.yamlArgo Rollouts 最佳实践金丝雀步骤必须有analysis节点,不能只靠人肉观察AnalysisTemplate 至少检查错误率和 P99 延迟两个指标failureLimit设为 2(两次失败就中止),不要设太高生产环境 Rollout 先pause,人工确认后再promoterevisionHistoryLimit设为 3,避免保留太多旧 ReplicaSet蓝绿发布比金丝雀简单但资源消耗翻倍,流量波动大的场景选金丝雀Istio/SMI trafficRouting 精确到百分比,Nginx Ingress 只能按权重近似五、小结GitOps 的核心转变是:从人推集群变成集群自己拉 Git。ArgoCD 是这个转变的落地工具——声明式 Application 定义目标,Repo Server 拉取渲染,Controller 对比同步,Notification Controller 通知结果。多环境用 ApplicationSet 模板化,金丝雀发布用 Argo Rollouts AnalysisTemplate 自动化,认证用 OIDCRBAC 分权限,通知用 SlackEmail 全覆盖。关键教训:生产的 selfHeal 不要盲目开启,紧急场景下自愈会 Undo 应急操作;AnalysisTemplate 的 Prometheus query 必须提前验证,否则金丝雀会卡死在 analysis 步骤。思考题如果你的公司有 5 个集群(dev/staging/prod-cn/prod-us/prod-eu),怎么设计 ApplicationSet 让每个集群自动生成对应环境的 Application?ArgoCD 的 selfHeal 和手动 kubectl 修改之间如何平衡?生产环境应该 auto sync 还是 manual sync?金丝雀发布的 AnalysisTemplate 除了 Prometheus,还支持 Web hook 和 Job 类型。什么场景下用 Web hook 比 Prometheus 更合适?延伸阅读ArgoCD 官方文档Argo Rollouts 官方文档ApplicationSet ControllerGitOps 原则(OpenGitOps)ArgoCD 通知ArgoCD SSO 配置