kubeadm 配置 (v1beta4)

概览

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

自 v1beta3 以来的变更列表

• 在 ClusterConfiguration 下的控制平面组件中支持自定义环境变量。使用 apiServer.extraEnvs、controllerManager.extraEnvs、scheduler.extraEnvs、etcd.local.extraEnvs。
• ResetConfiguration API 类型现已在 v1beta4 中受支持。用户可以通过向 kubeadm reset 传递 --config 文件来重置节点。
• 干运行模式 (dry run mode) 现可在 InitConfiguration 和 JoinConfiguration 中配置。
• 将现有的 string/string 额外参数映射替换为支持重复的结构化额外参数。此更改适用于 ClusterConfiguration - apiServer.extraArgs、controllerManager.extraArgs、scheduler.extraArgs、etcd.local.extraArgs。也适用于 nodeRegistration.kubeletExtraArgs。
• 添加 ClusterConfiguration.encryptionAlgorithm，可用于设置此集群密钥和证书使用的非对称加密算法。可以是 "RSA-2048"（默认）、"RSA-3072"、"RSA-4096" 或 "ECDSA-P256" 中的一个。
• 添加 ClusterConfiguration.dns.disabled 和 ClusterConfiguration.proxy.disabled，可用于在集群初始化期间禁用 CoreDNS 和 kube-proxy 附加组件。在集群创建期间跳过相关的附加组件阶段将把相同的字段设置为 true。
• 在 InitConfiguration 和 JoinConfiguration 中添加 nodeRegistration.imagePullSerial 字段，可用于控制 kubeadm 是串行还是并行拉取镜像。
• 将 --config 传递给 kubeadm upgrade 子命令时，v1beta4 现在支持 UpgradeConfiguration kubeadm API。在使用 --config 传递给 upgrade 子命令时，对 kubelet 和 kube-proxy 的组件配置以及 InitConfiguration 和 ClusterConfiguration 的使用已被弃用，并将被忽略。
• 向 InitConfiguration、JoinConfiguration、ResetConfiguration 和 UpgradeConfiguration 中添加 Timeouts 结构，可用于配置各种超时。ClusterConfiguration.timeoutForControlPlane 字段被 Timeouts.controlPlaneComponentHealthCheck 替换。JoinConfiguration.discovery.timeout 被 timeouts.Discovery 替换。
• 向 ClusterConfiguration 中添加 certificateValidityPeriod 和 caCertificateValidityPeriod 字段。这些字段可用于控制 kubeadm 在 init、join、upgrade 和 certs 等子命令期间生成的证书的有效期。非 CA 证书的默认值仍然是 1 年，CA 证书的默认值仍然是 10 年。只有非 CA 证书可以继续通过 kubeadm certs renew 进行续订。

从旧的 kubeadm 配置版本迁移

• kubeadm v1.15.x 及更新版本可用于从 v1beta1 迁移到 v1beta2。
• kubeadm v1.22.x 及更新版本不再支持 v1beta1 和更旧的 API，但可用于将 v1beta2 迁移到 v1beta3。
• kubeadm v1.27.x 及更新版本不再支持 v1beta2 和更旧的 API。
• kubeadm v1.31.x 及更新版本可用于从 v1beta3 迁移到 v1beta4。

基础知识

配置 kubeadm 的首选方法是使用 --config 选项传递 YAML 配置文件。kubeadm 配置文件中定义的一些配置选项也可以作为命令行标志使用，但这种方法只支持最常见/简单的用例。

一个 kubeadm 配置文件可以包含使用三个破折号 (---) 分隔的多种配置类型。

kubeadm 支持以下配置类型

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration

apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration

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

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

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

apiVersion: kubeadm.k8s.io/v1beta4
kind: ResetConfiguration

apiVersion: kubeadm.k8s.io/v1beta4
kind: UpgradeConfiguration

要打印 init 和 join 操作的默认配置，请使用以下命令

kubeadm config print init-defaults
kubeadm config print join-defaults
kubeadm config print reset-defaults
kubeadm config print upgrade-defaults

配置文件中必须包含的配置类型列表取决于你正在执行的操作 (init 或 join) 以及你将使用的配置选项（默认值或高级定制）。

如果未提供某些配置类型，或者仅提供部分内容，kubeadm 将使用默认值；kubeadm 提供的默认值还包括在需要时强制执行组件之间的值一致性（例如，controller manager 上的 --cluster-cidr 标志和 kube-proxy 上的 clusterCIDR）。

