使用 kubeadm 创建集群

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

kubeadm 工具很棒，如果你需要：

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

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

在开始之前

要遵循本指南，你需要：

• 一台或多台运行兼容 deb/rpm 的 Linux 操作系统的计算机；例如：Ubuntu 或 CentOS。
• 每台机器 2 GB 以上的内存，内存不足时应用会受限制。
• 用作控制平面节点的计算机上至少有2个 CPU。
• 集群中所有计算机之间具有完全的网络连接。你可以使用公共网络或专用网络。

你还需要使用可以在新集群中部署特定 Kubernetes 版本对应的 ​kubeadm​。

Kubernetes 版本及版本偏差策略适用于 ​kubeadm ​以及整个 Kubernetes。 查阅该策略以了解支持哪些版本的 Kubernetes 和 ​kubeadm​。 该页面是为 Kubernetes v1.24 编写的。

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

Note: 根据定义，在 ​kubeadm alpha​ 下的所有命令均在 alpha 级别上受支持。

目标

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

操作指南

主机准备

在所有主机上安装 容器运行时 和 kubeadm。

Note:
如果你已经安装了kubeadm，执行 ​apt-get update && apt-get upgrade​ 或 ​yum update​ 以获取 kubeadm 的最新版本。
升级时，kubelet 每隔几秒钟重新启动一次， 在 crashloop 状态中等待 kubeadm 发布指令。crashloop 状态是正常现象。 初始化控制平面后，kubelet 将正常运行。

准备所需的容器镜像 

这个步骤是可选的，只适用于你希望 ​kubeadm init​ 和 ​kubeadm join​ 不去下载存放在 ​k8s.gcr.io​ 上的默认的容器镜像的情况。

当你在离线的节点上创建一个集群的时候，Kubeadm 有一些命令可以帮助你预拉取所需的镜像。

Kubeadm 允许你给所需要的镜像指定一个自定义的镜像仓库。

初始化控制平面节点

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

1. （推荐）如果计划将单个控制平面 kubeadm 集群升级成高可用， 你应该指定 ​--control-plane-endpoint​ 为所有控制平面节点设置共享端点。 端点可以是负载均衡器的 DNS 名称或 IP 地址。
2. 选择一个 Pod 网络插件，并验证是否需要为 ​kubeadm init​ 传递参数。 根据你选择的第三方网络插件，你可能需要设置 ​--pod-network-cidr​ 的值。 
3. （可选）​kubeadm ​试图通过使用已知的端点列表来检测容器运行时。 使用不同的容器运行时或在预配置的节点上安装了多个容器运行时，请为 ​kubeadm init​ 指定 ​--cri-socket​ 参数。
4. （可选）除非另有说明，否则 ​kubeadm ​使用与默认网关关联的网络接口来设置此控制平面节点 API server 的广播地址。 要使用其他网络接口，请为 ​kubeadm init​ 设置 ​--apiserver-advertise-address=<ip-address>​ 参数。 要部署使用 IPv6 地址的 Kubernetes 集群， 必须指定一个 IPv6 地址，例如 ​--apiserver-advertise-address=fd00::101​

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

kubeadm init <args>

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

​--apiserver-advertise-address​ 可用于为控制平面节点的 API server 设置广播地址， ​--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​，你必须首先卸载集群。

如果将具有不同架构的节点加入集群， 请确保已部署的 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>

要使非 root 用户可以运行 kubectl，请运行以下命令， 它们也是 ​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

Warning:
kubeadm 对 ​admin.conf​ 中的证书进行签名时，将其配置为 ​Subject: O = system:masters, CN = kubernetes-admin​。 ​system:masters​ 是一个例外的、超级用户组，可以绕过鉴权层（例如 RBAC）。 不要将 ​admin.conf​ 文件与任何人共享，应该使用 ​kubeadm kubeconfig user​ 命令为其他用户生成 kubeconfig 文件，完成对他们的定制授权。

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

令牌用于控制平面节点和加入节点之间的相互身份验证。 这里包含的令牌是密钥。确保它的安全， 因为拥有此令牌的任何人都可以将经过身份验证的节点添加到你的集群中。 可以使用 ​kubeadm token​ 命令列出，创建和删除这些令牌。

安装 Pod 网络附加组件 

Caution:
本节包含有关网络设置和部署顺序的重要信息。 在继续之前，请仔细阅读所有建议。
你必须部署一个基于 Pod 网络插件的 容器网络接口 (CNI)，以便你的 Pod 可以相互通信。 在安装网络之前，集群 DNS (CoreDNS) 将不会启动。

• 注意你的 Pod 网络不得与任何主机网络重叠： 如果有重叠，你很可能会遇到问题。 （如果你发现网络插件的首选 Pod 网络与某些主机网络之间存在冲突， 则应考虑使用一个合适的 CIDR 块来代替， 然后在执行 ​kubeadm init​ 时使用 ​--pod-network-cidr​ 参数并在你的网络插件的 YAML 中替换它）。
• 默认情况下，​kubeadm ​将集群设置为使用和强制使用 RBAC（基于角色的访问控制）。 确保你的 Pod 网络插件支持 RBAC，以及用于部署它的 manifests 也是如此。
• 如果要为集群使用 IPv6（双协议栈或仅单协议栈 IPv6 网络）， 请确保你的 Pod 网络插件支持 IPv6。 IPv6 支持已在 CNI v0.6.0 版本中添加。

