Argo CD v2.2 到 v2.3 升级指南：组件内置、CLI 二进制下载配置与 SSH 签名算法变更-编程实验室

Argo CD v2.2 到 v2.3 升级指南：组件内置、CLI 二进制下载配置与 SSH 签名算法变更

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

本篇技术指南围绕 Argo CD 从 v2.2 升级到 v2.3 的官方升级文档，系统梳理该版本中组件打包方式、镜像内容、内置工具链版本以及 SSH 认证行为等关键变更，并结合当前仓库源码与配置清单给出可复现的操作步骤。读者读完本篇后，能够判断自己的部署方式（kubectl apply / Kustomize / Helm）是否需要调整，能够通过argocd-cmConfigMap 配置多平台 CLI 下载入口，并能在升级到 2.3.7 前完成 SSH 兼容性检查与规避方案落地。

升级总览：v2.2 → v2.3 的核心变化

v2.2 到 v2.3 的升级并不涉及数据迁移或 API 破坏性变更，重点集中在以下几类运行时变化：

组件打包方式变化：Argo CD Notifications 与 ApplicationSet 正式并入 Argo CD 本体；
镜像内容变化：移除非 Linux 平台 CLI 二进制、移除 Python 运行时；
内置工具链升级：Kustomize 由 4.2.0 升级到 4.4.1，Helm 由 3.7.1 升级到 3.8.0；
安全策略收紧：2.3.7 起基础镜像升级到 Ubuntu 22.04，OpenSSH 升级到 8.9，不再支持ssh-rsaSHA-1 签名算法。

本文的升级目标版本是 v2.3，如需查看其他版本间的升级说明，可参考升级总览文档，其中列出了全部相邻版本升级指南的入口。

Argo CD Notifications 与 ApplicationSet 正式内置

变更内容

从 v2.3 开始，Argo CD Notifications（通知控制器）和 ApplicationSet 控制器已成为 Argo CD 发行的一部分，无需再单独安装这两个组件。默认的 Argo CD 安装清单（manifest）已经内置了它们。

这一变化在当前仓库的 manifest 结构中可以直接得到印证：manifests/base/kustomization.yaml的resources列表同时包含了./notification与./applicationset-controller，与 application-controller、dex、repo-server、server、redis 等核心组件并列：

resources: - ./application-controller - ./dex - ./repo-server - ./server - ./config - ./redis - ./notification - ./applicationset-controller

对应的manifests/base/notification/目录下包含 notifications 控制器的 Deployment、ServiceAccount、RBAC、ConfigMap、Secret 以及指标采集 Service 等完整资源，manifests/base/applicationset-controller/目录同样包含 ApplicationSet 控制器所需的完整资源。在代码层面，仓库根目录的notification_controller/包实现了通知控制器逻辑，applicationset/目录则包含 ApplicationSet 控制器的核心实现。

不同部署方式下的操作指引

使用kubectl apply部署的用户：无需任何操作。新清单会自动带上内置组件。
使用 Kustomize 组装清单的用户：内置清单是旧版独立安装的“drop-in 替换”。如果你之前在 Kustomize 中引用了argoproj-labs/argocd-notifications和argoproj-labs/applicationset仓库的清单，直接删除这些引用即可，同时移除对应的kustomization.yaml中相应资源块。
使用 argocd-notifications Helm chart 的用户：可以将原 chart 的 values 迁移到 argo-cd chart values 中的notifications一节。绝大部分配置项保持原样，个别字段需要对照当前 argo-cd chart 的 values 文档逐一核对与调整。

注意：当前仓库 VERSION 文件显示仓库基线已演进到 3.6.0，但上述“组件内置”的布局自 v2.3 起即已确立，并延续至今。

配置额外的 Argo CD CLI 下载入口

变更背景

v2.3 起，Argo CD 镜像中移除了非 Linux 平台的 CLI 二进制（包括 Darwin amd64 和 Windows amd64），UI 帮助页面中对应的下载按钮也随之移除。被移除的二进制仍然会作为 release assets 发布，只是不再打进镜像。

为了保持多平台 CLI 的可获取性，社区通过配置项将其重新开放：你可以在argocd-cmConfigMap 中添加help.download.<os>-<arch>键，为帮助页面配置指向任意下载地址的按钮。官方默认清单中的完整示例可参见 argocd-cm.yaml：

