企业官网建设流程全解析

Argo CD v2.3 升级到 v2.4 完整指南：破坏性变更、RBAC 适配与迁移实战

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

导读

本文以 Argo CD 官方升级文档 docs/operator-manual/upgrading/2.3-2.4.md 为核心骨架，系统梳理从 v2.3 升级到 v2.4 过程中必须关注的所有破坏性变更与安全增强：project过滤器重命名引发的已知问题、Ksonnet 与 Helm 2 支持的移除、SSH 签名算法策略变化、新增exec/logsRBAC 资源、repo-server 独立 ServiceAccount、以及 Config Management Plugin 的环境变量前缀改造等。读完本文，你将能够制定一份完整的升级检查清单，并依据仓库源码与配置示例完成逐项迁移验证，安全地把生产集群升级到 v2.4 系列版本。

升级前必读：已知问题总览

v2.4 是一次包含多个破坏性变更（Breaking Change）的大版本升级。在动手之前，请先对照下面的清单逐项检查你的环境，本文后续小节会逐一给出详细说明与解决方案：

• project过滤器被重命名为projects，存在 API 兼容性 bug（2.4.27 之前）
• Ksonnet 支持被彻底移除
• Helm 2 支持被移除（Helm 3 为唯一支持版本）
• OpenSSH 升级到 8.9，不再支持ssh-rsaSHA-1 签名算法
• 新增exec与logs两个 RBAC 资源，需要重新审视授权策略
• repo-server 改用独立 ServiceAccount，不再使用default
• sidecar 插件不再共享/tmp目录
• 插件用户自定义环境变量统一增加ARGOCD_ENV_前缀
• sidecar 插件不再接收主 repo-server 容器的环境变量

已知问题：2.4.27 之前损坏的project过滤器

问题根因

Argo CD 2.4.0 引入了一个破坏性的 API 变更：将查询参数project重命名为projects。这一变更直接影响所有通过 REST API 与 Argo CD API Server 通信的客户端。

从当前仓库的 protobuf 定义可以确认这一点，projects已成为查询参数的正式字段名，例如 pkg/apiclient/application/application.pb.go#L50：

Projects []string `protobuf:"bytes,3,rep,name=projects" json:"projects,omitempty"`

同时在 pkg/apiclient/applicationset/applicationset.pb.go#L96 中也有同样的projects字段，说明该变更同时作用于 Application 与 ApplicationSet 的查询接口。

对 API 客户端的影响

如果客户端仍在使用旧字段project进行过滤，过滤器将不会被应用，返回结果包含未过滤的完整列表。这可能带来严重后果：例如你依赖该过滤器列出待删除的 Application（argocd app list --project xxx并批量删除的场景），一旦过滤失效，可能会误删其他项目的应用。

对 CLI 客户端的影响

v2.4.0 之前的 CLI 客户端依赖客户端侧（client-side）过滤，因此不受此 bug 影响。

修复方式

升级到以下任一版本即可同时接受project与projects两种写法作为合法过滤器：

• Argo CD >= 2.4.27
• Argo CD >= 2.5.15
• Argo CD >= 2.6.6

Ksonnet 支持已移除

Ksonnet 早在 2019 年就被官方弃用（deprecated），此后不再维护。v2.4 正式将其从 Argo CD 中移除。

迁移建议：如果你仍在使用 Ksonnet 管理应用清单，需要在升级前将 Application 的spec.source从ksonnet类型迁移到 Helm、Kustomize 或原生 YAML/JSON 等受支持方式，否则升级后相关应用将无法完成渲染。

Helm 2 支持已移除

Helm 2 自 2020 年 11 月起官方不再支持。Argo CD 为了平滑过渡长期保留了 Helm 2 兼容层；v2.4 认为 Helm 3 已经足够稳定，正式移除 Helm 2 支持。

