升级 kubeadm 集群

本页介绍如何将 kubeadm 创建的 Kubernetes 集群从 1.30.x 版本 升级到 1.31.x 版本以及从 1.31.x 升级到 1.31.y（其中 y > x）。略过次版本号的升级是 不被支持的。更多详情请访问版本偏差策略。

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

升级工作的基本流程如下：

  1. 升级主控制平面节点
  2. 升级其他控制平面节点
  3. 升级工作节点

准备开始

  • 务必仔细认真阅读发行说明。
  • 集群应使用静态的控制平面和 etcd Pod 或者外部 etcd。
  • 务必备份所有重要组件，例如存储在数据库中应用层面的状态。 kubeadm upgrade 不会影响你的工作负载，只会涉及 Kubernetes 内部的组件，但备份终究是好的。
  • 必须禁用交换分区。

附加信息

  • 下述说明了在升级过程中何时腾空每个节点。如果你正在对任何 kubelet 进行小版本升级， 你需要先腾空待升级的节点（或多个节点）。对于控制面节点，其上可能运行着 CoreDNS Pod 或者其它非常重要的负载。更多信息见腾空节点。
  • Kubernetes 项目推荐你使用版本匹配的 kubelet 和 kubeadm。 但你也可以使用比 kubeadm 版本更低的 kubelet 版本，前提是该版本仍处于支持的版本范围内。 欲了解更多信息，请访问 kubeadm 与 kubelet 的版本差异。

  • 升级后，因为容器规约的哈希值已更改，所有容器都会被重新启动。

  • 要验证 kubelet 服务在升级后是否成功重启，可以执行 systemctl status kubelet 或 journalctl -xeu kubelet 查看服务日志。

  • kubeadm upgrade 支持 --config 和 UpgradeConfiguration API 类型 可用于配置升级过程。
  • kubeadm upgrade 不支持重新配置现有集群。 请按照重新配置 kubeadm 集群中的步骤来进行。

升级 etcd 时的注意事项

由于 kube-apiserver 静态 Pod 始终在运行（即使你已经执行了腾空节点的操作）， 因此当你执行包括 etcd 升级在内的 kubeadm 升级时，对服务器正在进行的请求将停滞， 因为要重新启动新的 etcd 静态 Pod。作为一种解决方法，可以在运行 kubeadm upgrade apply 命令之前主动停止 kube-apiserver 进程几秒钟。这样可以允许正在进行的请求完成处理并关闭现有连接， 并最大限度地减少 etcd 停机的后果。此操作可以在控制平面节点上按如下方式完成：

  1. killall -s SIGTERM kube-apiserver # 触发 kube-apiserver 体面关闭
  2. sleep 20 # 等待一下，以完成进行中的请求
  3. kubeadm upgrade ... # 执行 kubeadm 升级命令

更改软件包仓库

如果你正在使用社区版的软件包仓库（pkgs.k8s.io）， 你需要启用所需的 Kubernetes 小版本的软件包仓库。 这一点在更改 Kubernetes 软件包仓库文档中有详细说明。

说明： 自 2023 年 9 月 13 日起，Kubernetes 已经弃用并冻结了旧版软件包仓库 (apt.kubernetes.io 和yum.kubernetes.io)。 强烈建议使用托管在 pkgs.k8s.io 上的新软件包仓库来安装 2023 年 9 月 13 日之后发布的 Kubernetes 版本。 旧版软件包仓库已被弃用，其内容可能在未来的任何时间被删除，恕不另行通知。新的软件包仓库提供了从 Kubernetes v1.24.0 版本开始的下载。

确定要升级到哪个版本

使用操作系统的包管理器找到最新的补丁版本 Kubernetes 1.31：

  1. # 在列表中查找最新的 1.31 版本
  2. # 它看起来应该是 1.31.x-*，其中 x 是最新的补丁版本
  3. sudo apt update
  4. sudo apt-cache madison kubeadm
  1. # 在列表中查找最新的 1.31 版本
  2. # 它看起来应该是 1.31.x-*，其中 x 是最新的补丁版本
  3. sudo yum list --showduplicates kubeadm --disableexcludes=kubernetes

升级控制平面节点

控制面节点上的升级过程应该每次处理一个节点。 首先选择一个要先行升级的控制面节点。该节点上必须拥有 /etc/kubernetes/admin.conf 文件。

执行 “kubeadm upgrade”

