kubeadm init

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

Synopsis

运行此命令以设置 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]

Options

--apiserver-advertise-address string

API Server 将声明其正在监听的 IP 地址。如果未设置，将使用默认网络接口。

--apiserver-bind-port int32     Default: 6443

API Server 绑定到的端口。

--apiserver-cert-extra-sans strings

用于 API Server 服务证书的可选额外主题备用名称 (SAN)。可以是 IP 地址和 DNS 名称。

--cert-dir string     Default: "/etc/kubernetes/pki"

用于保存和存储证书的路径。

--certificate-key string

用于加密 kubeadm-certs Secret 中的控制平面证书的密钥。证书密钥是十六进制编码的字符串，为 32 字节的 AES 密钥。

--config string

kubeadm 配置文件路径。

--control-plane-endpoint string

为控制平面指定稳定的 IP 地址或 DNS 名称。

--cri-socket string

用于连接的 CRI 套接字路径。如果为空，kubeadm 将尝试自动检测此值；仅当安装了多个 CRI 或使用非标准 CRI 套接字时才使用此选项。

--dry-run

不应用任何更改；仅输出将要执行的操作。

--feature-gates string

一组描述各种功能的键值对。选项包括：
ControlPlaneKubeletLocalMode=true|false (BETA - default=true)
NodeLocalCRISocket=true|false (BETA - default=true)
PublicKeysECDSA=true|false (已弃用 - default=false)
RootlessControlPlane=true|false (ALPHA - default=false)
WaitForAllControlPlaneComponents=true|false (default=true)

-h, --help

init 的帮助信息

--ignore-preflight-errors strings

要显示为警告的检查错误列表。例如：'IsPrivilegedUser,Swap'。值 'all' 将忽略所有检查中的错误。

--image-repository string     Default: "registry.k8s.io"

选择一个容器注册表来拉取控制平面镜像

--kubernetes-version string     Default: "stable-1"

为控制平面选择特定的 Kubernetes 版本。

--node-name string

指定节点名称。

--patches string

包含命名为“target[suffix][+patchtype].extension”的文件的目录路径。例如，“kube-apiserver0+merge.yaml”或仅“etcd.json”。“target”可以是“kube-apiserver”、“kube-controller-manager”、“kube-scheduler”、“etcd”、“kubeletconfiguration”、“corednsdeployment”之一。“patchtype”可以是“strategic”、“merge”或“json”之一，它们匹配 kubectl 支持的补丁格式。“patchtype”的默认值是“strategic”。“extension”必须是“json”或“yaml”。“suffix”是一个可选字符串，可用于确定应用哪个补丁（按字母数字顺序）。

--pod-network-cidr string

为 Pod 网络指定 IP 地址范围。如果设置，控制平面将为每个节点自动分配 CIDR。

--service-cidr string     Default: "10.96.0.0/12"

为服务 VIP 使用替代 IP 地址范围。

--service-dns-domain string     Default: "cluster.local"

为服务使用替代域名，例如“myorg.internal”。

--skip-certificate-key-print

不打印用于加密控制平面证书的密钥。

--skip-phases strings

要跳过的阶段列表

--skip-token-print

跳过“kubeadm init”生成的默认引导令牌的打印。

--token string

用于在节点和控制平面节点之间建立双向信任的令牌。格式为 [a-z0-9]{6}.[a-z0-9]{16} - 例如 abcdef.0123456789abcdef

--token-ttl duration     Default: 24h0m0s

令牌自动删除的持续时间（例如，1s、2m、3h）。如果设置为“0”，令牌将永远不会过期。

--upload-certs

将控制平面证书上传到 kubeadm-certs Secret。

从父命令继承的选项

--rootfs string

“真实”主机根文件系统的路径。这将导致 kubeadm chroot 到提供的路径。

Init 工作流

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

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

  2. 生成自签名 CA，以设置集群中每个组件的身份。用户可以通过将 CA 证书和/或密钥放入通过 --cert-dir（默认为 /etc/kubernetes/pki）配置的证书目录中来提供自己的 CA 证书和/或密钥。API Server 证书将为任何 --apiserver-cert-extra-sans 参数包含其他 SAN 条目，必要时将进行小写处理。

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

  4. 为 API Server、controller-manager 和 scheduler 生成静态 Pod manifest。如果未提供外部 etcd，则会为 etcd 生成额外的静态 Pod manifest。

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

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

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

  6. 生成附加节点将来可以使用该令牌来向控制平面注册自己的令牌。可以选择，用户可以通过 --token 提供令牌，如 kubeadm token 文档中所述。

  7. 进行所有必要配置，以允许使用 Bootstrap Tokens 和 TLS Bootstrap 机制进行节点加入。

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

    • 允许 Bootstrap Tokens 访问 CSR 签名 API。

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

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

  8. 通过 API Server 安装 DNS 服务器 (CoreDNS) 和 kube-proxy 附加组件。在 Kubernetes 1.11 及更高版本中，CoreDNS 是默认 DNS 服务器。请注意，尽管 DNS 服务器已部署，但它要到 CNI 安装后才能调度。