apiVersion: v1 kind: ConfigMap metadata: name: argocd-cm namespace: argocd labels: app.kubernetes.io/name: argocd-cm app.kubernetes.io/part-of: argocd data: help.download.linux-amd64: "path-or-url-to-download" help.download.linux-arm64: "path-or-url-to-download" help.download.linux-ppc64le: "path-or-url-to-download" help.download.linux-s390x: "path-or-url-to-download" help.download.darwin-amd64: "path-or-url-to-download" help.download.darwin-arm64: "path-or-url-to-download" help.download.windows-amd64: "path-or-url-to-download"

支持的操作系统与架构列表

从当前仓库源码看，Argo CD 仅识别以下<os>-<arch>组合，其余键会被忽略。相关逻辑位于 util/settings/settings.go 的getDownloadBinaryUrlsFromConfigMap函数，它会遍历固定列表并逐个读取 ConfigMap 数据：

linux-amd64
linux-arm64
linux-ppc64le
linux-s390x
darwin-amd64
darwin-arm64
windows-amd64

对应测试 util/settings/settings_test.go 验证了这一行为：配置help.download.darwin-amd64、help.download.linux-s390x和不受支持的help.download.unsupported时，最终只有前两个被识别进BinaryURLs映射，未列出的键被静默忽略。

使用注意事项

帮助页面（Help page）始终默认展示一个内置的 Linux CLI 下载按钮，无需任何配置即可让用户获取可用的 CLI；
如果你为服务器自身架构额外配置了help.download.linux-<arch>，页面上会出现两个 Linux 按钮（一个默认按钮加一个自定义按钮），这是预期行为，详见 UI 自定义文档；
键对应的值可以是路径或完整 URL（例如https://example.com/argocd-darwin-arm64），Argo CD 只负责在帮助页面渲染指向该地址的下载按钮，不校验地址可达性。

基础镜像移除了 Python

v2.3 起，Argo CD 基础镜像不再包含 Python 运行时。如果你正在使用依赖 Python 的 Config Management Plugin（配置管理插件，CMP），升级后插件将无法在容器内找到 Python 解释器。

解决方案是基于 Argo CD 官方镜像构建自定义镜像，在镜像中自行安装 Python，然后让 repo-server 使用该自定义镜像运行。具体做法为：

编写 Dockerfile，基于quay.io/argoproj/argocd:<版本>安装所需 Python 版本及其依赖；
将自定义镜像发布到镜像仓库；
修改 Argo CD 部署清单中 repo-server 的镜像引用；
确保 CMP 的command配置指向正确的可执行文件路径（必要时使用绝对路径，如/usr/local/bin/python3）。

内置 Kustomize 版本升级（4.2.0 → 4.4.1）

v2.3 将内置 Kustomize 从 4.2.0 升级到 4.4.1。这意味着应用仓库中使用的 Kustomize 特性集会随之变化，升级前建议：

检查应用仓库中是否使用了 4.2.0 不支持、或行为与 4.4.1 不一致的 Kustomize 语法（如patchesJson6902、replacements相关特性在不同小版本间的行为差异）；
在测试环境中对存量 Application 执行一次 dry-run 或 Sync 演练，确认生成的 manifest 与预期一致。

从当前仓库的依赖看，Kustomize 组件已演进到更新版本（go.mod中sigs.k8s.io/kustomize/api v0.21.1为当前基线），说明 Argo CD 对 Kustomize 的升级是持续进行的；本升级指南所述 4.4.1 是 v2.3 发布时的内置版本。

内置 Helm 版本升级（3.7.1 → 3.8.0）

v2.3 同时将内置 Helm 从 3.7.1 升级到 3.8.0。Helm 3.8 带来的变化包括更严格的依赖校验行为与部分模板函数行为的调整。建议在升级 Argo CD 前：

在本地使用 Helm 3.8.0 对使用 Helm 模板的应用执行helm template渲染，比对渲染结果；
关注 Helm 3.8 release notes 中关于--insecure-skip-tls-verify、OCI registry 支持等与 Argo CD 集成路径相关的改动；
若应用使用了 Helm chart 依赖，注意重新执行helm dependency update以刷新Chart.lock。

2.3.7 起移除 SSH SHA-1 签名算法支持

变更背景

