kubeadm init

此命令初始化 Kubernetes 控制平面节点。

运行此命令以设置 Kubernetes 控制平面

概要

运行此命令以设置 Kubernetes 控制平面

“init”命令执行以下阶段

preflight                     Run pre-flight checks
certs                         Certificate generation
  /ca                           Generate the self-signed Kubernetes CA to provision identities for other Kubernetes components
  /apiserver                    Generate the certificate for serving the Kubernetes API
  /apiserver-kubelet-client     Generate the certificate for the API server to connect to kubelet
  /front-proxy-ca               Generate the self-signed CA to provision identities for front proxy
  /front-proxy-client           Generate the certificate for the front proxy client
  /etcd-ca                      Generate the self-signed CA to provision identities for etcd
  /etcd-server                  Generate the certificate for serving etcd
  /etcd-peer                    Generate the certificate for etcd nodes to communicate with each other
  /etcd-healthcheck-client      Generate the certificate for liveness probes to healthcheck etcd
  /apiserver-etcd-client        Generate the certificate the apiserver uses to access etcd
  /sa                           Generate a private key for signing service account tokens along with its public key
kubeconfig                    Generate all kubeconfig files necessary to establish the control plane and the admin kubeconfig file
  /admin                        Generate a kubeconfig file for the admin to use and for kubeadm itself
  /super-admin                  Generate a kubeconfig file for the super-admin
  /kubelet                      Generate a kubeconfig file for the kubelet to use *only* for cluster bootstrapping purposes
  /controller-manager           Generate a kubeconfig file for the controller manager to use
  /scheduler                    Generate a kubeconfig file for the scheduler to use
etcd                          Generate static Pod manifest file for local etcd
  /local                        Generate the static Pod manifest file for a local, single-node local etcd instance
control-plane                 Generate all static Pod manifest files necessary to establish the control plane
  /apiserver                    Generates the kube-apiserver static Pod manifest
  /controller-manager           Generates the kube-controller-manager static Pod manifest
  /scheduler                    Generates the kube-scheduler static Pod manifest
kubelet-start                 Write kubelet settings and (re)start the kubelet
upload-config                 Upload the kubeadm and kubelet configuration to a ConfigMap
  /kubeadm                      Upload the kubeadm ClusterConfiguration to a ConfigMap
  /kubelet                      Upload the kubelet component config to a ConfigMap
upload-certs                  Upload certificates to kubeadm-certs
mark-control-plane            Mark a node as a control-plane
bootstrap-token               Generates bootstrap tokens used to join a node to a cluster
kubelet-finalize              Updates settings relevant to the kubelet after TLS bootstrap
  /enable-client-cert-rotation  Enable kubelet client certificate rotation
addon                         Install required addons for passing conformance tests
  /coredns                      Install the CoreDNS addon to a Kubernetes cluster
  /kube-proxy                   Install the kube-proxy addon to a Kubernetes cluster
show-join-command             Show the join command for control-plane and worker node

kubeadm init [flags]

选项

从父命令继承的选项

初始化工作流程

kubeadm init 通过执行以下步骤来引导 Kubernetes 控制平面节点

1. 在进行更改之前运行一系列预检检查以验证系统状态。某些检查仅触发警告，其他检查被视为错误，并将退出 kubeadm，直到问题得到纠正或用户指定 --ignore-preflight-errors=<错误列表>。

2. 生成一个自签名 CA，以便为集群中的每个组件设置身份。用户可以通过将自己的 CA 证书和/或密钥放在通过 --cert-dir 配置的证书目录中（默认情况下为 /etc/kubernetes/pki）来提供它们。API 服务器证书将为任何 --apiserver-cert-extra-sans 参数添加额外的 SAN 条目，必要时将小写。

3. 在 /etc/kubernetes/ 中为 kubelet、控制器管理器和调度器编写 kubeconfig 文件，以便连接到 API 服务器，每个文件都有自己的身份。还会编写额外的 kubeconfig 文件，用于 kubeadm 作为管理实体 (admin.conf) 和可以绕过 RBAC 的超级管理员用户 (super-admin.conf)。

4. 为 API 服务器、控制器管理器和调度器生成静态 Pod 清单。如果没有提供外部 etcd，则会为 etcd 生成一个额外的静态 Pod 清单。

   静态 Pod 清单写入 /etc/kubernetes/manifests；kubelet 监视此目录以在启动时创建 Pod。

   控制平面 Pod 启动并运行后，kubeadm init 序列可以继续。

5. 将标签和污点应用于控制平面节点，以便不会在该节点上运行其他工作负载。

6. 生成其他节点将来可以用来向控制平面注册自身的令牌。或者，用户可以通过 --token 提供令牌，如 kubeadm 令牌 文档中所述。

