使用 kubeadm 创建集群

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

如果您需要以下内容，kubeadm 工具非常有用

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

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

开始之前

要遵循本指南，您需要

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

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

Kubernetes 的版本和版本偏差支持策略 适用于 kubeadm 以及 Kubernetes 本身。查看该策略以了解支持哪些版本的 Kubernetes 和 kubeadm。本页针对 Kubernetes v1.30 编写。

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

目标

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

说明

准备主机

组件安装

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

网络设置

kubeadm 与其他 Kubernetes 组件类似，尝试在与主机上的默认网关关联的网络接口上找到一个可用的 IP。然后，该 IP 将用于组件执行的广告和/或监听。

要找出此 IP 在 Linux 主机上的位置，您可以使用

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 以指向高可用性场景中负载均衡器的地址。

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 网络后，您可以通过检查 kubectl get pods --all-namespaces 输出中的 CoreDNS Pod 是否为 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-

加入您的节点

节点是您的工作负载（容器和 Pod 等）运行的地方。要将新节点添加到您的集群，请对每台机器执行以下操作

  • SSH 到该机器

  • 成为 root（例如 sudo su -）

  • 安装运行时（如果需要）

  • 运行 kubeadm init 输出的命令。例如

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

如果您没有令牌，可以通过在控制平面节点上运行以下命令获取它

kubeadm token list

输出类似于

TOKEN                    TTL  EXPIRES              USAGES           DESCRIPTION            EXTRA GROUPS
8ewj1p.9r9hcjoqgajrj4gi  23h  2018-06-12T02:51:28Z authentication,  The default bootstrap  system:
                                                   signing          token generated by     bootstrappers:
                                                                    'kubeadm init'.        kubeadm:
                                                                                           default-node-token

默认情况下，令牌在 24 小时后过期。如果您在当前令牌过期后将节点加入到集群，可以通过在控制平面节点上运行以下命令创建新令牌

kubeadm token create

输出类似于

5didvk.d09sbcov8ph2amjw

如果您没有 --discovery-token-ca-cert-hash 的值，可以通过在控制平面节点上运行以下命令链获取它

openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | \
   openssl dgst -sha256 -hex | sed 's/^.* //'

输出类似于

8cb2de97839780a412b93877f8507ad6c94f73add17d5d7058e91741c9d5ec78

输出应该类似于

[preflight] Running pre-flight checks

... (log output of join workflow) ...

Node join complete:
* Certificate signing request sent to control-plane and response
  received.
* Kubelet informed of new secure connection details.

Run 'kubectl get nodes' on control-plane to see this machine join.

几秒钟后，您应该在控制平面节点上运行 kubectl get nodes 的输出中注意到此节点。

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

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

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

（可选）将 API 服务器代理到本地主机

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

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

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

示例

  • kubeadm 版本为 1.30
  • kubernetesVersion 必须为 1.30 或 1.29

kubeadm 与 kubelet 的偏差

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

示例

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

kubeadm 与 kubeadm 的偏差

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

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

kubeadm join 的示例

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

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

kubeadm upgrade 的示例

  • 使用 kubeadm 版本 1.29 创建或升级了节点
  • 用于升级节点的 kubeadm 版本必须为 1.29 或 1.30

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

限制

集群弹性

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

解决方法

平台兼容性

kubeadm deb/rpm 软件包和二进制文件是针对 amd64、arm（32 位）、arm64、ppc64le 和 s390x 构建的，遵循 多平台提案。

自 v1.12 起，还支持用于控制平面和附加组件的多平台容器镜像。

并非所有平台都提供网络提供商的解决方案。请咨询上面的网络提供商列表或每个提供商的文档，以确定提供商是否支持您选择的平台。

故障排除

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

下一步

反馈

上次修改时间：2024 年 2 月 16 日下午 12:25 PST：修复 Kubeadm 的 Kubelet 偏差版本 (#44815) (a172e82830)