安装 kubeadm
本页面介绍如何安装
kubeadm
工具包。有关在完成此安装过程后如何使用 kubeadm 创建集群的信息,请参阅使用 kubeadm 创建集群页面。
此安装指南适用于 Kubernetes v1.34。如果你想使用不同的 Kubernetes 版本,请参考以下页面:
准备工作
- 兼容的 Linux 主机。Kubernetes 项目提供了基于 Debian 和 Red Hat 的 Linux 发行版以及没有包管理器的发行版的通用说明。
- 每台机器 2 GB 或更多内存(少于 2 GB 将为应用程序留下很少的空间)。
- 控制平面机器需要 2 个或更多 CPU。
- 集群中所有机器之间完全网络连通(公共或私有网络均可)。
- 每个节点都有唯一的 hostname、MAC 地址和 product_uuid。有关更多详细信息,请参阅此处。
- 你的机器上需要打开某些端口。有关更多详细信息,请参阅此处。
注意
kubeadm
安装是通过使用动态链接的二进制文件完成的,并假定你的目标系统提供 glibc
。这在许多 Linux 发行版(包括 Debian、Ubuntu、Fedora、CentOS 等)上是合理的假设,但对于默认不包含 glibc
的自定义和轻量级发行版(如 Alpine Linux)则并非总是如此。期望发行版要么包含 glibc
,要么提供一个兼容层,提供预期的符号。检查操作系统版本
- kubeadm 项目支持 LTS 内核。请参阅LTS 内核列表。
- 你可以使用命令
uname -r
获取内核版本。
有关更多信息,请参阅Linux 内核要求。
- kubeadm 项目支持最新的内核版本。有关最新内核列表,请参阅Windows Server 发布信息。
- 你可以使用命令
systeminfo
获取内核版本(也称为操作系统版本)。
有关更多信息,请参阅Windows 操作系统版本兼容性。
kubeadm 创建的 Kubernetes 集群依赖于使用内核功能的软件。此软件包括但不限于容器运行时、kubelet 和容器网络接口插件。
为了帮助你避免因不支持的内核版本而导致的意外错误,kubeadm 运行 SystemVerification
预检检查。如果内核版本不受支持,此检查将失败。
如果你知道你的内核提供了所需的功能,即使 kubeadm 不支持其版本,你也可以选择跳过此检查。
验证每个节点的 MAC 地址和 product_uuid 是否唯一
- 你可以使用命令
ip link
或ifconfig -a
获取网络接口的 MAC 地址。 - product_uuid 可以使用命令
sudo cat /sys/class/dmi/product_uuid
检查。
硬件设备很可能有唯一的地址,尽管某些虚拟机可能具有相同的值。Kubernetes 使用这些值来唯一标识集群中的节点。如果这些值对于每个节点不唯一,则安装过程可能会失败。
检查网络适配器
如果你有多个网络适配器,并且你的 Kubernetes 组件无法在默认路由上访问,我们建议你添加 IP 路由,以便 Kubernetes 集群地址通过适当的适配器。
检查所需端口
这些所需端口需要打开,以便 Kubernetes 组件能够相互通信。你可以使用 netcat 等工具检查端口是否打开。例如:
nc 127.0.0.1 6443 -zv -w 2
你使用的 Pod 网络插件可能也需要打开某些端口。由于这因每个 Pod 网络插件而异,请参阅插件的文档以了解需要哪些端口。
Swap 配置
kubelet 的默认行为是如果节点上检测到交换内存则启动失败。这意味着交换要么被禁用,要么被 kubelet 容忍。
- 要容忍交换,请将
failSwapOn: false
添加到 kubelet 配置或作为命令行参数。注意:即使提供了failSwapOn: false
,工作负载默认也不会有交换访问权限。这可以通过在 kubelet 配置文件中设置swapBehavior
来更改。要使用交换,请设置除默认NoSwap
设置之外的swapBehavior
。有关更多详细信息,请参阅交换内存管理。 - 要禁用交换,可以使用
sudo swapoff -a
暂时禁用交换。要使此更改在重新启动后持久生效,请确保在/etc/fstab
、systemd.swap
等配置文件中禁用交换,具体取决于系统上的配置方式。
安装容器运行时
要在 Pod 中运行容器,Kubernetes 使用容器运行时。
默认情况下,Kubernetes 使用容器运行时接口 (CRI) 与你选择的容器运行时进行接口。
如果你未指定运行时,kubeadm 将自动尝试通过扫描已知端点列表来检测已安装的容器运行时。
如果检测到多个或没有容器运行时,kubeadm 将抛出错误并要求你指定要使用哪个。
有关更多信息,请参阅容器运行时。
注意
Docker Engine 没有实现 CRI,而 CRI 是容器运行时与 Kubernetes 协同工作的要求。因此,必须安装一个附加服务 cri-dockerd。cri-dockerd 是一个基于旧版内置 Docker Engine 支持的项目,该支持已在版本 1.24 中从 kubelet 中移除。下表包含受支持操作系统的已知端点。
运行时 | 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 命名管道路径 |
---|---|
containerd | npipe:////./pipe/containerd-containerd |
Docker Engine(使用 cri-dockerd) | npipe:////./pipe/cri-dockerd |
安装 kubeadm、kubelet 和 kubectl
你将在所有机器上安装这些软件包:
kubeadm
:用于引导集群的命令。kubelet
:在集群中所有机器上运行的组件,用于启动 Pod 和容器等。kubectl
:用于与集群通信的命令行工具。
kubeadm 不会为你安装或管理 kubelet
或 kubectl
,因此你需要确保它们与你希望 kubeadm 为你安装的 Kubernetes 控制平面版本匹配。如果版本不匹配,可能会出现版本偏差,从而导致意外的、有 bug 的行为。但是,kubelet 和控制平面之间支持一个次要版本偏差,但 kubelet 版本不能超过 API 服务器版本。例如,运行 1.7.0 的 kubelet 应该与 1.8.0 API 服务器完全兼容,但反之则不然。
有关安装 kubectl
的信息,请参阅安装和设置 kubectl。
警告
这些说明将所有 Kubernetes 软件包从任何系统升级中排除。这是因为 kubeadm 和 Kubernetes 需要特别注意升级。有关版本偏差的更多信息,请参阅:
apt.kubernetes.io
和 yum.kubernetes.io
)已于 2023 年 9 月 13 日起弃用并冻结。强烈建议并要求使用托管在 pkgs.k8s.io
的新软件包仓库,以便安装 2023 年 9 月 13 日之后发布的 Kubernetes 版本。 弃用的旧版仓库及其内容可能会在未来随时移除,恕不另行通知。新软件包仓库提供从 v1.24.0 开始的 Kubernetes 版本的下载。注意
每个 Kubernetes 次要版本都有一个专门的软件包仓库。如果你想安装 v1.34 以外的次要版本,请参阅你所需次要版本的安装指南。这些说明适用于 Kubernetes v1.34。
更新
apt
软件包索引并安装使用 Kubernetesapt
仓库所需的软件包。sudo apt-get update # apt-transport-https may be a dummy package; if so, you can skip that package sudo apt-get install -y apt-transport-https ca-certificates curl gpg
下载 Kubernetes 软件包仓库的公共签名密钥。所有仓库都使用相同的签名密钥,因此你可以忽略 URL 中的版本。
# If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below. # sudo mkdir -p -m 755 /etc/apt/keyrings curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.34/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
注意
在 Debian 12 和 Ubuntu 22.04 之前的版本中,目录/etc/apt/keyrings
默认不存在,应在 curl 命令之前创建。添加适当的 Kubernetes
apt
仓库。请注意,此仓库仅包含 Kubernetes 1.34 的软件包;对于其他 Kubernetes 次要版本,你需要更改 URL 中的 Kubernetes 次要版本以匹配你所需的次要版本(你还应该检查你正在阅读的文档是否是你计划安装的 Kubernetes 版本)。# This overwrites any existing configuration in /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.34/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
更新
apt
软件包索引,安装 kubelet、kubeadm 和 kubectl,并固定它们的版本。sudo apt-get update sudo apt-get install -y kubelet kubeadm kubectl sudo apt-mark hold kubelet kubeadm kubectl
(可选)在运行 kubeadm 之前启用 kubelet 服务。
sudo systemctl enable --now kubelet
将 SELinux 设置为
permissive
模式。这些说明适用于 Kubernetes 1.34。
# Set SELinux in permissive mode (effectively disabling it) sudo setenforce 0 sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config
注意
- 通过运行
setenforce 0
和sed ...
将 SELinux 设置为 permissive 模式实际上会禁用它。这是允许容器访问主机文件系统所必需的;例如,某些集群网络插件需要它。你必须这样做,直到 kubelet 中的 SELinux 支持得到改进。 - 如果你知道如何配置 SELinux,则可以保持启用状态,但这可能需要 kubeadm 不支持的设置。
添加 Kubernetes
yum
仓库。仓库定义中的exclude
参数确保在运行yum update
时不会升级与 Kubernetes 相关的软件包,因为升级 Kubernetes 必须遵循特殊的程序。请注意,此仓库仅包含 Kubernetes 1.34 的软件包;对于其他 Kubernetes 次要版本,你需要更改 URL 中的 Kubernetes 次要版本以匹配你所需的次要版本(你还应该检查你正在阅读的文档是否是你计划安装的 Kubernetes 版本)。# This overwrites any existing configuration in /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.34/rpm/ enabled=1 gpgcheck=1 gpgkey=https://pkgs.k8s.io/core:/stable:/v1.34/rpm/repodata/repomd.xml.key exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni EOF
安装 kubelet、kubeadm 和 kubectl。
sudo yum install -y kubelet kubeadm kubectl --disableexcludes=kubernetes
(可选)在运行 kubeadm 之前启用 kubelet 服务。
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
变量必须设置为可写目录。如果你正在运行 Flatcar Container Linux,请将 DOWNLOAD_DIR="/opt/bin"
。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
并添加 kubelet
systemd 服务。
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
按照安装工具页面上的说明安装 kubectl
。
(可选)在运行 kubeadm 之前启用 kubelet 服务。
sudo systemctl enable --now kubelet
注意
Flatcar Container Linux 发行版将/usr
目录挂载为只读文件系统。在引导集群之前,你需要采取额外步骤来配置一个可写目录。请参阅Kubeadm 故障排除指南,了解如何设置可写目录。kubelet 现在每隔几秒钟重启一次,因为它在崩溃循环中等待 kubeadm 告诉它该做什么。
配置 cgroup 驱动程序
容器运行时和 kubelet 都有一个名为“cgroup 驱动程序”的属性,这对于 Linux 机器上的 cgroup 管理很重要。
故障排除
如果你在使用 kubeadm 时遇到困难,请查阅我们的故障排除文档。
下一步
本页面上的项目涉及提供 Kubernetes 所需功能的第三方产品或项目。Kubernetes 项目作者不对这些第三方产品或项目负责。有关更多详细信息,请参阅CNCF 网站指南。
在提议添加额外第三方链接的更改之前,你应该阅读内容指南。