Ubuntu 上 Kubernetes 集群升级注意事项
一 版本与路径规划
- 明确目标版本后，遵循“每次仅升级一个次要版本”的原则，例如从 v1.28 → v1.29 → v1.30；跨多个次要版本直接升级不被支持。升级前阅读目标版本的 Release Notes / 变更日志，关注 Deprecations / Removals。
- 遵守组件版本偏差策略：kubelet 不得高于 kube-apiserver；通常要求 kubelet 与 apiserver 的小版本差不超过 1；多个 apiserver 实例间版本差不超过 1；kubectl 与 apiserver 的差距通常不超过 1 个次要版本。
- 在 Ubuntu 上用包管理器确认可用补丁版本：执行 apt update && apt-cache madison kubeadm，选择形如 1.29.x-00 的目标版本，避免误装跨主次版本包。
二 升级前检查与备份
- 集群健康检查：确认所有节点 Ready、核心组件 Running，检查 etcd 集群健康与数据一致性，评估工作负载与 存储/网络 的兼容性（如 emptyDir 在驱逐时的数据风险）。
- 备份关键数据与配置：
- 备份 etcd（示例）：
ETCDCTL_API=3 etcdctl snapshot save /tmp/etcd-backup.db \
–endpoints=https://127.0.0.1:2379 \
–cacert= --cert= --key=
- 备份 /etc/kubernetes 目录（包含集群配置与证书）。
- 基础设施与系统：确保 NTP 同步、防火墙/安全组策略允许 6443/10250 等端口、swap 已禁用，并准备回滚方案（如回滚包版本、恢复备份、回滚清单）。
三 升级顺序与操作步骤
- 总体顺序：先控制平面，后工作节点；逐个节点进行，升级期间保持集群可用的最小副本数。
- 控制平面节点（首个）：
- 标记维护：kubectl cordon ；如该节点也跑业务负载，执行 kubectl drain --ignore-daemonsets。
- 升级 kubeadm：apt-mark unhold kubeadm && apt-get install -y kubeadm=<目标版本> && apt-mark hold kubeadm。
- 检查与执行：kubeadm upgrade plan；随后 kubeadm upgrade apply <目标版本>（会自动处理控制面静态 Pod 与证书续期，如需跳过证书续期可用 –certificate-renewal=false）。
- 升级 kubelet/kubectl：apt-mark unhold kubelet kubectl && apt-get install -y kubelet=<目标版本> kubectl=<目标版本> && apt-mark hold kubelet kubectl。
- 重启 kubelet：systemctl daemon-reload && systemctl restart kubelet；kubectl uncordon 恢复调度。
- 其他控制平面节点：执行 kubeadm upgrade node（无需再执行 plan 与 CNI 升级）。
- 工作节点：与控制面节点类似，先 cordon/drain，再升级 kubeadm/kubelet/kubectl 并 restart kubelet，最后 uncordon。
- 组件与插件：按各组件文档升级 CNI、CSI、Ingress Controller、CoreDNS 等，确保与目标版本兼容。
四 兼容性风险与验证
- API 弃用与 Helm：升级后若遇到类似 “no matches for kind … in version …” 的错误，说明清单使用了已被移除/弃用的 API 版本。建议在升级前用 kubectl api-resources、helm lint --strict、helm template --validate --kube-version <目标版本> 做静态与模拟校验，并按需迁移到 apps/v1、networking.k8s.io/v1 等稳定版本。
- 清单与控制器：升级 kubeadm 不会自动改写你的业务清单；对使用旧 API 的资源，可用 kubectl convert 辅助迁移，并在 CI 中固化版本校验。
- 升级后验证：逐节点确认 STATUS=Ready 且 VERSION 正确；检查 kube-system 核心组件 Running；查看 kubelet 日志（journalctl -xeu kubelet）；验证关键业务与存储卷可用性。
五 回滚与常见坑
- 回滚策略：若升级失败，优先恢复到升级前备份（如 etcd 快照、/etc/kubernetes 配置），并将 kubeadm/kubelet/kubectl 降级到原版本，重启服务后重新加入集群。
- 常见坑与规避：
- 禁止跨多个次要版本升级；控制面与 kubelet 版本偏差超限会导致不可预期问题。
- 节点维护务必 cordon/drain，并处理好 emptyDir 与本地卷数据风险。
- 升级期间避免同时操作多个节点，防止控制面或工作负载容量不足。
- 包被 hold 导致无法升级时，使用 –allow-change-held-packages 或先解除 hold。
- 单节点集群无法在驱逐后调度 Pod，升级会短时中断业务，需提前评估或准备替代节点。
