Argo CD v3.5 到 v3.6 升级指南破坏性变更、行为修正与 API 改动详解【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cdArgo CD v3.6 是一次以可观测性和 diff 工具链完善为重点的版本升级。本文基于官方升级文档docs/operator-manual/upgrading/3.5-3.6.md展开覆盖全部破坏性变更OTLP 环境变量重命名、argocd app diff本地默认文件集变更、行为改进GitOps Promoter 健康状态、健康事件溯源、渐进同步时序、parent-based 链路采样、OTel 依赖升级、CloudNativePG 健康检查与 API 变更ClusterconfigHash、gitops-engine 接口调整并对照仓库源码逐项给出实现依据帮助你在升级前评估影响面、制定回退方案。一、破坏性变更Breaking Changes1.1 Repo-server OTLP headers 环境变量重命名repo-server 组件读取 OpenTelemetry 采集头的环境变量由命名不规范的ARGOCD_REPO_OTLP_HEADERS更名为ARGOCD_REPO_SERVER_OTLP_HEADERS。新名称遵循ARGOCD_COMPONENT_OTLP_HEADERS的统一约定与ARGOCD_SERVER_OTLP_HEADERS、ARGOCD_APPLICATION_CONTROLLER_OTLP_HEADERS等其他组件保持一致也与仓库中随附的 repo-server Deployment 实际注入的名称对齐。影响面使用官方默认 manifest 的部署不受影响——manifests/install.yaml、manifests/core-install.yaml、manifests/namespace-install.yaml等安装清单中 repo-server Deployment 均直接设置ARGOCD_REPO_SERVER_OTLP_HEADERS源自otlp.headers配置项例如 manifests/base/repo-server/argocd-repo-server-deployment.yaml如果你通过自定义 Deployment patch 或 Helm values 直接设置了旧变量ARGOCD_REPO_OTLP_HEADERS必须将其重命名为ARGOCD_REPO_SERVER_OTLP_HEADERS旧变量在新版本中不再被读取。升级检查动作在集群中执行kubectl get deploy argocd-repo-server -o yaml | grep -i OTLP_HEADERS确认注入的是新变量名若有自定义 patch如kubectl patch或 HelmpostRender同步修改。1.2argocd app diff --local --server-side-generate的默认--local-include变更这是本次升级中实操影响最大的一项变更。当使用argocd app diff --local --server-side-generate本地文件发送到服务端生成清单再做 diff时--local-include的隐式默认值从[*.yaml, *.yml, *.json]变更为[*.yaml, *.yml, *.json, *.tpl, Chart.lock]这一点可在 CLI 源码中直接验证——cmd/argocd/commands/app_diff.go#L800 中该 flag 的默认值即为[]string{*.yaml, *.yml, *.json, *.tpl, Chart.lock}。新增两个条目的动机*.tpl—— 匹配任意深度的 Helm 模板 helper 文件如templates/_helpers.tpl、charts/subchart/templates/_helpers.tpl。缺失它时只要模板中调用了_helpers.tpl定义的命名 helper服务端helm template就会失败或渲染出错误结果Chart.lock—— 匹配任意深度的 Helm 依赖锁文件。缺失它时服务端会按Chart.yaml中的版本约束解析依赖而不是Chart.lock中的固定版本从而产生基于错误依赖版本的 diff。匹配规则说明务必理解不含路径分隔符的模式如*.yaml、*.tpl只按文件名匹配不限目录深度含/的模式按文件的相对路径匹配并支持**跨多层目录如charts/**。警告命令行上指定--local-include会整体替换默认集而不是追加。需要叠加自定义模式时必须把想保留的默认项全部重新写出。例如在默认集之外再包含charts/下所有文件argocd app diff my-app \ --local ./path \ --server-side-generate \ --local-include *.yaml --local-include *.yml --local-include *.json \ --local-include *.tpl --local-include Chart.lock \ --local-include charts/**注意Kustomize 应用如果在configMapGenerator或secretGenerator中引用非 YAML 源文件如*.env、*.properties必须通过--local-include显式补充对应模式因为不存在能覆盖所有文件名的通用默认值。影响与缓解方案Helm chart 若包含_helpers.tpl或Chart.lock升级后服务端 diff 开箱即用无需额外 flag如果你之前传过一份缺少*.tpl或Chart.lock的自定义--local-include列表请评估是否需要补上。常用命令模板恢复到 3.6 之前的行为仅按 YAML/JSON 文件名匹配argocd app diff my-app \ --local ./path \ --server-side-generate \ --local-include *.yaml --local-include *.yml --local-include *.json包含charts/下全部文件适用于charts/中携带非 YAML 内容且需要发送的场景argocd app diff my-app \ --local ./path \ --server-side-generate \ --local-include *.yaml --local-include *.yml --local-include *.json \ --local-include *.tpl --local-include Chart.lock \ --local-include charts/**包含 KustomizeconfigMapGenerator源文件如.env文件argocd app diff my-app \ --local ./path \ --server-side-generate \ --local-include *.yaml --local-include *.yml --local-include *.json \ --local-include *.tpl --local-include Chart.lock \ --local-include *.env二、行为改进与修复Behavioral Improvements / Fixes2.1 GitOps PromoterPromotionStrategy与ChangeTransferPolicy健康状态语义调整Argo CD 内置的针对promoter.argoproj.io/PromotionStrategy和promoter.argoproj.io/ChangeTransferPolicy资源的 health check在 promotion 进行中时现在上报Healthy而非Progressing。新行为细节promotion 进行中proposed commit 与 active commit 不同时返回Healthy——包括 commit 状态处于 pending 或 failed 的期间等待 hydration 完成期间仍返回Progressing例如 dry SHA 尚未填充、或环境在 proposed commit 上临时不同步控制器层面的等待状态同样返回Progressing资源尚无 status、未 ready、正在删除、或 spec generation 尚未被观测到调和错误等失败条件下的Degraded语义不变。健康消息内容不变变化的只是活动 promotion 期间上报的状态值。影响包含 GitOps Promoter 资源的应用在 promotion 进行期间升级后可能显示Healthy而非Progressing若你的告警或自动化以Progressing状态作为“promotion 正在进行”的信号应改为解析 health message 或 Promoter 自身的 status 字段。未使用 GitOps Promoter 资源的用户无需任何操作。2.2 健康状态变化事件现在指明“肇事”资源当 Application 聚合健康状态发生变化时发出的Updated health status事件消息末尾新增(Caused by ...)后缀直接列出导致新状态的资源例如Updated health status: Healthy - Degraded (Caused by apps/Deployment:default/api)最多列出 3 个资源。这一定位信息使排查应用健康抖动flapping时可以直接指向引发变化的具体资源。从源码实现看该后缀由 controller/health.go#L141 处拼接生成Caused by summary并有 controller/health_test.go 中的测试用例验证。影响如果你以编程方式消费并解析这条事件消息需要更新解析器以容忍新的(Caused by ...)后缀。2.3 Progressive Sync 前进步骤改为依赖 refresh 注解开启渐进同步progressive sync后appset 控制器一旦识别出其名下任一 Application 发生变化会向所有名下应用添加 refresh 注解并等待全部应用完成调和reconcile后才开始执行 progressive sync 步骤。这一机制保证前进决策基于各应用调和后的最新状态而非陈旧数据。影响使用 ApplicationSet 渐进同步且管理大量应用的场景可能会观察到应用推进步骤的延迟略有增加。相关实现位于 applicationset/progressivesync/progressive_sync.go 及 applicationset/controllers/progressive_sync_dependencies.go。2.4 链路采样改为 parent-based 且可配置变更前的行为只要启用 OpenTelemetry tracing设置了--otlp-addressArgo CD 无条件采样所有spanAlwaysSample。v3.6 的行为改用 parent-based head sampler根采样率可通过--otlp-sample-ratioflag或ARGOCD_COMPONENT_OTLP_SAMPLE_RATIO环境变量按组件配置默认1.0全量采样因此大多数部署行为不变。核心实现在 util/trace/trace.go#L79sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.TraceIDRatioBased(sampleRatio)))各组件argocd-server、argocd-application-controller、argocd-repo-server、argocd-cmp-server 等的启动命令均暴露了--otlp-sample-ratio例如 cmd/argocd-repo-server/commands/argocd_repo_server.go、cmd/argocd-server/commands/argocd_server.go、cmd/argocd-application-controller/commands/argocd_application_controller.go。有两个需要特别注意的行为差异注意——采样决策跨服务传播由发起 trace 的服务如 application controller做出的采样决策会被 trace 上下文流经的每个下游服务repo-server、commit-server遵守。这保证每条 trace 整体采样而非在进程边界上被部分采样。要在整个链路获得一致的采样率请为所有组件设置相同的--otlp-sample-ratio。警告——入站“不采样”决策现在会被遵守由于采样器是 parent-based携带已标记not sampled的 W3Ctraceparent的请求即使设置--otlp-sample-ratio1.0也不会被记录——旧版AlwaysSample下这类请求无论如何都会记录。此差异仅影响上游代理、网关或客户端向argocd-server注入 trace 上下文的部署若上游不传播traceparent每条 trace 仍以 Argo CD 为根并按配置比例采样。参数取值校验通过--otlp-sample-ratio传入[0.0, 1.0]之外的值或NaN会在启动时直接报错以 fail-fast 方式暴露配置错误而非静默改变采样率通过环境变量ARGOCD_COMPONENT_OTLP_SAMPLE_RATIO传入的非法或越界值则被忽略并回落到默认值1.0同时记录一条警告日志。2.5 OpenTelemetry 依赖升级Argo CD v3.6 将otelgrpc与otelhttptracing 插桩升级至 v0.70.0该版本捆绑了 OpenTelemetry 语义约定 v1.42.0 与 v1.43.0。语义约定升级意味着部分 span 属性名称可能被更名或移除基于 Argo CD OTEL traces 构建的 Grafana 看板/告警可能需要同步修改官方文档指向了语义约定的 release notes 以获取变更清单。其中一项具体变化otelgrpc现在从 gRPC dial target 而非解析后的对端 IP 设置server.address/server.portspan 属性。若你的看板或告警以server.address为键、并期望看到 Argo CD 内部 gRPC 调用argocd-server↔repo-server↔cmp-server的字面 Pod/Service IP可能需要更新。2.6 新增内置健康检查CloudNativePGDatabase新增针对 CloudNativePGpostgresql.cnpg.io/Database资源的内置 health check只有当 operator 已应用当前 generationstatus.applied且status.observedGeneration匹配时才上报Healthy。这使得同步波sync wave能将其作为真实的依赖屏障——不再把尚未 apply 的 Database 视为健康。相关资源定制位于 resource_customizations/postgresql.cnpg.io/。三、API 变更API Changes3.1 Cluster 对象新增configHash字段Cluster对象新增瞬态字段configHash用于可靠地检测配置变更。该字段不存在于底层 cluster secret 中而是在查询时动态计算得出。应将其视为不透明值opaque value不要对其生成机制做任何假设——它不属于 API 契约的一部分未来可能变化。3.2 gitops-engine 接口变更pkg/utils/kube/KubectlOptionsRunner.Create()函数的第三个参数cmd *cobra.Command现在被忽略因其底层依赖k8s.io/kubectl的pkg/cmd/create.CreateOptions.RunCreate()自 v0.37.0 起不再接收该参数。该参数将在 Argo CD 下一个大版本中移除此改动位于 vendor 的 gitops-engine 子模块 中。四、升级检查清单结合上述变更建议按以下顺序执行升级前检查OTLP 环境变量确认所有自定义 patch/Helm values 中的 OTLP headers 变量已改名为ARGOCD_REPO_SERVER_OTLP_HEADERS旧变量 v3.6 不再读取--local-include存量脚本搜索 CI/运维脚本中argocd app diff的--local-include用法——默认集变大后之前显式写出完整默认集YAML/JSON的调用不会丢失*.tpl/Chart.lock之外的行为但如果你依赖“只发送 YAML/JSON”的旧行为需按 1.2 节模板显式回退Kustomize 应用若用configMapGenerator/secretGenerator引用非 YAML 文件应显式补充对应模式Promoter 健康信号将基于Progressing状态判断 promotion 进行中的告警/自动化改为解析 health message 或 Promoter status 字段事件解析器升级消费Updated health status事件消息的下游解析逻辑容忍新增的(Caused by ...)后缀trace 看板核对基于 OTEL traces 的 Grafana 看板与告警中使用的 span 属性名重点server.address/server.port的来源变化并确认所有组件--otlp-sample-ratio配置一致且在[0.0, 1.0]区间内渐进同步容量大规模 ApplicationSet 场景评估 refresh 全量等待带来的推进延迟是否在可接受范围。以上每一项均可在仓库中找到对应证据升级文档本身位于 docs/operator-manual/upgrading/3.5-3.6.md默认文件集实现在 cmd/argocd/commands/app_diff.go采样器实现在 util/trace/trace.go健康事件实现在 controller/health.goOTLP 环境变量注入在 manifests/base/repo-server/argocd-repo-server-deployment.yaml可据此继续深入验证。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考