Argo CD v3.4 到 v3.5 升级指南Breaking Changes 全解析与迁移实践【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd导读本文基于仓库中的官方升级文档 3.4-3.5.md系统梳理从 Argo CD v3.4 升级到 v3.5 时的所有破坏性变更Breaking Changes、行为改进、API 与安全变化以及弃用项。文中将结合仓库源码如 util/helm/helm.go、ui/src/app/applications/components/utils.tsx、util/db/repository_secrets.go 等深入解释变更的底层原理并给出可直接复制的迁移命令、YAML 配置与操作步骤帮助运维人员制定一份完整的升级检查清单。一、破坏性变更Breaking Changes总览v3.5 是一个在 UI、Helm 集成、安全与 API 层面都发生实质变化的大版本。升级前建议按以下顺序逐项核对避免线上故障UI 应用详情页 CSS 类名加了user-app-前缀—— 影响自定义样式选择器Helm 升级到 v4.x—— 影响所有使用明文 HTTP非 HTTPSOCI 仓库的场景包括 Chart 依赖仓库UI 扩展必须外部化react/jsx-runtime—— 影响基于旧版 Argo CD UI 构建的扩展插件事件列表 gRPC 方法返回值类型变更—— 影响自定义 gRPC 客户端与基于 OpenAPI 生成的 REST 客户端GnuPG 签名验证被 Source Integrity 取代—— 涉及signatureKeys弃用与迁移。下文逐一展开。二、UI 自定义样式的类名前缀变更变更内容在 Argo CD 3.5 中Application 与 ApplicationSet 详情页会基于应用名称生成一个 CSS 类供运维人员通过自定义样式针对特定应用做页面定制。3.5 起该类的格式从application-details appName改为application-details user-app-appName即统一加上user-app-前缀。这一改动的动机是若应用名称恰好与某个内置组件的样式类同名例如应用叫login旧格式会渲染出application-details login从而把登录页面的.login样式错误地加载到应用详情页导致页面布局损坏对应 issue #24220。源码印证该逻辑在 ui/src/app/applications/components/utils.tsx 中实现export function getApplicationDetailsContainerClass(appName: string): string { return application-details user-app-${appName}; }对应的单元测试 ui/src/app/applications/components/utils.test.tsx 也明确断言了前缀行为expect(getApplicationDetailsContainerClass(guestbook)).toBe(application-details user-app-guestbook); expect(classes).toContain(user-app-login);迁移操作如果曾在自定义 CSS 中使用过这个类需要更新选择器/* Before (v3.4 及更早) */ .application-details.my-app { ... } /* After (v3.5) */ .application-details.user-app-my-app { ... }自定义样式的注入方式本身不受影响仍是通过argocd-cmConfigMap 的ui.cssurl配置远程 CSS 地址或将 CSS 文件挂载到 argocd-server 容器后指定路径详见 custom-styles.md。三、Helm v4 升级明文 HTTP OCI 仓库成为强制显式配置变更背景v3.5 将内置 Helm 升级到4.x文档首节写 4.2.0Helm Upgraded 一节最终确认升级到4.2.1。Helm v4 对 OCI 实现做了更严格的约束如果 registry 不启用 TLS必须在helm push、helm registry login以及helm dependency build时显式传入--plain-http。对 Argo CD 用户而言这意味着所有使用明文 HTTP OCI 仓库的场景都需要在 Argo CD 侧显式声明。主要有两类动作1. 为现有 OCI 仓库设置--insecure-oci-force-http方式一CLI 显式更新需使用 v3.5 版本的 CLIargocd repo add repo-url --type helm --enable-oci --insecure-oci-force-http --upsert # 或针对 typeoci 的仓库 argocd repo add repo-url --type oci --insecure-oci-force-http --upsert方式二直接编辑 Kubernetes SecretstringData: insecureOCIForceHttp: true2. 显式注册明文 HTTP 的依赖仓库如果 Helm Chart 的Chart.yaml中有以oci://...声明的 OCI 依赖且这些依赖托管在明文 HTTP registry 上那么这些依赖仓库现在必须像主仓库一样显式添加到 Argo CD 并设置--insecure-oci-force-http。原因在于Helm v3 时代明文 HTTP 的 OCI 依赖仓库可以不注册、透明访问Helm v4 时代Argo CD 必须知道哪些依赖仓库使用明文 HTTP才能在执行helm dependency build时正确传入--plain-http。底层实现flag 如何传递到 Helm 命令源码 util/helm/helm.go 中的DependencyBuild逻辑可以印证这一点Argo CD 会先遍历所有依赖仓库对启用了 OCI 且有凭据的仓库逐一执行helm registry login此时每个仓库可独立携带自己的InsecureOCIForceHttp随后再扫描一次只要任何一个依赖仓库设置了InsecureOCIForceHttp整个helm dependency build命令就会追加--plain-http——因为 helm dependency build 不支持按仓库分别指定 TLS 策略。// util/helm/helm.go 中的关键逻辑节选 plainHTTP : false for i : range h.repos { if h.repos[i].InsecureOCIForceHttp { plainHTTP true break } } _, err : h.cmd.dependencyBuild(h.insecure, plainHTTP)命令构造层面util/helm/cmd.go 的RegistryLogin会在plainHTTP为 true 时追加--plain-http而 util/helm/cmd_test.go 中的测试用例plain-http与insecure and plain-http both set验证了该参数在helm registry login、helm pull、helm dependency build三条命令上的拼接行为。--insecure-oci-force-http的合法性校验在 cmd/util/common.go 的ValidateInsecureOCIForceHTTP中实现该 flag 只能用于typeoci仓库或typehelm且开启了--enable-oci的仓库否则报错--insecure-oci-force-http requires --type oci or --enable-oci对应测试见 cmd/util/common_test.go。Secret 中insecureOCIForceHttp键的读写由 util/db/repository_secrets.go 通过updateSecretBool处理测试 util/db/repository_secrets_test.go 验证了该键与Repository.InsecureOCIForceHttp字段的双向同步。已知限制冲突的 TLS flagHelm v4当同一个 Argo CD OCI 仓库同时设置以下两个 flag 时会产生冲突--insecure-skip-server-verification传给 Helm 为--insecure-skip-tls-verify--insecure-oci-force-http传给 Helm 为--plain-httpHelm v4 会静默丢弃--plain-http因为--insecure-skip-tls-verify具有内部优先级最终明文 HTTP 操作会以http: server gave HTTP response to HTTPS client失败。受影响的具体场景场景失败环节typehelm--enable-oci仓库同时挂两个 flagChart 拉取失败主仓库设--insecure-skip-server-verification依赖仓库设--insecure-oci-force-httphelm dependency build失败官方文档明确指出当同一链路中两种配置都确实需要时目前没有 workaround。升级前请核查是否命中此限制。对spec.source.helm.version的影响如果 Application 中曾显式声明 Helm v3spec: source: helm: version: v3该字段在 v3.5 中会被忽略——Argo CD 将只使用 Helm v4 渲染 Chart。无需删除或修改此字段保留即可但应了解其不再生效。四、UI 扩展升级React 16 → React 19v3.5 将 Argo CD UI 从 React 16 升级到React 19。基于旧版 UI 构建的 UI 扩展在加载时可能抛出TypeError界面会呈现如下错误Extension name.js failed to load: TypeError: Cannot read properties of undefined (reading prop)解决办法重新构建扩展将react/jsx-runtime外部化externalize。完整的修复指南参见 ui-extensions-react-19-upgrading.md。未安装 UI 扩展的用户无需任何操作。五、事件列表 gRPC 方法返回类型变更API Changes变更内容Argo CD 3.5 将事件列表相关 gRPC API 的响应类型从 Kubernetes 的k8s.io.api.core.v1.EventList改为 Argo CD 自定义的EventList类型目的是在不把 Kubernetes protobuf 类型直接暴露到 Argo CD 公共 gRPC 接口的前提下兼容更新的 Kubernetes protobuf 定义。受影响的 gRPC 方法application.ApplicationService/ListResourceEventsapplicationset.ApplicationSetService/ListResourceEventsproject.ProjectService/ListEvents对 gRPC 客户端的影响任何调用上述 RPC 的生成型或自定义 gRPC 客户端都必须与 Argo CD 3.5 服务端同步重新生成或升级。以下方式不能作为兼容方案直接调用受影响 RPC 的程序或脚本必须同步更新使用 grpc-web 协议不是兼容 workaround。Argo CD 官方 CLI不依赖这些 API因此不受影响。对 REST 客户端和 UI 的影响REST 路径与请求方式完全不变GET /api/v1/applications/{name}/eventsGET /api/v1/applicationsets/{name}/eventsGET /api/v1/projects/{name}/eventsJSON 响应体仍是EventList形状的载荷因此 UI 和以 JSON 方式消费这些端点的 REST 集成不受影响。OpenAPI / Schema 注意点REST 路径和 JSON 载荷不变但生成的 OpenAPI schema 中这些端点改用了 Argo CD 的eventsEventList定义替代io.k8s.api.core.v1.EventList。如果基于 Argo CD 的 OpenAPI 定义生成 REST 客户端请将其视为 schema 级别的破坏性变更升级时需重新生成或更新。六、行为改进与修复Behavioral Improvements / Fixes1. 模拟身份Impersonation扩展到全部 server 操作启用模拟身份后3.5 之前只作用于 sync 操作3.5 起所有通过 UI 或 API 触发的操作查看日志、列出事件、删除资源、执行资源动作等都会使用由 AppProject 的destinationServiceAccounts配置派生的模拟服务账号。受影响的操作与所需权限操作Kubernetes API 调用所需 RBAC verbsGet resourceGET目标资源getPatch resourcePATCH目标资源get,patchDelete resourceDELETE目标资源deleteList resource eventsLIST于eventscore/v1listView pod logsGET于pods和pods/loggetRun resource actionGET、CREATE、PATCH目标资源get,create,patch上表覆盖内置操作自定义资源动作custom resource actions可能根据其调用的 Kubernetes API 需要额外权限。升级动作启用了 impersonation 的用户必须确保destinationServiceAccounts中配置的服务账号具备上述操作的权限。未启用 impersonation 的用户无需操作。2. 无凭据 SSH 仓库改用argocd-ssh-known-hosts-cm校验主机密钥Argo CD 将go-git升级到 v5.19.x其 SSH 主机密钥校验更加严格。为保证主机密钥校验仍能命中 Argo CD 托管的argocd-ssh-known-hosts-cmConfigMap并避免新版 go-git 下的knownhosts: key mismatch握手失败Argo CD 现在会为未配置显式凭据的 SSH 仓库自行构建 SSH auth。行为对比升级前无凭据的 SSH 仓库 URL 会走 go-git 的默认 auth builder基于ssh-agent构建 auth并从容器内的~/.ssh/known_hosts或$SSH_KNOWN_HOSTS读取 known_hosts升级后Argo CD 构建相同的ssh-agent式 auth但将主机密钥回调指向argocd-ssh-known-hosts-cmConfigMap与“配置了凭据的仓库”行为保持一致。升级动作如果此前依赖 repo-server 镜像/Pod 内自定义的~/.ssh/known_hosts例如打进自定义镜像或通过 volume 挂载请把这些主机密钥改加到argocd-ssh-known-hosts-cm。仅使用“配置了凭据的 SSH 仓库”或仅使用 HTTPS 仓库的用户无需操作。3. GnuPG 签名验证被 Source Integrity 取代GnuPG 密钥验证功能已被 Source Integrity 取代——后者是更通用的应用源完整性校验子系统。旧配置临时继续生效会输出 warning以方便迁移但建议尽快迁移。七、安全变更Security Changes本版本的安全侧变化集中在模拟身份impersonation覆盖面扩大见上文第六节与repo-server 新增 mTLS 支持见下文第九节两大块。另外需注意由于 Helm v4 对明文 HTTP OCI registry 的严格校验原先“透明访问”的明文 HTTP 依赖仓库不再被隐式信任必须显式登记并声明--insecure-oci-force-http见第三节这本质上也是一项安全收紧——未经登记的非 TLS 仓库将不再被静默访问。八、弃用项Deprecated Items1. GnuPG 签名配置弃用argocd proj add-signature-key与argocd proj remove-signature-key命令弃用AppProject 中声明.spec.signatureKeys弃用。应改在 AppProject YAML 中配置sourceIntegrity。2. GnuPG 签名验证结果弃用从 REST API 读取verifyResult字段弃用应改为消费结构化字段sourceIntegrityResult。迁移示例参考 source-integrity-git-gpg.md要复刻旧版 Argo CD 的验证行为可移除.spec.signatureKeys并写入apiVersion: argoproj.io/v1alpha1 kind: AppProject spec: sourceIntegrity: git: policies: - repos: - url: * # 项目内任意仓库 gpg: mode: head # 仅验证目标 revision 的 HEAD keys: - ... # 原 .spec.signatureKeys 中的密钥迁移说明中还提到当.spec.sourceIntegrity未定义而.spec.signatureKeys存在时Argo CD 会在后台做类似转换但官方建议主动迁移因为 source integrity 配置更灵活且.spec.signatureKeys将在未来版本移除。降级downgrade时则需反向操作在 AppProject 中重新引入.spec.signatureKeys并填入.spec.sourceIntegrity.git.policies的全部密钥再删除.spec.sourceIntegrity段降级后的旧功能仅支持全部仓库的 head 模式。未使用 GnuPG 签名验证的用户无需操作。九、其他变更Other Changes1. 发布物sbom.tar.gz内容调整普通 GitHub 发布中sbom.tar.gz仍包含bom-go-mod.spdxGo 依赖spdx-sbom-generator生成的 tag-value SPDXbom-docker-image.spdx发布镜像sigs.k8s.io/bom生成的 tag-value SPDX。变化在于 UI 依赖清单现在是bom-ui-pnpm.spdx.jsonpnpm sbom生成的SPDX 2.3 JSON取代了原来spdx-sbom-generator对./ui目录输出的 tag-value 格式。升级动作如果消费该归档的工具只扫描*.spdx文件请扩展以同时处理bom-ui-pnpm.spdx.json或改用argocd-sbom.intoto.jsonl验证sbom.tar.gz避免依赖固定的内部文件清单。2. repo-server 的 mTLS 支持新增mTLS 是默认关闭的可选能力未配置的运维人员无需任何操作。启用方式创建名为argocd-repo-server-mtls的 Secret 即可内容如下apiVersion: v1 kind: Secret metadata: name: argocd-repo-server-mtls namespace: argocd type: Opaque stringData: client-ca.crt: | PEM-encoded CA certificate that signed the client certs client.crt: | PEM-encoded shared client certificate client.key: | PEM-encoded private key for the shared client certificate该 Secret 会被自动挂载到每个相关 Pod 的/app/config/reposerver/mtls路径。所有组件默认从该挂载路径读取 cert/key/CA 文件因此只要 Secret 存在mTLS 即自动启用——无需修改 ConfigMap、无需 flag 覆盖、无需额外配置。关键点汇总服务端repo-server--client-ca-path默认指向/app/config/reposerver/mtls/client-ca.crt即自动挂载路径文件存在即启用 mTLS缺失则静默跳过不能与--disable-tls组合使用服务端 TLS cert/key 从/app/config/reposerver/tls/tls.crt与tls.key加载。客户端argocd-server、application-controller、applicationset-controller、notifications-controller--repo-server-client-cert-path默认指向/app/config/reposerver/mtls/client.crt文件不存在则跳过 mTLS 客户端证书--repo-server-client-cert-key-path默认指向/app/config/reposerver/mtls/client.key同理--repo-server-ca-cert-path可选当 repo-server 的服务端证书由自定义 CA 签发时使用。运维提示启用 mTLS 后repo-server 会为自身的 liveness 自检自动生成临时客户端证书无需修改探针所有上述配置均有对应的环境变量与argocd-cmd-params-cmConfigMap 键例如ARGOCD_REPO_SERVER_CLIENT_CA_PATH详见 mtls.md。完整搭建步骤、各组件证书选项、验证方法与排障指南见 mtls.md。3.--repo-server-strict-tls弃用改用--repo-server-ca-cert-path弃用范围--repo-server-strict-tls布尔 flag 在以下组件中全部弃用argocd-serverargocd-application-controllerargocd-applicationset-controllerargocd-notification弃用原因旧 flag 采用隐式行为自动加载/app/config/server/tls/下的内嵌证书难以在各组件间保持一致新方式更显式且与 Kubernetes Secret 挂载模式对齐。重要此弃用不影响TLS 能力本身——仍可用新 flag 配置纯 TLS不含 mTLS连接。迁移指南方式一迁移到--repo-server-ca-cert-path推荐# Before (3.4 及更早) argocd-server \ --repo-server-strict-tls # After (3.5) argocd-server \ --repo-server-ca-cert-path/app/config/server/tls/ca.crt对应 Kubernetes manifests 的写法变化# Before: spec: containers: - name: argocd-server args: - argocd-server - --repo-server-strict-tls volumeMounts: - name: server-tls mountPath: /app/config/server/tls # After: spec: containers: - name: argocd-server args: - argocd-server - --repo-server-ca-cert-path/app/config/server/tls/ca.crt volumeMounts: - name: server-tls mountPath: /app/config/server/tls方式二使用环境变量备选# Before: argocd-server --repo-server-strict-tls # After: export ARGOCD_SERVER_REPO_SERVER_CA_CERT_PATH/app/config/server/tls/ca.crt argocd-server方式三继续使用弃用 flag不推荐仅临时该 flag 在 3.5 仍可用会输出弃用警告且支持与新 flag 同时使用# 3.5 中仍可用会有弃用警告 argocd-server \ --repo-server-strict-tls \ --repo-server-ca-cert-path/app/config/server/tls/ca.crt向后兼容性两个 flag 可同时使用采用OR 语义任一为 true 即启用严格校验功能无损TLS 校验能力保持不变新 flag 更显式、更易维护。时间线v3.5弃用 flag 仍可用带警告v3.6该 flag 可能被移除请提前规划迁移。所有受影响组件server、application-controller、applicationset-controller、notification-controller的迁移模式一致。十、Kustomize / Helm / 自定义健康检查Kustomize本版本升级文档中未列出 Kustomize 的升级项无内容Helm升级到4.2.1破坏性变更已在本章第三节详述Custom Healthchecks本版本无新增自定义健康检查条目。十一、升级检查清单速查检查项是否受影响需执行动作自定义 CSS 中是否使用application-details app类是选择器改为application-details.user-app-app是否存在明文 HTTP 的 OCI 仓库typehelm enable-oci / typeoci是为仓库及依赖仓库设置--insecure-oci-force-http --upsert或 Secret 中加insecureOCIForceHttp: true主仓库/依赖仓库是否同时存在 insecure-skip-server-verification 与 insecure-oci-force-http是存在已知限制、无 workaround需调整架构Application 是否声明spec.source.helm.version: v3是该字段被忽略无需修改但应知晓用 Helm v4 渲染是否安装 UI 扩展是按 ui-extensions-react-19-upgrading.md 外部化react/jsx-runtime并重建是否直接调用事件列表 gRPC / 基于 OpenAPI 生成 REST 客户端是重新生成/升级客户端CLI 与 UI 不受影响是否启用 impersonation是为destinationServiceAccounts配置 get/patch/delete/list/create 等所需权限是否依赖无凭据 SSH 仓库的容器内~/.ssh/known_hosts是主机密钥改入argocd-ssh-known-hosts-cm是否使用 GnuPG 签名验证是迁移到sourceIntegrity详见 source-integrity-git-gpg.md是否消费sbom.tar.gz且只扫描*.spdx是兼容bom-ui-pnpm.spdx.json或改用argocd-sbom.intoto.jsonl是否配置 repo-server 的--repo-server-strict-tls是迁移到--repo-server-ca-cert-path或对应环境变量是否希望启用 repo-server mTLS可选创建argocd-repo-server-mtlsSecret 即自动启用十二、参考文档本文核心来源docs/operator-manual/upgrading/3.4-3.5.md升级总览docs/operator-manual/upgrading/overview.mdUI 扩展 React 19 升级指南docs/operator-manual/upgrading/ui-extensions-react-19-upgrading.md自定义样式docs/operator-manual/custom-styles.md模拟身份同步docs/operator-manual/app-sync-using-impersonation.mdSource Integritydocs/user-guide/source-integrity.md、GnuPG 迁移docs/user-guide/source-integrity-git-gpg.mdrepo-server mTLSdocs/operator-manual/mtls.md【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Argo CD v3.4 到 v3.5 升级指南Breaking Changes 全解析与迁移实践【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd导读本文基于仓库中的官方升级文档 3.4-3.5.md系统梳理从 Argo CD v3.4 升级到 v3.5 时的所有破坏性变更Breaking Changes、行为改进、API 与安全变化以及弃用项。文中将结合仓库源码如 util/helm/helm.go、ui/src/app/applications/components/utils.tsx、util/db/repository_secrets.go 等深入解释变更的底层原理并给出可直接复制的迁移命令、YAML 配置与操作步骤帮助运维人员制定一份完整的升级检查清单。一、破坏性变更Breaking Changes总览v3.5 是一个在 UI、Helm 集成、安全与 API 层面都发生实质变化的大版本。升级前建议按以下顺序逐项核对避免线上故障UI 应用详情页 CSS 类名加了user-app-前缀—— 影响自定义样式选择器Helm 升级到 v4.x—— 影响所有使用明文 HTTP非 HTTPSOCI 仓库的场景包括 Chart 依赖仓库UI 扩展必须外部化react/jsx-runtime—— 影响基于旧版 Argo CD UI 构建的扩展插件事件列表 gRPC 方法返回值类型变更—— 影响自定义 gRPC 客户端与基于 OpenAPI 生成的 REST 客户端GnuPG 签名验证被 Source Integrity 取代—— 涉及signatureKeys弃用与迁移。下文逐一展开。二、UI 自定义样式的类名前缀变更变更内容在 Argo CD 3.5 中Application 与 ApplicationSet 详情页会基于应用名称生成一个 CSS 类供运维人员通过自定义样式针对特定应用做页面定制。3.5 起该类的格式从application-details appName改为application-details user-app-appName即统一加上user-app-前缀。这一改动的动机是若应用名称恰好与某个内置组件的样式类同名例如应用叫login旧格式会渲染出application-details login从而把登录页面的.login样式错误地加载到应用详情页导致页面布局损坏对应 issue #24220。源码印证该逻辑在 ui/src/app/applications/components/utils.tsx 中实现export function getApplicationDetailsContainerClass(appName: string): string { return application-details user-app-${appName}; }对应的单元测试 ui/src/app/applications/components/utils.test.tsx 也明确断言了前缀行为expect(getApplicationDetailsContainerClass(guestbook)).toBe(application-details user-app-guestbook); expect(classes).toContain(user-app-login);迁移操作如果曾在自定义 CSS 中使用过这个类需要更新选择器/* Before (v3.4 及更早) */ .application-details.my-app { ... } /* After (v3.5) */ .application-details.user-app-my-app { ... }自定义样式的注入方式本身不受影响仍是通过argocd-cmConfigMap 的ui.cssurl配置远程 CSS 地址或将 CSS 文件挂载到 argocd-server 容器后指定路径详见 custom-styles.md。三、Helm v4 升级明文 HTTP OCI 仓库成为强制显式配置变更背景v3.5 将内置 Helm 升级到4.x文档首节写 4.2.0Helm Upgraded 一节最终确认升级到4.2.1。Helm v4 对 OCI 实现做了更严格的约束如果 registry 不启用 TLS必须在helm push、helm registry login以及helm dependency build时显式传入--plain-http。对 Argo CD 用户而言这意味着所有使用明文 HTTP OCI 仓库的场景都需要在 Argo CD 侧显式声明。主要有两类动作1. 为现有 OCI 仓库设置--insecure-oci-force-http方式一CLI 显式更新需使用 v3.5 版本的 CLIargocd repo add repo-url --type helm --enable-oci --insecure-oci-force-http --upsert # 或针对 typeoci 的仓库 argocd repo add repo-url --type oci --insecure-oci-force-http --upsert方式二直接编辑 Kubernetes SecretstringData: insecureOCIForceHttp: true2. 显式注册明文 HTTP 的依赖仓库如果 Helm Chart 的Chart.yaml中有以oci://...声明的 OCI 依赖且这些依赖托管在明文 HTTP registry 上那么这些依赖仓库现在必须像主仓库一样显式添加到 Argo CD 并设置--insecure-oci-force-http。原因在于Helm v3 时代明文 HTTP 的 OCI 依赖仓库可以不注册、透明访问Helm v4 时代Argo CD 必须知道哪些依赖仓库使用明文 HTTP才能在执行helm dependency build时正确传入--plain-http。底层实现flag 如何传递到 Helm 命令源码 util/helm/helm.go 中的DependencyBuild逻辑可以印证这一点Argo CD 会先遍历所有依赖仓库对启用了 OCI 且有凭据的仓库逐一执行helm registry login此时每个仓库可独立携带自己的InsecureOCIForceHttp随后再扫描一次只要任何一个依赖仓库设置了InsecureOCIForceHttp整个helm dependency build命令就会追加--plain-http——因为 helm dependency build 不支持按仓库分别指定 TLS 策略。// util/helm/helm.go 中的关键逻辑节选 plainHTTP : false for i : range h.repos { if h.repos[i].InsecureOCIForceHttp { plainHTTP true break } } _, err : h.cmd.dependencyBuild(h.insecure, plainHTTP)命令构造层面util/helm/cmd.go 的RegistryLogin会在plainHTTP为 true 时追加--plain-http而 util/helm/cmd_test.go 中的测试用例plain-http与insecure and plain-http both set验证了该参数在helm registry login、helm pull、helm dependency build三条命令上的拼接行为。--insecure-oci-force-http的合法性校验在 cmd/util/common.go 的ValidateInsecureOCIForceHTTP中实现该 flag 只能用于typeoci仓库或typehelm且开启了--enable-oci的仓库否则报错--insecure-oci-force-http requires --type oci or --enable-oci对应测试见 cmd/util/common_test.go。Secret 中insecureOCIForceHttp键的读写由 util/db/repository_secrets.go 通过updateSecretBool处理测试 util/db/repository_secrets_test.go 验证了该键与Repository.InsecureOCIForceHttp字段的双向同步。已知限制冲突的 TLS flagHelm v4当同一个 Argo CD OCI 仓库同时设置以下两个 flag 时会产生冲突--insecure-skip-server-verification传给 Helm 为--insecure-skip-tls-verify--insecure-oci-force-http传给 Helm 为--plain-httpHelm v4 会静默丢弃--plain-http因为--insecure-skip-tls-verify具有内部优先级最终明文 HTTP 操作会以http: server gave HTTP response to HTTPS client失败。受影响的具体场景场景失败环节typehelm--enable-oci仓库同时挂两个 flagChart 拉取失败主仓库设--insecure-skip-server-verification依赖仓库设--insecure-oci-force-httphelm dependency build失败官方文档明确指出当同一链路中两种配置都确实需要时目前没有 workaround。升级前请核查是否命中此限制。对spec.source.helm.version的影响如果 Application 中曾显式声明 Helm v3spec: source: helm: version: v3该字段在 v3.5 中会被忽略——Argo CD 将只使用 Helm v4 渲染 Chart。无需删除或修改此字段保留即可但应了解其不再生效。四、UI 扩展升级React 16 → React 19v3.5 将 Argo CD UI 从 React 16 升级到React 19。基于旧版 UI 构建的 UI 扩展在加载时可能抛出TypeError界面会呈现如下错误Extension name.js failed to load: TypeError: Cannot read properties of undefined (reading prop)解决办法重新构建扩展将react/jsx-runtime外部化externalize。完整的修复指南参见 ui-extensions-react-19-upgrading.md。未安装 UI 扩展的用户无需任何操作。五、事件列表 gRPC 方法返回类型变更API Changes变更内容Argo CD 3.5 将事件列表相关 gRPC API 的响应类型从 Kubernetes 的k8s.io.api.core.v1.EventList改为 Argo CD 自定义的EventList类型目的是在不把 Kubernetes protobuf 类型直接暴露到 Argo CD 公共 gRPC 接口的前提下兼容更新的 Kubernetes protobuf 定义。受影响的 gRPC 方法application.ApplicationService/ListResourceEventsapplicationset.ApplicationSetService/ListResourceEventsproject.ProjectService/ListEvents对 gRPC 客户端的影响任何调用上述 RPC 的生成型或自定义 gRPC 客户端都必须与 Argo CD 3.5 服务端同步重新生成或升级。以下方式不能作为兼容方案直接调用受影响 RPC 的程序或脚本必须同步更新使用 grpc-web 协议不是兼容 workaround。Argo CD 官方 CLI不依赖这些 API因此不受影响。对 REST 客户端和 UI 的影响REST 路径与请求方式完全不变GET /api/v1/applications/{name}/eventsGET /api/v1/applicationsets/{name}/eventsGET /api/v1/projects/{name}/eventsJSON 响应体仍是EventList形状的载荷因此 UI 和以 JSON 方式消费这些端点的 REST 集成不受影响。OpenAPI / Schema 注意点REST 路径和 JSON 载荷不变但生成的 OpenAPI schema 中这些端点改用了 Argo CD 的eventsEventList定义替代io.k8s.api.core.v1.EventList。如果基于 Argo CD 的 OpenAPI 定义生成 REST 客户端请将其视为 schema 级别的破坏性变更升级时需重新生成或更新。六、行为改进与修复Behavioral Improvements / Fixes1. 模拟身份Impersonation扩展到全部 server 操作启用模拟身份后3.5 之前只作用于 sync 操作3.5 起所有通过 UI 或 API 触发的操作查看日志、列出事件、删除资源、执行资源动作等都会使用由 AppProject 的destinationServiceAccounts配置派生的模拟服务账号。受影响的操作与所需权限操作Kubernetes API 调用所需 RBAC verbsGet resourceGET目标资源getPatch resourcePATCH目标资源get,patchDelete resourceDELETE目标资源deleteList resource eventsLIST于eventscore/v1listView pod logsGET于pods和pods/loggetRun resource actionGET、CREATE、PATCH目标资源get,create,patch上表覆盖内置操作自定义资源动作custom resource actions可能根据其调用的 Kubernetes API 需要额外权限。升级动作启用了 impersonation 的用户必须确保destinationServiceAccounts中配置的服务账号具备上述操作的权限。未启用 impersonation 的用户无需操作。2. 无凭据 SSH 仓库改用argocd-ssh-known-hosts-cm校验主机密钥Argo CD 将go-git升级到 v5.19.x其 SSH 主机密钥校验更加严格。为保证主机密钥校验仍能命中 Argo CD 托管的argocd-ssh-known-hosts-cmConfigMap并避免新版 go-git 下的knownhosts: key mismatch握手失败Argo CD 现在会为未配置显式凭据的 SSH 仓库自行构建 SSH auth。行为对比升级前无凭据的 SSH 仓库 URL 会走 go-git 的默认 auth builder基于ssh-agent构建 auth并从容器内的~/.ssh/known_hosts或$SSH_KNOWN_HOSTS读取 known_hosts升级后Argo CD 构建相同的ssh-agent式 auth但将主机密钥回调指向argocd-ssh-known-hosts-cmConfigMap与“配置了凭据的仓库”行为保持一致。升级动作如果此前依赖 repo-server 镜像/Pod 内自定义的~/.ssh/known_hosts例如打进自定义镜像或通过 volume 挂载请把这些主机密钥改加到argocd-ssh-known-hosts-cm。仅使用“配置了凭据的 SSH 仓库”或仅使用 HTTPS 仓库的用户无需操作。3. GnuPG 签名验证被 Source Integrity 取代GnuPG 密钥验证功能已被 Source Integrity 取代——后者是更通用的应用源完整性校验子系统。旧配置临时继续生效会输出 warning以方便迁移但建议尽快迁移。七、安全变更Security Changes本版本的安全侧变化集中在模拟身份impersonation覆盖面扩大见上文第六节与repo-server 新增 mTLS 支持见下文第九节两大块。另外需注意由于 Helm v4 对明文 HTTP OCI registry 的严格校验原先“透明访问”的明文 HTTP 依赖仓库不再被隐式信任必须显式登记并声明--insecure-oci-force-http见第三节这本质上也是一项安全收紧——未经登记的非 TLS 仓库将不再被静默访问。八、弃用项Deprecated Items1. GnuPG 签名配置弃用argocd proj add-signature-key与argocd proj remove-signature-key命令弃用AppProject 中声明.spec.signatureKeys弃用。应改在 AppProject YAML 中配置sourceIntegrity。2. GnuPG 签名验证结果弃用从 REST API 读取verifyResult字段弃用应改为消费结构化字段sourceIntegrityResult。迁移示例参考 source-integrity-git-gpg.md要复刻旧版 Argo CD 的验证行为可移除.spec.signatureKeys并写入apiVersion: argoproj.io/v1alpha1 kind: AppProject spec: sourceIntegrity: git: policies: - repos: - url: * # 项目内任意仓库 gpg: mode: head # 仅验证目标 revision 的 HEAD keys: - ... # 原 .spec.signatureKeys 中的密钥迁移说明中还提到当.spec.sourceIntegrity未定义而.spec.signatureKeys存在时Argo CD 会在后台做类似转换但官方建议主动迁移因为 source integrity 配置更灵活且.spec.signatureKeys将在未来版本移除。降级downgrade时则需反向操作在 AppProject 中重新引入.spec.signatureKeys并填入.spec.sourceIntegrity.git.policies的全部密钥再删除.spec.sourceIntegrity段降级后的旧功能仅支持全部仓库的 head 模式。未使用 GnuPG 签名验证的用户无需操作。九、其他变更Other Changes1. 发布物sbom.tar.gz内容调整普通 GitHub 发布中sbom.tar.gz仍包含bom-go-mod.spdxGo 依赖spdx-sbom-generator生成的 tag-value SPDXbom-docker-image.spdx发布镜像sigs.k8s.io/bom生成的 tag-value SPDX。变化在于 UI 依赖清单现在是bom-ui-pnpm.spdx.jsonpnpm sbom生成的SPDX 2.3 JSON取代了原来spdx-sbom-generator对./ui目录输出的 tag-value 格式。升级动作如果消费该归档的工具只扫描*.spdx文件请扩展以同时处理bom-ui-pnpm.spdx.json或改用argocd-sbom.intoto.jsonl验证sbom.tar.gz避免依赖固定的内部文件清单。2. repo-server 的 mTLS 支持新增mTLS 是默认关闭的可选能力未配置的运维人员无需任何操作。启用方式创建名为argocd-repo-server-mtls的 Secret 即可内容如下apiVersion: v1 kind: Secret metadata: name: argocd-repo-server-mtls namespace: argocd type: Opaque stringData: client-ca.crt: | PEM-encoded CA certificate that signed the client certs client.crt: | PEM-encoded shared client certificate client.key: | PEM-encoded private key for the shared client certificate该 Secret 会被自动挂载到每个相关 Pod 的/app/config/reposerver/mtls路径。所有组件默认从该挂载路径读取 cert/key/CA 文件因此只要 Secret 存在mTLS 即自动启用——无需修改 ConfigMap、无需 flag 覆盖、无需额外配置。关键点汇总服务端repo-server--client-ca-path默认指向/app/config/reposerver/mtls/client-ca.crt即自动挂载路径文件存在即启用 mTLS缺失则静默跳过不能与--disable-tls组合使用服务端 TLS cert/key 从/app/config/reposerver/tls/tls.crt与tls.key加载。客户端argocd-server、application-controller、applicationset-controller、notifications-controller--repo-server-client-cert-path默认指向/app/config/reposerver/mtls/client.crt文件不存在则跳过 mTLS 客户端证书--repo-server-client-cert-key-path默认指向/app/config/reposerver/mtls/client.key同理--repo-server-ca-cert-path可选当 repo-server 的服务端证书由自定义 CA 签发时使用。运维提示启用 mTLS 后repo-server 会为自身的 liveness 自检自动生成临时客户端证书无需修改探针所有上述配置均有对应的环境变量与argocd-cmd-params-cmConfigMap 键例如ARGOCD_REPO_SERVER_CLIENT_CA_PATH详见 mtls.md。完整搭建步骤、各组件证书选项、验证方法与排障指南见 mtls.md。3.--repo-server-strict-tls弃用改用--repo-server-ca-cert-path弃用范围--repo-server-strict-tls布尔 flag 在以下组件中全部弃用argocd-serverargocd-application-controllerargocd-applicationset-controllerargocd-notification弃用原因旧 flag 采用隐式行为自动加载/app/config/server/tls/下的内嵌证书难以在各组件间保持一致新方式更显式且与 Kubernetes Secret 挂载模式对齐。重要此弃用不影响TLS 能力本身——仍可用新 flag 配置纯 TLS不含 mTLS连接。迁移指南方式一迁移到--repo-server-ca-cert-path推荐# Before (3.4 及更早) argocd-server \ --repo-server-strict-tls # After (3.5) argocd-server \ --repo-server-ca-cert-path/app/config/server/tls/ca.crt对应 Kubernetes manifests 的写法变化# Before: spec: containers: - name: argocd-server args: - argocd-server - --repo-server-strict-tls volumeMounts: - name: server-tls mountPath: /app/config/server/tls # After: spec: containers: - name: argocd-server args: - argocd-server - --repo-server-ca-cert-path/app/config/server/tls/ca.crt volumeMounts: - name: server-tls mountPath: /app/config/server/tls方式二使用环境变量备选# Before: argocd-server --repo-server-strict-tls # After: export ARGOCD_SERVER_REPO_SERVER_CA_CERT_PATH/app/config/server/tls/ca.crt argocd-server方式三继续使用弃用 flag不推荐仅临时该 flag 在 3.5 仍可用会输出弃用警告且支持与新 flag 同时使用# 3.5 中仍可用会有弃用警告 argocd-server \ --repo-server-strict-tls \ --repo-server-ca-cert-path/app/config/server/tls/ca.crt向后兼容性两个 flag 可同时使用采用OR 语义任一为 true 即启用严格校验功能无损TLS 校验能力保持不变新 flag 更显式、更易维护。时间线v3.5弃用 flag 仍可用带警告v3.6该 flag 可能被移除请提前规划迁移。所有受影响组件server、application-controller、applicationset-controller、notification-controller的迁移模式一致。十、Kustomize / Helm / 自定义健康检查Kustomize本版本升级文档中未列出 Kustomize 的升级项无内容Helm升级到4.2.1破坏性变更已在本章第三节详述Custom Healthchecks本版本无新增自定义健康检查条目。十一、升级检查清单速查检查项是否受影响需执行动作自定义 CSS 中是否使用application-details app类是选择器改为application-details.user-app-app是否存在明文 HTTP 的 OCI 仓库typehelm enable-oci / typeoci是为仓库及依赖仓库设置--insecure-oci-force-http --upsert或 Secret 中加insecureOCIForceHttp: true主仓库/依赖仓库是否同时存在 insecure-skip-server-verification 与 insecure-oci-force-http是存在已知限制、无 workaround需调整架构Application 是否声明spec.source.helm.version: v3是该字段被忽略无需修改但应知晓用 Helm v4 渲染是否安装 UI 扩展是按 ui-extensions-react-19-upgrading.md 外部化react/jsx-runtime并重建是否直接调用事件列表 gRPC / 基于 OpenAPI 生成 REST 客户端是重新生成/升级客户端CLI 与 UI 不受影响是否启用 impersonation是为destinationServiceAccounts配置 get/patch/delete/list/create 等所需权限是否依赖无凭据 SSH 仓库的容器内~/.ssh/known_hosts是主机密钥改入argocd-ssh-known-hosts-cm是否使用 GnuPG 签名验证是迁移到sourceIntegrity详见 source-integrity-git-gpg.md是否消费sbom.tar.gz且只扫描*.spdx是兼容bom-ui-pnpm.spdx.json或改用argocd-sbom.intoto.jsonl是否配置 repo-server 的--repo-server-strict-tls是迁移到--repo-server-ca-cert-path或对应环境变量是否希望启用 repo-server mTLS可选创建argocd-repo-server-mtlsSecret 即自动启用十二、参考文档本文核心来源docs/operator-manual/upgrading/3.4-3.5.md升级总览docs/operator-manual/upgrading/overview.mdUI 扩展 React 19 升级指南docs/operator-manual/upgrading/ui-extensions-react-19-upgrading.md自定义样式docs/operator-manual/custom-styles.md模拟身份同步docs/operator-manual/app-sync-using-impersonation.mdSource Integritydocs/user-guide/source-integrity.md、GnuPG 迁移docs/user-guide/source-integrity-git-gpg.mdrepo-server mTLSdocs/operator-manual/mtls.md【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