迁移建议：升级前请确认所有使用 Helm 的应用源均已采用 Helm 3 语义。helm template、helm install等命令的调用参数必须符合 Helm 3 语法（例如移除--name，改用 release name 位置参数等），并确保仓库中的Chart.yaml与values.yaml与 Helm 3 兼容。

私有仓库 SSH 密钥的 SHA-1 签名算法支持已移除

注：该变更同时回移植到了 2.3.7 与 2.2.12。

变更背景

Argo CD 2.4 将基础镜像从 Ubuntu 20.04 升级到 Ubuntu 22.04，随之 OpenSSH 升级到 8.9。OpenSSH 自 8.8 起放弃了对ssh-rsaSHA-1 密钥签名算法的支持。

需要特别强调的是：签名算法（signature algorithm）与生成密钥时使用的算法不是一回事，你无需更换或重新生成现有密钥。签名算法是在建立 SSH 连接时与服务器协商的：客户端向服务器提供一份它接受的签名算法列表，服务器选择其中匹配的算法完成连接。对于绝大多数保持更新的 Git 托管服务商，除了ssh-rsa之外通常还有其他可接受的算法。

升级前如何检查你的 Git 提供方

在升级到 Argo CD 2.4 之前，请确认使用 SSH 认证的 Git 提供方（GitHub、GitLab、Bitbucket、Azure DevOps 等）是否支持比ssh-rsa更新的算法：

1. 确保本机 SSH 版本 >= 8.9（Argo CD 2.4 使用的版本），如低于该版本请先升级：

   ssh -V

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

2. 使用 OpenSSH 8.8 发布说明中给出的方法，检测服务器是否仍在使用弱ssh-rsa主机密钥算法——通过把ssh-rsa从允许列表中移除再尝试连接：

   ssh -oHostKeyAlgorithms=-ssh-rsa user@host

   如果主机密钥校验失败且没有其他受支持的主机密钥类型可用，说明该服务器软件需要升级。

3. 若服务器不支持可接受的算法，你会看到类似下面的错误，表示该服务器需要更新其支持的签名算法，Argo CD 将无法连接：

   $ 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

无法立即修改服务器时的临时缓解方案

OpenSSH 8.8 发布说明给出了临时 workaround：如果无法修改服务器端的签名算法配置，可以在~/.ssh/config中对指定目标主机选择性重新启用 RSA/SHA1，用于主机认证与用户认证：

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

官方建议仅在遗留实现完成升级或改用其他密钥类型（如 ECDSA 或 Ed25519）之前，把 RSA/SHA1 作为临时过渡措施。

将该方案应用到 Argo CD，你需要创建一个包含上述 ssh config 内容的 ConfigMap，并挂载到 repo-server 的/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

然后在argocd-repo-serverDeployment 中挂载该 ConfigMap：

spec: template: spec: containers: - name: argocd-repo-server volumeMounts: - name: ssh-config mountPath: /home/argocd/.ssh/config subPath: config volumes: - name: ssh-config configMap: name: argocd-ssh-config

配置 RBAC 以适配新的exec资源

变更说明

v2.4 引入了新的execRBAC 资源。从仓库源码可以看到该资源的正式定义位于 util/rbac/rbac.go#L69-L70：

ResourceLogs = "logs" ResourceExec = "exec"

并且exec已被纳入内置策略：内置只读角色拥有logs, get权限，内置管理员角色拥有exec, create权限，详见 assets/builtin-policy.csv#L18 与 assets/builtin-policy.csv#L51：

p, role:readonly, logs, get, */*, allow p, role:admin, exec, create, */*, allow

升级后的自动授权行为

当你升级到 2.4 时，RBAC 策略中满足以下条件的规则会自动获得exec权限：

• 资源字段（resource）为*
• 动作字段（action）为create或*

为了避免意外授予新的权限，建议把原来的通配策略替换为显式列出旧资源的一系列新策略。

配置示例

旧策略：

