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
  /experimental-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=<list-of-errors>。

2. 生成自签名 CA 以设置集群中每个组件的身份。用户可以通过将自己的 CA 证书和/或密钥放到通过--cert-dir（默认情况下为/etc/kubernetes/pki）配置的证书目录中来提供自己的 CA 证书和/或密钥。APIServer 证书将为任何--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 开始，kubeadm 中的 kube-dns 已弃用，并在 v1.21 中删除。

在 kubeadm 中使用 init 阶段

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 自定义组件来传递它们。

功能开关列表

功能开关描述

EtcdLearnerMode

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

PublicKeysECDSA

可用于创建使用 ECDSA 证书而不是默认 RSA 算法的集群。还支持使用kubeadm certs renew续订现有的 ECDSA 证书，但您无法在运行时或升级期间在 RSA 和 ECDSA 算法之间切换。Kubernetes 1.30 存在一个错误，即在生成的 kubeconfig 文件中的密钥设置为使用 RSA，即使启用了功能开关。

RootlessControlPlane

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

WaitForAllControlPlaneComponents

启用此功能开关后，kubeadm 将等待控制平面节点上的所有控制平面组件（kube-apiserver、kube-controller-manager、kube-scheduler）在其/healthz端点上报告状态 200。这些检查在https://127.0.0.1:PORT/healthz上执行，其中PORT取自组件的--secure-port。如果您在 kubeadm 配置中指定了自定义的--secure-port值，则会尊重这些值。在未启用功能开关的情况下，kubeadm 将仅等待控制平面节点上的 kube-apiserver 变得就绪。等待过程在 kubeadm 启动主机上的 kubelet 后立即开始。如果您希望在kubeadm init或kubeadm join命令执行期间观察所有控制平面组件的就绪状态，建议您启用此功能开关。

已弃用功能开关列表

功能开关描述

UpgradeAddonsBeforeControlPlane

这是一个已禁用的功能开关，它是在 Kubernetes v1.28 中引入的，以便在集群升级期间重新激活旧的已弃用行为。对于 v1.28 之前的 kubeadm 版本，kubeadm 会在kubeadm upgrade apply期间立即升级集群附加组件（包括 CoreDNS 和 kube-proxy），而不管是否有其他尚未升级的控制平面实例。这可能会导致兼容性问题。从 v1.28 开始，kubeadm 默认采用一种模式，该模式始终检查所有控制平面实例是否已升级，然后再开始升级附加组件。此行为适用于kubeadm upgrade apply和kubeadm upgrade node。kubeadm 通过检查 kube-apiserver Pod 的映像是否已升级来确定控制平面实例是否已升级。您必须按顺序执行控制平面实例升级，或者至少确保在所有其他控制平面实例完全升级之前，不要启动最后一个控制平面实例升级，并且附加组件升级将在最后一个控制平面实例升级后执行。已弃用的UpgradeAddonsBeforeControlPlane功能开关让您有机会保留旧的升级行为。您不应该需要这种旧行为；如果您需要，您应该考虑更改您的集群或升级流程，因为此功能开关将在将来的版本中被移除。

已移除功能开关列表

功能开关描述

IPv6DualStack

此标志有助于在功能开发过程中配置组件双栈。有关 Kubernetes 双栈支持的更多详细信息，请参阅使用 kubeadm 的双栈支持。

UnversionedKubeletConfigMap

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

添加 kube-proxy 参数

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

• kube-proxy 参考

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

• IPVS

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

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

• control-plane-flags

在没有互联网连接的情况下运行 kubeadm

要在没有互联网连接的情况下运行 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包含自定义的imageRepository，以及 etcd 和 CoreDNS 的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. 使用此令牌同时启动控制平面节点和工作节点。当它们启动时，它们应该相互找到并形成集群。相同的 --token 参数可以在 kubeadm init 和 kubeadm join 中使用。

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 对此主机所做的任何更改