Argo CD：Kubernetes GitOps 持续交付

Argo CD 是面向 Kubernetes 的 GitOps 持续交付工具。Git 仓库保存应用的期望状态，Argo CD 比较 Git 与集群实际状态，并按人工或自动策略进行同步。

GitLab CI：测试代码 → 构建并推送镜像 → 更新部署仓库中的镜像版本
                                              ↓
Argo CD：读取 Git 中的 Helm/Manifest → 对比集群 → Sync → 健康检查

这样 CI 不需要持有集群管理员 kubeconfig。发布审批、版本历史和回滚入口都落在 Git 变更中。

Argo CD 管理的是 Kubernetes 期望状态。开始前应先掌握 Kubernetes 对象与 Manifest 和 Helm，并能用 Kubernetes 故障排查 区分“同步失败”与“应用运行失败”。

核心概念

概念	作用
Application	定义 Git 来源、目标集群、Namespace 和同步策略
AppProject	限制 Application 可使用的仓库、集群、Namespace 和资源类型
Sync	将 Git 期望状态应用到集群
Sync Status	Synced 或 OutOfSync，表示 Git 与集群是否一致
Health Status	Healthy、Progressing、Degraded 等运行健康状态
Prune	删除 Git 中已移除、但集群仍存在的受管资源
Self Heal	发现集群被手工改动后恢复为 Git 状态
ApplicationSet	根据目录、集群或参数批量生成 Application

“Synced”只代表配置一致，不代表业务一定正常；还要结合 Health、Probe、日志、指标和实际请求验证。

安装原则

官方快速安装可以应用发布清单：

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/<固定版本>/manifests/install.yaml
kubectl get pods -n argocd

生产环境必须把 <固定版本> 替换为经过验证的具体版本，不能长期引用 stable。还要规划：

• 高可用与资源 requests/limits。
• Ingress/TLS、SSO、RBAC 和管理员账户策略。
• Git 仓库凭据、Known Hosts 与企业 CA。
• Argo CD 自身配置的备份与声明式管理。
• 目标集群权限，避免所有应用共享无限 Cluster Admin。

首次验证 UI 可使用临时端口转发，不应把服务直接裸露公网：

kubectl port-forward svc/argocd-server -n argocd 8080:443

Application 示例

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: order-prod
  namespace: argocd
spec:
  project: production
  source:
    repoURL: ssh://git@gitlab.example.com/platform/deployments.git
    targetRevision: main
    path: apps/order-service/prod
    helm:
      valueFiles:
        - values-prod.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: order
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

初期建议人工 Sync。确认权限、资源边界和回滚流程后，再决定是否开启自动同步。

自动同步

syncPolicy:
  automated:
    enabled: true
    prune: true
    selfHeal: true
  syncOptions:
    - CreateNamespace=true

设置	效果	风险
enabled	Git 变化后自动同步	错误提交会更快进入集群
prune	自动删除 Git 中移除的资源	目录错误或重构可能批量删除资源
selfHeal	手工修改集群后自动恢复	紧急现场修改会被覆盖

生产启用 prune 前必须配置 AppProject 边界、保护关键资源，并验证空目录、分支切换和重命名场景。Git 才是期望状态来源，紧急修改后也要回写 Git。

推荐仓库结构

deployments/
├── charts/
│   └── order-service/
└── apps/
    └── order-service/
        ├── dev/values-dev.yaml
        ├── test/values-test.yaml
        └── prod/values-prod.yaml

应用源码仓库负责测试和构建镜像；部署仓库保存环境 Values 与发布版本。CI 构建完成后提交新的镜像 SHA/版本到部署仓库，生产变更通过 Merge Request 审批。

发布与回滚

构建镜像 app:<commit-sha>
  → 修改 prod Values 中 image.tag
  → Merge Request 审核
  → 合并后 Argo CD 显示 OutOfSync
  → 人工/自动 Sync
  → 检查 Healthy、日志、指标和业务

推荐通过 Git revert 恢复之前的镜像版本，再由 Argo CD 同步。这样 Git 历史、期望状态和集群状态保持一致。数据库迁移等不可逆变化仍需要独立回滚方案。

排障顺序

argocd app get order-prod
argocd app diff order-prod
argocd app history order-prod
kubectl get application order-prod -n argocd -o yaml
kubectl logs -n argocd deploy/argocd-application-controller

现象	优先检查
一直 OutOfSync	Helm 渲染差异、默认字段、Webhook 修改、忽略差异规则
Sync Failed	RBAC、CRD 顺序、Namespace、资源配额和 API 版本
Synced 但 Degraded	Pod、Probe、镜像、PVC、配置和应用日志
Git 仓库连接失败	SSH Key、Token、Known Hosts、CA、DNS 和代理
手工修改立即消失	是否启用了 selfHeal；正确做法是修改 Git
资源意外被删	prune、Application 路径、分支和 AppProject 边界

安全边界

• 使用 AppProject 限制允许的仓库、Namespace 和资源类型。
• Git 仓库凭据与集群凭据最小权限，定期轮换。
• SSO/RBAC 区分只读、同步、项目管理和平台管理权限。
• Secret 不以明文进入 Git；选择受控的密钥加密或外部 Secret 方案。
• 生产 Sync、prune 和 Application 删除应保留审计与审批。

官方参考：Argo CD Overview、Declarative Setup、Automated Sync Policy。