文章目录为什么升级不是"小事"一、升级前的准备工作1.1 理解 K8s 版本支持策略1.2 kubeadm upgrade plan：升级前的全面体检1.3 etcd 备份：升级失败的最后防线二、Control Plane 升级：组件顺序决定成败2.1 升级顺序的本质原因2.2 kubeadm 升级 Control Plane2.3 手动部署集群的升级顺序三、Node 升级：drain 操作的细节3.1 升级流程总览3.2 drain 参数详解3.3 PodDisruptionBudget：升级卡住的根本原因3.4 StatefulSet 升级的特殊考虑3.5 kubelet 升级四、升级失败后的回滚路径4.1 Control Plane 回滚：可以但有代价4.2 Node 回滚：只能向前五、跨集群迁移：升级之外的另一个维度5.1 升级 vs 迁移的本质区别5.2 Velero 备份与恢复：7 阶段深度解析5.3 命名空间映射：测试到生产的标准路径5.4 PV/PVC 恢复的三种模式5.5 restore-existing-resource-policy：更新 vs 跳过5.6 迁移前后的完整 Checklist六、API 版本迁移：升级后不可跳过的工作6.1 K8s 1.22+ 的 API 废弃清单6.2 PodSecurityPolicy 迁移：最复杂的 API 迁移6.3 批量转换废弃 API七、完整升级决策树八、总结核心问题：K8s 小版本升级为什么也需要提前规划？升级失败时如何安全回滚？适用环境：K8s 1.22+ 集群，kubeadm 部署场景为什么升级不是"小事"在 K8s 生态中，"升级集群"这件事被严重低估。大多数工程师觉得：下载新版本二进制文件，改个配置，重启服务——不就完了？实际情况远没有这么简单。K8s 每个次版本（minor version）都有严格的支持窗口（n-2 模式，当前支持的最低版本大约落后最新版本 2 个次版本），超过窗口后不再收到安全补丁。而真正让升级变得棘手的，是以下几个因素：API 版本废弃：K8s 1.22 开始大量 beta API 被移除，1.25 直接删除了 PodSecurityPolicy组件版本耦合：Control Plane 各组件（etcd、apiserver、controller-manager、scheduler）之间有版本兼容性约束，必须按特定顺序升级有状态应用的 PDB 限制：StatefulSet 配合 PodDisruptionBudget，升级期间 drain 节点可能被无限期阻塞数据迁移场景：集群内升级和跨集群迁移是两件完全不同的事，工具和策略都不同本文将按照以下顺序展开：同集群升级跨集群迁移升级前的准备工作兼容性检查 + etcd 备份Control Plane 升级etcd → apiserver → 其他组件Node 升级drain → kubelet → uncordon升级还是迁移?Velero 备份与恢复同版本 vs 跨版本迁移升级后验证功能测试 + 性能基线对比命名空间映射与PV/PVC 恢复策略API 版本迁移废弃 API 批量转换完成升级 / 迁移一、升级前的准备工作1.1 理解 K8s 版本支持策略K8s 遵循n-2 支持窗口：当前最新版本支持的最低版本状态1.321.30当前稳定1.311.29安全修复1.301.28安全修复版本号格式为major.minor.patch：patch（补丁版本）：向后兼容，放心升级minor（次版本）：有 API 变更，需要检查兼容性major（主版本）：罕见，目前从未发生升级时应当升级到最新的 patch 版本，而非次版本的早期 patch。例如从 1.27.3 升级，应该升到 1.28.x 的最新 patch。1.2 kubeadm upgrade plan：升级前的全面体检kubeadm upgrade plan是升级前最关键的一步，它会检查：当前集群所有组件的版本可用的升级目标版本升级过程中需要变更的配置项# 在 Control Plane 节点上执行kubeadm upgrade plan# 输出示例（简化）# [upgrade/config] Making sure the configuration is trustworthy:# Components that need to be upgraded by the target version:# COMPONENT CURRENT AVAILABLE# kube-apiserver v1.27.3 v1.28.5# kube-controller-manager v1.27.3 v1.28.5# kube-scheduler v1.27.3 v1.28.5# kube-proxy v1.27.3 v1.28.5# CoreDNS v1.10.1 v1.10.1# etcd 3.5.9.0 3.5.10.0# 可以看到升级目标版本，以及哪些组件将被更新使用--print-config可以看到升级时将使用的完整配置：kubeadm upgrade plan v1.28.5 --print-config这个输出的价值在于：提前看到 kubelet 的配置变更，避免升级后出现意外的配置漂移。1.3 etcd 备份：升级失败的最后防线升级 etcd 之前必须先备份数据。etcd 是整个 K8s 集群的"大脑"，所有资源状态都存储在其中。一旦 etcd 损坏，集群将无法恢复。# 查看 etcd 静态 Pod 的位置kubectl get pods-nkube-system-lcomponent=etcd-owide# 在 etcd Pod 内执行快照备份ETCDCTL_API=3etcdctl\--endpoints=https://127.0.0.1:2379\--cacert=/etc/kubernetes/pki/etcd/ca.crt\--cert=/etc/kubernetes/pki/etcd/server.crt\--key=/etc/kubernetes/pki/etcd/server.key\snapshot save /tmp/etcd-snapshot-$(date+%Y%m%d).db# 验证备份文件ls-lh/tmp/etcd-snapshot-*.db提示：etcd 快照文件通常在 100MB~数 GB 之间，取决于集群中存储的资源数量。备份目标路径需要确保有足够磁盘空间。二、Control Plane 升级：组件顺序决定成败2.1 升级顺序的本质原因K8s Control Plane 各组件之间的版本兼容性遵循以下规则：Control Plane 组件所有组件依赖版本约束