安装 kubeadm

本页面显示如何安装 kubeadm 工具箱。 有关在执行此安装过程后如何使用 kubeadm 创建集群的信息， 请参见使用 kubeadm 创建集群。

此 installation guide 适用于Kubernetes v1.32。如果你想使用其他 Kubernetes 版本，请参考以下页面：

准备开始

  • 一台兼容的 Linux 主机。Kubernetes 项目为基于 Debian 和 Red Hat 的 Linux 发行版以及一些不提供包管理器的发行版提供通用的指令。
  • 每台机器 2 GB 或更多的 RAM（如果少于这个数字将会影响你应用的运行内存）。
  • 控制平面机器需要 CPU 2 核心或更多。
  • 集群中的所有机器的网络彼此均能相互连接（公网和内网都可以）。
  • 节点之中不可以有重复的主机名、MAC 地址或 product_uuid。请参见这里了解更多详细信息。
  • 开启机器上的某些端口。请参见这里了解更多详细信息。
  • 交换分区的配置。kubelet 的默认行为是在节点上检测到交换内存时无法启动。 更多细节参阅交换内存管理。
    • 如果 kubelet 未被正确配置使用交换分区，则你必须禁用交换分区。 例如，sudo swapoff -a 将暂时禁用交换分区。要使此更改在重启后保持不变，请确保在如 /etc/fstab、systemd.swap 等配置文件中禁用交换分区，具体取决于你的系统如何配置。

检查你的操作系统版本

  • kubeadm 项目支持 LTS 内核。参阅 LTS 内核列表。
  • 你可以使用命令 uname -r 获取内核版本。

欲了解更多信息，参阅 Linux 内核要求。

  • kubeadm 项目支持最近的内核版本。有关最新内核的列表，参阅 Windows Server 版本信息。
  • 你可以使用命令 systeminfo 获取内核版本（也称为操作系统版本）。

欲了解更多信息，参阅 Windows 操作系统版本兼容性。

由 kubeadm 创建的 Kubernetes 集群依赖于使用内核特性的相关软件。
这些软件包括但不限于容器运行时、
kubelet 和容器网络接口（CNI）插件。

为帮助你避免因内核版本不受支持而引发的意外错误，kubeadm 运行 SystemVerification 执行预检。
如果内核版本不受支持，预检将失败。

如果你确认你的内核具备所需特性，尽管其版本不在 kubeadm 支持范围内，你也可以选择跳过此检查。

确保每个节点上 MAC 地址和 product_uuid 的唯一性

  • 你可以使用命令 ip link 或 ifconfig -a 来获取网络接口的 MAC 地址
  • 可以使用 sudo cat /sys/class/dmi/id/product_uuid 命令对 product_uuid 校验

一般来讲，硬件设备会拥有唯一的地址，但是有些虚拟机的地址可能会重复。 Kubernetes 使用这些值来唯一确定集群中的节点。 如果这些值在每个节点上不唯一，可能会导致安装失败。

检查网络适配器

如果你有一个以上的网络适配器，同时你的 Kubernetes 组件通过默认路由不可达，我们建议你预先添加 IP 路由规则， 这样 Kubernetes 集群就可以通过对应的适配器完成连接。

检查所需端口

启用这些必要的端口后才能使 Kubernetes 的各组件相互通信。 可以使用 netcat 之类的工具来检查端口是否开放，例如：

nc 127.0.0.1 6443 -zv -w 2

你使用的 Pod 网络插件 (详见后续章节) 也可能需要开启某些特定端口。 由于各个 Pod 网络插件的功能都有所不同，请参阅他们各自文档中对端口的要求。

交换分区的配置

kubelet 的默认行为是在节点上检测到交换内存时无法启动。 这意味着要么禁用交换（swap）功能，要么让 kubelet 容忍交换。

  • 若需允许交换分区（swap），请在 kubelet 配置文件中添加 failSwapOn: false，或通过命令行参数指定。 注意：即使设置了 failSwapOn: false，工作负载默认情况下仍无法访问交换空间。 可以通过在 kubelet 配置文件中设置 swapBehavior 来修改此设置。若要使用交换空间， 请设置 swapBehavior 的值，这个值不能是默认的 NoSwap。 更多细节参阅交换内存管理。
  • 要禁用交换分区（swap），可以使用命令 sudo swapoff -a 暂时关闭交换分区功能。 要使此更改在重启后仍然生效，请确保在系统的配置文件（如 /etc/fstab 或 systemd.swap）中禁用交换功能， 具体取决于你的系统配置方式。

