kubeadm 配置 (v1beta3)

概述

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

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

• 已弃用的字段 "ClusterConfiguration.useHyperKubeImage" 现在被移除。 kubeadm 不再支持 hyperkube 镜像。
• 字段 "ClusterConfiguration.dns.type" 已经被移除，因为 CoreDNS 是 kubeadm 所支持 的唯一 DNS 服务器类型。
• 保存私密信息的字段现在包含了 "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/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/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

ClusterConfiguration

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

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 所部署的组件应用的补丁信息。

BootstrapToken

出现在：

• InitConfiguration

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

BootstrapTokenString

出现在：

• BootstrapToken

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