kubeadm init

此命令初始化一个 Kubernetes 控制平面节点。

概要

运行此命令来搭建 Kubernetes 控制平面节点。

“init” 命令执行以下阶段:

  1. preflight Run pre-flight checks
  2. certs Certificate generation
  3. /ca Generate the self-signed Kubernetes CA to provision identities for other Kubernetes components
  4. /apiserver Generate the certificate for serving the Kubernetes API
  5. /apiserver-kubelet-client Generate the certificate for the API server to connect to kubelet
  6. /front-proxy-ca Generate the self-signed CA to provision identities for front proxy
  7. /front-proxy-client Generate the certificate for the front proxy client
  8. /etcd-ca Generate the self-signed CA to provision identities for etcd
  9. /etcd-server Generate the certificate for serving etcd
  10. /etcd-peer Generate the certificate for etcd nodes to communicate with each other
  11. /etcd-healthcheck-client Generate the certificate for liveness probes to healthcheck etcd
  12. /apiserver-etcd-client Generate the certificate the apiserver uses to access etcd
  13. /sa Generate a private key for signing service account tokens along with its public key
  14. kubeconfig Generate all kubeconfig files necessary to establish the control plane and the admin kubeconfig file
  15. /admin Generate a kubeconfig file for the admin to use and for kubeadm itself
  16. /kubelet Generate a kubeconfig file for the kubelet to use *only* for cluster bootstrapping purposes
  17. /controller-manager Generate a kubeconfig file for the controller manager to use
  18. /scheduler Generate a kubeconfig file for the scheduler to use
  19. kubelet-start Write kubelet settings and (re)start the kubelet
  20. control-plane Generate all static Pod manifest files necessary to establish the control plane
  21. /apiserver Generates the kube-apiserver static Pod manifest
  22. /controller-manager Generates the kube-controller-manager static Pod manifest
  23. /scheduler Generates the kube-scheduler static Pod manifest
  24. etcd Generate static Pod manifest file for local etcd
  25. /local Generate the static Pod manifest file for a local, single-node local etcd instance
  26. upload-config Upload the kubeadm and kubelet configuration to a ConfigMap
  27. /kubeadm Upload the kubeadm ClusterConfiguration to a ConfigMap
  28. /kubelet Upload the kubelet component config to a ConfigMap
  29. upload-certs Upload certificates to kubeadm-certs
  30. mark-control-plane Mark a node as a control-plane
  31. bootstrap-token Generates bootstrap tokens used to join a node to a cluster
  32. kubelet-finalize Updates settings relevant to the kubelet after TLS bootstrap
  33. /experimental-cert-rotation Enable kubelet client certificate rotation
  34. addon Install required addons for passing Conformance tests
  35. /coredns Install the CoreDNS addon to a Kubernetes cluster
  36. /kube-proxy Install the kube-proxy addon to a Kubernetes cluster
  1. kubeadm init [flags]

选项