对于第一个控制面节点

  1. 升级 kubeadm：

    1. # 用最新的补丁版本号替换 1.31.x-* 中的 x
    2. sudo apt-mark unhold kubeadm && \
    3. sudo apt-get update && sudo apt-get install -y kubeadm='1.31.x-*' && \
    4. sudo apt-mark hold kubeadm
    1. # 用最新的补丁版本号替换 1.31.x-* 中的 x
    2. sudo yum install -y kubeadm-'1.31.x-*' --disableexcludes=kubernetes

  2. 验证下载操作正常，并且 kubeadm 版本正确：

    1. kubeadm version

  3. 验证升级计划：

    1. sudo kubeadm upgrade plan

    此命令检查你的集群是否可被升级，并取回你要升级的目标版本。 命令也会显示一个包含组件配置版本状态的表格。

    说明：

    kubeadm upgrade 也会自动对 kubeadm 在节点上所管理的证书执行续约操作。 如果需要略过证书续约操作，可以使用标志 --certificate-renewal=false。 更多的信息，可参阅证书管理指南。

  4. 选择要升级到的目标版本，运行合适的命令。例如：

    1. # 将 x 替换为你为此次升级所选择的补丁版本号
    2. sudo kubeadm upgrade apply v1.31.x

    一旦该命令结束，你应该会看到：

    1. [upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.31.x". Enjoy!
    3. [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 默认采用这样一种模式： 在开始升级插件之前，先检查是否已经升级所有的控制平面实例。 你必须按顺序执行控制平面实例的升级，或者至少确保在所有其他控制平面实例已完成升级之前不启动最后一个控制平面实例的升级， 并且在最后一个控制平面实例完成升级之后才执行插件的升级。

  5. 手动升级你的 CNI 驱动插件。

    你的容器网络接口（CNI）驱动应该提供了程序自身的升级说明。 参阅插件页面查找你的 CNI 驱动， 并查看是否需要其他升级步骤。

    如果 CNI 驱动作为 DaemonSet 运行，则在其他控制平面节点上不需要此步骤。

对于其它控制面节点

与第一个控制面节点相同，但是使用：

  1. sudo kubeadm upgrade node

而不是：

  1. sudo kubeadm upgrade apply

此外，不需要执行 kubeadm upgrade plan 和更新 CNI 驱动插件的操作。

腾空节点

将节点标记为不可调度并驱逐所有负载，准备节点的维护：

  1. # 将 <node-to-drain> 替换为你要腾空的控制面节点名称
  2. kubectl drain <node-to-drain> --ignore-daemonsets

升级 kubelet 和 kubectl

  1. 升级 kubelet 和 kubectl：

    1. # 用最新的补丁版本替换 1.31.x-* 中的 x
    2. sudo apt-mark unhold kubelet kubectl && \
    3. sudo apt-get update && sudo apt-get install -y kubelet='1.31.x-*' kubectl='1.31.x-*' && \
    4. sudo apt-mark hold kubelet kubectl
    1. # 用最新的补丁版本号替换 1.31.x-* 中的 x
    2. sudo yum install -y kubelet-'1.31.x-*' kubectl-'1.31.x-*' --disableexcludes=kubernetes

  2. 重启 kubelet：

    1. sudo systemctl daemon-reload
    2. sudo systemctl restart kubelet

解除节点的保护

通过将节点标记为可调度，让其重新上线：

  1. # 将 <node-to-uncordon> 替换为你的节点名称
  2. kubectl uncordon <node-to-uncordon>

升级工作节点

工作节点上的升级过程应该一次执行一个节点，或者一次执行几个节点， 以不影响运行工作负载所需的最小容量。

以下内容演示如何升级 Linux 和 Windows 工作节点：

验证集群的状态

在所有节点上升级 kubelet 后，通过从 kubectl 可以访问集群的任何位置运行以下命令， 验证所有节点是否再次可用：

  1. kubectl get nodes

STATUS 应显示所有节点为 Ready 状态，并且版本号已经被更新。

从故障状态恢复

如果 kubeadm upgrade 失败并且没有回滚，例如由于执行期间节点意外关闭， 你可以再次运行 kubeadm upgrade。 此命令是幂等的，并最终确保实际状态是你声明的期望状态。

要从故障状态恢复，你还可以运行 sudo kubeadm upgrade apply --force 而无需更改集群正在运行的版本。

在升级期间，kubeadm 向 /etc/kubernetes/tmp 目录下的如下备份文件夹写入数据：

  • kubeadm-backup-etcd-<date>-<time>
  • kubeadm-backup-manifests-<date>-<time>

kubeadm-backup-etcd 包含当前控制面节点本地 etcd 成员数据的备份。 如果 etcd 升级失败并且自动回滚也无法修复，则可以将此文件夹中的内容复制到 /var/lib/etcd 进行手工修复。如果使用的是外部的 etcd，则此备份文件夹为空。

kubeadm-backup-manifests 包含当前控制面节点的静态 Pod 清单文件的备份版本。 如果升级失败并且无法自动回滚，则此文件夹中的内容可以复制到 /etc/kubernetes/manifests 目录实现手工恢复。 如果由于某些原因，在升级前后某个组件的清单未发生变化，则 kubeadm 也不会为之生成备份版本。

说明：

集群通过 kubeadm 升级后，备份目录 /etc/kubernetes/tmp 将保留，这些备份文件需要手动清理。

工作原理

kubeadm upgrade apply 做了以下工作：

  • 检查你的集群是否处于可升级状态:
    • API 服务器是可访问的
    • 所有节点处于 Ready 状态
    • 控制面是健康的
  • 强制执行版本偏差策略。
  • 确保控制面的镜像是可用的或可拉取到服务器上。
  • 如果组件配置要求版本升级，则生成替代配置与/或使用用户提供的覆盖版本配置。
  • 升级控制面组件或回滚（如果其中任何一个组件无法启动）。
  • 应用新的 CoreDNS 和 kube-proxy 清单，并强制创建所有必需的 RBAC 规则。
  • 如果旧文件在 180 天后过期，将创建 API 服务器的新证书和密钥文件并备份旧文件。

kubeadm upgrade node 在其他控制平节点上执行以下操作：

  • 从集群中获取 kubeadm ClusterConfiguration。
  • （可选操作）备份 kube-apiserver 证书。
  • 升级控制平面组件的静态 Pod 清单。
  • 为本节点升级 kubelet 配置

kubeadm upgrade node 在工作节点上完成以下工作：

  • 从集群取回 kubeadm ClusterConfiguration。
  • 为本节点升级 kubelet 配置。