Edit This Page

kubeadm join

此命令用来初始化 Kubernetes 工作节点并将其加入集群。

摘要

当节点加入 kubeadm 初始化的集群时,我们需要建立双向信任。 这个过程可以分解为发现(让待加入节点信任 Kubernetes 控制平面节点)和 TLS 引导(让Kubernetes 控制平面节点信任待加入节点)两个部分。

有两种主要的发现方案。 第一种方法是使用共享令牌和 API 服务器的 IP 地址。 第二种是提供一个文件 - 标准 kubeconfig 文件的一个子集。 该文件可以是本地文件,也可以通过 HTTPS URL 下载。 格式是 kubeadm join --discovery-token abcdef.1234567890abcdef 1.2.3.4:6443kubeadm join--discovery-file path/to/file.conf 或者kubeadm join --discovery-file https://url/file.conf。 只能使用其中一种。 如果发现信息是从 URL 加载的,必须使用 HTTPS。 此外,在这种情况下,主机安装的 CA 包用于验证连接。

如果使用共享令牌进行发现,还应该传递 --discovery-token-ca-cert-hash 参数来验证 Kubernetes 控制平面节点提供的根证书颁发机构(CA)的公钥。 此参数的值指定为 "<hash-type>:<hex-encoded-value>",其中支持的哈希类型为 "sha256"。哈希是通过 Subject Public Key Info(SPKI)对象的字节计算的(如 RFC7469)。 这个值可以从 "kubeadm init" 的输出中获得,或者可以使用标准工具进行计算。 可以多次重复 --discovery-token-ca-cert-hash 参数以允许多个公钥。

如果无法提前知道 CA 公钥哈希,则可以通过 --discovery-token-unsafe-skip-ca-verification 参数禁用此验证。 这削弱了kubeadm 安全模型,因为其他节点可能会模仿 Kubernetes 控制平面节点。

TLS 引导机制也通过共享令牌驱动。 这用于向 Kubernetes 控制平面节点进行临时的身份验证,以提交本地创建的密钥对的证书签名请求(CSR)。 默认情况下,kubeadm 将设置 Kubernetes 控制平面节点自动批准这些签名请求。 这个令牌通过 --tls-bootstrap-token abcdef.1234567890abcdef 参数传入。

通常两个部分会使用相同的令牌。 在这种情况下可以使用 --token 参数,而不是单独指定每个令牌。

"join [api-server-endpoint]" 命令执行下列阶段:

preflight              Run join pre-flight checks
control-plane-prepare  Prepare the machine for serving a control plane
  /download-certs        [EXPERIMENTAL] Download certificates shared among control-plane nodes from the kubeadm-certs Secret
  /certs                 Generate the certificates for the new control plane components
  /kubeconfig            Generate the kubeconfig for the new control plane components
  /control-plane         Generate the manifests for the new control plane components
kubelet-start          Write kubelet settings, certificates and (re)start the kubelet
control-plane-join     Join a machine as a control plane instance
  /etcd                  Add a new local etcd member
  /update-status         Register the new control-plane node into the ClusterStatus maintained in the kubeadm-config ConfigMap
  /mark-control-plane    Mark a node as a control-plane
kubeadm join [api-server-endpoint] [flags]

选项

--apiserver-advertise-address string
如果该节点托管一个新的控制平面实例,则 API 服务器将公布其正在侦听的 IP 地址。如果未设置,则使用默认网络接口。
--apiserver-bind-port int32     默认值: 6443
如果节点应该托管新的控制平面实例,则为 API 服务器要绑定的端口。
--certificate-key string
使用此密钥可以解密由 init 上传的证书 secret。
--config string
kubeadm 配置文件的路径。
--control-plane
在此节点上创建一个新的控制平面实例
--cri-socket string
要连接的 CRI 套接字的路径。如果为空,则 kubeadm 将尝试自动检测此值;仅当安装了多个 CRI 或具有非标准 CRI 插槽时,才使用此选项。
--discovery-file string
对于基于文件的发现,给出用于加载集群信息的文件或者 URL。
--discovery-token string
对于基于令牌的发现,该令牌用于验证从 API 服务器获取的集群信息。
--discovery-token-ca-cert-hash stringSlice
对基于令牌的发现,验证根 CA 公钥是否与此哈希匹配 (格式: "<type>:<value>")。
--discovery-token-unsafe-skip-ca-verification
对于基于令牌的发现,允许在未关联 --discovery-token-ca-cert-hash 参数的情况下添加节点。
-k, --experimental-kustomize string
用于存储 kustomize 为静态 pod 清单所提供的补丁的路径。
-h, --help
join 操作的帮助命令
--ignore-preflight-errors stringSlice
错误将显示为警告的检查列表;例如:'IsPrivilegedUser,Swap'。取值为 'all' 时将忽略检查中的所有错误。
--node-name string
指定节点的名称
--skip-phases stringSlice
要跳过的阶段列表
--tls-bootstrap-token string
指定在加入节点时用于临时通过 Kubernetes 控制平面进行身份验证的令牌。
--token string
如果未提供这些值,则将它们用于 discovery-token 令牌和 tls-bootstrap 令牌。

