Argo CD v1.8 到 v2.0 升级指南：关键变更解析与运维注意事项-港品优选

Argo CD v1.8 到 v2.0 升级指南：关键变更解析与运维注意事项

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd

本文基于仓库内官方升级文档 docs/operator-manual/upgrading/1.8-2.0.md 编写，围绕 Argo CD 从 v1.8 升级到 v2.0 时涉及的十余项核心变更展开。文章覆盖 Redis 版本升级、容器镜像仓库迁移、Dex 命令拆分、CLI 参数类型收紧、Helm v3 默认化等升级要点，并结合仓库源码与配置验证每一项变更的落地细节，帮助读者在升级前完成影响面评估与风险排查。

升级总览：v2.0 是一次需要规划的大版本跳跃

v2.0 是 Argo CD 的一个里程碑式大版本，它不仅在功能层面将 Helm v3 设为默认渲染引擎、迁移 CRD 到新的 API group，也在基础设施层面完成了 Docker 基础镜像迁移、容器镜像仓库切换、Dex 工具拆分等"动筋骨"的操作。与常规小版本升级不同，这次升级中有多项变更会直接影响生产环境的部署方式、镜像拉取能力和集群访问行为，建议按照本文逐项核对，再制定升级计划。

升级文档将变更划分为三类，本文沿用这一脉络展开：

运行时基础设施变更：Redis 版本、Docker 基础镜像、容器镜像仓库；
二进制与部署形态变更：argocd-dex工具拆分、单二进制多子命令行为；
功能与兼容性变更：环境变量展开、CLI 参数类型、Go 版本、CRD API、Helm/Kustomize 渲染工具链。

运行时基础设施变更

Redis 升级到 v6.2.1：无状态存储，建议错峰升级

v2.0 内置的 Redis 版本升级到了 v6.2.1。官方升级文档明确指出两点判断依据：

Redis 升级本身可以实现无停机，因为 Argo CD不把 Redis 作为持久化存储使用（它主要用于缓存与临时状态，如应用列表、git 仓库信息的缓存）；
但如果在生产环境中有多个用户同时使用，仍建议在低峰时段执行升级，以避免出现用户可见的短暂失败。

从升级文档的表述看，这里没有强制停机窗口，但"建议错峰"反映了官方对用户体验的谨慎态度。升级前后建议观察 Redis 的INFO输出以及 Argo CD 各组件的日志，确认缓存重新预热过程无异常。

Docker 镜像基础从 Debian 迁移到 Ubuntu

官方 Docker 镜像的基础镜像从debian:10-slim切换为ubuntu:20.10。升级文档特别提醒：

虽然这通常不影响用户体验，但如果你使用自定义构建镜像或在自定义镜像中包含第三方工具，则可能受到影响。

这意味着：如果你的部署方式是直接使用官方镜像，则无感；如果你们基于官方镜像二次构建（例如打入自研的 git helper、脚本或二进制工具），需要在升级前验证这些自定义组件在新基础镜像（Ubuntu 20.10 对应的 glibc、工具链和包管理方式）下是否仍然正常工作。官方给出的行动建议是——在推上生产之前，先在测试环境用自定义工具验证 v2.0 镜像。

容器镜像仓库切换到 quay.io，Docker Hub 仓库进入下线期

由于 Docker Hub 新的速率限制（rate-limiting）与镜像保留策略，Argo 项目决定将旗下所有子项目发布的镜像迁往 quay.io 仓库。

v2.0 带来的具体变化是：

安装清单（installation manifests）默认从quay.io拉取镜像；
Docker Hub 仓库进入sundown（停用倒计时）：v2.0 期间仍会同时向两个仓库推送镜像，但Argo CD 2.1 发布后，将停止向 Docker Hub 推送；
因此升级文档给出的硬性要求是：确保你的集群能够从quay.io拉取镜像。

如果集群暂时无法访问quay.io（例如出于网络策略原因），升级文档提供了一个临时 workaround：手动修改安装清单中的容器镜像 slug 指向 Docker Hub 以安装 Argo CD 2.0。但必须注意，该 workaround 在 2.1 版本中不再可用——因为届时 Docker Hub 将停止接收新镜像推送。也就是说，无论采用哪种方式，最终都必须打通到quay.io的拉取通道。

