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]

选项

--apiserver-advertise-address string

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

--apiserver-bind-port int32     Default: 6443

API Server 绑定的端口。

--apiserver-cert-extra-sans strings

用于 API Server 服务证书的可选额外 Subject Alternative Names (SANs)。可以是 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 socket 路径。如果为空，kubeadm 将尝试自动检测此值；仅当您安装了多个 CRI 或具有非标准的 CRI socket 时才使用此选项。

--dry-run

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

--feature-gates string

一组描述各种特性门控的 key=value 对。选项包括
ControlPlaneKubeletLocalMode=true|false (BETA - default=true)
NodeLocalCRISocket=true|false (ALPHA - default=false)
PublicKeysECDSA=true|false (DEPRECATED - default=false)
RootlessControlPlane=true|false (ALPHA - default=false)
WaitForAllControlPlaneComponents=true|false (BETA - 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"

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

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

为 Service 使用替代域，例如 "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，为集群中的每个组件设置身份。用户可以通过将其放入通过 --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 引导（TLS Bootstrap） 机制加入。

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

    • 允许引导令牌访问 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-
NodeLocalCRISocketfalse1.32--
WaitForAllControlPlaneComponentstrue1.301.33-

特性门控说明

ControlPlaneKubeletLocalMode
启用此特性门控后，当加入新的控制平面节点时，kubeadm 将配置 kubelet 连接到本地的 kube-apiserver。这确保在滚动升级期间不会违反版本偏差策略。
NodeLocalCRISocket
启用此特性门控后，kubeadm 将从/向文件 /var/lib/kubelet/instance-config.yaml 读取/写入每个节点的 CRI socket，而不是从/向 Node 对象上的 annotation kubeadm.alpha.kubernetes.io/cri-socket 读取/写入。新文件作为实例配置补丁应用，在使用 --patches 标志时，它会在任何其他用户管理的补丁之前应用。它包含来自 KubeletConfiguration 文件格式 的单个字段 containerRuntimeEndpoint。如果在升级期间启用了该特性门控，但文件 /var/lib/kubelet/instance-config.yaml 尚不存在，kubeadm 将尝试从文件 /var/lib/kubelet/kubeadm-flags.env 读取 CRI socket 值。
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 算法之间切换。v1.31 之前的 Kubernetes 版本存在一个错误，即使启用了 PublicKeysECDSA 特性门控，生成的 kubeconfig 文件中的密钥仍被设置为使用 RSA。此特性门控已被弃用，取而代之的是 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 成员作为学习者，并且只有在 etcd 数据完全对齐后才会被提升为投票成员。
IPv6DualStack
此标志有助于在特性开发中配置组件双栈。有关 Kubernetes 双栈支持的更多详细信息，请参阅使用 kubeadm 的双栈支持。
UnversionedKubeletConfigMap
此标志控制 ConfigMap 的名称，kubeadm 在其中存储 kubelet 配置数据。如果未指定此标志或将其设置为 true，ConfigMap 的名称为 kubelet-config。如果将此标志设置为 false，ConfigMap 的名称将包含 Kubernetes 的主要和次要版本（例如：kubelet-config-1.33）。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 模式的信息，请参阅

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

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

在没有互联网连接的情况下运行 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。

自定义 sandbox (pause) 镜像

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

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

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

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

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 character string>.<16 character string> 的形式。更正式地说，它必须匹配正则表达式：[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。

下一步

上次修改时间：2025 年 2 月 6 日下午 4:48 PST：kubeadm：将 WaitForAllControlPlaneComponents 提升至 Beta (e74b41a774)