从 Helm 手工发布迁移到 Argo CD

适用场景

目前用 helm upgrade 手工或 CI 直接发布，希望改为 GitOps 持续对账、可视化差异和一键回滚。迁移重点是 values 管理、发布顺序和 Hook 处理。

前置条件

• 可用的 Argo CD。
• Helm chart 和 values 已进入 Git 仓库。
• 明确哪些资源由 Argo CD 管理。
• 保留 Helm CLI 作为应急手段。

步骤

1. 导出现有 release：

helm list -A
helm get values demo -n demo > demo-values.yaml
helm get manifest demo -n demo > demo-manifest.yaml

2. 把 chart 和 values 放入 Git：

gitops/
  apps/demo/
    Chart.yaml
    values.yaml
    values-prod.yaml

3. 创建 Argo CD Application：

argocd app create demo \
  --repo https://github.com/example/gitops.git \
  --path apps/demo \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace demo \
  --helm-set-file values=values-prod.yaml \
  --sync-policy none

4. 先对比差异，不要立即自动同步：

argocd app diff demo
argocd app sync demo --dry-run

5. 处理 Helm Hook：

• pre-install/post-install 对应 Argo CD 的 PreSync/PostSync。
• 迁移 Job 要加 hook-delete-policy，避免重复执行。
• 数据库迁移和发布顺序用 sync wave 控制。

6. 确认稳定后开启自动同步：

argocd app set demo --sync-policy automated --self-heal

验证

• argocd app get demo 为 Synced/Healthy。
• 修改 Git 中的 values 后自动同步。
• 手动修改集群资源后 self-heal 恢复。
• Helm Hook 只执行一次。
• 回滚能通过 Git revert 完成。

回滚

• 保留原 Helm release 和 values。
• 关闭自动同步：argocd app set demo --sync-policy none。
• 紧急回滚可用 helm rollback，但下一次 Argo CD 同步会覆盖。
• 保留旧 chart 版本和镜像 tag。

常见坑

• CI 和 Argo CD 同时发布，反复覆盖。
• values 文件路径或 --helm-set-file 参数错误，渲染结果不同。
• Helm Hook 在 Argo CD 中重复执行，迁移 Job 不幂等。
• auto-prune 删除 Helm 创建但 Git 中没有的资源。
• CRD 和 webhook 的安装顺序没有用 sync wave 控制。
• release 名称和 namespace 与旧 release 不一致，产生两套资源。
• 没有配置 ServerSideApply，大 CRD 应用失败。

相关命令

• argocd — 创建应用、diff、sync 和回滚
• helm — 查看旧 release 和 values
• kubectl — 查看资源
• git — 管理 GitOps 仓库