Kubernetes 1.37 Garhwal 的升级检查重点与兼容边界

Kubernetes 1.37 Garhwal 的升级检查应先覆盖版本偏差、Linux 节点的 cgroup 模式、API 调用兼容和网络存储插件，再安排控制平面与节点升级。上游发布了新版本，只说明有了可选目标，不能替代当前集群的兼容结论。

官方地址：https://kubernetes.io/

官方 1.37 发布系列页将该版本命名为 Garhwal，发布公告提供了版本背景。下面聚焦把发布信息转成升级工单；不会把所有新增能力都视为必须开启的配置。托管集群还须服从供应商开放的版本和维护规则。

从发布信息建立明确的升级工单

设想一个准备从 1.36 迁移到 1.37 的团队：节点版本看起来统一，但网络插件、备份和业务发布由不同人员负责。最容易遗漏的不是安装命令，而是“谁确认哪个条件，失败后停在哪里”。这个假设场景适合先建立一张有负责人和暂停条件的工单，再讨论自动执行。

工单填写当前完整版本、目标补丁版本、集群创建工具、控制平面拓扑、节点池、变更窗口及业务负责人。目标应固定为明确版本，不把“1.37 最新版”写成长期不变的流水线输入。发布页的计划日期与已经提供的版本也应分别对待，不能仅因预定日期已过就认定补丁已可安装。

对 kubeadm 管理的集群，官方升级说明覆盖 1.36.x 到 1.37.x，并明确不支持跳过次版本。如果当前是 1.35，不能把 kubelet 的允许偏差误解为可以直接跨级执行控制平面升级。每个中间阶段都应有对应版本的升级说明。

权限分开，先收集组件与扩展清单

建议把资料采集身份和升级执行身份分开。前者读取组件版本、节点条件及扩展配置；后者负责经过授权的节点维护和控制平面变更。具体权限由部署方式决定，不应为了读取清单就把永久集群管理员凭据交给通用流水线。工单记录身份名称与权限范围，不保存令牌、私钥或完整 kubeconfig。

这些是建议纳入变更工单的项目，不代表本文已经连接或测试任何集群。插件支持范围须查相应维护者资料，本文不为未指定插件作兼容承诺。

将兼容边界写入升级阶段

版本偏差政策给的是组件之间的支持上限，不是一套可以任意排列的升级步骤。官方规定高可用 API Server 的最新和最旧实例相差不超过一个次版本，kubelet 不能新于它连接的 API Server；kubectl 通常允许在 API Server 前后一个次版本内。混合控制平面会缩小共同允许范围，部署工具还可能增加限制。

例如控制平面暂时同时存在 1.36 与 1.37 时，不应仅根据较新的实例就把 kubelet 提到 1.37。工单需要列出每个中间状态实际会连接哪些 API Server，再求兼容范围，而不是只看最终版本。依据见 官方版本偏差政策。

节点环境还有一项具体变化：官方 1.37 kubeadm 升级文档说明，Linux kubelet 的 FailCgroupV1 默认值为 true。仍依赖 cgroup v1 的节点应先评估操作系统、运行时与工作负载的迁移安排，不能等批量替换 kubelet 后才发现启动条件不满足。

API 部分要区分“弃用提示”和“目标版本不再提供”。对实际使用的 group/version/resource 逐项查 官方弃用 API 迁移指南及目标版本说明，同时检查客户端、控制器和 Webhook。这里不假定某个未核实的 API 一定在 1.37 删除；只有具体调用与官方条目对应后，才能形成整改项。

让失败条件决定暂停位置

按照 kubeadm 官方升级说明，总体安排是先主控制平面节点，再其他控制平面节点，最后工作节点；控制平面节点应逐个处理。节点维护、CNI 更新和软件包源选择也须遵循该部署对应的步骤，不能用一个并行安装任务代替。

自动化可以围绕三个阶段组织：准备阶段形成兼容清单和恢复材料；执行阶段按已确认的拓扑推进一批；观察阶段确认业务和基础能力后才放行下一批。建议把超时、节点无法恢复就绪、网络或存储异常、关键业务指标恶化定义为暂停条件。阈值由业务目标确定，不能直接复制别人的固定等待秒数。

例如节点因旧 cgroup 模式无法启动，应停止扩大节点池变更，先保留失败节点的环境差异和日志，交给节点环境负责人处理。一次重试成功也不能自动抹掉失败记录；否则后续批次可能再次遇到同一前置条件。

恢复方案必须独立于版本回退

把软件包改回旧版本，不等于完成集群恢复。集群状态、证书和配置、插件状态、应用数据可能分别有自己的恢复条件。因此建议工单明确“暂停继续升级”“恢复节点服务”“恢复集群状态”“恢复应用数据”四类动作的负责人，不把它们合并为一个含糊的回滚按钮。

备份记录至少说明对象、完成时间、保留位置的受控引用和恢复演练结论；不得在通知中暴露备份凭据。恢复是否会覆盖升级窗口内的新写入，也应由数据负责人评估。本文不提供通用降级命令，不承诺所有部署支持原地降级。

用通知记录关闭升级工单

每一批通知至少包含集群标识、目标版本、已完成节点范围、当前暂停原因、下一责任人和工单链接。通知发送失败与升级失败分别记录，避免基础设施已经变更却无人收到消息。流水线应保留可追踪状态，重入时依据实际完成范围恢复工作，不重新覆盖已完成节点。

• 版本入口：目标补丁版本和安装来源已明确，未把计划发布当成可用产物。
• 兼容入口：控制平面混合版本、节点 cgroup、插件和 API 调用均有负责人。
• 执行出口：每批节点和关键业务观察结果有记录，暂停条件能够阻止扩散。
• 恢复出口：备份对象、恢复责任和数据时间范围分别说明。

只升级 kubectl 能获得 1.37 的服务端能力吗？不能，客户端版本不能代替 API Server 和相关组件的实现；应按所用功能核对服务端及配置条件。

托管集群能直接照搬 kubeadm 流程吗？不能。控制平面权限、升级窗口、节点镜像和支持版本可能由服务商管理，应将本文清单映射到供应商流程。

所有节点 Ready 就可以关闭工单吗？Ready 是必要观察项之一，还应确认实际使用的网络、存储、扩展控制器与业务路径。关闭条件应在变更前约定，不能在操作完成后临时降低要求。