按“评估、控制面、节点、addon、验证、回滚”的顺序完成一次可审计的 Kubernetes 集群升级

适用场景

• 自建 kubeadm 集群做 minor 版本升级，或托管集群升级节点池、控制面。
• 升级前演练、变更评审、值班交接，以及升级失败后的回退决策。
• 需要把升级步骤、验证标准和回滚边界写成可执行清单的团队。
• 不适用：跨多个 minor 直接升级、同时更换 CNI 或容器运行时、需要迁移 etcd 存储的大改。这些应拆成独立变更，每项单独评估。

本流程默认先在测试集群演练，再按节点池灰度。托管集群的控制面由云厂商负责，控制面命令以厂商文档为准；评估、节点、addon 和验证部分仍可复用。

前置检查

1. 确认升级路径。目标版本必须在支持矩阵内，源版本能逐级升级；记录当前 kubeadm、kubelet、kubectl、etcd 和运行时版本。不要跳级，也不要把“控制面升级成功”当成“集群升级完成”。

2. 扫描废弃 API 和 CRD。使用 pluto detect-all-in-cluster、kubectl deprecations 或 kubent 检查工作负载、Helm release、Operator 和 CRD；重点看已删除的 API 版本、转换 Webhook 和聚合 API。升级前先在测试集群应用一遍清单。

3. 核对 addon 兼容性。CNI、CSI、Ingress/Gateway、cert-manager、metrics-server、集群自动扩缩容、策略引擎、监控日志、备份和各类 Operator 都要有与目标版本匹配的发布说明。Webhook 的证书、超时和 failurePolicy 也要检查。

4. 备份控制面和工作负载。至少保存 etcd 快照、/etc/kubernetes、关键 CRD、PVC 和数据库备份，并实际验证恢复路径：

sudo etcdctl snapshot save /backup/etcd-$(date +%F-%H%M).db \
  --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
sudo etcdctl snapshot status /backup/etcd-<timestamp>.db -w table

只有快照文件不够，必须知道如何停止写入、在多成员间恢复并重新拉起控制面。工作负载和 PVC 可用 Velero 或存储快照备份，数据库要单独做一致性备份。

5. 检查容量和可用性。确认节点有 N+1 余量，关键服务多副本且有 PodDisruptionBudget，StatefulSet、数据库和消息队列有专门的迁移方案。可以先在一个非关键节点做 cordon/drain 演练，确认 Pod 能正常迁移、PVC 能重新挂载。

6. 冻结变更并约定窗口。暂停 CI/CD 自动发布、集群自动扩缩容和会修改集群的定时任务；通知业务方，明确维护窗口、成功标准、回滚触发条件和决策人。升级期间不要同时做网络、存储或应用大版本变更。

7. 检查证书、时间和健康基线。执行 kubeadm certs check-expiration，确认 NTP/chrony 正常，记录 kubectl get --raw='/readyz?verbose'、etcdctl endpoint health --cluster、节点状态和关键业务指标，作为升级后的对照。

8. 托管集群额外确认：控制面版本是否由厂商滚动升级、节点池镜像和 kubelet 是否需要单独升级、addon 是否会自动升级、是否支持降级。多数托管集群不支持控制面降级，回滚方案要提前写清楚。

操作步骤

1. 固定升级前基线

kubectl version -o yaml > /backup/version-before.yaml
kubectl get nodes -o wide > /backup/nodes-before.txt
kubectl get pods -A -o wide > /backup/pods-before.txt
kubectl get --raw='/readyz?verbose' > /backup/readyz-before.txt

同时记录 etcd 成员列表、API Server 延迟、错误率、核心业务成功率和当前告警。升级过程中如果指标偏离基线，先暂停，不要继续扩大批次。

2. 升级控制面

自建集群先用发行版包管理器升级 kubeadm，再升级第一个控制面节点：

sudo kubeadm upgrade plan
sudo kubeadm upgrade apply <target-version>

随后升级 kubelet、kubectl，重启 kubelet。kubeadm upgrade apply 负责控制面组件、静态 Pod 和证书续期；升级后确认 API Server、controller-manager、scheduler 和 etcd 都正常，再处理下一个控制面节点。

其余控制面节点先升级 kubeadm 包，再逐台执行：

sudo kubeadm upgrade node

随后升级 kubelet、kubectl 并重启 kubelet。一次只动一台，升级前 cordon，升级后确认 kubectl get --raw='/readyz?verbose'、etcd quorum、leader 和系统 Pod 正常，再 uncordon。HA 集群绝不能同时重启两台控制面；如果 etcd 使用 stacked 模式，更要把 quorum 放在第一位。控制面升级失败时，不要急着重启全部节点，先保留现场和日志。

3. 升级节点

按节点池滚动，先选非关键池。每台节点执行：

kubectl cordon <node>
kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

--delete-emptydir-data 会删除 emptyDir 数据，只对确认无状态或已有备份的工作负载使用。drain 卡住时检查 PDB、DaemonSet、本地存储和 finalizer，不要用 --force 跳过所有保护。