安装容器运行时

为了在 Pod 中运行容器，Kubernetes 使用容器运行时（Container Runtime）。

默认情况下，Kubernetes 使用容器运行时接口（Container Runtime Interface，CRI） 来与你所选择的容器运行时交互。

如果你不指定运行时，kubeadm 会自动尝试通过扫描已知的端点列表来检测已安装的容器运行时。

如果检测到有多个或者没有容器运行时，kubeadm 将抛出一个错误并要求你指定一个想要使用的运行时。

参阅容器运行时以了解更多信息。

下面的表格包括被支持的操作系统的已知端点。

Linux 容器运行时
运行时 Unix 域套接字
containerd unix:///var/run/containerd/containerd.sock
CRI-O unix:///var/run/crio/crio.sock
Docker Engine（使用 cri-dockerd） unix:///var/run/cri-dockerd.sock

Windows 容器运行时
运行时 Windows 命名管道路径
containerd npipe:////./pipe/containerd-containerd
Docker Engine（使用 cri-dockerd） npipe:////./pipe/cri-dockerd

安装 kubeadm、kubelet 和 kubectl

你需要在每台机器上安装以下的软件包：

  • kubeadm：用来初始化集群的指令。

  • kubelet：在集群中的每个节点上用来启动 Pod 和容器等。

  • kubectl：用来与集群通信的命令行工具。

kubeadm 不能帮你安装或者管理 kubelet 或 kubectl， 所以你需要确保它们与通过 kubeadm 安装的控制平面的版本相匹配。 如果不这样做，则存在发生版本偏差的风险，可能会导致一些预料之外的错误和问题。 然而，控制平面与 kubelet 之间可以存在一个次要版本的偏差，但 kubelet 的版本不可以超过 API 服务器的版本。 例如，1.7.0 版本的 kubelet 可以完全兼容 1.8.0 版本的 API 服务器，反之则不可以。

有关安装 kubectl 的信息，请参阅安装和设置 kubectl 文档。

关于版本偏差的更多信息，请参阅以下文档：

以下指令适用于 Kubernetes 1.32.

  1. 更新 apt 包索引并安装使用 Kubernetes apt 仓库所需要的包：

    sudo apt-get update
# apt-transport-https 可能是一个虚拟包（dummy package）；如果是的话，你可以跳过安装这个包
sudo apt-get install -y apt-transport-https ca-certificates curl gpg

  1. 下载用于 Kubernetes 软件包仓库的公共签名密钥。所有仓库都使用相同的签名密钥，因此你可以忽略URL中的版本：

    # 如果 `/etc/apt/keyrings` 目录不存在，则应在 curl 命令之前创建它，请阅读下面的注释。
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.32/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

  1. 添加 Kubernetes apt 仓库。 请注意，此仓库仅包含适用于 Kubernetes 1.32 的软件包； 对于其他 Kubernetes 次要版本，则需要更改 URL 中的 Kubernetes 次要版本以匹配你所需的次要版本 （你还应该检查正在阅读的安装文档是否为你计划安装的 Kubernetes 版本的文档）。

    # 此操作会覆盖 /etc/apt/sources.list.d/kubernetes.list 中现存的所有配置。
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

  1. 更新 apt 包索引，安装 kubelet、kubeadm 和 kubectl，并锁定其版本：

    sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

  1. 将 SELinux 设置为 permissive 模式：

    以下指令适用于 Kubernetes 1.32。

    # 将 SELinux 设置为 permissive 模式（相当于将其禁用）
