Argo CD v1.7 升级至 v1.8 迁移指南：StatefulSet 转换、Application 健康评估与 gRPC 指标变更

Argo CD v1.7 升级至 v1.8 迁移指南StatefulSet 转换、Application 健康评估与 gRPC 指标变更【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本指南以 Argo CD 官方升级文档 docs/operator-manual/upgrading/1.7-1.8.md 为核心骨架完整讲解从 v1.7 升级到 v1.8 时需要注意的三项破坏性变更argocd-application-controller从 Deployment 迁移为 StatefulSet、argoproj.io/ApplicationCRD 内置健康评估被移除、gRPC 指标默认关闭。读完本文你将能够独立完成 v1.7 → v1.8 的安全升级、正确处理旧资源清理与回滚并通过argocd-cmConfigMap 恢复 app-of-apps 场景下的健康检查按需重新开启 gRPC 指标采集。升级前的背景Argo CD 的版本升级规则在进入 v1.7 → v1.8 的具体变更之前先明确 Argo CD 的版本升级约定见 docs/operator-manual/upgrading/overview.mdPatch 版本如 v1.5.1 → v1.5.3不引入破坏性变更一般无需特殊处理。Minor 版本如 v1.3.0 → v1.5.2可能引入带变通方案的次要变更需要逐一阅读涉及版本的升级说明如 v1.3 到 v1.4、v1.4 到 v1.5。Major 版本引入向后不兼容的行为变更官方建议先按灾难恢复指南备份 Argo CD 配置。v1.8 作为一次 minor 版本升级包含三处带 workaround 的破坏性变更正是本文要逐一解决的核心内容。升级完成后还需要继续沿用常规升级流程可参考后续的 v1.8 到 v2.0 说明。变更一argocd-application-controller 由 Deployment 迁移为 StatefulSet变更内容与原因从 v1.8 起argocd-application-controller的资源类型由Deployment转换为StatefulSet。这一转换可以在当前仓库的 manifests 中得到印证目录 manifests/base/application-controller-deployment/ 中同时保留了argocd-application-controller-statefulset.yaml与argocd-application-controller-deployment.yaml其 kustomization.yaml 将两者共同纳入渲染资源列表。从源码结构看控制器长期支持多副本分片sharding机制例如 controller/sharding/sharding.go 与 controller/sharding/cache.go而 StatefulSet 提供的稳定网络标识与有序部署语义更适合承载这类需要稳定身份的多副本控制平面组件。在 StatefulSet 清单中可以看到replicas: 1的默认配置以及 argocd-application-controller-statefulset.yaml 中ARGOCD_CONTROLLER_REPLICAS、ARGOCD_CONTROLLER_SHARDING_ALGORITHM等分片相关环境变量注入进一步佐证了 StatefulSet 形态与控制器分片能力的配套关系。升级时必须手动删除旧 Deployment由于 Deployment 与 StatefulSet 同名都是argocd-application-controller直接应用新清单并不会自动清除旧资源升级后你必须手动删除旧的 Deploymentkubectl -n argocd delete deployment argocd-application-controller回滚到 v1.7 时的对称操作同样地如果你在升级后决定回滚到 v1.7别忘了删除 v1.8 创建的 StatefulSetkubectl -n argocd delete statefulset argocd-application-controller这一步容易被遗漏但若不清理v1.7 的 Deployment 清单与遗留的 StatefulSet 会同时存在于集群中导致控制器行为异常。变更二argoproj.io/Application CRD 的健康评估被移除变更影响v1.8 移除了对argoproj.io/ApplicationCRD 的内置健康评估详见 Argo CD issue #3781 的讨论。这直接影响使用app-of-apps 模式并通过sync waves编排同步顺序的场景在 app-of-apps 模式中父 Application 管理多个子 Application如果依赖 sync waves通过argocd.argoproj.io/sync-wave注解控制资源同步顺序数值越小越先部署参见 docs/user-guide/sync-waves.md编排子应用的部署次序此时父 Application 的健康状态需要反映子 Application 的status.health而内置评估被移除后该健康评估逻辑将缺失。恢复方式在 argocd-cm 中配置自定义健康检查官方给出的恢复方案是在argocd-cmConfigMap 中添加如下resource.customizations配置Lua 脚本--- apiVersion: v1 kind: ConfigMap metadata: name: argocd-cm namespace: argocd labels: app.kubernetes.io/name: argocd-cm app.kubernetes.io/part-of: argocd data: resource.customizations: | argoproj.io/Application: health.lua: | hs {} hs.status Progressing hs.message if obj.status ~ nil then if obj.status.health ~ nil then hs.status obj.status.health.status if obj.status.health.message ~ nil then hs.message obj.status.health.message end end end return hs这段 Lua 脚本的逻辑是默认将健康状态置为Progressing若对象存在status.health则透传其中的status与message。这本质上是把父应用健康 子应用健康的映射关系以自定义健康检查的形式重新接回 Argo CD。若现有安装的argocd-cm尚无resources.customizations配置可将上述data:片段保存为文件再用kubectl patch合并进去kubectl -n argocd patch configmaps argocd-cm --patch-file argocd-cm-patch.yaml关于该配置的补充说明从当前仓库文档 docs/operator-manual/health.md 可以看到健康检查配置还支持另一种扁平化键写法resource.customizations.health.group_kind例如data: resource.customizations.health.argoproj.io_Application: | hs {} ...其中group_前缀用于带 API group 的资源如batch_Job对应batch/Job而核心资源如PersistentVolumeClaim则省略 group 前缀、直接使用 Kind。两种写法底层都通过 docs/operator-manual/argocd-cm.yaml 中定义的resource.customizations.*系列键生效v1.7→v1.8 文档示例使用的是旧式嵌套结构resource.customizations下挂argoproj.io/Application而扁平化写法是文档中更推荐、更利于与ignoreDifferences、actions等键区分的形态可按需选用。自定义健康检查的编写建议若你还需要为其他 CRD 编写类似的自定义健康检查docs/operator-manual/health.md 给出了几条实践准则先观察资源status子资源中的真实条件condition再据此编写检查逻辑若 CRD 的status采用 kstatus 标准格式应在健康检查中注释说明若 CRD 在status中正确提供observedGeneration字段应尽量使用它以避免在 CRD controller 尚未完成调和时健康状态出现抖动。注意以上为仓库文档原文的外部参考链接说明具体实现以仓库内 resource_customizations 目录下的真实health.lua示例为准。变更三gRPC 指标默认关闭变更内容v1.8 起argocd-server与argocd-repo-server默认不再暴露 gRPC 指标。官方认为这些指标的采集开销过高因此将其设为默认关闭。需要恢复时通过环境变量开启ARGOCD_ENABLE_GRPC_TIME_HISTOGRAMtrue该环境变量名在当前仓库源码中有明确定义common/common.go 中的EnvEnableGRPCTimeHistogramEnv ARGOCD_ENABLE_GRPC_TIME_HISTOGRAM注释为enables gRPC metrics collection可据此确认它控制的是 gRPC 指标采集开关而非全部 Prometheus 指标。指标采集端点的补充信息在 docs/operator-manual/metrics.md 中可以看到与 gRPC 指标相关的更多上下文API Server 的指标抓取端点为argocd-server-metrics:8083/metrics其中明确注明For GRPC metrics to show up environment variableARGOCD_ENABLE_GRPC_TIME_HISTOGRAMmust be set to trueRepo Server 的指标抓取端点为argocd-repo-server:8084/metrics同样注明 gRPC 指标默认不暴露需设置该环境变量开启受开关控制的典型 gRPC 指标包括grpc_server_handled_total服务器上已完成的 RPC 总数不论成败、grpc_server_msg_sent_total服务器已发送的 gRPC 流消息总数等。同时 docs/operator-manual/high_availability.md 也将其列为高可用部署中可选的性能采集开关enables collecting RPC performance metrics。因此如果你依赖 gRPC 维度的延迟直方图做容量规划或性能监控升级后务必在相应组件的 Deployment/StatefulSet 环境变量中显式加上ARGOCD_ENABLE_GRPC_TIME_HISTOGRAMtrue否则相关图表会静默变为空。完成升级继续走常规升级流程处理完上述三项变更后即可继续遵循常规升级流程完成版本切换非 HA 部署清单位于仓库 manifests/install.yamlkubectl apply -n argocd --server-side --force-conflicts -f install.yamlHA 部署清单位于仓库 manifests/ha/install.yamlkubectl apply -n argocd --server-side --force-conflicts -f ha/install.yaml上述命令中的--server-side --force-conflicts是必要参数部分 Argo CD CRD 的体积超过了客户端 apply 的大小限制必须使用服务端 apply详见 docs/getting_started.md 中的安装说明。即使某些版本仅涉及镜像变更官方仍强烈建议应用整套清单因为清单中可能包含重要的参数修改整体应用可以避免引入错误配置。升级核对清单应用 v1.8 清单后手动删除旧的argocd-application-controllerDeployment若使用 app-of-apps sync waves在argocd-cm中恢复 Application 健康评估 Lua 脚本或改用resource.customizations.health.argoproj.io_Application扁平键必要时用kubectl patch合并依赖 gRPC 指标时为argocd-server、argocd-repo-server设置ARGOCD_ENABLE_GRPC_TIME_HISTOGRAMtrue若需回滚到 v1.7删除 v1.8 创建的 StatefulSet并反向恢复上述配置升级全程以kubectl apply --server-side --force-conflicts应用整套目标版本清单。相关文档与资源升级总览 docs/operator-manual/upgrading/overview.md、下一版本 v1.8 到 v2.0、健康检查详解 docs/operator-manual/health.md、指标说明 docs/operator-manual/metrics.md、控制器清单 manifests/base/application-controller-deployment/。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考