使用 kubeadm 创建集群

使用 kubeadm，你可以创建一个符合最佳实践的最小可行 Kubernetes 集群。 事实上，你可以使用 kubeadm 设置一个能够通过Kubernetes 一致性测试的集群。 kubeadm 还支持其他集群生命周期功能，例如引导令牌和集群升级。

如果你需要以下功能，则 kubeadm 工具非常适合

  • 一种让你第一次尝试 Kubernetes 的简单方法。
  • 一种让现有用户自动化设置集群并测试其应用程序的方法。
  • 在其他生态系统和/或具有更大范围的安装工具中的构建模块。

你可以在各种机器上安装和使用 kubeadm：你的笔记本电脑、一组云服务器、Raspberry Pi 等。 无论你是在云端还是在本地部署，都可以将 kubeadm 集成到诸如 Ansible 或 Terraform 之类的配置系统中。

开始之前

要遵循本指南，你需要

  • 一台或多台运行 deb/rpm 兼容 Linux 操作系统的计算机；例如：Ubuntu 或 CentOS。
  • 每台机器 2 GiB 或更多的 RAM - 任何更小的 RAM 都会为你的应用程序留下很少的空间。
  • 你在用作控制平面节点的机器上至少 2 个 CPU。
  • 集群中所有机器之间的完全网络连接。 你可以使用公共或专用网络。

你还需要使用一个 kubeadm 版本，该版本可以部署你想要在新集群中使用的 Kubernetes 版本。

Kubernetes 的版本和版本偏差支持策略也适用于 kubeadm 和整个 Kubernetes。 请查看该策略以了解支持哪些版本的 Kubernetes 和 kubeadm。 此页面是为 Kubernetes v1.32 编写的。

kubeadm 工具的总体功能状态为正式发布 (GA)。 一些子功能仍在积极开发中。 随着工具的发展，创建集群的实现可能会略有变化，但总体实现应该是相当稳定的。

目标

  • 安装一个单控制平面的 Kubernetes 集群
  • 在集群上安装 Pod 网络，以便你的 Pod 可以相互通信

说明

准备主机

组件安装

在所有主机上安装容器运行时和 kubeadm。 有关详细说明和其他先决条件，请参阅安装 kubeadm。

网络设置

kubeadm 与其他 Kubernetes 组件类似，尝试在与主机上默认网关关联的网络接口上查找可用的 IP。 然后，此 IP 用于组件执行的通告和/或侦听。

要查找 Linux 主机上的此 IP，可以使用

ip route show # Look for a line starting with "default via"

Kubernetes 组件不接受自定义网络接口作为选项，因此必须将自定义 IP 地址作为标志传递给所有需要此类自定义配置的组件实例。

要为使用 init 和 join 创建的控制平面节点配置 API 服务器通告地址，可以使用标志 --apiserver-advertise-address。 最好，可以在kubeadm API中将此选项设置为 InitConfiguration.localAPIEndpoint 和 JoinConfiguration.controlPlane.localAPIEndpoint。

对于所有节点上的 kubelet，可以在 kubeadm 配置文件（InitConfiguration 或 JoinConfiguration）内的 .nodeRegistration.kubeletExtraArgs 中传递 --node-ip 选项。

有关双栈，请参阅使用 kubeadm 的双栈支持。

你分配给控制平面组件的 IP 地址将成为其 X.509 证书的主题备用名称字段的一部分。 更改这些 IP 地址将需要签署新证书并重新启动受影响的组件，以便反映证书文件的更改。 有关此主题的更多详细信息，请参阅手动证书续订。

准备所需的容器镜像

此步骤是可选的，仅在你希望 kubeadm init 和 kubeadm join 不下载托管在 registry.k8s.io 上的默认容器镜像的情况下适用。

当在没有互联网连接的节点上创建集群时，Kubeadm 具有可以帮助你预先提取所需镜像的命令。 有关更多详细信息，请参阅在没有互联网连接的情况下运行 kubeadm。

