kubeadm 配置 (v1beta4)

概述

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

v1beta3 以来更改列表

v1.33

• 向 UpgradeConfiguration.plan 添加 EtcdUpgrade 字段，可用于控制是否显示 etcd 升级计划。

v1.31

• 在 ClusterConfiguration 下支持控制平面组件中的自定义环境变量。使用 apiServer.extraEnvs、controllerManager.extraEnvs、scheduler.extraEnvs、etcd.local.extraEnvs。
• v1beta4 现在支持 ResetConfiguration API 类型。用户可以通过向 kubeadm reset 传递 --config 文件来重置节点。
• 现在可以在 InitConfiguration 和 JoinConfigurationB 中配置试运行模式。
• 将现有的字符串/字符串额外参数映射替换为支持重复项的结构化额外参数。此更改适用于 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 是串行还是并行拉取镜像。
• 现在 v1beta4 支持 UpgradeConfiguration kubeadm API，通过向 kubeadm upgrade 子命令传递 --config。对于 kubelet 和 kube-proxy、InitConfiguration 和 ClusterConfiguration 的组件配置用法已被弃用，在向 upgrade 子命令传递 --config 时将被忽略。
• 向 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 提供的默认值还包括强制执行组件之间的一致性（例如，控制器管理器上的 --cluster-cidr 标志和 kube-proxy 上的 clusterCIDR）。

用户始终可以覆盖默认值，唯一例外的是一小部分与安全性相关的设置（例如，强制 API 服务器的 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 子网或服务子网。

• 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/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 配置类型

执行 kubeadm join 并使用 --config 选项时，应提供 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-config ConfigMap，因为 kubeadm upgrade 等工具会使用该 ConfigMap。这些字段必须是可选的。

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

出现在

• 发现

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

ControlPlaneComponent

出现在

• ClusterConfiguration

• APIServer

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

DNS

出现在

• ClusterConfiguration

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

发现

出现在

• JoinConfiguration

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

EncryptionAlgorithmType

(string 的别名)

出现在

• ClusterConfiguration

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

EnvVar

出现在

• ControlPlaneComponent

• LocalEtcd

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

Etcd

出现在

• ClusterConfiguration

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

ExternalEtcd

出现在

• Etcd

ExternalEtcd 描述了一个外部 etcd 集群。Kubeadm 对证书文件存放位置一无所知，必须提供。

FileDiscovery

出现在

• 发现

FileDiscovery 用于指定一个 kubeconfig 文件（或 URL），从中加载集群信息。

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”命令的可配置选项。