sudo setenforce 0
sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config

  1. 添加 Kubernetes 的 yum 仓库。在仓库定义中的 exclude 参数确保了与 Kubernetes 相关的软件包在运行 yum update 时不会升级，因为升级 Kubernetes 需要遵循特定的过程。请注意，此仓库仅包含适用于 Kubernetes 1.32 的软件包； 对于其他 Kubernetes 次要版本，则需要更改 URL 中的 Kubernetes 次要版本以匹配你所需的次要版本 （你还应该检查正在阅读的安装文档是否为你计划安装的 Kubernetes 版本的文档）。

    # 此操作会覆盖 /etc/yum.repos.d/kubernetes.repo 中现存的所有配置
cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.32/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.32/rpm/repodata/repomd.xml.key
exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
EOF

  1. 安装 kubelet、kubeadm 和 kubectl，并启用 kubelet 以确保它在启动时自动启动:

    sudo yum install -y kubelet kubeadm kubectl --disableexcludes=kubernetes
sudo systemctl enable --now kubelet

安装 CNI 插件（大多数 Pod 网络都需要）：

CNI_PLUGINS_VERSION="v1.3.0"
ARCH="amd64"
DEST="/opt/cni/bin"
sudo mkdir -p "$DEST"
curl -L "https://github.com/containernetworking/plugins/releases/download/${CNI_PLUGINS_VERSION}/cni-plugins-linux-${ARCH}-${CNI_PLUGINS_VERSION}.tgz" | sudo tar -C "$DEST" -xz

定义要下载命令文件的目录：

DOWNLOAD_DIR="/usr/local/bin"
sudo mkdir -p "$DOWNLOAD_DIR"

可以选择安装 crictl（与容器运行时接口 (CRI) 交互时必需，但对 kubeadm 来说是可选的）：

CRICTL_VERSION="v1.31.0"
ARCH="amd64"
curl -L "https://github.com/kubernetes-sigs/cri-tools/releases/download/${CRICTL_VERSION}/crictl-${CRICTL_VERSION}-linux-${ARCH}.tar.gz" | sudo tar -C $DOWNLOAD_DIR -xz

安装 kubeadm、kubelet、kubectl 并添加 kubelet 系统服务：

RELEASE="$(curl -sSL https://dl.k8s.io/release/stable.txt)"
ARCH="amd64"
cd $DOWNLOAD_DIR
sudo curl -L --remote-name-all https://dl.k8s.io/release/${RELEASE}/bin/linux/${ARCH}/{kubeadm,kubelet}
sudo chmod +x {kubeadm,kubelet}

RELEASE_VERSION="v0.16.2"
curl -sSL "https://raw.githubusercontent.com/kubernetes/release/${RELEASE_VERSION}/cmd/krel/templates/latest/kubelet/kubelet.service" | sed "s:/usr/bin:${DOWNLOAD_DIR}:g" | sudo tee /usr/lib/systemd/system/kubelet.service
sudo mkdir -p /usr/lib/systemd/system/kubelet.service.d
curl -sSL "https://raw.githubusercontent.com/kubernetes/release/${RELEASE_VERSION}/cmd/krel/templates/latest/kubeadm/10-kubeadm.conf" | sed "s:/usr/bin:${DOWNLOAD_DIR}:g" | sudo tee /usr/lib/systemd/system/kubelet.service.d/10-kubeadm.conf

请参照安装工具页面的说明安装 kubelet。 激活并启动 kubelet：

systemctl enable --now kubelet

kubelet 现在每隔几秒就会重启，因为它陷入了一个等待 kubeadm 指令的死循环。

配置 cgroup 驱动程序

容器运行时和 kubelet 都具有名字为 "cgroup driver" 的属性，该属性对于在 Linux 机器上管理 CGroups 而言非常重要。

故障排查

如果你在使用 kubeadm 时遇到困难， 请参阅我们的故障排查文档。

接下来

本页面中的条目引用了第三方产品或项目，这些产品（项目）提供了 Kubernetes 所需的功能。Kubernetes 项目的开发人员不对这些第三方产品（项目）负责。请参阅CNCF 网站指南了解更多细节。

在提交更改建议，向本页添加新的第三方链接之前，你应该先阅读内容指南。

最后修改 April 16, 2025 at 4:10 PM PST: [zh] Update kubeadm/install-kubeadm.md (8366f69a45)