升级 kubeadm 集群

本页面解释如何将使用 kubeadm 创建的 Kubernetes 集群从版本 1.33.x 升级到版本 1.34.x，以及从版本 1.34.x 升级到版本 1.34.y (其中 y > x)。不支持跳过次要版本进行升级。更多详细信息，请访问 版本偏差策略。

要查看有关使用旧版 kubeadm 创建的集群的升级信息，请参阅以下页面：

Kubernetes 项目建议及时升级到最新的补丁版本，并确保你正在运行受支持的 Kubernetes 次要版本。遵循此建议有助于你保持安全。

高级升级工作流如下：

  1. 升级主控制平面节点。
  2. 升级附加控制平面节点。
  3. 升级工作节点。

准备工作

  • 请务必仔细阅读 发布说明。
  • 集群应使用静态控制平面和 etcd Pod 或外部 etcd。
  • 请务必备份任何重要组件，例如存储在数据库中的应用程序级状态。kubeadm upgrade 不会触及你的工作负载，只触及 Kubernetes 内部组件，但备份始终是最佳实践。
  • 必须禁用 Swap.

其他信息

  • 下面的说明概述了在升级过程中何时排空每个节点。如果你正在对任何 kubelet 执行次要版本升级，则必须首先排空你正在升级的节点。对于控制平面节点，它们可能正在运行 CoreDNS Pod 或其他关键工作负载。有关更多信息，请参阅 排空节点。
  • Kubernetes 项目建议你匹配 kubelet 和 kubeadm 版本。你也可以使用比 kubeadm 旧的 kubelet 版本，只要它在支持的版本范围内。更多详细信息，请访问 kubeadm 与 kubelet 的版本偏差。
  • 所有容器在升级后都会重新启动，因为容器规约的哈希值已更改。
  • 要验证 kubelet 升级后是否已成功重新启动，你可以执行 systemctl status kubelet 或使用 journalctl -xeu kubelet 查看服务日志。
  • kubeadm upgrade 支持带有 UpgradeConfiguration API 类型 的 --config，可用于配置升级过程。
  • kubeadm upgrade 不支持重新配置现有集群。请改为按照 重新配置 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 软件包仓库 文档中进行了解释。

确定要升级到的版本

使用操作系统软件包管理器查找 Kubernetes 1.34 的最新补丁版本

# Find the latest 1.34 version in the list.
# It should look like 1.34.x-*, where x is the latest patch.
sudo apt update
sudo apt-cache madison kubeadm


# Find the latest 1.34 version in the list.
# It should look like 1.34.x-*, where x is the latest patch.
sudo yum list --showduplicates kubeadm --disableexcludes=kubernetes

如果你没有看到预期的升级版本，请验证是否使用了 Kubernetes 软件包仓库。

升级控制平面节点

控制平面节点上的升级过程应一次一个节点地执行。选择一个你希望首先升级的控制平面节点。它必须具有 /etc/kubernetes/admin.conf 文件。

调用 "kubeadm upgrade"

对于第一个控制平面节点

  1. 升级 kubeadm

    # replace x in 1.34.x-* with the latest patch version
sudo apt-mark unhold kubeadm && \
sudo apt-get update && sudo apt-get install -y kubeadm='1.34.x-*' && \
sudo apt-mark hold kubeadm


    # replace x in 1.34.x-* with the latest patch version
sudo yum install -y kubeadm-'1.34.x-*' --disableexcludes=kubernetes

  2. 验证下载是否有效并具有预期版本

    kubeadm version

  3. 验证升级计划

    sudo kubeadm upgrade plan

    此命令检查你的集群是否可以升级，并获取你可以升级到的版本。它还显示一个包含组件配置版本状态的表格。

  4. 选择要升级到的版本，然后运行相应的命令。例如：

    # replace x with the patch version you picked for this upgrade
sudo kubeadm upgrade apply v1.34.x

    命令完成后，你应该会看到：

    [upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.34.x". Enjoy!

[upgrade/kubelet] Now that your control plane is upgraded, please proceed with upgrading your kubelets if you haven't already done so.

  5. 手动升级你的 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

  1. 升级 kubelet 和 kubectl

    # replace x in 1.34.x-* with the latest patch version
sudo apt-mark unhold kubelet kubectl && \
sudo apt-get update && sudo apt-get install -y kubelet='1.34.x-*' kubectl='1.34.x-*' && \
sudo apt-mark hold kubelet kubectl


    # replace x in 1.34.x-* with the latest patch version
sudo yum install -y kubelet-'1.34.x-*' kubectl-'1.34.x-*' --disableexcludes=kubernetes

  2. 重启 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 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 配置。
上次修改时间：2025 年 7 月 3 日下午 2:05 PST：修复 kubeadm 升级指南中的拼写错误：删除重复的“to”(5575d62223)