p, role:org-admin, *, create, my-proj/*, allow

新策略：

p, role:org-admin, clusters, create, my-proj/*, allow p, role:org-admin, projects, create, my-proj/*, allow p, role:org-admin, applications, create, my-proj/*, allow p, role:org-admin, repositories, create, my-proj/*, allow p, role:org-admin, certificates, create, my-proj/*, allow p, role:org-admin, accounts, create, my-proj/*, allow p, role:org-admin, gpgkeys, create, my-proj/*, allow

exec功能默认处于禁用状态，但即使如此，仍然建议你重新检查 RBAC 配置，遵循最小权限原则（least privilege）。

启用 logs 的 RBAC 强制校验

变更说明

v2.4 新增了logsRBAC 资源。在 2.3 中，拥有applications, get权限的用户会自动获得查看日志的权限；而在 2.4 中，日志访问与 Application 访问开始解耦，需要显式授予logs, get权限。仓库的内置策略同样体现了这一变化（assets/builtin-policy.csv#L18）。

重要提示：日志 RBAC 强制校验不会在 2.5 中默认开启。官方做出这一决定是为了避免破坏 Project Roles（项目角色）下的日志访问——项目角色目前没有提供授予logs资源访问权限的机制，详见 docs/user-guide/projects.md#project-roles。

启用方式

在argocd-cmConfigMap 中添加以下配置即可启用日志 RBAC 强制校验：

server.rbac.log.enforce.enable: "true"

保持原有日志访问能力

如果你希望启用强制校验后，原有用户仍能继续访问日志，只需把所有授予applications, get的策略行，同时补充一条logs, get：

旧策略：

p, role:staging-db-admins, applications, get, staging-db-admins/*, allow p, role:test-db-admins, applications, *, staging-db-admins/*, allow

新策略：

p, role:staging-db-admins, applications, get, staging-db-admins/*, allow p, role:staging-db-admins, logs, get, staging-db-admins/*, allow p, role:test-db-admins, applications, *, staging-db-admins/*, allow p, role:test-db-admins, logs, get, staging-db-admins/*, allow

Pod 日志 UI 的行为变化

• 自 2.4.9 起，Pod 视图中的 LOGS 标签页只对拥有显式logs, get授权策略的用户可见。
• 2.4.9 之前的已知 UI 问题：在 2.4.9 之前，没有显式logs, get策略的用户点击 LOGS 标签页时，屏幕底部会显示红色的 "unable to load data: Internal error"，并提示 "Failed to load data, please try again"。

测试 repo-server 使用新的独立 Service Account

作为一项安全增强，argocd-repo-serverDeployment 改为使用自己的 ServiceAccount，而不再是default。

如果你的自定义环境依赖 repo-server 使用defaultServiceAccount（例如某个插件使用该 ServiceAccount 进行认证），在将 2.4 升级部署到生产环境之前，务必先进行完整测试，确认此类依赖不受影响。

插件（Plugins）迁移指南

v2.4 对 Config Management Plugin 做了多项安全增强，涉及 sidecar 插件的卷挂载、环境变量前缀与传递范围，是升级过程中最容易被忽视的部分。

从 sidecar 插件中移除共享卷

作为安全增强，sidecar 插件不再与 repo-server 共享/tmp目录。如果你启用了一个或多个 sidecar 插件，请将每个 sidecar 的/tmp卷挂载替换为每个插件专用的卷：

apiVersion: apps/v1 kind: Deployment metadata: name: argocd-repo-server spec: template: spec: containers: - name: your-plugin-name volumeMounts: - mountPath: /tmp name: your-plugin-name-tmp volumes: # Add this volume. - name: your-plugin-name-tmp emptyDir: {}

关于 sidecar 插件的更多细节，可参考 docs/operator-manual/config-management-plugins.md#sidecar-plugin。

插件改用带前缀的环境变量

如果插件依赖用户提供的环境变量，则必须升级以兼容 Argo CD 2.4。下面是在 Application 的plugin配置段中设置用户环境变量的示例：

apiVersion: argoproj.io/v1alpha1 kind: Application spec: source: plugin: env: - name: FOO value: bar

从 2.4 起，所有用户提供的环境变量在传递给插件的init、generate或discover命令之前，都会统一加上ARGOCD_ENV_前缀，例如上述FOO会变成ARGOCD_ENV_FOO=bar。这样做的目的是防止用户通过环境变量覆盖或注入可能敏感的系统环境变量。

这一行为在 repo-server 的源码中有明确实现，位于 reposerver/repository/repository.go#L2340-L2351 的getPluginParamEnvs函数：

if plugin != nil { pluginEnv := plugin.Env for _, entry := range pluginEnv { newValue := parsedEnv.Envsubst(entry.Value) env = append(env, fmt.Sprintf("ARGOCD_ENV_%s=%s", entry.Name, newValue)) } paramEnv, err := plugin.Parameters.Environ() ... }

可见每个插件条目都会以ARGOCD_ENV_<name>=<value>的格式追加到环境变量列表中，并且会先通过Envsubst对值做变量替换。

迁移动作：

• 如果你编写了自定义插件并处理用户提供的环境变量，请更新插件代码以读取新的前缀（例如将FOO改为读取ARGOCD_ENV_FOO）。
• 如果你使用的是第三方插件，而它没有明确声明支持 Argo CD 2.4，则可能无法处理带前缀的环境变量。请在升级前向插件作者反馈并确认兼容性。

确认 sidecar 插件拥有全部必要的环境变量

2.4 之前存在一个 bug：init和generate命令会接收到主 repo-server 容器中的环境变量，且这些变量的优先级高于 sidecar 插件自身的环境变量。

从 2.4 开始，sidecar 插件不再接收主 repo-server 容器的环境变量。请确保 sidecar 插件运行所必需的每个环境变量都在 sidecar 插件本身上显式配置。

需要区分的是：

• argocd-cm 中配置的插件：继续接收主 repo-server 容器的环境变量，行为不变。
• sidecar 插件：只接收自身显式配置的环境变量，请逐一核对。

升级检查清单与验证建议

综合以上所有变更点，制定一份可用于生产环境的升级检查清单：

1. API 客户端：确认所有通过 REST API 调用 Argo CD 的自动化脚本/工具已升级，或已使用projects参数；若暂无法升级，目标版本必须 >= 2.4.27。
2. 清单工具链：确认没有使用 Ksonnet；所有 Helm 应用均兼容 Helm 3。
3. SSH 认证：用ssh -oHostKeyAlgorithms=-ssh-rsa user@host逐一验证所有使用 SSH 的 Git 仓库连接；对无法升级的服务器按需配置/home/argocd/.ssh/config临时缓解方案。
4. RBAC 策略：搜索策略文件中所有 resource 为*且 action 为create/*的规则，将其展开为显式资源列表，避免意外获得exec权限；评估是否启用server.rbac.log.enforce.enable，并同步补齐logs, get授权。
5. ServiceAccount：检查是否有自定义环境依赖 repo-server 的defaultServiceAccount。
6. 插件：为每个 sidecar 插件配置独立/tmp卷；更新自定义插件以处理ARGOCD_ENV_前缀；核对 sidecar 插件的全部必需环境变量；确认第三方插件的 2.4 兼容性。
7. 测试：在预发/测试环境完整跑一遍应用同步、日志查看、exec等功能验证后再升级生产。

上述每一项都可以在当前仓库中找到对应的实现或配置依据：RBAC 资源定义见 util/rbac/rbac.go，内置策略见 assets/builtin-policy.csv，插件环境变量实现见 reposerver/repository/repository.go，相关用户指南见 docs/operator-manual/config-management-plugins.md 与 docs/user-guide/projects.md。按此清单逐项验证，即可将 v2.4 的破坏性变更风险降至最低。

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