kubeadm 配置 (v1beta3)

概述

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

自 v1beta2 以来的更改列表

• 已删除已弃用的 "ClusterConfiguration.useHyperKubeImage" 字段。kubeadm 不再支持 hyperkube 镜像。
• 由于 CoreDNS 是 kubeadm 支持的唯一 DNS 服务器类型，因此已删除 "ClusterConfiguration.dns.type" 字段。
• 在包含密钥的字段上包含 "datapolicy" 标签。这将导致在用 klog 打印 API 结构时省略字段值。
• 添加 "InitConfiguration.skipPhases" 和 "JoinConfiguration.skipPhases" 以允许在 kubeadm init/join 命令执行期间跳过阶段列表。
• 添加 "InitConfiguration.nodeRegistration.imagePullPolicy" 和 "JoinConfiguration.nodeRegistration.imagePullPolicy" 以允许在 kubeadm "init" 和 "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 v1.27.x 及更高版本不再支持 v1beta2 及更早的 API。

基础知识

配置 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 子网或服务子网。

• 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.ac.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.ac.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 服务器实例的端点。

弃用：v1beta3 在 v1beta4 取代，将在未来的版本中删除，1.34 或更高版本。请迁移

资源类型

• 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 init 首次运行时使用。之后，字段中的信息将不会上传到 kubeadm-config ConfigMap，该 ConfigMap 由 kubeadm upgrade 等使用。这些字段必须为空。

JoinConfiguration

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

APIEndpoint

出现于

• InitConfiguration

• JoinControlPlane

APIEndpoint struct 包含部署在节点上的 API 服务器实例的元素。

APIServer

出现于

• ClusterConfiguration

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

BootstrapTokenDiscovery

出现于

• Discovery

BootstrapTokenDiscovery 用于设置基于 bootstrap token 的发现的选项。

ControlPlaneComponent

出现于

• ClusterConfiguration

• APIServer

ControlPlaneComponent 包含集群控制平面组件通用的设置

DNS

出现于

• ClusterConfiguration

DNS 定义了集群中应使用的 DNS 插件

Discovery

出现于

• JoinConfiguration

Discovery 指定 kubelet 在 TLS 引导过程中使用的选项。

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 集群。

网络

出现于

• ClusterConfiguration

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

NodeRegistrationOptions

出现于

• InitConfiguration

• JoinConfiguration

NodeRegistrationOptions 包含与通过 kubeadm init 或 kubeadm join 将新的控制平面或节点注册到集群相关的字段。

Patches

出现于

• InitConfiguration

• JoinConfiguration

Patches 包含与应用 kubeadm 部署的组件的补丁相关的选项。