Argo CD 2.3.7 将基础镜像从 Ubuntu 21.04 升级到 Ubuntu 22.04，随之 OpenSSH 升级到 8.9。OpenSSH 自 8.8 起默认禁用了ssh-rsa公钥签名算法（SHA-1），因此 Argo CD 在连接仅支持ssh-rsa签名算法的 Git 服务器时会出现协商失败。

这里需要特别澄清一个常见误解：签名算法与生成密钥时使用的算法不是一回事。ssh-keygen生成密钥的算法（如 RSA）不必变更，你现有的私钥无需重新生成；受影响的是连接建立时客户端与服务端协商的“签名算法”（signature algorithm）列表。

签名算法的协商过程如下：SSH 客户端在建立连接时向服务端提交其支持的签名算法列表，服务端若有匹配项则连接继续。大多数主流 Git 服务商（如 GitHub、GitLab 等）的 SSH 服务器都已支持除ssh-rsa之外的其他算法，因此通常不受影响。

升级前检查步骤

在升级到 Argo CD 2.3.7 之前，请按以下步骤检查你的 Git 提供方是否支持比rsa-ssh更新的签名算法：

第一步：确认本地 SSH 版本 ≥ 8.9（即 Argo CD 所使用的版本），不满足则先升级：

ssh -V

示例输出：OpenSSH_8.9p1 Ubuntu-3, OpenSSL 3.0.2 15 Mar 2022

第二步：从允许列表中移除ssh-rsa后尝试连接，验证服务器是否仍可用其他主机密钥类型完成认证：

ssh -oHostKeyAlgorithms=-ssh-rsa user@host

若连接成功，说明服务器支持更新的签名算法，无需处理；
若主机密钥校验失败且没有其他受支持的主机密钥类型可用，则说明该服务器软件需要升级。失败时的典型报错如下：

$ ssh -oHostKeyAlgorithms=-ssh-rsa vs-ssh.visualstudio.com Unable to negotiate with 20.42.134.1 port 22: no matching host key type found. Their offer: ssh-rsa

出现上述错误意味着服务器只提供ssh-rsa这一种签名算法，Argo CD 将无法连接该服务器，需要先推动服务器侧升级其支持的签名算法。

变通方案（Workaround）

如果暂时无法更改服务器的签名算法配置，可以参考 OpenSSH 8.8 release notes 提供的临时规避手段：在 SSH 客户端配置中选择性重新启用 RSA/SHA1。例如在~/.ssh/config中为单个目标主机添加如下配置段：

Host old-host HostkeyAlgorithms +ssh-rsa PubkeyAcceptedAlgorithms +ssh-rsa

将该方案应用到 Argo CD 时，可以创建一个包含上述 ssh 配置内容的 ConfigMap，并将其挂载到 repo-server（或其他需要 SSH 访问的组件）容器内的/home/argocd/.ssh/config路径。示例步骤如下：

apiVersion: v1 kind: ConfigMap metadata: name: argocd-ssh-config namespace: argocd data: config: | Host old-host HostkeyAlgorithms +ssh-rsa PubkeyAcceptedAlgorithms +ssh-rsa

然后在 repo-server 的 Deployment 中挂载该 ConfigMap：

volumeMounts: - name: ssh-config mountPath: /home/argocd/.ssh/config subPath: config

官方强烈建议仅在过渡期使用 RSA/SHA1 重启用方案，直到旧版服务器完成升级，或改用其他密钥类型（如 ECDSA 或 Ed25519）。重新启用 SHA-1 签名算法会削弱连接的安全性，应尽快消除这一依赖。

升级检查清单小结

变更项	影响范围	需要采取的动作
Notifications/ApplicationSet 内置	所有部署方式	`kubectl apply`无需操作；Kustomize 删除外部引用；Helm 迁移 values 到`notifications`节
移除非 Linux CLI 二进制	UI 帮助页	按需在`argocd-cm`配置`help.download.<os>-<arch>`
移除 Python	依赖 Python 的 CMP 用户	构建并部署自定义 repo-server 镜像
Kustomize 4.2.0 → 4.4.1	使用 Kustomize 的应用	测试环境验证渲染结果
Helm 3.7.1 → 3.8.0	使用 Helm 的应用	本地用 3.8.0 预渲染验证
移除 ssh-rsa SHA-1 签名	使用 SSH 认证的私有仓库（2.3.7 起）	升级前用`ssh -oHostKeyAlgorithms=-ssh-rsa`检查服务器；必要时以 ConfigMap 挂载 ssh config 临时放行