Kubeadm 允许你为所需的镜像使用自定义镜像存储库。 有关更多详细信息，请参阅使用自定义镜像。

初始化你的控制平面节点

控制平面节点是控制平面组件运行的机器，包括 etcd（集群数据库）和API 服务器（kubectl 命令行工具与此通信）。

  1. （推荐）如果你计划将此单控制平面 kubeadm 集群升级到高可用性，则应指定 --control-plane-endpoint 来设置所有控制平面节点的共享端点。 此类端点可以是 DNS 名称或负载均衡器的 IP 地址。
  2. 选择一个 Pod 网络插件，并验证它是否需要将任何参数传递给 kubeadm init。 根据你选择的第三方提供商，你可能需要将 --pod-network-cidr 设置为提供商特定的值。 请参阅安装 Pod 网络插件。
  3. （可选）kubeadm 尝试使用一系列众所周知的端点来检测容器运行时。要使用不同的容器运行时，或者在已配置的节点上安装了多个容器运行时，请为 kubeadm 指定 --cri-socket 参数。请参阅安装运行时。

要初始化控制平面节点，请运行

kubeadm init <args>

关于 apiserver-advertise-address 和 ControlPlaneEndpoint 的注意事项

虽然 --apiserver-advertise-address 可用于设置此特定控制平面节点的 API 服务器的通告地址，但 --control-plane-endpoint 可用于设置所有控制平面节点的共享端点。

--control-plane-endpoint 允许使用可以映射到 IP 地址的 IP 地址和 DNS 名称。请联系你的网络管理员，评估有关此类映射的可能解决方案。

以下是一个映射示例

192.168.0.102 cluster-endpoint

其中 192.168.0.102 是此节点的 IP 地址，cluster-endpoint 是映射到此 IP 的自定义 DNS 名称。这将允许你将 --control-plane-endpoint=cluster-endpoint 传递给 kubeadm init，并将相同的 DNS 名称传递给 kubeadm join。稍后，你可以修改 cluster-endpoint 以指向高可用性场景中负载均衡器的地址。

kubeadm 不支持将未使用 --control-plane-endpoint 创建的单控制平面集群转换为高可用集群。

更多信息

有关 kubeadm init 参数的更多信息，请参阅 kubeadm 参考指南。

要使用配置文件配置 kubeadm init，请参阅使用配置文件初始化 kubeadm。

要自定义控制平面组件，包括为控制平面组件和 etcd 服务器的可选 IPv6 活性探测分配，请按照自定义参数中的说明为每个组件提供额外的参数。

要重新配置已创建的集群，请参阅重新配置 kubeadm 集群。

要再次运行 kubeadm init，必须首先拆除集群。

如果将具有不同架构的节点加入集群，请确保已部署的 DaemonSet 具有对此架构的容器镜像支持。

kubeadm init 首先运行一系列预检，以确保机器已准备好运行 Kubernetes。这些预检会显示警告并在发生错误时退出。然后，kubeadm init 下载并安装集群控制平面组件。这可能需要几分钟。完成后，你应该看到

Your Kubernetes control-plane has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

You should now deploy a Pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
  /docs/concepts/cluster-administration/addons/

You can now join any number of machines by running the following on each node
as root:

  kubeadm join <control-plane-host>:<control-plane-port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>

要使 kubectl 为非 root 用户工作，请运行这些命令，这些命令也是 kubeadm init 输出的一部分

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

或者，如果你是 root 用户，则可以运行

export KUBECONFIG=/etc/kubernetes/admin.conf

记录 kubeadm init 输出的 kubeadm join 命令。你需要此命令来将节点加入到你的集群。

令牌用于控制平面节点和加入节点之间的相互身份验证。此处包含的令牌是秘密的。请妥善保管，因为任何拥有此令牌的人都可以将经过身份验证的节点添加到你的集群。可以使用 kubeadm token 命令列出、创建和删除这些令牌。请参阅 kubeadm 参考指南。