7. 使用 引导令牌 和 TLS 引导 机制进行所有必要的配置以允许节点加入

   • 编写一个 ConfigMap，用于提供加入所需的所有信息，并设置相关的 RBAC 访问规则。

   • 允许引导令牌访问 CSR 签名 API。

   • 为新的 CSR 请求配置自动批准。

   有关其他信息，请参阅 kubeadm join。

8. 通过 API 服务器安装 DNS 服务器 (CoreDNS) 和 kube-proxy 附加组件。在 Kubernetes 1.11 及更高版本中，CoreDNS 是默认的 DNS 服务器。请注意，虽然 DNS 服务器已部署，但在安装 CNI 之前它不会被调度。

   警告

   自 v1.18 起，不建议将 kube-dns 与 kubeadm 一起使用，并在 v1.21 中删除。

使用 kubeadm 的初始化阶段

kubeadm 允许您使用 kubeadm init phase 命令分阶段创建控制平面节点。

要查看阶段和子阶段的有序列表，您可以调用 kubeadm init --help。该列表将位于帮助屏幕的顶部，每个阶段旁边都有一个描述。请注意，通过调用 kubeadm init，所有阶段和子阶段都将按照此顺序执行。

某些阶段具有唯一的标志，因此如果您想查看可用选项列表，请添加 --help，例如

sudo kubeadm init phase control-plane controller-manager --help

您还可以使用 --help 查看某个父阶段的子阶段列表

sudo kubeadm init phase control-plane --help

kubeadm init 还公开了一个名为 --skip-phases 的标志，可用于跳过某些阶段。该标志接受阶段名称列表，并且名称可以从上面的有序列表中获取。

示例

sudo kubeadm init phase control-plane all --config=configfile.yaml
sudo kubeadm init phase etcd local --config=configfile.yaml
# you can now modify the control plane and etcd manifest files
sudo kubeadm init --skip-phases=control-plane,etcd --config=configfile.yaml

此示例将根据 configfile.yaml 中的配置，在 /etc/kubernetes/manifests 中写入控制平面和 etcd 的清单文件。这允许您修改文件，然后使用 --skip-phases 跳过这些阶段。通过调用最后一个命令，您将使用自定义清单文件创建一个控制平面节点。

或者，您可以使用 InitConfiguration 下的 skipPhases 字段。

使用配置文件运行 kubeadm init

可以使用配置文件而不是命令行标志来配置 kubeadm init，并且某些更高级的功能可能仅作为配置文件选项可用。此文件使用 --config 标志传递，它必须包含 ClusterConfiguration 结构，以及可选地由 ---\n 分隔的其他结构。在某些情况下，可能不允许将 --config 与其他标志混合使用。

可以使用 kubeadm config print 命令打印默认配置。

如果您的配置未使用最新版本，则建议您使用 kubeadm config migrate 命令进行迁移。

有关配置的字段和用法的更多信息，您可以导航到我们的 API 参考页面。

使用带有特性门的 kubeadm init

kubeadm 支持一组 kubeadm 独有的特性门，只能在使用 kubeadm init 创建集群期间应用。这些特性可以控制集群的行为。特性在升级到 GA 后会被移除。

要传递特性门，您可以使用 kubeadm init 的 --feature-gates 标志，或者在使用 --config 传递 配置文件 时，将项目添加到 featureGates 字段中。

不支持将 核心 Kubernetes 组件的特性门 直接传递给 kubeadm。但是，可以通过 使用 kubeadm API 自定义组件 来传递它们。

特性门列表

特性门描述

ControlPlaneKubeletLocalMode

启用此特性门后，在加入新的控制平面节点时，kubeadm 将配置 kubelet 以连接到本地 kube-apiserver。这可确保在滚动升级期间不会违反版本偏差策略。

EtcdLearnerMode

启用此特性门后，在加入新的控制平面节点时，将创建一个新的 etcd 成员作为学习者，并且仅在 etcd 数据完全对齐后才提升为投票成员。

NodeLocalCRISocket

启用此特性门后，kubeadm 将从文件 /var/lib/kubelet/instance-config.yaml 中读取/写入每个节点的 CRI 套接字，而不是从节点对象上的注释 kubeadm.alpha.kubernetes.io/cri-socket 中读取/写入它。新的文件将作为实例配置补丁应用，在使用 --patches 标志时应用任何其他用户管理的补丁之前。它包含 KubeletConfiguration 文件格式 中的单个字段 containerRuntimeEndpoint。如果在升级过程中启用了特性门，但文件 /var/lib/kubelet/instance-config.yaml 尚不存在，kubeadm 将尝试从文件 /var/lib/kubelet/kubeadm-flags.env 中读取 CRI 套接字值。

WaitForAllControlPlaneComponents

