使用 kubeadm 创建集群

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

如果需要，kubeadm 工具非常适合

  • 以简单的方式试用 Kubernetes，可能还是第一次。
  • 现有用户自动化设置集群并测试其应用程序的方式。
  • 其他生态系统和/或安装程序工具中的构建块，这些工具具有更大的范围。

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

开始之前

要遵循本指南，您需要

  • 一台或多台运行 deb/rpm 兼容 Linux 操作系统的机器；例如：Ubuntu 或 CentOS。
  • 每台机器至少 2 GiB 的 RAM--更少的话，您的应用程序将没有足够的空间。
  • 用作控制平面节点的机器上至少有 2 个 CPU。
  • 集群中所有机器之间的完全网络连接。您可以使用公共网络或专用网络。

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

Kubernetes 的版本和版本偏差支持策略 也适用于 kubeadm 以及 Kubernetes 本身。请检查该策略，以了解 Kubernetes 和 kubeadm 的哪些版本受支持。本页内容适用于 Kubernetes v1.35。

kubeadm 工具的整体特性状态为通用可用 (GA)。某些子特性仍在积极开发中。随着工具的不断发展，创建集群的实现可能会略有变化，但整体实现应该相当稳定。

目标

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

说明

准备主机

组件安装

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

网络设置

与 Kubernetes 的其他组件类似，kubeadm 尝试在与默认网关关联的网络接口上找到可用的 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 尝试使用已知端点列表检测容器运行时。要使用不同的容器运行时或如果已在配置的节点上安装了多个容器运行时，请将 --cri-socket 参数传递给 kubeadm。请参阅 安装运行时。

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

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 是一个自定义 DNS 名称，该名称映射到此 IP。这将允许您将 --control-plane-endpoint=cluster-endpoint 传递给 kubeadm init 并将相同的 DNS 名称传递给 kubeadm join。稍后，您可以修改 cluster-endpoint 以指向高可用性场景中的负载均衡器的地址。

使用 --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 taint，这意味着调度器将能够调度所有位置的 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://: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 组件一起使用。可以通过 --kubernetes-version 标志（用于 kubeadm init）或使用 --config 时 ClusterConfiguration.kubernetesVersion 字段来将 Kubernetes 版本指定给 kubeadm。此选项将控制 kube-apiserver、kube-controller-manager、kube-scheduler 和 kube-proxy 的版本。

示例

  • kubeadm 的版本是 1.35
  • kubernetesVersion 必须是 1.35 或 1.34

kubeadm 与 kubelet 的版本差异

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

示例

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

kubeadm 与 kubeadm 的版本差异

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

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

kubeadm join 的示例

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

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

kubeadm upgrade 的示例

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

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

限制

集群弹性

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

解决方法

  • 定期 备份 etcd。kubeadm 配置的 etcd 数据目录位于控制平面节点上的 /var/lib/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 PST：调整和清理四个 kubeadm 文件 (67c5917e32)