kubeadm init

该命令用于初始化 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
wait-control-plane            Wait for the control plane to start
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）来提供自己的 CA。API Server 证书将包含任何 --apiserver-cert-extra-sans 参数的额外 SAN 条目（必要时转为小写）。

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

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

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

   一旦控制平面 Pod 启动并运行，kubeadm init 序列即可继续。

5. 为控制平面节点应用标签和污点，以确保不会在该节点上运行额外的负载。

6. 生成令牌，后续节点可以在将来使用该令牌向控制平面注册自己。用户可以选择通过 --token 提供令牌，详见 kubeadm token 文档。

7. 进行所有必要的配置，以允许节点通过 引导令牌 (Bootstrap Tokens) 和 TLS 引导 (TLS Bootstrap) 机制加入。

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

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

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

   有关更多信息，请参见 kubeadm join。

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

   警告

   从 v1.18 开始，kubeadm 对 kube-dns 的使用已被弃用，并在 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 中的配置，将控制平面和 etcd 的清单文件写入 /etc/kubernetes/manifests。这允许您修改文件，然后使用 --skip-phases 跳过这些阶段。通过调用最后一条命令，您将使用自定义清单文件创建控制平面节点。

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

使用配置文件运行 kubeadm init

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

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

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

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

使用功能门控（Feature Gates）运行 kubeadm init

kubeadm 支持一组对 kubeadm 而言是独特的功能门控，只能在集群创建时通过 kubeadm init 应用。这些功能可以控制集群的行为。当功能进入 GA 后，功能门控将被移除。

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

直接向 kubeadm 传递 Kubernetes 核心组件的功能门控 是不支持的。相反，可以通过 使用 kubeadm API 自定义组件 来传递它们。

功能门控列表

功能门控描述

NodeLocalCRISocket

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

已弃用的功能门控列表

功能门控描述

PublicKeysECDSA

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

RootlessControlPlane

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

已移除的功能门控列表

功能门控描述

ControlPlaneKubeletLocalMode

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

EtcdLearnerMode

当加入新的控制平面节点时，一个新的 etcd 成员将被创建为学习者（learner），并且仅在 etcd 数据完全对齐后才被提升为投票成员。

IPv6DualStack

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

UnversionedKubeletConfigMap

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

UpgradeAddonsBeforeControlPlane

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

WaitForAllControlPlaneComponents

启用此功能门控后，当控制平面节点上的所有控制平面组件（kube-apiserver、kube-controller-manager、kube-scheduler）报告其 /livez 或 /healthz 端点状态为 200 时，kubeadm 才会继续执行。这些检查在 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 命令执行期间观察所有控制平面组件的就绪状态，建议您启用此功能门控。

添加 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

您可以将 --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 phase 了解更多关于 kubeadm init 阶段的信息
• kubeadm join 用于引导 Kubernetes 工作节点并将其加入集群
• kubeadm upgrade 用于将 Kubernetes 集群升级到新版本
• kubeadm reset 撤消此主机上由 kubeadm init 或 kubeadm join 做的任何更改