—apiserver-advertise-address string
API 服务器所公布的其正在监听的 IP 地址。如果未设置,则使用默认网络接口。
—apiserver-bind-port int32     默认值:6443
API 服务器绑定的端口。
—apiserver-cert-extra-sans stringSlice
用于 API Server 服务证书的可选附加主题备用名称(SAN)。可以是 IP 地址和 DNS 名称。
—cert-dir string     默认值:”/etc/kubernetes/pki”
保存和存储证书的路径。
—certificate-key string
用于加密 kubeadm-certs Secret 中的控制平面证书的密钥。
—config string
kubeadm 配置文件的路径。
—control-plane-endpoint string
为控制平面指定一个稳定的 IP 地址或 DNS 名称。
—cri-socket string
要连接的 CRI 套接字的路径。如果为空,则 kubeadm 将尝试自动检测此值;仅当安装了多个 CRI 或具有非标准 CRI 插槽时,才使用此选项。
—dry-run
不要应用任何更改;只是输出将要执行的操作。
—experimental-patches string
包含名为 “target[suffix][+patchtype].extension” 的文件的目录路径。 例如,”kube-apiserver0+merge.yaml” 或仅仅是 “etcd.json”。 “patchtype” 可以是 “strategic”、”merge” 或 “json” 之一,并且它们与 kubectl 支持的补丁格式匹配。 默认的 “patchtype” 为 “strategic”。 “extension” 必须为 “json” 或 “yaml”。 “suffix” 是一个可选字符串,可用于确定首先按字母顺序应用哪些补丁。
—feature-gates string
一组用来描述各种功能特性的键值(key=value)对。选项是:
IPv6DualStack=true|false (ALPHA - default=false)
-h, —help
init 操作的帮助命令
—ignore-preflight-errors stringSlice
错误将显示为警告的检查列表;例如:’IsPrivilegedUser,Swap’。取值为 ‘all’ 时将忽略检查中的所有错误。
—image-repository string     默认值:”k8s.gcr.io”
选择用于拉取控制平面镜像的容器仓库
—kubernetes-version string     默认值:”stable-1”
为控制平面选择一个特定的 Kubernetes 版本。
—node-name string
指定节点的名称。
—pod-network-cidr string
指明 pod 网络可以使用的 IP 地址段。如果设置了这个参数,控制平面将会为每一个节点自动分配 CIDRs。
—service-cidr string     默认值:”10.96.0.0/12”
为服务的虚拟 IP 地址另外指定 IP 地址段
—service-dns-domain string     默认值:”cluster.local”
为服务另外指定域名,例如:”myorg.internal”。
—skip-certificate-key-print
不要打印用于加密控制平面证书的密钥。
—skip-phases stringSlice
要跳过的阶段列表
—skip-token-print
跳过打印 ‘kubeadm init’ 生成的默认引导令牌。
—token string
这个令牌用于建立控制平面节点与工作节点间的双向通信。格式为 [a-z0-9]{6}.[a-z0-9]{16} - 示例:abcdef.0123456789abcdef
—token-ttl duration     默认值:24h0m0s
令牌被自动删除之前的持续时间(例如 1 s,2 m,3 h)。如果设置为 ‘0’,则令牌将永不过期
—upload-certs
将控制平面证书上传到 kubeadm-certs Secret。

从父命令继承的选项

—rootfs string
[实验] 到 ‘真实’ 主机根文件系统的路径。

Init 命令的工作流程

kubeadm init 命令通过执行下列步骤来启动一个 Kubernetes 控制平面节点。

  1. 在做出变更前运行一系列的预检项来验证系统状态。一些检查项目仅仅触发警告, 其它的则会被视为错误并且退出 kubeadm,除非问题得到解决或者用户指定了 --ignore-preflight-errors=<错误列表> 参数。

  2. 生成一个自签名的 CA 证书来为集群中的每一个组件建立身份标识。 用户可以通过将其放入 --cert-dir 配置的证书目录中(默认为 /etc/kubernetes/pki) 来提供他们自己的 CA 证书以及/或者密钥。 APIServer 证书将为任何 --apiserver-cert-extra-sans 参数值提供附加的 SAN 条目,必要时将其小写。

  3. 将 kubeconfig 文件写入 /etc/kubernetes/ 目录以便 kubelet、控制器管理器和调度器用来连接到 API 服务器,它们每一个都有自己的身份标识,同时生成一个名为 admin.conf 的独立的 kubeconfig 文件,用于管理操作。

  4. 为 API 服务器、控制器管理器和调度器生成静态 Pod 的清单文件。假使没有提供一个外部的 etcd 服务的话,也会为 etcd 生成一份额外的静态 Pod 清单文件。

    静态 Pod 的清单文件被写入到 /etc/kubernetes/manifests 目录; kubelet 会监视这个目录以便在系统启动的时候创建 Pod。

    一旦控制平面的 Pod 都运行起来, kubeadm init 的工作流程就继续往下执行。

  5. 对控制平面节点应用标签和污点标记以便不会在它上面运行其它的工作负载。

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

  7. 为了使得节点能够遵照启动引导令牌TLS 启动引导 这两份文档中描述的机制加入到集群中,kubeadm 会执行所有的必要配置:

    • 创建一个 ConfigMap 提供添加集群节点所需的信息,并为该 ConfigMap 设置相关的 RBAC 访问规则。

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

    • 配置自动签发新的 CSR 请求。

    更多相关信息,请查看 kubeadm join

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

    Warning: 从 v1.18 开始,在 kubeadm 中使用 kube-dns 的支持已被废弃,并已在 v1.21 版本中删除。