这一变更直接影响所有通过 manifests 目录下安装清单（如install.yaml、core-install.yaml、namespace-install.yaml等）部署的集群，升级前建议先在非生产集群执行一次完整的清单应用与镜像拉取演练。

二进制与部署形态变更

Dex 工具从 argocd-util 迁移到 argocd-dex

v2.0 中，Dex 相关的两个命令rundex和gendexcfg从argocd-util迁移到了独立的argocd-dex二进制。这意味着argocd-dex-server这个 Deployment 的启动方式需要同步调整。

升级文档给出了两份关键清单片段。initContainer部分从拷贝/执行argocd-util改为安装argocd-dex二进制：

initContainers: - command: - cp - -n - /usr/local/bin/argocd - /shared/argocd-dex

主容器部分则以/shared/argocd-dex rundex方式启动：

containers: - command: - /shared/argocd-dex - rundex

需要注意的是，argocd-dex-serverDeployment 的 manifests 在仓库中（见 manifests/base 目录下的argocd-dex-server-deployment.yaml等文件），自定义部署的用户需要对比官方清单，将自己的 initContainer 与容器 command 同步更新。

v2.0 起 argocd 二进制行为改变：按名称分发子命令

升级文档特别强调，从 v2.0 开始argocd二进制行为发生了变化：所有 argocd 二进制（argocd-dex、argocd-server、argocd-repo-server、argocd-application-controller、argocd-util、argocd）都被打包在同一个二进制内部，二进制会根据**它被调用时的名字（argv[0]）**来决定启用哪个子命令。

这一点对镜像构建和部署脚本有直接影响：

在 initContainer 中cp /usr/local/bin/argocd /shared/argocd-dex，本质上就是把同一份二进制复制并重命名为argocd-dex，运行时它即会以 dex 子命令模式工作；
如果某个 Deployment 仍然通过旧名字（如直接调用argocd-util rundex）启动，升级后行为会与预期不符，必须按上面的方式改为argocd-dex rundex。

建议升级前检查所有自定义的 Kubernetes 清单或 Helm values，确保不存在对argocd-util rundex/argocd-util gendexcfg的引用。

功能与兼容性变更

环境变量展开逻辑改进：缺失变量展开为空字符串

Argo CD 支持在配置管理工具（Config Management Tools）参数中使用环境变量。v2.0 对展开逻辑做了改进：缺失的环境变量现在会被展开为空字符串，而不是保持原样或报错。

这一行为与 docs/user-guide/build-environment.md 中定义的构建环境变量体系配合使用。该文档列出的可用变量包括（节选）：

变量	说明
`ARGOCD_APP_NAME`	应用名称
`ARGOCD_APP_NAMESPACE`	应用目标命名空间
`ARGOCD_APP_PROJECT_NAME`	应用所属项目名
`ARGOCD_APP_REVISION`	解析后的完整 revision（如`f913b6cbf58aa5ae5ca1f8a2b149477aebcbd9d8`）
`ARGOCD_APP_REVISION_SHORT`	短 revision（如`f913b6c`）
`ARGOCD_APP_SOURCE_PATH`	应用在源仓库中的路径
`ARGOCD_APP_SOURCE_REPO_URL`	源仓库 URL
`KUBE_VERSION`	Kubernetes 语义版本（不含尾部元数据）
`KUBE_API_VERSIONS`	Kubernetes API 版本

同时，如果不想让某个变量被插值，可以用$$转义$，例如在插件命令中写echo $$FOO。

升级影响：如果你此前依赖"缺失环境变量保持原样"的行为（例如把${VAR}传给 Helm 并期望它原样出现在渲染结果中），升级后这些位置会变成空字符串，可能导致渲染结果变化。建议在升级前对使用环境变量插值的应用做一次渲染结果对比（argocd app diff/argocd app manifests），确认没有因空串替换导致的 manifest 差异。

app sync 重试参数类型从 String 收紧为 Duration