用户始终可以覆盖默认值，但与安全相关的一小部分设置除外（例如，强制 api server 使用 authorization-mode Node 和 RBAC）。

如果用户提供了与你正在执行的操作不符的配置类型，kubeadm 将忽略这些类型并打印警告。

Kubeadm init 配置类型

使用 --config 选项执行 kubeadm init 时，可以使用以下配置类型：InitConfiguration, ClusterConfiguration, KubeProxyConfiguration, KubeletConfiguration，但 InitConfiguration 和 ClusterConfiguration 中只有一个是必需的。

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

InitConfiguration 类型应用于配置运行时设置，在 kubeadm init 的情况下，这些设置包括引导令牌的配置以及执行 kubeadm 的节点特有的所有设置，包括

• NodeRegistration，它包含与将新节点注册到集群相关的字段；使用它来定制节点名称、要使用的 CRI 套接字或应仅应用于此节点的任何其他设置（例如节点 IP）。

• LocalAPIEndpoint，它表示要部署在此节点上的 API 服务器实例的端点；例如，使用它来定制 API 服务器的广播地址。

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

ClusterConfiguration 类型应用于配置集群范围的设置，包括以下设置：

• networking，它包含集群网络拓扑的配置；例如，使用它来定制 Pod 子网或 Services 子网。

• 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。

以下是一个包含多个配置类型的单个 YAML 文件的完整示例，可在运行 kubeadm init 期间使用。

apiVersion: kubeadm.k8s.io/v1beta4
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: "unix:///var/run/containerd/containerd.sock"
  taints:
    - key: "kubeadmNode"
      value: "someValue"
      effect: "NoSchedule"
  kubeletExtraArgs:
    - name: v
      value: "5"
  ignorePreflightErrors:
    - IsPrivilegedUser
  imagePullPolicy: "IfNotPresent"
  imagePullSerial: true

localAPIEndpoint:
  advertiseAddress: "10.100.0.1"
  bindPort: 6443
certificateKey: "e6a2eb8581237ab72a4f494f30285ec12a9694d750b9785706a83bfcbbbd2204"
skipPhases:
  - preflight
timeouts:
  controlPlaneComponentHealthCheck: "60s"
  kubenetesAPICall: "40s"
---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
etcd:

  # one of local or external
  local:
    imageRepository: "registry.k8s.io"
    imageTag: "3.2.24"
    dataDir: "/var/lib/etcd"
    extraArgs:
      - name: listen-client-urls
        value: http://10.100.0.1:2379
    extraEnvs:
      - name: SOME_VAR
        value: SOME_VALUE
    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:
    - name: authorization-mode
      value: Node,RBAC
  extraEnvs:
    - name: SOME_VAR
      value: SOME_VALUE
  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"

controllerManager:
  extraArgs:
    - name: node-cidr-mask-size
      value: "20"
  extraVolumes:
    - name: "some-volume"
      hostPath: "/etc/some-path"
      mountPath: "/etc/some-pod-path"
      readOnly: false
      pathType: File

scheduler:
  extraArgs:
    - name: address
      value: 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"
encryptionAlgorithm: ECDSA-P256
dns:
  disabled: true  # disable CoreDNS
proxy:
  disabled: true   # disable kube-proxy

---
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/v1beta4
kind: JoinConfiguration
discovery:
  bootstrapToken:
    apiServerEndpoint: some-address:6443
    token: abcdef.0123456789abcdef
    unsafeSkipCAVerification: true
  tlsBootstrapToken: abcdef.0123456789abcdef

JoinConfiguration 类型应用于配置运行时设置，在 kubeadm join 的情况下，这些设置包括用于访问集群信息的发现方法以及执行 kubeadm 的节点特有的所有设置，包括

• nodeRegistration，它包含与将新节点注册到集群相关的字段；使用它来定制节点名称、要使用的 CRI 套接字或应仅应用于此节点的任何其他设置（例如节点 IP）。

• apiEndpoint，它表示最终将部署在此节点上的 API 服务器实例的端点。

Kubeadm reset 配置类型

使用 --config 选项执行 kubeadm reset 时，应提供 ResetConfiguration 类型。

apiVersion: kubeadm.k8s.io/v1beta4
kind: ResetConfiguration
...