从父命令继承的选项

--rootfs string
[实验] 指向 '真实' 宿主机根文件系统的路径。

加入流程

kubeadm join 初始化 Kubernetes 工作节点并将其加入集群。 该操作过程包含下面几个步骤:

  1. kubeadm 从 API 服务器下载必要的集群信息。 默认情况下,它使用引导令牌和 CA 密钥哈希来验证数据的真实性。 也可以通过文件或 URL 直接发现根 CA。

  2. 如果调用 kubeadm 时启用了 --feature-gates=DynamicKubeletConfig,它首先从主机上检索 kubelet 初始化配置并将其写入磁盘。 当 kubelet 启动时,kubeadm 更新节点的 Node.spec.configSource 属性。 进一步了解动态 kubelet 配置 请参考 使用配置文件设置 Kubelet 参数重新配置集群中节点的 Kubelet

  3. 一旦知道集群信息,kubelet 就可以开始 TLS 引导过程。 TLS 引导程序使用共享令牌与 Kubernetes API 服务器进行临时的身份验证,以提交证书签名请求 (CSR); 默认情况下,控制平面自动对该 CSR 请求进行签名。

  4. 最后,kubeadm 配置本地 kubelet 使用分配给节点的确定标识连接到 API 服务器。

发现要信任的集群 CA

Kubeadm 的发现有几个选项,每个选项都有安全性上的优缺点。 适合您的环境的正确方法取决于节点是如何准备的以及您对网络的安全性期望和节点的生命周期特点。

带 CA 锁定模式的基于令牌的发现

这是 Kubernetes 1.8 及以上版本中的默认模式。 在这种模式下,kubeadm 下载集群配置(包括根CA)并使用令牌验证它,并且会验证根 CA 的公钥与所提供的哈希是否匹配,以及 API 服务器证书在根 CA 下是否有效。

CA 键哈希格式为 sha256:<hex_encoded_hash>。 默认情况下,在 kubeadm init 最后打印的 kubeadm join 命令或者 kubeadm token create --print-join-command 的输出信息中返回哈希值。 它使用标准格式 (请参考 RFC7469) 并且也能通过第三方工具或者驱动系统进行计算。 例如,使用 OpenSSL CLI:

openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -hex | sed 's/^.* //'

kubeadm join 命令示例

kubeadm join --discovery-token abcdef.1234567890abcdef --discovery-token-ca-cert-hash sha256:1234..cdef 1.2.3.4:6443

优势:

  • 允许引导节点安全地发现主节点的信任根,即使其他工作节点或网络受到损害。

  • 方便手动执行,因为所需的所有信息都适合于易于复制和粘贴的单个 kubeadm join 命令。

劣势:

  • CA 哈希通常在主节点被提供之前是不知道的,这使得构建使用 kubeadm 的自动化配置工具更加困难。 通过预先生成CA,您可以解决这个限制。

无 CA 锁定模式的基于令牌的发现

_这是 Kubernetes 1.7 和早期版本_中的默认设置;使用时要注意一些重要的补充说明。 此模式仅依赖于对称令牌来签名(HMAC-SHA256)发现信息,这些发现信息为主节点建立信任根。 在 Kubernetes 1.8 及以上版本中仍然可以使用 --discovery-token-unsafe-skip-ca-verification 参数,但是如果可能的话,您应该考虑使用一种其他模式。

kubeadm join 命令示例

