Longhorn 升级路径强制校验（Upgrade Path Enforcement）实现解析与实战指南

云原生存储高可用容器编排【免费下载链接】longhornCloud-Native distributed storage built on and for Kubernetes项目地址https://gitcode.com/gh_mirrors/lo/longhorn点击查看免费下载Longhorn 自 1.5.0 起正式引入升级路径强制校验Upgrade Path Enforcement所有longhorn-manager、longhorn-admission-webhook、longhorn-conversion-webhook、longhorn-recovery-backend组件在启动入口都会校验当前版本 → 目标版本是否为受支持的升级路径Helm / Rancher 安装方式则通过pre-upgradeHelm Hook Job 在升级开始前阻断非法升级。本文以 enhancements/20230315-upgrade-path-enforcement.md 为骨架结合 chart/templates/preupgrade-job.yaml、chart/values.yaml 等仓库源码完整讲解升级路径判定规则、kubectl / Helm / Rancher 三种升级方式下的拦截行为、失败回滚与防降级机制并给出可复制的验证与测试方法。背景为什么需要升级路径强制校验Longhorn 官方长期宣称只支持从上一个稳定版本升级例如升级到 1.5.x 只支持从 1.4.x 或 1.5.0 开始。但在该增强提案落地之前这一约束只停留在文档承诺层面并未在代码中强制任何用户都可以尝试从任意旧版本直接升级这会带来两个实际问题测试成本失控跨多个大版本的升级路径组合数量庞大项目无法逐一覆盖验证出现兼容性问题时难以定位。升级失败后无法安全回滚且无法阻止降级没有版本门禁升级/降级行为不可控可能破坏数据或系统状态。该增强提案关联 Issue 为 longhorn/longhorn#5131的核心目标就是把仅支持从受支持版本升级这一规则从口头承诺变成代码强制。从 CHANGELOG/CHANGELOG-1.5.0.md 可以看到该功能随 1.5.0 正式发布To ensure compatibility after an upgrade, we have implemented upgrade path enforcement. This prevents unintended downgrades and ensures the system and data remain intact.Goals 与 Non-goals提案明确划定了边界Goals要做强制升级路径拒绝不支持的升级且不影响现有系统支持从受授权版本升级到主版本支持失败升级回滚到上一版本阻止意外降级。Non-goals不做升级失败后的自动回滚——回滚操作由管理员手动执行系统不自动触发。总体方案两道防线提案设计了两道互相独立的校验防线分别覆盖两类安装/升级方式升级方式校验时机拦截主体kubectl applydeploy/longhorn.yaml各组件 Pod 启动入口longhorn-manager、longhorn-admission-webhook、longhorn-conversion-webhook、longhorn-recovery-backendHelm/ Rancher App Marketplacepre-upgradeHelm Hook Job 运行期longhorn-pre-upgradeJob执行longhorn-manager pre-upgrade命令两道防线的判定逻辑相同获取当前已安装版本与目标升级版本按版本比较规则判断该路径是否受支持不支持时kubectl 方式下新 Pod 打印日志、广播事件并返回错误退出Helm 方式下 Hook Job 失败导致整个升级流程失败而已安装的旧版本 Longhorn 保持原样继续运行。升级路径判定规则版本比较矩阵设计文档给出了完整的授权判定表这是整个功能的核心规则currentVersion当前版本upgradeVersion目标版本是否允许x.y.*x.(y1).*✓x.y.0x.y.*✓x.y.*(x1).y.*✓x.(y-1).*x.(y1).*✗x.(y-2).*x.(y1).*✗x.y.*x.(y-1).*✗x.y.*x.y.(*-1)✗解读如下同大版本内的小版本升级从x.y.*任意 patch升级到x.(y1).*允许例如 1.4.x → 1.5.x同小版本内的 patch 升级从x.y.0升级到x.y.*允许即首次安装 1.5.0 后可以升级到 1.5.x 后续补丁版大版本升级Major Release从x.y.*升级到(x1).y.*允许注意此处指同一 minor 号跨 major 的受支持路径跨小版本跳级x.(y-1).*→x.(y1).*、x.(y-2).*→x.(y1).*一律禁止例如 1.3.x → 1.5.x 被拦截任何降级一律禁止包括 patch 版本号变小x.y.*→x.y.(*-1)在内的所有降级路径都返回拒绝。实现上当前版本通过GetCurrentLonghornVersion函数获取目标版本取自meta.Version。由于该增强提案的代码实现在 longhorn/longhorn 的主代码仓库中当前镜像仓库以部署资源与文档为主读者可结合后续章节的测试流程验证上述规则。场景一从 x.y.* 或 x.(y1).0 升级到 x.(y1).*受支持放行这是最常见的上一个稳定版 → 当前稳定版升级路径两种方式均放行。使用 kubectl 升级安装旧版本以x.y.*或x.(y1).0为例kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/vx.y.*/deploy/longhorn.yaml # 或 kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/vx.(y1).0/deploy/longhorn.yaml等 Longhorn 正常运行后应用目标版本清单kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/vx.(y1).*/deploy/longhorn.yaml校验通过各组件 Pod 正常启动升级成功。使用 Helm / Rancher App Marketplace 升级先用 Helm 安装 Longhornx.y.*或x.(y1).0参见官方 install-with-helm 文档或通过 Rancher Apps Marketplace 安装再升级到x.(y1).*Helm 使用helm upgradeRancher 在 Catalog 中更新 App 版本pre-upgradeHook Job 校验通过升级成功。场景二从受授权版本升级到主版本Major Release当跨主版本升级属于受支持路径时对应判定表中x.y.*→(x1).y.*一行同样放行kubectl安装vx.y.*后执行kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v(x1).0.*/deploy/longhorn.yaml升级成功Helm / Rancher安装x.y.*后升级到(x1).0.*pre-upgradeHook 校验通过升级成功。场景三从不支持路径升级如 x.(y-1).* → x.(y1).*被拦截这是升级路径强制校验最核心的拦截场景例如从 1.3.x 直接升级 1.5.x。kubectl 方式下的拦截表现安装x.(y-1).*例如 v1.3.x并正常使用执行kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/vx.(y1).*/deploy/longhorn.yaml升级不被允许longhorn-manager、longhorn-admission-webhook、longhorn-conversion-webhook、longhorn-recovery-backend的新 Pod 在入口校验失败后拒绝启动用户需要手动回滚到旧版本清单使longhorn-managerPod 重新运行。注意此时旧版本的系统组件并未被破坏——新 Pod 启动失败只影响新组件旧 Deployment 的现有 Pod 仍在服务因此手动kubectl apply旧清单即可恢复。Helm / Rancher 方式下的拦截表现安装x.(y-1).*后尝试升级到x.(y1).*Helm 在升级流程开始前先创建pre-upgradeHook JobJob 内执行longhorn-manager pre-upgrade校验命令发现路径不受支持后Job 失败导致整个 Helm 升级流程失败Longhorn 系统保持完整并继续对外提供服务。场景四失败升级的回滚Rollback提案明确不做自动回滚但提供了完整的手动回滚路径。kubectl 回滚用旧版本清单重新应用即可恢复kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/[previous installed version]/deploy/longhorn.yamlLonghorn 回滚成功可能需要手动清理新版本引入的新组件。Helm / Rancher 回滚方式一利用 Helm 历史版本回滚helm history longhorn # 查看之前安装的 REVISION helm rollback longhorn [REVISION]方式二直接升级回旧版本helm upgrade longhorn longhorn/longhorn --namespace longhorn-system --version [previous installed version]Rancher 场景则在 Rancher App Marketplace 中重新升级安装回之前的 Longhorn 版本即可。手动清理示例设计文档给出了一个具体例子从 v1.3.x 升级到 v1.5.x 时新版本会引入新的 Deploymentlonghorn-recovery-backend由于升级路径不支持升级失败。回滚到 v1.3.x 后需要手动删除longhorn-recovery-backend这个 Deployment因为它不存在于旧版本中会残留为新组件。同理任何新版本新增的 CRD、Deployment、DaemonSet、Service 等对象都应在回滚后按需清理。场景五降级拦截Downgrade Prevention降级在任何情况下都被禁止这是防止意外降级目标的具体落地。kubectl安装x.y.*后尝试kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/vx.(y-z).*/deploy/longhorn.yaml任意低版本longhorn-manager入口校验失败并阻止降级若降级目标版本包含longhorn-admission-webhook、longhorn-conversion-webhook、longhorn-recovery-backend这些组件同样参与拦截用户需手动回滚到当前版本重启longhorn-managerPodHelm / Rancher降级时pre-upgradeHook Job 失败整个降级流程终止Longhorn 保持完整继续运行。源码实现Helm pre-upgrade Hook Job设计文档明确提出仿照post-upgradeJob 新增一个pre-upgradeJob。当前仓库中该设计已经落地为 chart/templates/preupgrade-job.yaml与 chart/templates/postupgrade-job.yaml 形成对称结构。关键点对比如下维度longhorn-pre-upgradelonghorn-post-upgradeHelm Hookpre-upgradepost-upgradeHook 删除策略hook-succeeded,before-hook-creation,hook-failedhook-succeeded,before-hook-creation命令longhorn-manager pre-upgradelonghorn-manager post-upgradeactiveDeadlineSeconds900900backoffLimit11restartPolicyOnFailureOnFailurepre-upgradeJob 的完整结构去除 Helm 模板变量后的骨架如下apiVersion: batch/v1 kind: Job metadata: annotations: helm.sh/hook: pre-upgrade helm.sh/hook-delete-policy: hook-succeeded,before-hook-creation,hook-failed name: longhorn-pre-upgrade spec: activeDeadlineSeconds: 900 backoffLimit: 1 template: spec: containers: - name: longhorn-pre-upgrade command: - longhorn-manager - pre-upgrade env: - name: POD_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace restartPolicy: OnFailure serviceAccountName: longhorn-service-account几个值得注意的工程细节删除策略hook-failed也被列入删除策略意味着校验失败时 Job 对象也会被清理避免残留干扰后续重试权限与调度Job 使用longhorn-service-account并支持通过tolerations/nodeSelector取自longhornManager配置与调度保持一致环境变量注入POD_NAMESPACE供pre-upgrade命令定位当前 Longhorn 命名空间若设置了LONGHORN_DISTRO发行版信息也会一并传入运行时机pre-upgradeHook 在 Helm 渲染并应用新版本资源之前运行因此校验失败时Helm 直接中止新版本资源根本不会落盘——这就是Longhorn 完好无损、继续提供服务的机制保证。可配置开关preUpgradeChecker仓库的 Helm 值文件 chart/values.yamlL258-L262提供了两个与升级校验相关的开关preUpgradeChecker: # 是否执行 pre-upgrade 检查。使用 Argo CD 或其他 GitOps 方案安装 Longhorn 时建议关闭。 jobEnabled: true # 是否在 Longhorn Manager DaemonSet Pod 启动后执行版本检查。关闭本项会同时禁用 jobEnabled。官方建议保持开启。 upgradeVersionCheck: truejobEnabled控制是否创建pre-upgradeHook Job。注释明确提示使用 Argo CD 或类似 GitOps 方案安装 Longhorn 时应关闭此项——因为 GitOps 工具对 Helm Hooks 的处理方式不同可能造成 Hook Job 行为异常CHANGELOG/CHANGELOG-1.5.2.md 中也有Remove or Change Helm pre-upgrade hook to support ArgoCD的改进记录upgradeVersionCheck控制 DaemonSet Pod 启动后的版本检查关闭它也会连带禁用jobEnabled官方建议保持开启。这两个开关说明升级校验体系由Pod 入口检查 Helm Hook 检查两部分组成且可分别/联动关闭以满足 GitOps 等特殊部署形态。测试计划如何验证升级路径强制校验设计文档给出了标准测试流程可在测试集群上直接复现测试受支持的升级路径安装 Longhorn v1.4.x等待所有 Pod ready创建 Volume 并写入数据升级到 Longhorn v1.5.0等待所有 Pod 升级完成检查数据未损坏。测试不支持的升级路径安装 Longhorn v1.3.x等待所有 Pod ready创建 Volume 并写入数据升级到 Longhorn v1.5.0升级过程卡住或失败即被入口校验/Hook Job 拦截检查数据未损坏以相同配置回滚到 Longhorn v1.3.x确认 v1.3.x 正常工作。该测试覆盖了拦截、数据完整性、回滚三大关键承诺。值得注意的是当前仓库 support-versions.txt 维护着受支持的最新版本列表v1.11.3 / v1.12.1各版本 CHANGELOG 中均保留了Longhorn only allows upgrades from supported versions的声明实际升级时请以官方 release 文档中的升级路径矩阵为准。总结升级路径强制校验是 Longhorn 保障升级可控性的关键机制其设计要点可归纳为规则统一无论 kubectl 还是 Helm / Rancher都基于同一套版本比较矩阵仅允许 x.y.* → x.(y1).、x.y.0 → x.y.、x.y.* → (x1).y.*禁止跨级与一切降级双防线覆盖kubectl 场景由四个核心组件longhorn-manager、longhorn-admission-webhook、longhorn-conversion-webhook、longhorn-recovery-backend在 Pod 入口拦截Helm / Rancher 场景由pre-upgradeHook Job 在资源落盘前拦截失败不留痕被拦截时旧版本系统保持原样继续服务升级/降级失败不会破坏已有数据回滚靠手动项目不做自动回滚但提供 kubectl 重放旧清单、helm rollback等完整的手动回滚路径并提醒清理新版本残留组件如 v1.5.x 新增的longhorn-recovery-backendDeployment可适配 GitOps通过 chart/values.yaml 的preUpgradeChecker.jobEnabled/upgradeVersionCheck开关可在 Argo CD 等场景下灵活调整校验行为。对生产环境管理员而言理解这套机制意味着升级前务必确认当前版本与目标版本处于受支持路径一旦升级被拦截不要强行清理 Pod而是直接回滚旧版本清单并清理新引入组件即可无损恢复。赞分享云原生存储高可用容器编排【免费下载链接】longhornCloud-Native distributed storage built on and for Kubernetes项目地址https://gitcode.com/gh_mirrors/lo/longhorn点击查看免费下载相关推荐Longhorn Engine Upgrade Enforcement 解析升级前的引擎镜像版本强制校验机制Longhorn Engine Upgrade Enforcement 解析升级前的引擎镜像版本强制校验机制 本文围绕 Longhorn 的 Engine U云原生存储高可用容器编排FastAPI 路径参数完全指南类型转换、数据校验与路径转换器实战path-params 详解FastAPI 路径参数完全指南类型转换、数据校验与路径转换器实战path params 详解 导读 路径参数Path Parameter是任何 We后端Web框架API设计FastAPI 路径参数Path Parameters实战指南声明语法、类型校验、枚举约束与路径转换器FastAPI 路径参数Path Parameters实战指南声明语法、类型校验、枚举约束与路径转换器 本文以 FastAPI 官方教程《Path Par后端Web框架API设计上一篇react-notification-system源码探秘核心组件NotificationItem与Container实现原理下一篇Allosaurus音频预处理技巧优化输入数据提升识别效果的方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考