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]

选项

从父命令继承的选项

Init 工作流程

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

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

2. 生成一个自签名 CA 以设置集群中每个组件的身份。用户可以通过将自己的 CA 证书和/或密钥放在通过 --cert-dir（默认情况下为 /etc/kubernetes/pki）配置的证书目录中来提供自己的 CA 证书和/或密钥。APIServer 证书将对任何 --apiserver-cert-extra-sans 参数（如果需要，则小写）具有额外的 SAN 条目。

3. 在 /etc/kubernetes/ 中写入 kubeconfig 文件，供 kubelet、controller-manager 和 scheduler 用于连接到 API 服务器，每个文件都有自己的身份。此外，还将写入其他 kubeconfig 文件，用于 kubeadm 作为管理实体 (admin.conf) 以及用于可以绕过 RBAC 的超级管理员用户 (super-admin.conf)。

4. 生成 API 服务器、controller-manager 和 scheduler 的静态 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 自定义组件 传递它们。

特征门列表

特性开关描述

ControlPlaneKubeletLocalMode

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

EtcdLearnerMode

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

PublicKeysECDSA

可用于创建使用 ECDSA 证书而不是默认 RSA 算法的集群。还支持使用 kubeadm certs renew 续订现有 ECDSA 证书，但不能在运行时或升级过程中在 RSA 和 ECDSA 算法之间切换。Kubernetes 1.31 中存在一个错误，即生成的 kubeconfig 文件中的密钥被设置为使用 RSA，即使启用了特性开关。在 v1.31 之前的 Kubernetes 版本中存在一个错误，即生成的 kubeconfig 文件中的密钥被设置为使用 RSA，即使启用了 PublicKeysECDSA 特性开关。

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 命令执行期间希望观察所有控制平面组件的准备状态的情况下启用此特性开关。

已弃用特性开关列表

特性开关描述

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.31）。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

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

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

• 控制平面标志

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

要运行没有互联网连接的 kubeadm，您必须预先提取所需的控制平面映像。

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

kubeadm config images list
kubeadm config images pull

您可以将 --config 与 kubeadm 配置文件 一同传递给以上命令，以控制 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。

自定义沙箱 (pause) 映像

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

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

通过将标志 --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 对此主机进行的任何更改