kubeadm 組態 (v1beta4)

概觀

套件 v1beta4 定義 kubeadm 組態檔案格式的 v1beta4 版本。此版本改進 v1beta3 格式，修正一些小問題並新增一些欄位。

自 v1beta3 以來的變更清單

• 在 ClusterConfiguration 下的控制平面元件中支援自訂環境變數。使用 apiServer.extraEnvs、controllerManager.extraEnvs、scheduler.extraEnvs、etcd.local.extraEnvs。
• v1beta4 現在支援 ResetConfiguration API 類型。使用者可以透過將 --config 檔案傳遞至 kubeadm reset 來重設節點。
• 現在可以在 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 是否依序或平行提取映像檔。
• 當將 --config 傳遞至 kubeadm upgrade 子命令時，v1beta4 現在支援 UpgradeConfiguration kubeadm API。將元件組態用於 kubelet 和 kube-proxy、InitConfiguration 和 ClusterConfiguration 已棄用，並且在將 --config 傳遞至 upgrade 子命令時會被忽略。
• 在 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 的建議方式是傳遞 YAML 設定檔，並搭配 --config 選項。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 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 的情況下，這些設定是 bootstrap token 的設定以及所有特定於執行 kubeadm 的節點的設定，包括

• NodeRegistration，其中包含與將新節點註冊到叢集相關的欄位；使用它來自訂節點名稱、要使用的 CRI socket 或任何其他應僅適用於此節點的設定 (例如，節點 IP)。

• LocalAPIEndpoint，代表要在此節點上部署的 API server 實例的端點；使用它來自訂 API server 宣告位址 (advertise address) 等。

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

ClusterConfiguration 類型應用於設定叢集範圍的設定，包括以下設定

• networking，其中包含叢集網路拓撲的設定；使用它來自訂 Pod 子網路或服務子網路等。

• etcd：使用它來自訂本機 etcd 或設定 API server 以使用外部 etcd 叢集等。

• kube-apiserver、kube-scheduler、kube-controller-manager 設定；使用它來自訂控制平面組件，方法是新增自訂設定或覆寫 kubeadm 預設設定。

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

KubeProxyConfiguration 類型應用於變更傳遞到叢集中部署的 kube-proxy 實例的設定。如果未提供此物件或僅部分提供，kubeadm 將套用預設值。

請參閱 https://kubernetes.dev.org.tw/docs/reference/command-line-tools-reference/kube-proxy/ 或 https://pkg.go.dev/k8s.io/kube-proxy/config/v1alpha1#KubeProxyConfiguration 以取得 kube-proxy 官方文件。

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

KubeletConfiguration 類型應用於變更將傳遞到叢集中部署的所有 kubelet 實例的設定。如果未提供此物件或僅部分提供，kubeadm 將套用預設值。

請參閱 https://kubernetes.dev.org.tw/docs/reference/command-line-tools-reference/kubelet/ 或 https://pkg.go.dev/k8s.io/kubelet/config/v1beta1#KubeletConfiguration 以取得 kubelet 官方文件。

以下是一個完整填寫的 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 socket 或任何其他應僅適用於此節點的設定 (例如，節點 IP)。

• apiEndpoint，代表最終將在此節點上部署的 API server 實例的端點。

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 描述一個 bootstrap token，以 Secret 形式儲存在叢集中

BootstrapTokenString

出現在

• BootstrapToken

BootstrapTokenString 是一個格式為 abcdef.abcdef0123456789 的 token，用於從加入節點的角度驗證 API server 的實用性，以及作為節點在 "kubeadm join" 啟動階段的驗證方法。此 token 是且應該是短效期的。

ClusterConfiguration

ClusterConfiguration 包含 kubeadm 叢集的叢集範圍設定。

InitConfiguration

InitConfiguration 包含特定於 "kubeadm init" 的執行階段資訊元素列表。kubeadm init 的專用資訊。這些欄位僅在第一次執行 kubeadm init 時使用。之後，欄位中的資訊不會上傳到 kubeadm-config ConfigMap，該 ConfigMap 由 kubeadm upgrade 等使用。這些欄位必須為 omitempty。

JoinConfiguration

JoinConfiguration 包含描述特定節點的元素。

ResetConfiguration

ResetConfiguration 包含特定於 kubeadm reset 的執行階段資訊欄位列表。

UpgradeConfiguration

UpgradeConfiguration 包含特定於 kubeadm upgrade 子命令的選項列表。

APIEndpoint

出現在

• InitConfiguration

• JoinControlPlane

APIEndpoint 結構包含節點上部署的 API server 實例的元素。

APIServer

出現在

• ClusterConfiguration

APIServer 保留叢集中 API server 部署的必要設定

Arg

出現在

• ControlPlaneComponent

• LocalEtcd

• NodeRegistrationOptions

Arg 代表具有名稱和值的引數。

BootstrapTokenDiscovery

出現在

• Discovery

BootstrapTokenDiscovery 用於設定基於 bootstrap token 的探索選項。

ControlPlaneComponent

出現在

• ClusterConfiguration

• APIServer

ControlPlaneComponent 保留叢集控制平面組件的通用設定

DNS

出現在

• ClusterConfiguration

DNS 定義應在叢集中使用的 DNS 附加元件

Discovery

出現在

• JoinConfiguration

Discovery 指定 kubelet 在 TLS Bootstrap 程序期間使用的選項

EncryptionAlgorithmType

(string 的別名)

出現在

• ClusterConfiguration

EncryptionAlgorithmType 可以定義非對稱加密演算法類型。

EnvVar

出現在

• ControlPlaneComponent

• LocalEtcd

EnvVar 代表容器中存在的環境變數。

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

• UpgradeApplyConfiguration

• UpgradeNodeConfiguration

Patches 包含與將修補程式套用至 kubeadm 部署的組件相關的選項。

Proxy

出現在

• ClusterConfiguration

Proxy 定義應在叢集中使用的 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" 命令。