Kubernetes集群版本升级从来不是单纯改一下控制平面的镜像标签，真正让人头疼的是隐藏在版本之间的差异。每一次次要版本跃迁，上游都会废弃或移除一部分API、调整默认参数、更换底层依赖。如果跳过兼容性检查直接升级，轻则工作负载调度异常，重则整个命名空间不可用。因此，在动刀之前建立一套系统化的检查流程，比事后救火成本低得多。
API废弃与移除的扫描方法
Kubernetes最典型的兼容性断裂点来自API版本的废弃策略。比如从1.25开始，batch/v1beta1的CronJob被彻底移除，如果集群里还有老资源没迁移到batch/v1，升级后这些对象会变成“幽灵资源”，kube-apiserver不再识别。手动翻YAML不现实，社区维护的kubent（kube-no-trouble）工具可以连接集群，比对当前存储对象与目标版本的API支持矩阵。
使用方式并不复杂，但在CI环境里更推荐以离线模式运行。下面这段命令会扫描当前上下文中的所有废弃API用法：
# 下载并运行kubent扫描废弃API kubent --cluster -o json > api_deprecated_report.json # 查看摘要 cat api_deprecated_report.json | grep -c "deprecated"
扫描报告要逐条处理，不能只看数量。有些对象只是被其他控制器托管，删除重建即可；但像自定义Controller写入的CRD实例，可能需要先停掉控制器再迁移。另外注意，kubent只能发现“已存在”的对象，如果CI流水线里还有老模板会在升级后新建，那必须在代码仓库侧做静态检查，例如用pluto工具扫描Helm chart。
节点与容器运行时的依赖对齐
另一个容易翻车的层面是节点操作系统和容器运行时。1.24版本正式移除了dockershim，这意味着默认情况下kubelet不再通过Docker引擎拉起容器。如果节点还是老一套只装了Docker而没有配置containerd或cri-o，升级后节点会卡在NotReady。兼容性检查必须包含节点镜像和运行时版本的清点。
可以用下面的脚本批量收集节点信息，确认每个节点的容器运行时及kubelet版本：
# 获取所有节点的容器运行时与版本 kubectl get nodes -o wide # 进一步描述某个节点查看RuntimeVersion kubectl describe node node-01 | grep -i "Container Runtime Version"
对于大批节点，建议写一个简单的表格来跟踪。例如：
| 节点名 | 当前运行时 | 目标运行时 | 是否需重装 |
|---|---|---|---|
| node-01 | docker://20.10 | containerd://1.6 | 是 |
| node-02 | containerd://1.6 | containerd://1.7 | 否 |
除运行时外，内核参数和kubelet配置也要比对。比如某些老内核不支持新版的overlayfs挂载选项，或者kubelet的--cgroup-driver与容器运行时不一致，都会在升级后引发诡异的启动失败。因此兼容性检查清单里应包含节点基线配置的差异对比。
工作负载与扩展组件的版本约束
集群自身兼容只是基础，跑在上面的业务和扩展组件才是升级后能否正常运行的关键。Helm release如果引用的chart还写死extensions/v1beta1的Ingress，在1.22之后就会安装失败。Operator框架开发的自定义控制器若依赖旧版client-go，也可能无法连接新apiserver。检查时要列出所有第三方组件及其声明支持的Kubernetes版本区间。
下面是一段用kubectl和jq提取已安装Helm版本及对应chart的示例，辅助判断是否需要先升级chart：
# 列出所有helm release及chart版本 helm list -A -o json | jq -r '.[] | "(.name)t(.chart)t(.app_version)"' # 对疑似老chart做pluto静态扫描 pluto detect-files -d ./charts/old-nginx
对于自研控制器，要检查其go.mod里k8s.io/client-go的版本是否支持目标集群的API。一般规则是client-go版本与集群版本偏差不超过一个小版本。若差距过大，应先在测试集群验证CRD的读写，再决定升级顺序。许多团队忽略了对CustomResourceDefinition本身的转换策略检查，当CRD的storedVersions不含目标版本时，apiserver会拒绝升级，这类问题只能在预发环境提前暴露。
综合来看，Kubernetes版本升级的兼容性检查是一条从集群内核到应用外围的链路工程。只有把API废弃、节点运行时、工作负载与扩展组件全部纳入同一份检查矩阵，并配合预发集群的灰度演练，才能把生产事故的概率压到最低。每次升级前花半天做这些交叉验证，远比半夜被告警叫起来回滚要轻松得多。
Kubernetes版本升级兼容性检查修改时间：2026-08-18 09:32:28