argocd app sync命令暴露了若干重试参数用于参数化同步重试行为。v2.0 之前，其中两个参数--retry-backoff-duration和--retry-backoff-max-duration被声明为string类型，导致用户可以传入不带时间单位的数值（如10），甚至任意随机字符串。

v2.0 中这两个参数迁移为duration类型，现在必须提供合法的时间单位（如s、m、h）。升级文档给出了明确的对照示例：

# 不带时间单位 -> 非法，v2.0 起会报错 argocd app sync <app-name> --retry-backoff-duration=10 # 带合法时间单位 -> 合法 argocd app sync <app-name> --retry-backoff-duration=10s

这一变更在源码中有直接佐证：在 cmd/argocd/commands/app.go 中，三个重试相关 flag 均通过DurationVar/Int64Var注册，帮助文本明确要求 duration 格式：

command.Flags().DurationVar(&retryBackoffDuration, "retry-backoff-duration", argoappv1.DefaultSyncRetryDuration, "Retry backoff base duration. Input needs to be a duration (e.g. 2m, 1h)") command.Flags().DurationVar(&retryBackoffMaxDuration, "retry-backoff-max-duration", argoappv1.DefaultSyncRetryMaxDuration, "Max retry backoff duration. Input needs to be a duration (e.g. 2m, 1h)") command.Flags().Int64Var(&retryBackoffFactor, "retry-backoff-factor", argoappv1.DefaultSyncRetryFactor, "Factor multiplies the base duration after each failed retry")

解析后的值最终组装进RetryStrategy.Backoff（Duration/MaxDuration/Factor字段）随同步请求发送（见同一文件中的 sync 请求构造逻辑）。

升级影响：所有 CI/CD 流水线、脚本中对这两个参数的无单位传参（如--retry-backoff-duration=10）在升级到 v2.0 后会直接失败，必须批量改为带单位的写法（10s、2m、1h等）。--retry-limit、--retry-refresh、--retry-backoff-factor的行为不受此变更影响。

构建工具链切换到 Go 1.16：TLS 证书校验行为变化

官方 Argo CD 二进制从 Go 1.14.x 直接升级到Go 1.16构建。升级文档特别提示了一个 TLS 相关的隐蔽破坏点：

Go 1.15 引入了对 TLS 连接中服务端名称不再与证书CommonName属性校验的弃用行为。

具体影响是：如果你的仓库服务器（repository server）使用了仅靠CommonName匹配的证书，升级后到这些服务器的 TLS 连接可能失败。官方给出的解决办法是：为这些服务器签发包含正确SAN（Subject Alternative Name）的证书。

升级影响：升级前建议检查所有通过 HTTPS/TLS 访问的 git 仓库、Helm 仓库等远端服务的证书，确认其 SAN 中包含了访问所用的主机名，避免升级后 repo 连接集体失败。

CRD 从 apiextensions/v1beta1 迁移到 apiextensions/v1

Argo CD 的Application和AppProject两个 CRD 从已废弃的apiextensions/v1beta1API group 迁移到了apiextensions/v1。

升级文档明确澄清了三点：

这不影响 CRD 自身的版本（即 CRD 资源的version字段语义没有变化）；
不预期用户需要对现有的Application/AppProjectCR 做任何修改；
该条目仅是"完整性说明"——即官方预期此变更对用户透明。

从实践角度，升级时只需要用 v2.0 附带的 manifests/crds 目录下的新 CRD manifest 替换旧版本即可，无需改动已存在的 CR 资源。如果你通过 Helm 或 Kustomize 管理 CRD 安装，注意同步更新对应的渲染源。

Helm v3 成为默认渲染版本，v2 进入弃用倒计时

这是本次升级中对应用渲染影响最大的一项变更：

Helm v3 成为所有 Chart 渲染的默认版本；
禁用了基于Chart.yaml中apiVersion字段的 Helm 版本自动检测——也就是说，无论 Chart 的apiVersion写的是 v1（Helm 2 风格）还是 v2（Helm 3 风格），一律使用 Helm v3 渲染。