启用此特性门后，kubeadm 将等待控制平面节点上的所有控制平面组件（kube-apiserver、kube-controller-manager、kube-scheduler）在其 /livez 或 /healthz 端点上报告状态 200。这些检查在 https://ADDRESS:PORT/ENDPOINT 上执行。

• PORT 取自组件的 --secure-port。
• ADDRESS 是 kube-apiserver 的 --advertise-address，以及 kube-controller-manager 和 kube-scheduler 的 --bind-address。
• ENDPOINT 仅对 kube-controller-manager 是 /healthz，直到它也支持 /livez 为止。

如果您在 kubeadm 配置中指定自定义 ADDRESS 或 PORT，它们将被遵守。如果未启用特性门，kubeadm 将仅等待控制平面节点上的 kube-apiserver 准备就绪。等待过程在 kubeadm 启动主机上的 kubelet 后立即开始。如果您希望在 kubeadm init 或 kubeadm join 命令执行期间观察所有控制平面组件的准备状态，建议您启用此特性门。

已弃用特性门列表

特性门描述

PublicKeysECDSA

可用于创建使用 ECDSA 证书而不是默认 RSA 算法的集群。还可以使用 kubeadm certs renew 更新现有的 ECDSA 证书，但您不能在运行中或升级过程中在 RSA 和 ECDSA 算法之间切换。Kubernetes v1.31 之前的版本中存在一个错误，即使您启用了 PublicKeysECDSA 特性门，生成的 kubeconfig 文件中的密钥也会设置为使用 RSA。此特性门已弃用，取而代之的是 kubeadm v1beta4 中可用的 encryptionAlgorithm 功能。

RootlessControlPlane

设置此标志将配置 kubeadm 部署的控制平面组件静态 Pod 容器，使 kube-apiserver、kube-controller-manager、kube-scheduler 和 etcd 以非 root 用户身份运行。如果未设置该标志，则这些组件将以 root 用户身份运行。您可以在升级到较新版本的 Kubernetes 之前更改此特性门的值。

已移除特性门列表

特性门描述

IPv6DualStack

此标志有助于在该特性正在进行时配置组件的双栈。有关 Kubernetes 双栈支持的更多详细信息，请参阅 使用 kubeadm 的双栈支持。

UnversionedKubeletConfigMap

此标志控制 ConfigMap 的名称，kubeadm 在其中存储 kubelet 配置数据。如果未指定此标志或将其设置为 true，则 ConfigMap 的名称为 kubelet-config。如果将此标志设置为 false，则 ConfigMap 的名称将包含 Kubernetes 的主要和次要版本（例如：kubelet-config-1.32）。Kubeadm 确保用于读取和写入该 ConfigMap 的 RBAC 规则适合您设置的值。当 kubeadm 写入此 ConfigMap（在 kubeadm init 或 kubeadm upgrade apply 期间）时，kubeadm 将遵守 UnversionedKubeletConfigMap 的值。在读取该 ConfigMap（在 kubeadm join、kubeadm reset、kubeadm upgrade... 期间）时，kubeadm 尝试首先使用未版本化的 ConfigMap 名称。如果失败，kubeadm 将回退到使用该 ConfigMap 的旧（版本化）名称。

UpgradeAddonsBeforeControlPlane

此特性门已移除。它在 v1.28 中作为已弃用特性引入，然后在 v1.31 中移除。有关旧版本的文档，请切换到相应的网站版本。

添加 kube-proxy 参数

有关 kubeadm 配置中 kube-proxy 参数的信息，请参阅

• kube-proxy 参考

有关使用 kubeadm 启用 IPVS 模式的信息，请参阅

• IPVS

将自定义标志传递给控制平面组件

有关将标志传递给控制平面组件的信息，请参阅

• control-plane-flags

在没有 Internet 连接的情况下运行 kubeadm

要在没有 Internet 连接的情况下运行 kubeadm，您必须预先拉取所需的控制平面镜像。

您可以使用 kubeadm config images 子命令列出和拉取镜像

kubeadm config images list
kubeadm config images pull

您可以使用 kubeadm 配置文件 将 --config 传递给上述命令，以控制 kubernetesVersion 和 imageRepository 字段。

kubeadm 要求的所有默认 registry.k8s.io 镜像都支持多种架构。

使用自定义镜像

默认情况下，kubeadm 从 registry.k8s.io 拉取镜像。如果请求的 Kubernetes 版本是 CI 标签（例如 ci/latest），则使用 gcr.io/k8s-staging-ci-images。

您可以使用 带有配置文件的 kubeadm 来覆盖此行为。允许的自定义包括

• 提供 kubernetesVersion，它会影响镜像的版本。
• 提供要使用的替代 imageRepository，而不是 registry.k8s.io。
• 为 etcd 或 CoreDNS 提供特定的 imageRepository 和 imageTag。