节点排空后，升级 kubeadm 包，执行 sudo kubeadm upgrade node，再升级 kubelet、kubectl 和节点镜像，重启 kubelet，最后 kubectl uncordon <node>。确认 Node Ready、CNI Pod、CoreDNS、存储挂载和该节点上的业务 Pod 正常，等待指标稳定后再处理下一台。StatefulSet、数据库和消息队列节点要逐台确认副本和选主状态。

4. 升级 addon

顺序通常是“CRD → 控制器 → 工作负载”，一次只升级一个组件。重点检查 CNI、CSI、Ingress/Gateway、cert-manager、metrics-server、自动扩缩容、监控日志、策略和备份组件。升级后确认 CRD 已建立、Webhook 证书有效、APIService 可用：

kubectl get crd
kubectl get apiservices
kubectl -n <namespace> rollout status deployment/<name>

addon 升级失败时优先回滚该 addon，不要用“继续升级其他组件”掩盖问题。CRD 的降级可能丢失字段，升级前要备份 CRD 和自定义资源。

5. 收尾

恢复 CI/CD 和自动扩缩容，移除临时告警静默，更新集群文档、版本台账和升级记录。记录每批耗时、遇到的问题和实际回滚点。升级后至少观察一个完整业务高峰，再宣布完成。

验证

• kubectl get nodes 全部 Ready，kubelet 版本与目标一致，没有反复 NotReady。
• kubectl get --raw='/readyz?verbose'、/livez、/healthz 全部通过；API Server 延迟和错误率在基线内。
• etcdctl endpoint health --cluster 全部健康，endpoint status --cluster -w table 没有 leader 抖动，成员列表完整。
• 系统 Pod 没有 CrashLoopBackOff、Pending 或频繁重启；CNI、CSI、CoreDNS、Ingress、metrics-server、cert-manager 正常。
• 核心业务完成登录、写入、读取、支付或下单等端到端验证；滚动发布、HPA、PDB、Job 和定时任务都能工作。
• DNS 解析、Service、Ingress/Gateway、PVC 挂载、快照和备份恢复通过抽检。
• 审计日志、控制器日志和 kubelet 日志没有大量 x509、forbidden、NotFound 或版本不兼容错误。
• 监控、日志、追踪和告警恢复正常，错误预算消耗可接受；托管集群的节点池版本与 addon 状态一致。

失败与回滚

先约定触发条件：API Server 持续不可用、etcd 失去 quorum、大面积节点 NotReady、关键 addon 不兼容、核心业务持续错误或 SLO 快速燃烧。触发后立即停止后续批次，保留现场，由决策人确认回滚还是向前修复。

控制面回滚。 官方升级流程不覆盖控制面降级，通常需从 etcd 快照和控制面备份恢复：停止升级、修复单点问题，或恢复 etcd 快照与 /etc/kubernetes 备份，再安装旧版本 kubelet/kubectl 和旧节点镜像。快照恢复会丢失快照之后的写入，必须先切断业务写入、评估数据损失，并确认所有控制面成员使用同一份快照。不要在生产上执行 kubeadm reset 当作回滚，它会清掉集群状态。

节点回滚。 重新安装上一版 kubelet、容器运行时和节点镜像，重新加入集群并 uncordon。节点回滚后仍要满足版本偏差策略，不能长期保留过旧组件。节点上的本地数据和 emptyDir 要提前确认。

addon 回滚。 用 Helm 或原清单回滚到上一版，恢复 CRD 和 Webhook 配置；CRD 降级前先备份自定义资源。回滚后重新验证 APIService、证书和控制器日志。

工作负载回滚。 应用镜像和配置的回滚与集群升级分开执行，避免把应用故障误判为集群故障。数据库迁移要与应用升级解耦，必要时使用备份或 PITR。

故障转移与重建。 如果控制面节点无法恢复，优先用备份重建节点并重新加入，不要在没有 quorum 的情况下强行写入。恢复完成后重新做一次 etcd 快照、证书检查和业务验收，并写复盘记录。

相关命令

• k8s-upgrade-checklist — 升级前逐项检查与常见误区
• kubeadm — 控制面升级、节点加入与证书管理
• kubelet — 节点组件版本、启动与 NotReady 排障
• etcd — 快照、成员管理与 quorum 检查
• pluto — 废弃 API 扫描
• velero — 工作负载与 PVC 备份恢复
• kubectl — 排空、验证与日常排障
• k8s-production-checklist — 升级后的生产检查
• lab-k8s-upgrade — 在 kind/一次性集群演练升级、回滚与验证

参考链接

• Kubernetes: Upgrading kubeadm clusters
• Kubernetes: Version skew policy
• Kubernetes: Deprecated API migration guide
• Kubernetes: Operating etcd clusters for Kubernetes
• etcd: Disaster recovery

读完自测

合上页面，先回答，再展开对照。

1. 为什么 Kubernetes 升级不能跨多个 minor 版本直接进行？
2. 控制面升级时为什么要逐台进行，每台之后验证什么？
3. 什么情况下应该回滚，回滚前必须确认哪些数据边界？