由此可能产生的现象是：之前用 Helm v2 渲染的应用可能出现 minor out-of-sync 状态（典型如 Helm 添加的某个 annotation 发生变化）。官方建议的处理方式是直接重新同步（sync）该应用即可恢复一致。

对于必须继续使用 Helm v2 渲染的存量 Chart，需要显式在 Application 上配置 Helm v2，具体方法见 docs/user-guide/helm.md#helm-version。该文档进一步说明了这一字段的定位变化：它最初用于 Helm 2 → 3 过渡期让用户选择渲染引擎；随着 Helm 2 上游停止维护并 EOL，该字段在较新版本中仅保留向后兼容，存量配置如spec.source.helm.version: v3可以保留、无需修改。

同时升级文档给出了 Helm v2 的弃用时间表：

Helm v2 在 Argo CD 中已被视为 deprecated，因为它不再获得上游 Helm 项目的任何更新；
官方仍会在接下来的两个版本中打包 Helm v2 二进制；
宽限期结束后将移除Helm v2 二进制。

因此升级到 v2.0 是推动团队将存量 Chart 迁移到 Helm v3 的最佳时机——建议在此版本周期内完成所有 Helm v2 Chart 的升级验证，避免在后续版本被迫一次性迁移。

Kustomize 更新到 v3.9.4

v2.0 默认打包的 Kustomize 版本更新为v3.9.4。升级文档要求：

升级前确认你的 manifests 能在此 Kustomize 版本下正确渲染；
如果需要与旧版 Kustomize 保持兼容，可考虑配置自定义 Kustomize 版本，并让 Application 显式使用该版本渲染（相关配置方式见 docs/user-guide/kustomize.md）。

由于 Kustomize 各版本在部分内置函数、overlay 合并语义上存在差异，建议在升级前用argocd app diff对使用 Kustomize 的应用做渲染对比，重点排查使用了较新/较旧语法特性的项目。

升级检查清单与行动建议

综合上述变更，将升级前、升级中、升级后的行动项整理如下，可直接作为团队的升级 checklist：

升级前（准备与影响面评估）

核对集群到quay.io的网络连通性，提前配置镜像拉取凭据或白名单（此项为硬性要求）；
检查所有 TLS 访问的仓库服务器证书是否包含正确 SAN（应对 Go 1.15+ 的 CommonName 弃用行为）；
扫描 CI/CD 脚本与流水线中的argocd app sync --retry-backoff-*传参，将无单位数值改为合法 duration；
检查自定义 Docker 镜像及内置第三方工具在 Ubuntu 基础镜像下的兼容性；
使用argocd app diff对比使用 Helm v2 渲染的应用，评估 Helm v3 默认化带来的 out-of-sync 影响；
确认 Kustomize 应用在当前默认版本（v3.9.4）下渲染结果一致；
检查自定义清单中对argocd-util rundex/gendexcfg的引用，规划迁移到argocd-dex。

升级中（执行与验证）

在非生产集群先完成一次完整升级演练，替换 manifests/crds 下的新 CRD；
更新argocd-dex-serverDeployment 的 initContainer 与容器 command 为新二进制形态；
Redis 升级建议安排在低峰时段执行。

升级后（验证与收尾）

对出现 minor out-of-sync 的 Helm 应用执行重新同步；
确认所有组件日志无 Redis 重连异常、TLS 校验失败等报错；
制定 Helm v2 Chart 的迁移计划，在官方宽限期内完成升级（Helm v2 二进制最多保留两个版本）。

小结

Argo CD v2.0 升级涉及的面非常广：从镜像仓库、基础镜像、Redis 版本这类基础设施，到argocd-dex二进制拆分、单二进制按名分发这类部署形态，再到 CLI 参数类型、Helm/Kustomize 渲染引擎、TLS 校验这类兼容性行为。其中quay.io拉取通道打通、duration 参数写法修正、TLS 证书 SAN 校验是升级中最容易在生产环境"翻车"的三个点。建议在升级前逐项对照本文清单完成影响面评估，并先在非生产集群完整演练一次，再安排生产升级。

企业官网建设流程全解析