kubeadm 配置 (v1beta3)

概述

v1beta3 包定义 v1beta3 版本的 kubeadm 配置文件格式。 此版本改进了 v1beta2 的格式，修复了一些小问题并添加了一些新的字段。

从 v1beta2 版本以来的变更列表：

• 已弃用的字段 “ClusterConfiguration.useHyperKubeImage” 现在被移除。 kubeadm 不再支持 hyperkube 镜像。
• “ClusterConfiguration.dns.type” 字段已经被移除，因为 CoreDNS 是 kubeadm 所支持的唯一 DNS 服务器类型。
• 保存 Secret 信息的字段现在包含了 “datapolicy” 标记（tag）。 这一标记会导致 API 结构通过 klog 打印输出时，会忽略这些字段的值。
• 添加了 “InitConfiguration.skipPhases”、”JoinConfiguration.skipPhases”， 以允许在执行 kubeadm init/join 命令时略过某些阶段。
• 添加了 “InitConfiguration.nodeRegistration.imagePullPolicy” 和 “JoinConfiguration.nodeRegistration.imagePullPolicy” 以允许在 kubeadm init 和 kubeadm join 期间指定镜像拉取策略。 这两个字段的值必须是 “Always”、”Never” 或 “IfNotPresent” 之一。 默认值是 “IfNotPresent”，也是添加此字段之前的默认行为。
• 添加了 “InitConfiguration.patches.directory” 和 “JoinConfiguration.patches.directory” 以允许用户配置一个目录， kubeadm 将从该目录中提取组件的补丁包。
• BootstrapToken* API 和相关的工具被从 “kubeadm” API 组中移出， 放到一个新的 “bootstraptoken” 组中。kubeadm API 版本 v1beta3 不再包含 BootstrapToken* 结构。

从老的 kubeadm 配置版本迁移：

• kubeadm v1.15.x 及更新的版本可以用来从 v1beta1 迁移到 v1beta2 版本；
• kubeadm v1.22.x 及更新的版本不再支持 v1beta1 和更老的 API，但可以用来从 v1beta2 迁移到 v1beta3。

基础知识

配置 kubeadm 的推荐方式是使用 --config 选项向其传递一个 YAML 配置文件。 kubeadm 配置文件中定义的某些配置选项也可以作为命令行标志来使用，不过这种方法所支持的都是一些最常见的、最简单的使用场景。

一个 kubeadm 配置文件中可以包含多个配置类型，使用三根横线（---）作为分隔符。

kubeadm 支持以下配置类型：

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
apiVersion: kubeadm.k8s.io/v1beta3
kind: JoinConfiguration

要输出 “init” 和 “join” 动作的默认值，可以使用下面的命令：

kubeadm config print init-defaults
kubeadm config print join-defaults

配置文件中必须包含的配置类型列表取决于你在执行的动作（init 或 join）， 也取决于你要使用的配置选项（默认值或者高级定制）。

如果某些配置类型没有提供，或者仅部分提供，kubeadm 将使用默认值； kubeadm 所提供的默认值在必要时也会保证其在多个组件之间是一致的 （例如控制器管理器上的 --cluster-cidr 参数和 kube-proxy 上的 clusterCIDR）。

用户总是可以重载默认配置值，唯一的例外是一小部分与安全性相关联的配置 （例如在 API 服务器上强制实施 Node 和 RBAC 鉴权模式）。

如果用户所提供的配置类型并非你所执行的操作需要的，kubeadm 会忽略这些配置类型并打印警告信息。

kubeadm init 配置类型

当带有 --config 选项来执行 kubeadm init 命令时，可以使用下面的配置类型： InitConfiguration、ClusterConfiguration、KubeProxyConfiguration、KubeletConfiguration， 但 InitConfiguration 和 ClusterConfiguration 之间只有一个是必须提供的。

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
bootstrapTokens:
  ...
nodeRegistration:
  ...

类型 InitConfiguration 用来配置运行时设置，就 kubeadm init 命令而言， 包括启动引导令牌以及所有与 kubeadm 所在节点相关的设置，包括：

• nodeRegistration：其中包含与向集群注册新节点相关的字段； 使用这个类型来定制节点名称、要使用的 CRI 套接字或者其他仅对当前节点起作用的设置 （例如节点 IP 地址）。
• localAPIEndpoint：代表的是要部署到此节点上的 API 服务器实例的端点； 使用这个类型可以完成定制 API 服务器公告地址这类操作。

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
networking:
  ...
etcd:
  ...
apiServer:
  extraArgs:
    ...
  extraVolumes:
    ...
