使用 kubeadm 创建集群

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

如果你需要以下功能，kubeadm 工具会很有用

  • 一种简单的方式来尝试 Kubernetes，可能这是你第一次使用。
  • 一种现有用户自动化设置集群和测试应用程序的方式。
  • 作为其他生态系统和/或范围更广的安装工具中的构建模块。

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

准备工作

要遵循本指南，你需要

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

你还需要使用与你想要在新集群中使用的 Kubernetes 版本兼容的 kubeadm 版本。

Kubernetes 的版本和版本偏差支持策略适用于 kubeadm 和整个 Kubernetes。请查阅该策略以了解支持的 Kubernetes 和 kubeadm 版本。此页面针对 Kubernetes v1.34 编写。

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 init。

要自定义控制平面组件，包括为控制平面组件和 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 Server 代理到 localhost

如果你想从集群外部连接到 API Server，可以使用 kubectl proxy

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

你现在可以通过 https://: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 可以与与 kubeadm 版本相同或旧一个版本的 Kubernetes 组件一起使用。可以使用 kubeadm init 的 --kubernetes-version 标志或在使用 --config 时使用 ClusterConfiguration.kubernetesVersion 字段向 kubeadm 指定 Kubernetes 版本。此选项将控制 kube-apiserver、kube-controller-manager、kube-scheduler 和 kube-proxy 的版本。

示例

  • kubeadm 版本为 1.34
  • kubernetesVersion 必须是 1.34 或 1.33

kubeadm 与 kubelet 的偏差

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

示例

  • kubeadm 版本为 1.34
  • 主机上的 kubelet 必须是 1.34、1.33、1.32 或 1.31

kubeadm 之间的偏差

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

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

kubeadm join 的示例

  • kubeadm 版本 1.34 用于使用 kubeadm init 创建集群
  • 加入节点必须使用版本为 1.34 的 kubeadm 二进制文件

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

kubeadm upgrade 的示例

  • kubeadm 版本 1.33 用于创建或升级节点
  • 用于升级节点的 kubeadm 版本必须是 1.33 或 1.34

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

限制

集群弹性

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

变通方法

平台兼容性

kubeadm deb/rpm 软件包和二进制文件是为 amd64、arm (32-bit)、arm64、ppc64le 和 s390x 构建的，遵循多平台提案。

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

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

故障排除

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

下一步

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

反馈

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