kubeadm join --token abcdef.1234567890abcdef --discovery-token-unsafe-skip-ca-verification 1.2.3.4:6443`

优势

  • 仍然可以防止许多网络级攻击。

  • 可以提前生成令牌并与主节点和工作节点共享,这样主节点和工作节点就可以并行引导而无需协调。 这允许它在许多配置场景中使用。

劣势

  • 如果攻击者能够通过某些漏洞窃取引导令牌,那么他们可以使用该令牌(连同网络级访问)为其它处于引导过程中的节点提供假冒的主节点。 在您的环境中,这可能是一个适当的折衷方法,也可能不是。

基于 HTTPS 或文件发现

这种方案提供了一种带外方式在主节点和引导节点之间建立信任根。 如果使用 kubeadm 构建自动配置,请考虑使用此模式。

kubeadm join 命令示例:

  • kubeadm join --discovery-file path/to/file.conf (本地文件)

  • kubeadm join --discovery-file https://url/file.conf (远程 HTTPS URL)

优势:

  • 允许引导节点安全地发现主节点的信任根,即使网络或其他工作节点受到损害。

劣势:

  • 要求您有某种方法将发现信息从主节点传送到引导节点。 例如,这可以通过云提供商或驱动工具实现。 该文件中的信息不是加密的,而是需要 HTTPS 或等效文件来保证其完整性。

确保您的安装更加安全

Kubeadm 的默认值可能不适用于所有人。 本节说明如何以牺牲可用性为代价来加强 kubeadm 安装。

关闭节点客户端证书的自动批准

默认情况下,Kubernetes 启用了 CSR 自动批准器,如果在身份验证时使用 Bootstrap Token,它会批准对 kubelet 的任何客户端证书的请求。 如果不希望集群自动批准kubelet客户端证书,可以通过执行以下命令关闭它:

$ kubectl delete clusterrole kubeadm:node-autoapprove-bootstrap

关闭后,kubeadm join 操作将会被阻断,直到管理员已经手动批准了在途中的 CSR 才会继续:

$ kubectl get csr
NAME                                                   AGE       REQUESTOR                 CONDITION
node-csr-c69HXe7aYcqkS1bKmH4faEnHAWxn6i2bHZ2mD04jZyQ   18s       system:bootstrap:878f07   Pending

$ kubectl certificate approve node-csr-c69HXe7aYcqkS1bKmH4faEnHAWxn6i2bHZ2mD04jZyQ
certificatesigningrequest "node-csr-c69HXe7aYcqkS1bKmH4faEnHAWxn6i2bHZ2mD04jZyQ" approved

$ kubectl get csr
NAME                                                   AGE       REQUESTOR                 CONDITION
node-csr-c69HXe7aYcqkS1bKmH4faEnHAWxn6i2bHZ2mD04jZyQ   1m        system:bootstrap:878f07   Approved,Issued

只有执行了 kubectl certificate approve 后,kubeadm join 才会继续。

关闭对集群信息 ConfigMap 的公开访问

为了实现使用令牌作为唯一验证信息的加入工作流,默认情况下会公开带有验证主节点标识所需数据的 ConfigMap。 虽然此 ConfigMap 中没有私有数据,但一些用户可能希望无论如何都关闭它。 这样做需要禁用 kubeadm join 工作流的 --discovery-token 参数。 以下是实现步骤:

$ kubectl -n kube-public get cm cluster-info -o yaml | grep "kubeconfig:" -A11 | grep "apiVersion" -A10 | sed "s/    //" | tee cluster-info.yaml
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <ca-cert>
    server: https://<ip>:<port>
  name: ""
contexts: []
current-context: ""
kind: Config
preferences: {}
users: []
  • 使用 cluster-info.yaml 文件作为 kubeadm join --discovery-file 参数。

  • 关闭 cluster-info ConfigMap 的公开访问:

$ kubectl -n kube-public delete rolebinding kubeadm:bootstrap-signer-clusterinfo

这些命令应该在执行 kubeadm init 之后、在kubeadm join 之前执行。

使用带有配置文件的 kubeadm join

警告:

配置文件目前是 alpha 功能,在将来的版本中可能会变动。

可以用配置文件替代命令行参数的方法配置 kubeadm join,一些高级功能也只有在使用配置文件时才可选用。 该文件通过 --config 参数来传递,并且文件中必须包含 JoinConfiguration 结构。

执行下面的命令可以查看 JoinConfiguration 默认值:

kubeadm config print-default --api-objects=JoinConfiguration

要了解 JoinConfiguration 中各个字段的详细信息请参考 godoc

接下来