...

类型 ClusterConfiguration 用来定制集群范围的设置，具体包括以下设置：

• networking：其中包含集群的网络拓扑配置。使用这一部分可以定制 Pod 的子网或者 Service 的子网。

• etcd：etcd 数据库的配置。例如使用这个部分可以定制本地 etcd 或者配置 API 服务器使用一个外部的 etcd 集群。

• kube-apiserver、kube-scheduler、kube-controller-manager 配置：这些部分可以通过添加定制的设置或者重载 kubeadm 的默认设置来定制控制面组件。

apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
  ...

KubeProxyConfiguration 类型用来更改传递给在集群中部署的 kube-proxy 实例的配置。 如果此对象没有提供，或者仅部分提供，kubeadm 使用默认值。

关于 kube-proxy 的官方文档，可参阅 https://kubernetes.io/zh-cn/docs/reference/command-line-tools-reference/kube-proxy/ 或者 https://pkg.go.dev/k8s.io/kube-proxy/config/v1alpha1#KubeProxyConfiguration。

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
  ...

KubeletConfiguration 类型用来更改传递给在集群中部署的 kubelet 实例的配置。 如果此对象没有提供，或者仅部分提供，kubeadm 使用默认值。

关于 kubelet 的官方文档，可参阅 https://kubernetes.io/zh-cn/docs/reference/command-line-tools-reference/kubelet/ 或者 https://pkg.go.dev/k8s.io/kubelet/config/v1beta1#KubeletConfiguration。

下面是一个为执行 kubeadm init 而提供的、包含多个配置类型的单一 YAML 文件， 其中填充了很多部分。

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
bootstrapTokens:
  - token: "9a08jv.c0izixklcxtmnze7"
    description: "kubeadm bootstrap token"
    ttl: "24h"
  - token: "783bde.3f89s0fje9f38fhf"
    description: "another bootstrap token"
    usages:
      - authentication
      - signing
    groups:
      - system:bootstrappers:kubeadm:default-node-token
nodeRegistration:
  name: "ec2-10-100-0-1"
  criSocket: "/var/run/dockershim.sock"
  taints:
    - key: "kubeadmNode"
      value: "someValue"
      effect: "NoSchedule"
  kubeletExtraArgs:
    v: 4
  ignorePreflightErrors:
    - IsPrivilegedUser
  imagePullPolicy: "IfNotPresent"
localAPIEndpoint:
  advertiseAddress: "10.100.0.1"
  bindPort: 6443
certificateKey: "e6a2eb8581237ab72a4f494f30285ec12a9694d750b9785706a83bfcbbbd2204"
skipPhases:
  - addon/kube-proxy
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
etcd:
  # one of local or external
  local:
    imageRepository: "registry.k8s.io"
    imageTag: "3.2.24"
    dataDir: "/var/lib/etcd"
    extraArgs:
      listen-client-urls: "http://10.100.0.1:2379"
    serverCertSANs:
      -  "ec2-10-100-0-1.compute-1.amazonaws.com"
    peerCertSANs:
      - "10.100.0.1"
  # external:
    # endpoints:
    # - "10.100.0.1:2379"
    # - "10.100.0.2:2379"
    # caFile: "/etcd/kubernetes/pki/etcd/etcd-ca.crt"
    # certFile: "/etcd/kubernetes/pki/etcd/etcd.crt"
    # keyFile: "/etcd/kubernetes/pki/etcd/etcd.key"
networking:
  serviceSubnet: "10.96.0.0/16"
  podSubnet: "10.244.0.0/24"
  dnsDomain: "cluster.local"
kubernetesVersion: "v1.21.0"
controlPlaneEndpoint: "10.100.0.1:6443"
apiServer:
  extraArgs:
    authorization-mode: "Node,RBAC"
  extraVolumes:
    - name: "some-volume"
      hostPath: "/etc/some-path"
      mountPath: "/etc/some-pod-path"
      readOnly: false
      pathType: File
  certSANs:
    - "10.100.1.1"
    - "ec2-10-100-0-1.compute-1.amazonaws.com"
  timeoutForControlPlane: 4m0s
controllerManager:
  extraArgs:
    "node-cidr-mask-size": "20"
  extraVolumes:
    - name: "some-volume"
      hostPath: "/etc/some-path"
      mountPath: "/etc/some-pod-path"
      readOnly: false
      pathType: File
scheduler:
  extraArgs:
    bind-address: "10.100.0.1"
  extraVolumes:
    - name: "some-volume"
      hostPath: "/etc/some-path"
      mountPath: "/etc/some-pod-path"
      readOnly: false
      pathType: File