Kubeadm upgrade 配置类型

使用 --config 选项执行 kubeadm upgrade 时，应提供 UpgradeConfiguration 类型。

apiVersion: kubeadm.k8s.io/v1beta4
kind: UpgradeConfiguration
apply:
  ...
diff:
  ...
node:
  ...
plan:
  ...

UpgradeConfiguration 结构包含一些仅适用于 kubeadm upgrade 不同子命令的子结构。例如，apply 子结构将与 kubeadm upgrade apply 子命令一起使用，在这种情况下将忽略所有其他子结构。

资源类型

• ClusterConfiguration
• InitConfiguration
• JoinConfiguration
• ResetConfiguration
• UpgradeConfiguration

BootstrapToken

出现在

• InitConfiguration

• InitConfiguration

BootstrapToken 描述了一个引导令牌，它作为 Secret 存储在集群中

BootstrapTokenString

出现在

• BootstrapToken

BootstrapTokenString 是一个格式为 abcdef.abcdef0123456789 的令牌，用于从加入节点的角度验证 API 服务器的可用性，并作为节点在 "kubeadm join" 引导阶段的身份验证方法。此令牌是且应该是短期的。

ClusterConfiguration

ClusterConfiguration 包含 kubeadm 集群的集群范围配置。

InitConfiguration

InitConfiguration 包含一系列仅限 "kubeadm init" 运行时的特定信息。仅限 kubeadm init 的信息。这些字段仅在首次运行 kubeadm init 时使用。之后，这些字段中的信息不会上传到用于 kubeadm upgrade 等命令的 kubeadm-config ConfigMap。这些字段必须可省略 (omitempty)。

JoinConfiguration

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

ResetConfiguration

ResetConfiguration 包含一系列专门用于 kubeadm reset 的运行时信息字段。

UpgradeConfiguration

UpgradeConfiguration 包含一系列特定于 kubeadm upgrade 子命令的选项。

APIEndpoint

出现在

• InitConfiguration

• JoinControlPlane

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

APIServer

出现在

• ClusterConfiguration

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

Arg

出现在

• ControlPlaneComponent

• LocalEtcd

• NodeRegistrationOptions

Arg 表示一个带有名称和值的参数。

BootstrapTokenDiscovery

出现在

• Discovery

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

ControlPlaneComponent

出现在

• ClusterConfiguration

• APIServer

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

DNS

出现在

• ClusterConfiguration

DNS 定义了集群中应使用的 DNS 附加组件。

Discovery

出现在

• JoinConfiguration

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

EncryptionAlgorithmType

(string 的别名)

出现在

• ClusterConfiguration

EncryptionAlgorithmType 可以定义非对称加密算法类型。

EnvVar

出现在

• ControlPlaneComponent

• LocalEtcd

EnvVar 表示容器中存在的环境变量。

Etcd

出现在

• ClusterConfiguration

Etcd 包含描述 Etcd 配置的元素。

ExternalEtcd

出现在

• Etcd

ExternalEtcd 描述外部 etcd 集群。Kubeadm 不知道证书文件的位置，它们必须由用户提供。

FileDiscovery

出现在

• Discovery

FileDiscovery 用于指定一个文件或 URL，该文件或 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

• UpgradeApplyConfiguration

• UpgradeNodeConfiguration

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

Proxy

出现在

• ClusterConfiguration

Proxy 定义了集群中应该使用的代理插件。

Timeouts

出现在

• InitConfiguration

• JoinConfiguration

• ResetConfiguration

• UpgradeConfiguration

Timeouts 包含适用于 kubeadm 命令的各种超时设置。

UpgradeApplyConfiguration

出现在

• UpgradeConfiguration

UpgradeApplyConfiguration 包含特定于 "kubeadm upgrade apply" 命令的可配置选项列表。

UpgradeDiffConfiguration

出现在

• UpgradeConfiguration

UpgradeDiffConfiguration 包含特定于 kubeadm upgrade diff 命令的可配置选项列表。

UpgradeNodeConfiguration

出现在

• UpgradeConfiguration

UpgradeNodeConfiguration 包含特定于 "kubeadm upgrade node" 命令的可配置选项列表。

UpgradePlanConfiguration

出现在

• UpgradeConfiguration

UpgradePlanConfiguration 包含特定于 "kubeadm upgrade plan" 命令的可配置选项列表。