Note: kubeadm 应该是与 CNI 无关的，对 CNI 驱动进行验证目前不在我们的端到端测试范畴之内。 如果你发现与 CNI 插件相关的问题，应在其各自的问题跟踪器中记录而不是在 kubeadm 或 kubernetes 问题跟踪器中记录。

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

你可以使用以下命令在控制平面节点或具有 kubeconfig 凭据的节点上安装 Pod 网络附加组件：

kubectl apply -f <add-on.yaml>

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

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

如果你的网络无法正常工作或 CoreDNS 不在“运行中”状态，请查看 ​kubeadm ​的 故障排除指南。

托管节点标签 

默认情况下，kubeadm 启用 NodeRestriction 准入控制器来限制 kubelets 在节点注册时可以应用哪些标签。准入控制器文档描述 kubelet ​--node-labels​ 选项允许使用哪些标签。 其中 ​node-role.kubernetes.io/control-plane​ 标签就是这样一个受限制的标签， kubeadm 在节点创建后使用特权客户端手动应用此标签。 你可以使用一个有特权的 kubeconfig，比如由 kubeadm 管理的 ​/etc/kubernetes/admin.conf​， 通过执行 ​kubectl label​ 来手动完成操作。

控制平面节点隔离

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

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

输出看起来像：

node "test-01" untainted

这将从任何拥有 ​node-role.kubernetes.io/control-plane​ 和 ​node-role.kubernetes.io/master​ 污点的节点上移除该污点。

包括控制平面节点，这意味着调度程序将能够在任何地方调度 Pods。

Note: ​node-role.kubernetes.io/master​ 污点已被废弃，kubeadm 将在 1.25 版本中停止使用它。

加入节点

节点是你的工作负载（容器和 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

Note: 要为 ​<control-plane-host>:<control-plane-port>​ 指定 IPv6 元组，必须将 IPv6 地址括在方括号中，例如：​[fd00::101]:2073​

输出应类似于：

[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​，你会注意到该节点出现在输出中。

Note: 由于集群节点通常是按顺序初始化的，CoreDNS Pods 很可能都运行在第一个控制面节点上。 为了提供更高的可用性，请在加入至少一个新节点后 使用 ​kubectl -n kube-system rollout restart deployment coredns​ 命令，重新平衡 CoreDNS Pods。

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

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

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

Note:
上面的示例假定为 root 用户启用了 SSH 访问。如果不是这种情况， 你可以使用 ​scp​ 将 ​admin.conf​ 文件复制给其他允许访问的用户。
admin.conf 文件为用户提供了对集群的超级用户特权。 该文件应谨慎使用。对于普通用户，建议生成一个你为其授予特权的唯一证书。 你可以使用 ​kubeadm alpha kubeconfig user --client-name <CN>​ 命令执行此操作。 该命令会将 KubeConfig 文件打印到 STDOUT，你应该将其保存到文件并分发给用户。 之后，使用 ​kubectl create (cluster)rolebinding​ 授予特权。

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

如果要从集群外部连接到 API 服务器，则可以使用 ​kubectl proxy​：

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

你现在可以在本地访问 API 服务器 ​http://localhost:8001/api/v1​。

清理

如果你在集群中使用了一次性服务器进行测试，则可以关闭这些服务器，而无需进一步清理。你可以使用 ​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 允许所管理的组件有一定程度的版本偏差， 但是建议你将 kubeadm 的版本与控制平面组件、kube-proxy 和 kubelet 的版本相匹配。

kubeadm 中的 Kubernetes 版本偏差

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

例如：

• kubeadm 的版本为 1.24。
• ​kubernetesVersion ​必须为 1.24 或者 1.23。

kubeadm 中 kubelet 的版本偏差

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

例如：

• kubeadm 的版本为 1.24
• 主机上的 kubelet 版本必须为 1.24 或者 1.23

kubeadm 支持的 kubeadm 的版本偏差

kubeadm 命令在现有节点或由 kubeadm 管理的整个集群上的操作有一定限制。

如果新的节点加入到集群中，用于 ​kubeadm join​ 的 kubeadm 二进制文件必须与用 ​kubeadm init​ 创建集群或用 ​kubeadm upgrade​ 升级同一节点时所用的 kubeadm 版本一致。 类似的规则适用于除了 ​kubeadm upgrade​ 以外的其他 kubeadm 命令。

​kubeadm join​ 的例子：

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

对于正在升级的节点，所使用的的 kubeadm 必须与管理该节点的 kubeadm 具有相同的 MINOR 版本或比后者新一个 MINOR 版本。

​kubeadm upgrade​ 的例子:

• 用于创建或升级节点的 kubeadm 版本为 1.23。
• 用于升级节点的 kubeadm 版本必须为 1.23 或 1.24。

局限性

集群弹性

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

解决方法：

• 定期备份 etcd。 kubeadm 配置的 etcd 数据目录位于控制平面节点上的 ​/var/lib/etcd​ 中。
• 使用多个控制平面节点。你可以阅读 可选的高可用性拓扑选择集群拓扑提供的 高可用性。

平台兼容性

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

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

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

Note:要为<control-plane-host>:<control-plane-port>指定IPv6元组，必须将IPv6地址括在方括号中，例如：[fd00::101]:2073