certificatesDir: "/etc/kubernetes/pki"
imageRepository: "registry.k8s.io"
clusterName: "example-cluster"
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
# kubelet specific options here
---
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
# kube-proxy specific options here

kubeadm join 配置类型

当使用 --config 选项执行 kubeadm join 命令时， 需要提供 JoinConfiguration 类型。

apiVersion: kubeadm.k8s.io/v1beta3
kind: JoinConfiguration
  ...

JoinConfiguration 类型用来配置运行时设置，就 kubeadm join 而言包括用来访问集群信息的发现方法，以及所有特定于 kubeadm 执行所在节点的设置，包括：

• nodeRegistration：其中包含向集群注册新节点相关的配置字段； 使用这个类型可以定制节点名称、用使用的 CRI 套接字和所有其他仅适用于当前节点的设置 （例如节点 IP 地址）。
• apiEndpoint：用来代表最终要部署到此节点上的 API 服务器实例的端点。

资源类型

• ClusterConfiguration
• InitConfiguration
• JoinConfiguration

BootstrapToken

出现在：

• InitConfiguration

BootstrapToken 描述的是一个启动引导令牌，以 Secret 形式存储在集群中。

BootstrapTokenString

出现在：

• BootstrapToken

BootstrapTokenString 形式为 abcdef.abcdef0123456789 的一个令牌， 用来从加入集群的节点角度验证 API 服务器的身份，或者 “kubeadm join” 在节点启动引导时作为一种身份认证方法。 此令牌的生命期是短暂的，并且应该如此。

ClusterConfiguration

ClusterConfiguration 包含一个 kubeadm 集群的集群范围配置信息。

InitConfiguration

InitConfiguration 包含一组特定于 “kubeadm init” 的运行时元素。 这里的字段仅用于第一次运行 kubeadm init 命令。 之后，此结构中的字段信息不会再被上传到 kubeadm upgrade 所要使用的 kubeadm-config ConfigMap 中。 这些字段必须设置 “omitempty”

JoinConfiguration

JoinConfiguration 包含描述特定节点的元素。

APIEndpoint

出现在：

• InitConfiguration
• JoinControlPlane

APIEndpoint 结构包含某节点上部署的 API 服务器的配置元素。

APIServer

出现在：

• ClusterConfiguration

APIServer 包含集群中 API 服务器部署所必需的设置。

BootstrapTokenDiscovery

出现在：

• Discovery

BootstrapTokenDiscovery 用来设置基于引导令牌的服务发现选项。

ControlPlaneComponent

出现在：

• ClusterConfiguration
• APIServer

ControlPlaneComponent 中包含对集群中所有控制面组件都适用的设置。

DNS

出现在：

• ClusterConfiguration

DNS 结构定义要在集群中使用的 DNS 插件。

Discovery

出现在：

• JoinConfiguration

Discovery 设置 TLS 启动引导过程中 kubelet 要使用的配置选项。

Etcd

出现在：

• ClusterConfiguration

Etcd 包含用来描述 etcd 配置的元素。

ExternalEtcd

出现在：

• Etcd

ExternalEtcd 描述外部 etcd 集群。 kubeadm 不清楚证书文件的存放位置，因此必须单独提供证书信息。

FileDiscovery

出现在：

• Discovery

FileDiscovery 用来指定一个文件或者 URL 路径，指向一个 kubeconfig 文件； 该配置文件可用来加载集群信息。

HostPathMount

出现在：

• ControlPlaneComponent

HostPathMount 包含从主机节点挂载的卷的信息。

ImageMeta

出现在：

• DNS
• LocalEtcd

ImageMeta 用来配置来源不是 Kubernetes/kubernetes 发布过程的组件所使用的镜像。

JoinControlPlane

出现在：

• JoinConfiguration

JoinControlPlane 包含在正在加入集群的节点上要部署的额外的控制面组件的设置。

LocalEtcd

出现在：

• Etcd

LocalEtcd 描述的是 kubeadm 要使用的本地 etcd 集群。

Networking

出现在：

• ClusterConfiguration

Networking 中包含描述集群网络配置的元素。

NodeRegistrationOptions

出现在：

• InitConfiguration
• JoinConfiguration

NodeRegistrationOptions 包含向集群中注册新的控制面或节点所需要的信息； 节点注册可能通过 “kubeadm init” 或 “kubeadm join” 完成。

Patches

出现在：

• InitConfiguration
• JoinConfiguration

Patches 包含要向 kubeadm 所部署的组件应用的补丁信息。