安装 Pod 网络附加组件

一些外部项目使用 CNI 提供 Kubernetes Pod 网络，其中一些还支持 网络策略。

请参阅实现 Kubernetes 网络模型的附加组件列表。

有关 Kubernetes 支持的非详尽的网络附加组件列表，请参阅安装附加组件页面。你可以在控制平面节点或具有 kubeconfig 凭据的节点上使用以下命令安装 Pod 网络附加组件

kubectl apply -f <add-on.yaml>

每个集群只能安装一个 Pod 网络。

安装 Pod 网络后，你可以通过检查 CoreDNS Pod 是否在 kubectl get pods --all-namespaces 的输出中为 Running 来确认它是否正常工作。一旦 CoreDNS Pod 启动并运行，你可以继续加入你的节点。

如果你的网络无法工作或 CoreDNS 未处于 Running 状态，请查看 kubeadm 的故障排除指南。

托管节点标签

默认情况下，kubeadm 启用 NodeRestriction 准入控制器，该控制器限制 kubelet 在节点注册时可以自行应用的标签。准入控制器文档涵盖了允许与 kubelet --node-labels 选项一起使用的标签。node-role.kubernetes.io/control-plane 标签是一个受限制的标签，kubeadm 在创建节点后使用特权客户端手动应用它。要手动执行此操作，你可以使用 kubectl label 并确保它使用特权 kubeconfig，例如 kubeadm 管理的 /etc/kubernetes/admin.conf。

控制平面节点隔离

默认情况下，出于安全原因，你的集群不会在控制平面节点上调度 Pod。如果你希望能够在控制平面节点上调度 Pod，例如对于单机 Kubernetes 集群，请运行

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

输出将类似于

node "test-01" untainted
...

这将从任何具有 node-role.kubernetes.io/control-plane:NoSchedule 污点的节点（包括控制平面节点）中删除该污点，这意味着调度程序将能够调度任何地方的 Pod。

此外，你可以执行以下命令从控制平面节点中删除 node.kubernetes.io/exclude-from-external-load-balancers 标签，该标签将其从后端服务器列表中排除。

kubectl label nodes --all node.kubernetes.io/exclude-from-external-load-balancers-

添加更多控制平面节点

有关通过添加更多控制平面节点来创建高可用性 kubeadm 集群的步骤，请参阅使用 kubeadm 创建高可用性集群。

添加工作节点

工作节点是你的工作负载运行的地方。

以下页面展示了如何使用 kubeadm join 命令将 Linux 和 Windows 工作节点添加到集群

（可选）从控制平面节点以外的机器控制你的集群

为了让其他计算机（例如笔记本电脑）上的 kubectl 与你的集群通信，你需要将管理员 kubeconfig 文件从你的控制平面节点复制到你的工作站，如下所示

scp root@<control-plane-host>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf get nodes

（可选）将 API 服务器代理到 localhost

如果您想从集群外部连接到 API 服务器，可以使用 kubectl proxy

scp root@<control-plane-host>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf proxy

现在您可以通过 https://127.0.0.1:8001/api/v1 在本地访问 API 服务器

清理

如果您使用一次性服务器进行集群测试，可以将其关闭，无需进行进一步清理。您可以使用 kubectl config delete-cluster 删除本地对集群的引用。

但是，如果您想更彻底地取消配置集群，应首先排空节点，确保节点为空，然后再取消配置节点。

移除节点

使用适当的凭据与控制平面节点通信，运行

kubectl drain <node name> --delete-emptydir-data --force --ignore-daemonsets

在移除节点之前，重置 kubeadm 安装的状态

kubeadm reset

重置过程不会重置或清理 iptables 规则或 IPVS 表。如果要重置 iptables，必须手动执行

iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X

如果要重置 IPVS 表，必须运行以下命令

ipvsadm -C

现在移除节点

kubectl delete node <node name>

如果您想重新开始，请使用适当的参数运行 kubeadm init 或 kubeadm join。

清理控制平面

