用 Argo CD 搭建 GitOps 持续交付

适用场景

希望把 Kubernetes 的部署状态收敛到 Git 仓库，由集群持续拉取并对账，而不是在 CI 里直接执行 kubectl apply。适合多环境、多集群和需要审计变更记录的团队。

前置条件

• 一个可用的 Kubernetes 集群和 kubectl 管理权限。
• Git 仓库，存放 Kustomize、Helm 或纯 YAML 清单。
• 可被集群访问的仓库地址；私有仓库准备 Deploy Key 或访问令牌。
• 明确哪些资源由 Argo CD 管理，避免和现有 CI 同时写同一批对象。

步骤

1. 安装 Argo CD：

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

2. 暴露 UI 并获取初始密码：

kubectl -n argocd port-forward svc/argocd-server 8080:443
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d

生产环境建议通过 Ingress/Gateway 暴露，并接入 OIDC 登录，不要长期使用 port-forward 和 admin 本地账号。

3. 登录并准备仓库：

argocd login localhost:8080 --username admin --insecure
argocd repo add https://github.com/example/gitops.git \
  --username git --password "$GIT_TOKEN"

4. 创建 Application：

argocd app create demo \
  --repo https://github.com/example/gitops.git \
  --path apps/demo/overlays/prod \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace demo \
  --sync-policy automated \
  --auto-prune \
  --self-heal

5. 先手动同步一次并观察差异：

argocd app diff demo
argocd app sync demo
argocd app get demo

6. 确认稳定后再开启自动同步。删除资源前先确认 auto-prune 的影响范围，生产环境可先用 --sync-option Prune=false 做灰度。

7. 需要按团队隔离时，创建 AppProject 限制可部署的仓库、集群和命名空间：

argocd proj create team-a \
  --src https://github.com/example/gitops.git \
  --dest https://kubernetes.default.svc,demo

验证

• argocd app get demo 的 Sync 状态为 Synced，Health 为 Healthy。
• 修改 Git 中的镜像标签后，Argo CD 能自动检测并同步。
• 手动删除受管资源后，self-heal 能把资源恢复。
• argocd app history demo 能看到每次同步对应的 Git 提交。

回滚

• 在 Git 中 revert 出问题的提交，等待自动同步；这是最推荐的回滚方式。
• 紧急情况可用 argocd app rollback demo <历史ID>，但下一次自动同步仍会回到 Git 状态。
• 关闭自动同步：argocd app set demo --sync-policy none，再手工处理。
• 保留 Argo CD 自身的备份，至少备份 Application、AppProject 和仓库凭据。

常见坑

• CI 和 Argo CD 同时部署同一应用，会反复互相覆盖；明确唯一写入方。
• auto-prune 会删除 Git 中移除的资源，首次开启前先看 diff。
• Helm chart 的 lookup 函数在 Argo CD 渲染时可能拿不到集群状态。
• 私有仓库证书、代理和 DNS 不通会导致 ComparisonError，先看 repo-server 日志。
• 多集群场景要确认目标集群的 API Server 地址和凭据，不要只配置 in-cluster。
• Application 的 destination.namespace 不会自动创建命名空间，必要时加 CreateNamespace=true。

相关命令

• argocd — CLI 登录、创建应用、同步与回滚
• kubectl — 查看 Argo CD 组件和受管资源
• helm — 管理 chart 版本
• kustomize — 渲染多环境清单