出于向后兼容性的原因，默认 registry.k8s.io 和使用 imageRepository 指定的自定义存储库之间的镜像路径可能不同。例如，一个镜像在 registry.k8s.io/subpath/image 处可能有子路径，但在使用自定义存储库时默认为 my.customrepository.io/image。

为了确保将镜像推送到 kubeadm 可以使用的路径中的自定义存储库，您必须

• 使用 kubeadm config images {list|pull} 从 registry.k8s.io 的默认路径拉取镜像。
• 将镜像推送到 kubeadm config images list --config=config.yaml 的路径，其中 config.yaml 包含 etcd 和 CoreDNS 的自定义 imageRepository 和/或 imageTag。
• 将相同的 config.yaml 传递给 kubeadm init。

自定义沙盒（暂停）镜像

要为这些设置自定义镜像，您需要在容器运行时中配置它以使用该镜像。 请参阅您的容器运行时的文档，了解如何更改此设置；对于选定的容器运行时，您还可以在容器运行时主题中找到建议。

将控制平面证书上传到集群

通过将标志 --upload-certs 添加到 kubeadm init，您可以临时将控制平面证书上传到集群中的 Secret。 请注意，此 Secret 将在 2 小时后自动过期。 证书使用 32 字节密钥加密，可以使用 --certificate-key 指定该密钥。 当其他控制平面节点加入时，可以使用相同的密钥下载证书，方法是将 --control-plane 和 --certificate-key 传递给 kubeadm join。

以下阶段命令可用于在证书过期后重新上传证书

kubeadm init phase upload-certs --upload-certs --config=SOME_YAML_FILE

如果未将预定义的证书密钥传递给 kubeadm init 和 kubeadm init phase upload-certs，则将自动生成一个新密钥。

以下命令可用于按需生成新密钥

kubeadm certs certificate-key

使用 kubeadm 进行证书管理

有关使用 kubeadm 进行证书管理的详细信息，请参阅使用 Kubeadm 进行证书管理。 该文档包含有关使用外部 CA、自定义证书和证书续订的信息。

管理 kubelet 的 kubeadm drop-in 文件

kubeadm 软件包附带一个用于由 systemd 运行 kubelet 的配置文件。 请注意，kubeadm CLI 从不触及此 drop-in 文件。 此 drop-in 文件是 kubeadm DEB/RPM 软件包的一部分。

有关更多信息，请参阅管理 systemd 的 kubeadm drop-in 文件。

将 kubeadm 与 CRI 运行时一起使用

默认情况下，kubeadm 尝试检测您的容器运行时。 有关此检测的更多详细信息，请参阅kubeadm CRI 安装指南。

设置节点名称

默认情况下，kubeadm 根据机器的主机地址分配节点名称。 您可以使用 --node-name 标志覆盖此设置。 该标志将适当的 --hostname-override 值传递给 kubelet。

请注意，覆盖主机名可能会干扰云提供商。

kubeadm 自动化

您可以并行化令牌分发以便于自动化，而不是像基本的 kubeadm 教程中那样将从 kubeadm init 获得的令牌复制到每个节点。 要实现此自动化，您必须知道控制平面节点启动后的 IP 地址，或者使用 DNS 名称或负载均衡器的地址。

1. 生成令牌。 此令牌必须采用 <6 个字符的字符串>.<16 个字符的字符串> 的形式。 更正式地说，它必须匹配正则表达式：[a-z0-9]{6}\.[a-z0-9]{16}。

   kubeadm 可以为您生成令牌

   kubeadm token generate
   

2. 使用此令牌同时启动控制平面节点和工作节点。 当它们启动时，它们应该会找到彼此并组成集群。 可以在 kubeadm init 和 kubeadm join 上使用相同的 --token 参数。

3. 加入其他控制平面节点时，--certificate-key 也可以这样做。 可以使用以下命令生成密钥

   kubeadm certs certificate-key
   

集群启动后，您可以使用控制平面节点中的 /etc/kubernetes/admin.conf 文件以管理员凭据与集群通信，或者为其他用户生成 kubeconfig 文件。

请注意，这种引导方式的安全性有所降低，因为它不允许使用 --discovery-token-ca-cert-hash 验证根 CA 哈希（因为它在配置节点时不会生成）。 详细信息，请参阅kubeadm join。

后续步骤

• kubeadm init 阶段 了解有关 kubeadm init 阶段的更多信息
• kubeadm join 引导 Kubernetes 工作节点并将其加入集群
• kubeadm upgrade 将 Kubernetes 集群升级到较新版本
• kubeadm reset 恢复由 kubeadm init 或 kubeadm join 对此主机所做的任何更改