升级 kubeadm 集群
本页面介绍如何将使用 kubeadm 创建的 Kubernetes 集群从 1.29.x 版本升级到 1.30.x 版本，以及从 1.30.x 版本升级到 1.30.y 版本（其中 y > x）。跳过次要版本升级是不受支持的。有关更多详细信息，请访问版本偏差策略。
要查看有关使用旧版本 kubeadm 创建的集群升级的信息，请参阅以下页面
- 将 kubeadm 集群从 1.28 升级到 1.29
- 将 kubeadm 集群从 1.27 升级到 1.28
- 将 kubeadm 集群从 1.26 升级到 1.27
- 将 kubeadm 集群从 1.25 升级到 1.26
升级工作流程概览如下
- 升级主控制平面节点。
- 升级其他控制平面节点。
- 升级工作节点。
准备工作
- 确保你已仔细阅读发行说明。
- 集群应使用静态控制平面和 etcd Pod 或外部 etcd。
- 确保备份任何重要组件，例如存储在数据库中的应用级状态。
kubeadm upgrade不会触碰你的工作负载，只会触碰 Kubernetes 内部组件，但备份始终是最佳实践。 - 必须禁用交换分区.
其他信息
- 以下说明概述了在升级过程中何时排空每个节点。如果你要对任何 kubelet 执行**次要**版本升级，则**必须**先排空要升级的节点（或多个节点）。对于控制平面节点，它们可能正在运行 CoreDNS Pod 或其他关键工作负载。有关更多信息，请参阅排空节点。
- Kubernetes 项目建议你使 kubelet 和 kubeadm 版本保持一致。你也可以使用比 kubeadm 旧的 kubelet 版本，前提是它在支持的版本范围内。有关更多详细信息，请访问kubeadm 与 kubelet 的版本偏差。
- 升级后所有容器都会重启，因为容器规范哈希值已更改。
- 要验证 kubelet 服务在 kubelet 升级后是否已成功重启，你可以执行
systemctl status kubelet或使用journalctl -xeu kubelet查看服务日志。 - 不建议使用带有kubeadm 配置 API 类型的
kubeadm upgrade命令的--config标志来重新配置集群，这可能会导致意外结果。请按照重新配置 kubeadm 集群中的步骤操作。
升级 etcd 时的注意事项
由于 kube-apiserver 静态 Pod 一直在运行（即使你已排空节点），因此当你执行包含 etcd 升级的 kubeadm 升级时，在新的 etcd 静态 Pod 重启期间，对服务器的飞行中请求将暂停。作为一种解决方法，可以在启动 kubeadm upgrade apply 命令之前几秒钟主动停止 kube-apiserver 进程。这允许完成飞行中请求并关闭现有连接，并最大程度地减少 etcd 停机时间的影响。这可以在控制平面节点上按如下方式完成
killall -s SIGTERM kube-apiserver # trigger a graceful kube-apiserver shutdown
sleep 20 # wait a little bit to permit completing in-flight requests
kubeadm upgrade ... # execute a kubeadm upgrade command
更改软件包存储库
如果你使用的是社区拥有的软件包存储库（pkgs.k8s.io），则需要为所需的 Kubernetes 次要版本启用软件包存储库。这在更改 Kubernetes 软件包存储库文档中进行了说明。
apt.kubernetes.io 和 yum.kubernetes.io）已于2023 年 9 月 13 日起弃用并冻结。**强烈建议使用托管在 pkgs.k8s.io 上的新软件包存储库，并且需要使用它来安装 2023 年 9 月 13 日之后发布的 Kubernetes 版本。**弃用的旧版存储库及其内容可能会在将来的任何时间删除，恕不另行通知。新的软件包存储库提供从 v1.24.0 版本开始的 Kubernetes 版本的下载。确定要升级到的版本
使用操作系统包管理器查找 Kubernetes 1.30 的最新补丁版本
# Find the latest 1.30 version in the list.
# It should look like 1.30.x-*, where x is the latest patch.
sudo apt update
sudo apt-cache madison kubeadm
# Find the latest 1.30 version in the list.
# It should look like 1.30.x-*, where x is the latest patch.
sudo yum list --showduplicates kubeadm --disableexcludes=kubernetes
升级控制平面节点
控制平面节点上的升级过程应一次在一个节点上执行。选择要首先升级的控制平面节点。它必须具有 /etc/kubernetes/admin.conf 文件。
调用“kubeadm upgrade”
对于第一个控制平面节点
升级 kubeadm
# replace x in 1.30.x-* with the latest patch version sudo apt-mark unhold kubeadm && \ sudo apt-get update && sudo apt-get install -y kubeadm='1.30.x-*' && \ sudo apt-mark hold kubeadm# replace x in 1.30.x-* with the latest patch version sudo yum install -y kubeadm-'1.30.x-*' --disableexcludes=kubernetes验证下载是否正常并且版本符合预期
kubeadm version验证升级计划
sudo kubeadm upgrade plan此命令检查你的集群是否可以升级，并获取你可以升级到的版本。它还会显示一个包含组件配置版本状态的表格。
注意
如果kubeadm upgrade plan显示任何需要手动升级的组件配置，则用户必须通过--config命令行标志向kubeadm upgrade apply提供包含替换配置的配置文件。否则将导致kubeadm upgrade apply退出并显示错误，并且不执行升级。选择要升级到的版本，然后运行相应的命令。例如
# replace x with the patch version you picked for this upgrade sudo kubeadm upgrade apply v1.30.x命令完成后，你应该会看到
[upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.30.x". Enjoy! [upgrade/kubelet] Now that your control plane is upgraded, please proceed with upgrading your kubelets if you haven't already done so.注意
对于 v1.28 之前的版本，kubeadm 默认使用在kubeadm upgrade apply期间立即升级插件（包括 CoreDNS 和 kube-proxy）的模式，而不管是否有其他尚未升级的控制平面实例。这可能会导致兼容性问题。从 v1.28 开始，kubeadm 默认使用一种模式，该模式会检查在开始升级插件之前是否已升级所有控制平面实例。你必须按顺序执行控制平面实例升级，或者至少确保在所有其他控制平面实例都已完全升级之前，不会启动最后一个控制平面实例升级，并且插件升级将在最后一个控制平面实例升级之后执行。如果你想保留旧的升级行为，请通过kubeadm upgrade apply --feature-gates=UpgradeAddonsBeforeControlPlane=true启用UpgradeAddonsBeforeControlPlane特性门控。Kubernetes 项目通常不建议启用此特性门控，你应该改为更改升级过程或集群插件，以便你无需启用旧行为。UpgradeAddonsBeforeControlPlane特性门控将在未来的版本中删除。手动升级你的 CNI 提供程序插件。
你的容器网络接口 (CNI) 提供程序可能有自己的升级说明需要遵循。查看插件页面以找到你的 CNI 提供程序，并查看是否需要其他升级步骤。
如果 CNI 提供程序作为 DaemonSet 运行，则在其他控制平面节点上不需要此步骤。
对于其他控制平面节点
与第一个控制平面节点相同，但使用
sudo kubeadm upgrade node
代替
sudo kubeadm upgrade apply
也不再需要调用 kubeadm upgrade plan 和升级 CNI 提供程序插件。
排空节点
通过将节点标记为不可调度并驱逐工作负载来准备进行维护
# replace <node-to-drain> with the name of your node you are draining
kubectl drain <node-to-drain> --ignore-daemonsets
升级 kubelet 和 kubectl
升级 kubelet 和 kubectl
# replace x in 1.30.x-* with the latest patch version sudo apt-mark unhold kubelet kubectl && \ sudo apt-get update && sudo apt-get install -y kubelet='1.30.x-*' kubectl='1.30.x-*' && \ sudo apt-mark hold kubelet kubectl# replace x in 1.30.x-* with the latest patch version sudo yum install -y kubelet-'1.30.x-*' kubectl-'1.30.x-*' --disableexcludes=kubernetes重启 kubelet
sudo systemctl daemon-reload sudo systemctl restart kubelet
解除节点的警戒状态
通过将节点标记为可调度来使其重新联机
# replace <node-to-uncordon> with the name of your node
kubectl uncordon <node-to-uncordon>
升级工作节点
工作节点上的升级过程应一次在一个节点或几个节点上执行，而不会影响运行工作负载所需的最低容量。
以下页面显示了如何升级 Linux 和 Windows 工作节点
验证集群状态
在所有节点上升级 kubelet 后，通过从 kubectl 可以访问集群的任何位置运行以下命令来验证所有节点是否再次可用
kubectl get nodes
STATUS 列应为所有节点显示 Ready，并且版本号应已更新。
从故障状态恢复
如果 kubeadm upgrade 失败并且没有回滚，例如由于执行期间意外关闭，则可以再次运行 kubeadm upgrade。此命令是幂等的，最终会确保实际状态是你声明的所需状态。
要从错误状态恢复，你还可以运行 sudo kubeadm upgrade apply --force，而无需更改集群正在运行的版本。
在升级过程中，kubeadm 会在 /etc/kubernetes/tmp 下写入以下备份文件夹
kubeadm-backup-etcd-<日期>-<时间>kubeadm-backup-manifests-<日期>-<时间>
kubeadm-backup-etcd 包含此控制平面节点的本地 etcd 成员数据的备份。如果 etcd 升级失败并且自动回滚不起作用，则可以将此文件夹的内容手动还原到 /var/lib/etcd 中。如果使用外部 etcd，则此备份文件夹将为空。
kubeadm-backup-manifests 包含此控制平面节点的静态 Pod 清单文件的备份。如果升级失败并且自动回滚不起作用，则可以将此文件夹的内容手动恢复到 /etc/kubernetes/manifests 中。如果由于某种原因，某个组件的升级前和升级后清单文件之间没有区别，则不会为其写入备份文件。
注意
使用 kubeadm 升级集群后，备份目录/etc/kubernetes/tmp 将保留，并且需要手动清除这些备份文件。工作原理
kubeadm upgrade apply 执行以下操作
- 检查您的集群是否处于可升级状态
- API 服务器可达
- 所有节点都处于
Ready状态 - 控制平面运行状况良好
- 强制执行版本偏差策略。
- 确保控制平面镜像可用或可拉取到机器。
- 如果组件配置需要版本升级，则生成替换和/或使用用户提供的覆盖。
- 升级控制平面组件，如果其中任何一个组件启动失败，则回滚。
- 应用新的
CoreDNS和kube-proxy清单，并确保创建所有必要的 RBAC 规则。 - 创建 API 服务器的新证书和密钥文件，如果旧文件将在 180 天内过期，则备份旧文件。
kubeadm upgrade node 在其他控制平面节点上执行以下操作
- 从集群中获取 kubeadm
ClusterConfiguration。 - 可选地备份 kube-apiserver 证书。
- 升级控制平面组件的静态 Pod 清单。
- 升级此节点的 kubelet 配置。
kubeadm upgrade node 在工作节点上执行以下操作
- 从集群中获取 kubeadm
ClusterConfiguration。 - 升级此节点的 kubelet 配置。