Argo CD 2.5 升级到 2.6 完整指南已知问题、破坏性变更与迁移避坑手册【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本篇升级指南以官方 v2.5 到 2.6 升级文档 为核心骨架系统梳理从 Argo CD 2.5 升级到 2.6 过程中必须掌握的已知问题Known Issues、破坏性变更Breaking Changes及对应解决方案。文中涉及的每个关键点均结合当前仓库源码server/application/application.proto、util/oidc/provider.go、gitops-engine/pkg/health/health_job.go等进行佐证帮助运维人员、平台工程师和 ApplicationSet 使用者在升级前完成风险评估在升级后快速定位并修复异常行为。一、升级前的已知问题清单1.1 2.6.6 之前的project过滤器失效问题问题背景2.4.0 引入的 API 破坏性变更Argo CD 2.4.0 引入了一个破坏性的 API 变更将 Application 列表查询过滤器从project重命名为projects从单数变为复数语义也由单个项目变为项目列表。这一变更直接反映在 API 定义中当前仓库的 ApplicationQuery 定义 中projects字段field 3用于限制返回的应用列表的项目名列表同时保留了projectfield 8作为为向后兼容保留的旧名称legacy name for backwards-compatibility。对 API 客户端的影响任何通过 REST API 与 Argo CD API Server 通信的客户端如果在请求中仍使用旧的project字段来过滤项目该过滤条件将不会生效在 2.4.0 到 2.6.5 之间未修复的版本中。失效的项目过滤器可能带来严重后果——例如当你依赖该过滤器列出待删除的 Applications 时过滤失效可能导致误删或漏删。对 CLI 客户端的影响版本低于 v2.4.0 的 CLI 客户端依赖客户端侧过滤client-side filtering不受此 bug 影响。修复方式直接升级到以下任一版本该版本会同时接受project和projects作为合法过滤器 2.4.27 2.5.15 2.6.6从当前源码看project作为 legacy 字段被完整保留application.proto这正是向后兼容两个过滤器名的实现基础。1.2 2.6.5 中嵌套于 matrix 下的 git files 生成器故障问题描述Argo CD 2.6.5 在matrix 嵌套的 git files 生成器中引入了一个 bug。该 bug仅在 git files 生成器作为 matrix 下嵌套的第二个生成器时触发。典型场景如下apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: guestbook spec: generators: - matrix: generators: - clusters: {} - git: repoURL: https://git.example.com/org/repo.git revision: HEAD files: - path: defaults/*.yaml template: # ...影响与风险故障发生时嵌套的 git files 生成器将不产生任何参数parameters进而导致 matrix 生成器同样不产生任何参数最终该 ApplicationSet无法生成任何 Application。更危险的是如果 ApplicationSet controller 被配置为允许删除应用它会删除所有此前由该 ApplicationSet 创建的 Applications——这是一次潜在的批量删应用事故必须高度重视。规避方案不要停留在 2.6.5直接升级到 2.5.15或 2.6.6即可规避该问题。二、破坏性变更逐项解读2.1 ApplicationSetsSprig semver 函数中^前缀的行为变化Argo CD 2.5 引入了 ApplicationSets 的 Go 模板能力Go 模板可以使用Sprig 函数库。Argo CD 2.6 将 Sprig 升级到v3其中包含对Masterminds/semver v3的升级。而 Masterminds/semver v3更改了语义化版本约束中^前缀的行为。你需要做什么如果你的 Go 模板化 ApplicationSet 中使用了Sprig 的 semver 函数如semverCompare且约束中使用了^前缀请务必阅读 Masterminds/semver v3.0.0 的变更日志理解^语义变化在升级到 2.6 后重新验证所有相关 ApplicationSet 的生成结果确认版本匹配逻辑仍符合预期。此类变更属于典型的依赖升级引发的隐式行为漂移升级后应重点关注 ApplicationSet 生成的参数与目标版本选择是否发生变化。2.2 挂起suspendedJob 的应用状态由 Progressing 改为 Suspended行为变化在 Argo CD v2.6之前管理一个被挂起的 Jobsuspended Job的 Application 会被标记为Progressing——这对许多用户来说是困惑且不符合预期的行为。从v2.6 开始Argo CD 会将此类 Application 标记为Suspended。源码佐证这一状态判断逻辑位于 gitops-engine 子仓库的健康检查实现中gitops-engine/pkg/health/health.go 定义了HealthStatusSuspended HealthStatusCode Suspendedgitops-engine/pkg/health/health_job.go 中检查 Job 的JobSuspended条件当isSuspended为真时返回HealthStatusSuspended对应测试用例见 gitops-engine/pkg/health/health_test.go 及测试数据 job-suspended.yaml。升级前必须检查的事项如果你有依赖旧行为的自动化流程——例如 CI 流水线中执行argocd app wait等待应用进入健康状态——必须在这些流程升级到 v2.6之前进行适配否则可能因状态语义变化导致等待逻辑异常例如等待超时或误判失败。2.3 API Server 默认要求令牌包含aud声明变更内容Argo CD v2.6 起用于向 API Server 认证的令牌必须包含audaudience受众声明。这是一项安全增强它可以防止本非用于 API Server 的令牌被拿来访问 API Server从而缩小令牌滥用的攻击面。实现细节源码级该校验逻辑在 util/oidc/provider.go 的Verify方法中实现首先通过security.UnverifiedHasAudClaim检查令牌是否包含aud声明若令牌不包含aud声明根据argoSettings.SkipAudienceCheckWhenTokenHasNoAudience()的取值决定是否放行若令牌包含aud声明则必须与配置的允许受众OAuth2AllowedAudiences至少匹配其一否则返回验证失败并聚合每个受众的失败原因便于排查。对应配置项定义见 util/settings/settings.goSkipAudienceCheckWhenTokenHasNoAudience *boolJSON 字段skipAudienceCheckWhenTokenHasNoAudience访问器SkipAudienceCheckWhenTokenHasNoAudience()在 settings.go 中实现。兼容性说明与临时降级开关如果你依赖的OIDC 提供商不提供aud声明可以通过在 Argo CD OIDC 配置中设置以下标志来关闭该强制要求# 在 OIDC 配置中设置 skipAudienceCheckWhenTokenHasNoAudience: true完整 OIDC 配置示例参见 用户管理文档 中的现有 OIDC 提供商一节。注意该开关只影响令牌根本没有aud声明的场景一旦令牌携带了aud声明仍必须匹配允许的受众列表见 provider.go 的逐受众验证循环。2.4argocd-cm插件支持的移除推迟到 2.7变更背景argocd-cm插件的支持原计划在 2.6 移除。当时sidecar 插件还不能按名称by name指定。Argo CD v2.6 引入了按名称指定 sidecar 插件的能力。迁移窗口argocd-cm插件支持的移除已推迟到 2.7目的是为需要按名称指定插件的用户提供过渡时间。从当前仓库的 CMP 配置实现看按名称解析插件是可行的插件配置的metadata.name会被用于构造 socket 路径见 cmpserver/plugin/config.gopluginSockFilePath与插件名拼接。这为 sidecar 插件按名称引用提供了底层基础。行动建议仍在使用argocd-cm插件的团队应利用 2.6 → 2.7 的过渡窗口逐步迁移到 sidecar 插件迁移时尽量使用按名称指定的新方式避免在 2.7 移除argocd-cm支持时被动。2.5 旧版 CLI 的argocd app create在 API 2.6.7 时失败变更内容从 Argo CD2.6.7开始当 Application 不存在时API 对 ApplicationGET请求返回PermissionDenied而不是此前的NotFound。受影响的 CLI 版本以下版本范围的 Argo CD CLI 在argocd app create执行流程中会先发GET请求再发POST请求且不能优雅地处理PermissionDenied响应因此会创建/更新 Application 失败2.5.0-rc1 及之后、且低于2.5.16的版本低于2.6.7的版本。而早于 2.5.0-rc1 的 CLI 不受影响。从当前仓库源码看Application 相关 API 确实会返回PermissionDenied语义的错误例如 server/application/application.go 中多处以argocommon.PermissionDeniedAPIError返回印证了该行为变更的存在。解决方案将CLI 升级到至少 2.5.16 或 2.6.7。特别提醒升级 API Server 后务必同步升级你使用的 CLI 版本避免 CLI 与 API 版本不匹配导致的操作失败。三、升级到 2.6 的检查清单Checklist综合以上变更建议在升级前完成以下核对序号检查项对应变更处理动作1是否有 REST API 客户端使用旧project过滤字段project 过滤器失效2.6.6 前升级到 2.4.27 / 2.5.15 / 2.6.6或改造客户端改用projects2是否使用 matrix 嵌套 git files 生成器2.6.5 生成器故障跳过 2.6.5直接升级到 2.5.15 / 2.6.63Go 模板 ApplicationSet 是否用 Sprig semver 的^semver^语义变化阅读 semver v3 变更日志并回归验证4CI/脚本是否依赖挂起 Job 的 Progressing 状态状态改为 Suspended升级前更新argocd app wait等流程5OIDC 提供商是否签发含aud的令牌默认强制要求aud声明确认提供商支持或在 OIDC 配置设skipAudienceCheckWhenTokenHasNoAudience: true6是否仍在使用argocd-cm插件移除推迟到 2.7利用过渡窗口迁移到 sidecar 插件并按名称引用7CLI 版本是否为 2.5.0-rc1 ~ 2.5.16 / 2.6.6 之间app create遇PermissionDenied失败CLI 升级到 2.5.16 或 2.6.7四、延伸阅读ApplicationSet 资源修改控制Controlling Resource ModificationApplicationSet Go 模板GoTemplate用户管理 / OIDC 配置ApplicationQuery API 定义projects与project双字段兼容OIDC 令牌aud校验实现Job 健康状态判断SuspendedCMP 插件按名称解析实现【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考