在 kubeadm 中使用 init phases

Kubeadm 允许你使用 kubeadm init phase 命令分阶段创建控制平面节点。

要查看阶段和子阶段的有序列表,可以调用 kubeadm init --help。 该列表将位于帮助屏幕的顶部,每个阶段旁边都有一个描述。 注意,通过调用 kubeadm init,所有阶段和子阶段都将按照此确切顺序执行。

某些阶段具有唯一的标志,因此,如果要查看可用选项的列表,请添加 --help,例如:

  1. sudo kubeadm init phase control-plane controller-manager --help

你也可以使用 --help 查看特定父阶段的子阶段列表:

  1. sudo kubeadm init phase control-plane --help

kubeadm init 还公开了一个名为 --skip-phases 的参数,该参数可用于跳过某些阶段。 参数接受阶段名称列表,并且这些名称可以从上面的有序列表中获取。

例如:

  1. sudo kubeadm init phase control-plane all --config=configfile.yaml
  2. sudo kubeadm init phase etcd local --config=configfile.yaml
  3. # 你现在可以修改控制平面和 etcd 清单文件
  4. sudo kubeadm init --skip-phases=control-plane,etcd --config=configfile.yaml

该示例将执行的操作是基于 configfile.yaml 中的配置在 /etc/kubernetes/manifests 中写入控制平面和 etcd 的清单文件。 这允许你修改文件,然后使用 --skip-phases 跳过这些阶段。 通过调用最后一个命令,你将使用自定义清单文件创建一个控制平面节点。

结合一份配置文件来使用 kubeadm init

Caution: 配置文件的功能仍然处于 alpha 状态并且在将来的版本中可能会改变。

通过一份配置文件而不是使用命令行参数来配置 kubeadm init 命令是可能的, 但是一些更加高级的功能只能够通过配置文件设定。 这份配置文件通过 --config 选项参数指定的, 它必须包含 ClusterConfiguration 结构,并可能包含更多由 ---\n 分隔的结构。 在某些情况下,可能不允许将 --config 与其他标志混合使用。

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

如果你的配置没有使用最新版本, 推荐使用 kubeadm config migrate 命令进行迁移。

有关配置的字段和用法的更多信息, 你可以访问 API 参考页面并从 列表 中选择一个版本。

添加 kube-proxy 参数

kubeadm 配置中有关 kube-proxy 的说明请查看:

使用 kubeadm 启用 IPVS 模式的说明请查看:

向控制平面组件传递自定义的命令行参数

有关向控制平面组件传递命令行参数的说明请查看: 控制平面命令行参数

使用自定义的镜像

默认情况下, kubeadm 会从 k8s.gcr.io 仓库拉取镜像。如果请求的 Kubernetes 版本是 CI 标签 (例如 ci/latest),则使用 gcr.io/k8s-staging-ci-images

你可以通过使用带有配置文件的 kubeadm 来重写此操作。

允许的自定义功能有:

  • 使用其他的 imageRepository 来代替 k8s.gcr.io
  • useHyperKubeImage 设置为 true,使用 HyperKube 镜像。
  • 为 etcd 或 DNS 附件提供特定的 imageRepositoryimageTag

请注意配置文件中的配置项 kubernetesVersion 或者命令行参数 --kubernetes-version 会影响到镜像的版本。

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