使用 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 编写 manifest 文件。这允许您修改文件，然后使用 --skip-phases 跳过这些阶段。通过调用最后一个命令，您将创建一个具有自定义 manifest 文件的控制平面节点。

功能状态： Kubernetes v1.22 [beta]

或者，您可以在 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 自定义组件 来传递它们。

功能门列表

kubeadm 功能门
特性默认AlphaBetaGA
ControlPlaneKubeletLocalModetrue1.311.33-
NodeLocalCRISockettrue1.321.34-
WaitForAllControlPlaneComponentstrue1.301.331.34

功能门描述

ControlPlaneKubeletLocalMode
启用此功能门后，在加入新的控制平面节点时，kubeadm 将配置 kubelet 连接到本地 kube-apiserver。这可确保在滚动升级期间不会违反版本偏差策略。
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 命令执行期间观察所有控制平面组件的就绪状态。

已弃用的功能门列表

kubeadm 已弃用的功能门
特性默认AlphaBetaGA已弃用
PublicKeysECDSAfalse1.19--1.31
RootlessControlPlanefalse1.22--1.31

功能门描述

PublicKeysECDSA
可用于创建使用 ECDSA 证书而非默认 RSA 算法的集群。使用 kubeadm certs renew 也可以支持续订现有的 ECDSA 证书，但您不能在运行时或升级过程中切换 RSA 和 ECDSA 算法。Kubernetes 版本早于 v1.31 时存在一个 bug，其中生成的 kubeconfig 文件中的密钥被设置为使用 RSA，即使您启用了 PublicKeysECDSA 功能门。此功能门因 kubeadm v1beta4 中可用的 encryptionAlgorithm 功能而被弃用。
RootlessControlPlane
设置此标志会将 kubeadm 部署的控制平面组件静态 Pod 容器（用于 kube-apiserver、kube-controller-manager、kube-scheduler 和 etcd）配置为以非 root 用户身份运行。如果未设置该标志，这些组件将以 root 用户身份运行。您可以在升级到更新版本的 Kubernetes 之前更改此功能门的值。

已移除的功能门列表

kubeadm 已移除的功能门
特性AlphaBetaGA已移除
EtcdLearnerMode1.271.291.321.33
IPv6DualStack1.161.211.231.24
UnversionedKubeletConfigMap1.221.231.251.26
UpgradeAddonsBeforeControlPlane1.28--1.31

功能门描述

EtcdLearnerMode
在加入新的控制平面节点时，将创建一个新的 etcd 成员作为 learner，并在 etcd 数据完全对齐后才提升为投票成员。
IPv6DualStack
此标志有助于在功能进行中配置组件的双栈。有关 Kubernetes 双栈支持的更多详细信息，请参阅 带有 kubeadm 的双栈支持。
UnversionedKubeletConfigMap
此标志控制 kubeadm 存储 kubelet 配置数据的 ConfigMap 的名称。如果未指定此标志或设置为 true，则 ConfigMap 名为 kubelet-config。如果您将此标志设置为 false，则 ConfigMap 的名称将包含 Kubernetes 的主次版本（例如：kubelet-config-1.34）。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 参数的信息，请参阅

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

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

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

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

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

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

kubeadm config images list
kubeadm config images pull

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

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

自定义沙盒 (pause) 镜像

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

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

通过将 --upload-certs 标志添加到 kubeadm init，您可以临时将控制平面证书上传到集群中的 Secret。请注意，此 Secret 将在 2 小时后自动过期。证书使用 --certificate-key 指定的 32 字节密钥进行加密。当附加的控制平面节点加入时，可以使用相同的密钥下载证书，方法是将 --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 init 获取的令牌复制到每个节点，如 基本 kubeadm 教程 中所示，您还可以并行分发令牌以方便自动化。要实现此自动化，您必须知道控制平面节点启动后将拥有的 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 phase 以了解更多关于 kubeadm init 阶段的信息。
  • kubeadm join 以引导 Kubernetes 工作节点并将其加入集群。
  • kubeadm upgrade 以将 Kubernetes 集群升级到新版本。
  • kubeadm reset 以撤销 kubeadm init 或 kubeadm join 对此主机所做的任何更改。
最后修改时间：2025 年 7 月 4 日太平洋标准时间晚上 11:28：添加 NodeLocalCRISocket 升级到 Beta 版的文档 (0135b1b08b)