Ubuntu 上使用 kubeadm 升级 Kubernetes 集群的标准流程
一 升级前准备与版本策略
- 备份关键数据与清单：导出关键资源清单与应用配置，备份 etcd（如使用外部 etcd 更要做好快照），并留存 /etc/kubernetes/ 配置与 kubeconfig。升级只影响控制面与节点组件，不会自动变更你的业务负载，但备份能显著降低风险。
- 检查节点与集群健康：所有节点 Ready、核心组件 Running，存储与网络插件可用，确保有至少一个可调度节点承载被驱逐的 Pod。
- 版本路径与偏差策略：
- 仅支持逐级升级（例如 1.28 → 1.29 → 1.30），不可跨多个次要版本；补丁版本建议直接升到该小版本的最新补丁。
- 版本偏差要点：kube-apiserver 各实例间最多相差 1 个次要版本；kubelet 不能比 apiserver 新，最多比 apiserver 旧 3 个次要版本（若 kubelet < 1.25，最多旧 2 个）；kube-proxy 与 apiserver 偏差同 kubelet；kube-controller-manager/scheduler 与 apiserver 最多旧 1 个次要版本；kubectl 可在 apiserver 相邻一个次要版本内使用。
- 运行时与镜像：自 v1.24 起移除 dockershim，请确保使用 containerd 等受支持的 CRI；如使用旧版镜像仓库导致拉取失败，可切换至 pkgs.k8s.io 社区仓库。
- 维护窗口与 HA：选择低峰时段，HA 集群建议通过 LB 摘除待升级节点，避免 API 中断。
二 控制平面节点升级步骤
- 升级 kubeadm（逐节点进行）：
- 查看可用版本并升级：
- apt 源示例：apt-mark unhold kubeadm && apt-get update && apt-get install -y kubeadm=<目标版本> && apt-mark hold kubeadm
- 验证：kubeadm version
- 检查升级计划：kubeadm upgrade plan（如提示需手动升级组件配置，按提示准备配置文件后再继续）
- 执行升级：
- 第一个控制面：sudo kubeadm upgrade apply <目标版本>
- 其他控制面：sudo kubeadm upgrade node（不再执行 plan 与 CNI 升级）
- 升级 kubelet 与 kubectl（逐节点进行）：
- apt-mark unhold kubelet kubectl && apt-get update && apt-get install -y kubelet=<目标版本> kubectl=<目标版本> && apt-mark hold kubelet kubectl
- systemctl daemon-reload && systemctl restart kubelet
- 取消不可调度并恢复：kubectl uncordon
- 验证：kubectl get nodes 与 kubectl version，确认控制面与节点版本达到目标。
三 工作节点升级步骤
- 腾空节点：kubectl drain --ignore-daemonsets --delete-emptydir-data --force
- 升级 kubeadm（可选，保持与集群版本一致）：apt-mark unhold kubeadm && apt-get update && apt-get install -y kubeadm=<目标版本> && apt-mark hold kubeadm
- 执行节点升级：sudo kubeadm upgrade node
- 升级 kubelet 与 kubectl：apt-mark unhold kubelet kubectl && apt-get update && apt-get install -y kubelet=<目标版本> kubectl=<目标版本> && apt-mark hold kubelet kubectl
- 重启 kubelet：systemctl daemon-reload && systemctl restart kubelet
- 恢复调度：kubectl uncordon
- 验证：kubectl get nodes 确认 VERSION 与 STATUS=Ready。
四 插件与常见问题处理
- 升级 CNI 插件与其他组件：CNI（如 Calico/Cilium）与 Ingress/Dashboard/Prometheus 等需按各自版本兼容矩阵升级；若以 DaemonSet 运行，通常在第一个控制面升级后其余控制面无需重复；升级后按需重启相关工作负载以适配新特性。
- 镜像拉取失败与 CRI 配置：
- 若遇到 “dial unix /var/run/dockershim.sock: no such file or directory”，说明仍在使用 dockershim；请迁移到 containerd，并在 /etc/crictl.yaml 中设置 runtime-endpoint/image-endpoint 为 unix:///run/containerd/containerd.sock。
- 若旧仓库无目标版本包，迁移至 pkgs.k8s.io 社区仓库并重新 apt update。
- 证书与配置：kubeadm 会在升级时自动续期控制面临时证书；如需跳过可用 --certificate-renewal=false（不建议生产使用）。若 kubeadm upgrade plan 提示需手动升级组件配置，按提示提供配置文件再执行 apply。
- 单节点集群注意：升级期间该节点被 drain 后将无可用节点承载 Pod，业务会中断；请提前准备额外节点或采用蓝绿/重建方式降低影响。
五 回滚与验证清单
- 快速回滚思路：
- 控制面回滚：kubeadm upgrade apply <原版本>（前提是控制面临时证书仍有效或已备份）；
- 节点回滚：先 kubeadm upgrade node 回退节点配置，再降级 kubelet/kubectl 并重启；
- 若升级前已备份 etcd 与控制面清单，可优先选择恢复备份以确保一致性。
- 升级后验证：
- 集群与节点：kubectl get nodes -owide、kubectl get componentstatuses（或等效健康检查）；
- 核心工作负载：kubectl get pods -A，确认 kube-system 与业务 Deployment/StatefulSet 全部 Running；
- 网络与存储：CNI 网段与策略生效、PV/PVC 挂载正常、Ingress 路由可达；
- 版本一致性：控制面与节点版本符合偏差策略，kubectl 版本在允许范围内。