通过将参数 --upload-certs 添加到 kubeadm init,你可以将控制平面证书临时上传到集群中的 Secret。 请注意,此 Secret 将在 2 小时后自动过期。证书使用 32 字节密钥加密,可以使用 --certificate-key 指定。 通过将 --control-plane--certificate-key 传递给 kubeadm join, 可以在添加其他控制平面节点时使用相同的密钥下载证书。

以下阶段命令可用于证书到期后重新上传证书:

  1. kubeadm init phase upload-certs --upload-certs --certificate-key=SOME_VALUE --config=SOME_YAML_FILE

如果未将参数 --certificate-key 传递给 kubeadm initkubeadm init phase upload-certs, 则会自动生成一个新密钥。

以下命令可用于按需生成新密钥:

  1. kubeadm certs certificate-key

使用 kubeadm 管理证书

有关使用 kubeadm 进行证书管理的详细信息,请参阅 使用 kubeadm 进行证书管理。 该文档包括有关使用外部 CA,自定义证书和证书更新的信息。

管理 kubeadm 为 kubelet 提供的 systemd 配置文件

kubeadm 包自带了关于 systemd 如何运行 kubelet 的配置文件。 请注意 kubeadm 客户端命令行工具永远不会修改这份 systemd 配置文件。 这份 systemd 配置文件属于 kubeadm DEB/RPM 包。

有关更多信息,请阅读 管理 systemd 的 kubeadm 内嵌文件

结合 CRI 运行时使用 kubeadm

默认情况下,kubeadm 尝试检测你的容器运行环境。有关此检测的更多详细信息,请参见 kubeadm CRI 安装指南

设置节点的名称

默认情况下, kubeadm 基于机器的主机地址分配一个节点名称。你可以使用 --node-name 参数覆盖此设置。 此标识将合适的 --hostname-override 值传递给 kubelet。

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

要在没有互联网连接的情况下运行 kubeadm,你必须提前拉取所需的控制平面镜像。

你可以使用 kubeadm config images 子命令列出并拉取镜像:

  1. kubeadm config images list
  2. kubeadm config images pull

kubeadm 需要的所有镜像,例如 k8s.gcr.io/kube-*k8s.gcr.io/etcdk8s.gcr.io/pause 都支持多种架构。

kubeadm 自动化

除了像文档 kubeadm 基础教程 中所描述的那样,将从 kubeadm init 取得的令牌复制到每个节点, 你还可以并行地分发令牌以实现简单自动化。 要实现自动化,你必须知道控制平面节点启动后将拥有的 IP 地址,或使用 DNS 名称或负载均衡器的地址。

  1. 生成一个令牌。这个令牌必须具有以下格式:< 6 个字符的字符串>.< 16 个字符的字符串>。 更加正式的说法是,它必须符合以下正则表达式:[a-z0-9]{6}\.[a-z0-9]{16}

    kubeadm 可以为你生成一个令牌:

    1. kubeadm token generate
  2. 使用这个令牌同时启动控制平面节点和工作节点。它们一旦运行起来应该就会互相寻找对方并且建立集群。 同样的 --token 参数可以同时用于 kubeadm initkubeadm join 命令。

  3. 当加入其他控制平面节点时,可以对 --certificate-key 执行类似的操作。可以使用以下方式生成密钥:

    1. kubeadm certs certificate-key

一旦集群启动起来,你就可以从控制平面节点的 /etc/kubernetes/admin.conf 文件获取管理凭证, 并使用这个凭证同集群通信。

注意这种搭建集群的方式在安全保证上会有一些宽松,因为这种方式不允许使用 --discovery-token-ca-cert-hash 来验证根 CA 的哈希值(因为当配置节点的时候,它还没有被生成)。 更多信息请参阅 kubeadm join 文档。

What’s next

最后修改 July 29, 2021 at 5:59 PM PST: kubeadm: use k8s-staging-ci-images instead of kubernetes-ci-images (be9926dff)