您可以在控制平面主机上使用 kubeadm reset 来触发尽力而为的清理。

有关此子命令及其选项的更多信息，请参阅kubeadm reset参考文档。

版本偏差策略

虽然 kubeadm 允许与其管理的某些组件存在版本偏差，但建议您将 kubeadm 版本与控制平面组件、kube-proxy 和 kubelet 的版本匹配。

kubeadm 与 Kubernetes 版本的偏差

kubeadm 可以与 Kubernetes 组件一起使用，这些组件的版本与 kubeadm 版本相同或旧一个版本。可以通过使用 kubeadm init 的 --kubernetes-version 标志或在使用 --config 时的 ClusterConfiguration.kubernetesVersion 字段向 kubeadm 指定 Kubernetes 版本。此选项将控制 kube-apiserver、kube-controller-manager、kube-scheduler 和 kube-proxy 的版本。

示例

  • kubeadm 版本为 1.32
  • kubernetesVersion 必须为 1.32 或 1.31

kubeadm 与 kubelet 的偏差

与 Kubernetes 版本类似，kubeadm 可以与 kubelet 版本一起使用，该版本与 kubeadm 版本相同或旧三个版本。

示例

  • kubeadm 版本为 1.32
  • 主机上的 kubelet 必须为 1.32、1.31、1.30 或 1.29

kubeadm 与 kubeadm 的偏差

kubeadm 命令在现有节点或由 kubeadm 管理的整个集群上运行时存在某些限制。

如果新节点加入集群，用于 kubeadm join 的 kubeadm 二进制文件必须与最后一次用于通过 kubeadm init 创建集群或通过 kubeadm upgrade 升级同一节点的 kubeadm 版本匹配。类似的规则也适用于其余的 kubeadm 命令，但 kubeadm upgrade 除外。

kubeadm join 的示例

  • kubeadm 版本 1.32 用于通过 kubeadm init 创建集群
  • 加入节点的 kubeadm 二进制文件必须是 1.32 版本

正在升级的节点必须使用与用于管理节点的 kubeadm 版本相同的小版本或更新一个小版本的 kubeadm 版本。

kubeadm upgrade 的示例

  • kubeadm 版本 1.31 用于创建或升级节点
  • 用于升级节点的 kubeadm 版本必须为 1.31 或 1.32

要了解有关不同 Kubernetes 组件之间版本偏差的更多信息，请参阅版本偏差策略。

局限性

集群弹性

此处创建的集群具有单个控制平面节点，其中在其上运行单个 etcd 数据库。这意味着，如果控制平面节点发生故障，您的集群可能会丢失数据，并且可能需要从头开始重新创建。

解决方法

平台兼容性

kubeadm deb/rpm 包和二进制文件是根据多平台提案为 amd64、arm (32 位)、arm64、ppc64le 和 s390x 构建的。

自 v1.12 起也支持控制平面和插件的多平台容器镜像。

只有一些网络提供商为所有平台提供解决方案。请查阅上面的网络提供商列表或每个提供商的文档，以确定该提供商是否支持您选择的平台。

故障排除

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

下一步

  • 使用 Sonobuoy 验证您的集群是否正常运行
  • 查看升级 kubeadm 集群，了解有关使用 kubeadm 升级集群的详细信息。
  • 在kubeadm 参考文档中了解有关高级 kubeadm 用法的更多信息
  • 了解有关 Kubernetes 概念和 kubectl 的更多信息。
  • 有关 Pod 网络插件的更长列表，请参阅集群网络页面。
  • 请参阅插件列表，以探索其他插件，包括用于日志记录、监控、网络策略、可视化和控制 Kubernetes 集群的工具。
  • 配置您的集群如何处理集群事件以及 Pod 中运行的应用程序的日志。有关涉及内容的概述，请参阅日志记录架构。

反馈

上次修改时间：2024 年 10 月 16 日，太平洋标准时间上午 9:28：调整和清理四个 kubeadm 文件 (67c5917e32)