Argo CD v3.2 到 v3.3 升级指南：破坏性变更、Server-Side Apply 迁移与 Source Hydrator 新机制

Argo CD v3.2 到 v3.3 升级指南破坏性变更、Server-Side Apply 迁移与 Source Hydrator 新机制【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本篇指南完整讲解从 Argo CD v3.2 升级到 v3.3 时的全部破坏性变更Breaking Changes与配套工具链升级要点重点覆盖因 ApplicationSet CRD 超出注解大小限制而强制推行的 Server-Side ApplySSA升级路径、Source Hydrator 改用 git notes 追踪水合状态的行为变化、K8s API 请求超时控制的环境变量拆分以及随版本新增的健康检查与 Helm/Kustomize 版本升级。读者读完可据此制定一份可执行、可回滚的升级预案并理解升级后各项行为差异的源码级原因。升级总览v3.3 带来了什么Argo CD v3.3 在 v3.2 基础上引入了若干必须知晓的破坏性变更主要集中在一个核心问题上ApplicationSet CRD 体积增长导致原有的客户端侧 applyclient-side apply升级方式失效必须改用 Server-Side Apply 冲突解决Source Hydrator 的状态追踪机制重构从每个 DRY 提交都生成水合提交改为用 git notes 记录水合状态仓库更干净但自动化依赖的行为需要同步调整若干行为收敛与清理移除水合期间的路径自动清理、匿名访问 Settings API 不再返回resourceOverrides、K8s server-side 超时改用独立环境变量、--self-heal-backoff-cooldown-seconds标志弃用依赖工具链升级Helm 升至 3.19.2、Kustomize 升至 5.8.0新增一批 Kubernetes 资源类型的健康检查。升级前建议先确认当前版本并完整阅读 升级文档 中与自身部署方式Argo CD 自管理 / 手工 manifests / Kustomize / Helm对应的章节。破坏性变更一ApplicationSet CRD 超出客户端侧 apply 大小限制问题根源262144 字节的注解上限在 v3.3 中ApplicationSet CRDapplicationsets.argoproj.io的体积已经超过了 Kubernetes 客户端侧 apply 的限制。若沿用旧版升级方式会看到如下报错The CustomResourceDefinition applicationsets.argoproj.io is invalid: metadata.annotations: Too long: may not be more than 262144 bytes其根因在于客户端侧 apply 会把上次应用的完整对象序列化写入last-applied注解而 Kubernetes API Server 对单个注解有 256 KiB262144 字节的大小限制。CRD 变大后该注解随之超限。解决办法Server-Side ApplySSA resolve conflictsv3.3 起升级 Argo CD必须使用 Server-Side ApplySSA并携带resolve conflicts语义。原因在于SSA 不会把字段存储进last-applied注解因此不受 262144 字节限制的影响--force-conflicts标志允许 apply 操作接管此前由其他工具如 Helm 或之前的kubectl apply管理的字段这是升级所必需的。需要注意的副作用凡是在 Argo CD manifests 中显式定义的字段如affinity、env、probes一旦你做过自定义修改升级时会被覆盖而manifests 中未指定的字段如resources的 limits/requests、tolerations会被保留。针对不同部署方式升级命令各有差异以下按场景逐一说明。场景一Argo CD 管理自身使用 Argo CD Application 升级当 Argo CD 通过一个 Argo CD Application 管理并升级自身时需要在 Application 的 spec 中启用 Server-Side Apply 同步选项spec: syncPolicy: syncOptions: - ServerSideApplytrue配置该选项后Argo CD 会自动加上resolve conflicts选项。这背后的实现可参见仓库中同步选项的常量定义gitops-engine/pkg/sync/common/types.goSyncOptionServerSideApply等选项均在此声明。场景二手工使用 Kustomize 或纯 manifests 升级使用纯 manifests 或 Kustomize overlay 手工升级时必须以--server-side --force-conflicts方式执行kubectl apply -n argocd --server-side --force-conflicts -f manifests/install.yaml对 Kustomize overlay 场景将manifests/install.yaml替换为kustomize build输出的内容即可核心参数不变。场景三使用 Helm 升级通过helm upgrade升级的用户不受此变更影响。因为 Helm 不使用客户端侧 apply不会生成last-applied注解自然也就不会触发注解超限问题。相关 manifests 均可在 manifests/ 目录下找到如 manifests/install.yaml、manifests/namespace-install.yaml 等。场景四已升级到 3.3.0 / 3.3.1 的用户部分用户升级到 3.3.0 或 3.3.1 并应用 SSA 后会遇到客户端侧 apply 迁移失败的错误one or more synchronization tasks completed unsuccessfully, reason: Failed to perform client-side apply migration: failed to perform client-side apply migration on manager kubectl-client-side-apply: error when patching /dev/shm/2047509016: CustomResourceDefinition.apiextensions.k8s.io applicationsets.argoproj.io is invalid: metadata.annotations: Too long: may not be more than 262144 bytes如果你曾通过配置同步选项ClientSideApplyMigrationfalse作为临时缓解手段升级到 3.3.2 之后应将其移除。因为关闭ClientSideApplyMigration存在未来与 K8s 各 field manager 产生冲突的风险。从源码看Argo CD 默认启用客户端侧 apply 迁移默认的 field manager 名为kubectl-client-side-apply定义于 gitops-engine/pkg/sync/common/types.go 的DefaultClientSideApplyMigrationManager在 controller/sync.go 中WithClientSideApplyMigration的启用与否由同步选项ClientSideApplyMigrationtrue/false控制。因此升级到 3.3.2 后删除ClientSideApplyMigrationfalse即可恢复正常迁移路径。破坏性变更二Source Hydrator 改用 git notes 追踪水合状态旧行为回顾在 v3.3 之前Source Hydrator 会对每一个DRY源提交都推送一个新的水合hydrated提交无论manifest.yaml等清单文件是否真的发生变化。之所以如此激进是因为水合器需要记录最近一次完成水合的 DRY 提交是哪一个——它将这一信息以drySha字段写进每个水合提交中的hydrator.metadata文件。新机制git notes 专属命名空间从 v3.3 起Source Hydrator 改用 [git notes] 记录最近一次完成水合的 DRY 提交状态而不再对每个 DRY 提交创建水合提交。git note 存放在一个为 Source Hydrator 预留的专属命名空间中与仓库的其他操作相互隔离状态既可靠又独立。在仓库源码中可以看到该机制的完整实现命名空间常量定义于 commitserver/commit/commit.goNoteNamespace即自定义 git notes 命名空间读取与写入分别由 util/git/client.go 中的GetCommitNote与AddAndPushNote实现对应的底层命令是git fetch origin refs/notes/namespace:refs/notes/namespace、git notes --refnamespace add -f -m note sha与git push origin refs/notes/namespace考虑到多分片 application controller 可能并发推送同一 notes refAddAndPushNote内置了带抖动的指数退避重试机制isRetryableNotePushError用于识别fetch first、reference already exists、cannot lock ref等可重试的并发冲突错误。每次水合运行的流程新的水合流程按以下顺序执行每次水合运行时水合器先拉取自己命名空间下已有的 git note检查上一次完成水合的 DRY 提交 SHA若 note 中的 SHA 与最新 DRY SHA 一致水合器记录一条 debug 日志并跳过水合若manifest.yaml等清单文件未发生变化即使 DRY SHA 是新的水合器跳过清单提交只更新 git note 以反映最新完成水合的 DRY SHA若清单文件确实发生了变化水合器提交更新后的清单并同时更新 git note。在 test/e2e/hydrator_test.go 的端到端测试中可以验证这一行为测试在第二次水合DRY 侧提交了新 commit 但无实际清单变化时断言Hydrated SHA 保持不变即无变化的水合不会产生新的水合提交另一个针对认证仓库的测试则专门验证了GetCommitNote与AddAndPushNote在拉取 git notes 时会正确使用仓库凭据。迁移影响与操作建议行为层面用户将不再看到每个 DRY 提交对应一个水合提交。只有真正的清单变更才会产生新提交其余情况的水合状态都记录在 git note 命名空间中运维层面依赖每个 DRY 提交必有水合提交的应用和自动化工具应改从 Source Hydrator 命名空间中的 git note 判断水合状态大部分用户无需任何操作但若有依赖水合提交作为信号的自动化请改为读取新的 git note。该设计的收益是明确的减少无关提交带来的仓库杂乱对DRY 变更频繁、清单变更稀少的团队显著提升性能降低自动化场景下合并冲突与分支膨胀的风险。破坏性变更三移除水合期间的 Application 路径自动清理在 v3.3 之前的版本中Source Hydrator 每次水合运行前会自动清理删除Application 配置路径下的所有文件再写入新的清单文件。从 v3.3 起这一清理逻辑已被移除水合器现在只会覆盖或创建与当前清单输出对应的文件路径中多余的文件或过期数据将保持原样除非被显式覆盖否则不会被删除。运维影响如果你的仓库或自动化此前依赖水合自动清理过时文件这一行为现在必须自行处理清理。此变更的初衷是避免误删无关文件——例如当应用路径与其他资产目录重叠、或应用被重构时自动清理可能造成意外删除。建议动作审查自动化工作流与仓库维护脚本按需清理应用路径下的旧文件如确有需要可引入定期的清理流程。当前行为详见 Source Hydrator 用户指南该指南同时说明了如何通过hydrator.enabled: true配置 argocd-cmd-params-cm 启用 Hydrator以及如何使用*-install-with-hydrator.yaml安装清单。破坏性变更四匿名调用 Settings API 返回字段减少v3.3 中Settings API 在匿名访问时返回的信息变少了不再返回resourceOverrides字段。该字段被视为敏感信息匿名场景下被剔除。若你的脚本或外部系统依赖匿名读取该字段需要改为携带认证的调用方式或调整数据来源。破坏性变更五新增环境变量控制 K8s Server-Side 请求超时v3.3 引入了一个新的环境变量ARGOCD_K8S_SERVER_SIDE_TIMEOUT用于单独控制 K8s API 请求的 server-side 超时。在此之前v3.2 及更早该超时由ARGOCD_K8S_TCP_TIMEOUT一并控制——而后者同时还负责与 K8s API Server 通信时的 TCP 超时。从源码可见两套超时的彻底分离定义于 pkg/apis/application/v1alpha1/cluster_constants.goK8sTCPTimeoutARGOCD_K8S_TCP_TIMEOUT默认 30 秒用于 TCP 层K8sServerSideTimeoutARGOCD_K8S_SERVER_SIDE_TIMEOUT默认 0即不主动设置用于随每个 API 请求下发的 server-side 超时参数。在 pkg/apis/application/v1alpha1/types.go 的 REST 配置构建逻辑中只有当K8sServerSideTimeout 0时才会通过传输层包装器注入该超时参数WithServerSideTimeout实现在 util/http/http.go其作用是为每个 API 请求附加 API Server 能够识别的超时查询参数。源码注释特别说明客户端侧 HTTP 超时config.Timeout保持为 0以显式地通过传输层包装器把超时参数传给 API Server。如果你曾为了调优 API 请求超时设置过ARGOCD_K8S_TCP_TIMEOUT升级后请评估是否需要同时/改设ARGOCD_K8S_SERVER_SIDE_TIMEOUT。破坏性变更六弃用 --self-heal-backoff-cooldown-seconds 标志argocd-application-controller的--self-heal-backoff-cooldown-seconds标志已被弃用并将在未来版本中移除。源码中cmd/argocd-application-controller/commands/argocd_application_controller.go可以看到该标志虽仍被注册默认值 330对应环境变量ARGOCD_APPLICATION_CONTROLLER_SELF_HEAL_BACKOFF_COOLDOWN_SECONDS但紧接着通过MarkDeprecated标记为已弃用且无实际效果deprecated and has no effect。与自愈相关的其他标志仍然有效升级后如需调整自愈节奏请使用以下参数标志默认值对应环境变量作用--self-heal-timeout-seconds0ARGOCD_APPLICATION_CONTROLLER_SELF_HEAL_TIMEOUT_SECONDS自愈尝试之间的超时--self-heal-backoff-timeout-seconds2ARGOCD_APPLICATION_CONTROLLER_SELF_HEAL_BACKOFF_TIMEOUT_SECONDS指数退避的初始超时--self-heal-backoff-factor3ARGOCD_APPLICATION_CONTROLLER_SELF_HEAL_BACKOFF_FACTOR指数退避的增长因子--self-heal-backoff-cap-seconds300ARGOCD_APPLICATION_CONTROLLER_SELF_HEAL_BACKOFF_CAP_SECONDS指数退避的最大超时工具链升级Helm 3.19.2 与 Kustomize 5.8.0Helm 升级至 3.19.2Argo CD v3.3 将内置 Helm 升级到3.19.2。根据官方 release notesHelm 3.19.2 没有破坏性变更。值得注意的是Helm 2.x 不再受支持因为 Argo CD 已移除调用helm version时的--client标志该标志仅存在于 Helm 2 中。如果你的环境中仍依赖 Helm 2 的远程 Tiller 模式请升级前完成到 Helm 3 的迁移。Kustomize 升级至 5.8.0内置 Kustomize 从 v5.7.0 升级到5.8.0官方 release notes 表明没有破坏性变更。但有两点需要关注Kustomize 5.7.1 引入了 shlex 库替换用于解析 exec 插件中的参数。如果你的现有 manifests 因此出现解析异常被破坏请参照 5.7.1 的 release notes 中的说明处理Kustomize 5.8.0 修复了命名空间未正确传递到 Helm chart 的问题。如果你依赖 kustomization 文件中的 Helm chart如helmCharts/helmGlobals指令请审查相关配置以确认行为符合预期。新增健康检查Healthchecksv3.3 为以下资源类型新增了内置健康检查可让这些自定义资源在 Argo CD UI 与 CLI 中获得健康状态判定ceph.rook.io/CephClusterceph.rook.io/CephObjectStoreobjectbucket.io/ObjectBucketClaimkeda.sh/ScaledJobservices.cloud.sap.com/ServiceBindingservices.cloud.sap.com/ServiceInstance_.cnrm.cloud.google.com/_grafana-org-operator.kubitus-project.gitlab.io/_上述健康检查的配置健康/降级/错误状态的 Lua 规则及测试数据均可在仓库的 resource_customizations/ 目录下找到对应资源分组例如 resource_customizations/ceph.rook.io/CephCluster/ 与 resource_customizations/keda.sh/ScaledJob/。如果你的集群中使用这些资源升级后即可直接获得更准确的健康状态展示。升级检查清单综合以上变更建议按以下清单执行 v3.2 → v3.3 升级备份升级前备份 Argo CD 的 CRD 与关键配置argocd-cmd-params-cm、argocd-rbac-cm、repositories/secrets 等确定部署方式并选择对应升级路径自管理Argo CD Application在 Application 中设置syncOptions: [ServerSideApplytrue]手工 manifests / Kustomizekubectl apply --server-side --force-conflictsHelmhelm upgrade不受影响正常执行即可检查遗留配置如曾为 3.3.0/3.3.1 设置过ClientSideApplyMigrationfalse升级到 3.3.2 后移除审查 Hydrator 依赖若有依赖每 DRY 提交一个水合提交的自动化改为读取 Source Hydrator 命名空间的 git note确认不需要依赖水合路径自动清理来维护仓库核对超时与自愈参数视情况设置ARGOCD_K8S_SERVER_SIDE_TIMEOUT替换已弃用的--self-heal-backoff-cooldown-seconds验证健康检查观察 Ceph、KEDA 等新增健康检查资源的状态展示是否符合预期回归验证确认同步、自愈、SSO/API匿名 Settings API 字段变化、Helm/Kustomize 渲染结果均正常。本指南对应的原始升级说明位于 docs/operator-manual/upgrading/3.2-3.3.md如需查阅其他版本间的升级说明可查看 docs/operator-manual/upgrading/ 目录下的对应文档。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考