kubeadm init

此命令用於初始化 Kubernetes 控制平面節點。

Synopsis

執行此命令以設定 Kubernetes 控制平面

“init”命令執行以下階段

preflight                     Run pre-flight checks
certs                         Certificate generation
  /ca                           Generate the self-signed Kubernetes CA to provision identities for other Kubernetes components
  /apiserver                    Generate the certificate for serving the Kubernetes API
  /apiserver-kubelet-client     Generate the certificate for the API server to connect to kubelet
  /front-proxy-ca               Generate the self-signed CA to provision identities for front proxy
  /front-proxy-client           Generate the certificate for the front proxy client
  /etcd-ca                      Generate the self-signed CA to provision identities for etcd
  /etcd-server                  Generate the certificate for serving etcd
  /etcd-peer                    Generate the certificate for etcd nodes to communicate with each other
  /etcd-healthcheck-client      Generate the certificate for liveness probes to healthcheck etcd
  /apiserver-etcd-client        Generate the certificate the apiserver uses to access etcd
  /sa                           Generate a private key for signing service account tokens along with its public key
kubeconfig                    Generate all kubeconfig files necessary to establish the control plane and the admin kubeconfig file
  /admin                        Generate a kubeconfig file for the admin to use and for kubeadm itself
  /super-admin                  Generate a kubeconfig file for the super-admin
  /kubelet                      Generate a kubeconfig file for the kubelet to use *only* for cluster bootstrapping purposes
  /controller-manager           Generate a kubeconfig file for the controller manager to use
  /scheduler                    Generate a kubeconfig file for the scheduler to use
etcd                          Generate static Pod manifest file for local etcd
  /local                        Generate the static Pod manifest file for a local, single-node local etcd instance
control-plane                 Generate all static Pod manifest files necessary to establish the control plane
  /apiserver                    Generates the kube-apiserver static Pod manifest
  /controller-manager           Generates the kube-controller-manager static Pod manifest
  /scheduler                    Generates the kube-scheduler static Pod manifest
kubelet-start                 Write kubelet settings and (re)start the kubelet
wait-control-plane            Wait for the control plane to start
upload-config                 Upload the kubeadm and kubelet configuration to a ConfigMap
  /kubeadm                      Upload the kubeadm ClusterConfiguration to a ConfigMap
  /kubelet                      Upload the kubelet component config to a ConfigMap
upload-certs                  Upload certificates to kubeadm-certs
mark-control-plane            Mark a node as a control-plane
bootstrap-token               Generates bootstrap tokens used to join a node to a cluster
kubelet-finalize              Updates settings relevant to the kubelet after TLS bootstrap
  /enable-client-cert-rotation  Enable kubelet client certificate rotation
addon                         Install required addons for passing conformance tests
  /coredns                      Install the CoreDNS addon to a Kubernetes cluster
  /kube-proxy                   Install the kube-proxy addon to a Kubernetes cluster
show-join-command             Show the join command for control-plane and worker node

kubeadm init [flags]

Options

--apiserver-advertise-address string

API Server 將宣告其正在監聽的 IP 地址。如果未設定，將使用預設網路介面。

--apiserver-bind-port int32     Default: 6443

API Server 繫結到的埠。

--apiserver-cert-extra-sans strings

用於 API Server 服務證書的可選額外主題備用名稱 (SAN)。可以是 IP 地址和 DNS 名稱。

--cert-dir string     Default: "/etc/kubernetes/pki"

用於儲存和儲存證書的路徑。

--certificate-key string

用於加密 kubeadm-certs Secret 中的控制平面證書的金鑰。證書金鑰是十六進位制編碼的字串，為 32 位元組的 AES 金鑰。

--config string

kubeadm 配置檔案路徑。

--control-plane-endpoint string

為控制平面指定穩定的 IP 地址或 DNS 名稱。

--cri-socket string

用於連線的 CRI 套接字路徑。如果為空，kubeadm 將嘗試自動檢測此值；僅當安裝了多個 CRI 或使用非標準 CRI 套接字時才使用此選項。

--dry-run

不應用任何更改；僅輸出將要執行的操作。

--feature-gates string

一組描述各種功能的鍵值對。選項包括：
ControlPlaneKubeletLocalMode=true|false (BETA - default=true)
NodeLocalCRISocket=true|false (BETA - default=true)
PublicKeysECDSA=true|false (已棄用 - default=false)
RootlessControlPlane=true|false (ALPHA - default=false)
WaitForAllControlPlaneComponents=true|false (default=true)

-h, --help

init 的幫助資訊

--ignore-preflight-errors strings

要顯示為警告的檢查錯誤列表。例如：'IsPrivilegedUser,Swap'。值 'all' 將忽略所有檢查中的錯誤。

--image-repository string     Default: "registry.k8s.io"

選擇一個容器登錄檔來拉取控制平面鏡像

--kubernetes-version string     Default: "stable-1"

為控制平面選擇特定的 Kubernetes 版本。

--node-name string

指定節點名稱。

--patches string

包含命名為“target[suffix][+patchtype].extension”的檔案的目錄路徑。例如，“kube-apiserver0+merge.yaml”或僅“etcd.json”。“target”可以是“kube-apiserver”、“kube-controller-manager”、“kube-scheduler”、“etcd”、“kubeletconfiguration”、“corednsdeployment”之一。“patchtype”可以是“strategic”、“merge”或“json”之一，它們匹配 kubectl 支援的補丁格式。“patchtype”的預設值是“strategic”。“extension”必須是“json”或“yaml”。“suffix”是一個可選字串，可用於確定應用哪個補丁（按字母數字順序）。

--pod-network-cidr string

為 Pod 網路指定 IP 地址範圍。如果設定，控制平面將為每個節點自動分配 CIDR。

--service-cidr string     Default: "10.96.0.0/12"

為服務 VIP 使用替代 IP 地址範圍。

--service-dns-domain string     Default: "cluster.local"

為服務使用替代域名，例如“myorg.internal”。

--skip-certificate-key-print

不列印用於加密控制平面證書的金鑰。

--skip-phases strings

要跳過的階段列表

--skip-token-print

跳過“kubeadm init”生成的預設引導令牌的列印。

--token string

用於在節點和控制平面節點之間建立雙向信任的令牌。格式為 [a-z0-9]{6}.[a-z0-9]{16} - 例如 abcdef.0123456789abcdef

--token-ttl duration     Default: 24h0m0s

令牌自動刪除的持續時間（例如，1s、2m、3h）。如果設定為“0”，令牌將永遠不會過期。

--upload-certs

將控制平面證書上傳到 kubeadm-certs Secret。

從父命令繼承的選項

--rootfs string

“真實”主機根檔案系統的路徑。這將導致 kubeadm chroot 到提供的路徑。

Init 工作流

kubeadm init 透過執行以下步驟引導 Kubernetes 控制平面節點。

  1. 執行一系列預檢檢查，以在進行更改之前驗證系統狀態。某些檢查只會觸發警告，而其他檢查則被視為錯誤，並將退出 kubeadm，直到問題得到糾正或使用者指定 --ignore-preflight-errors=<list-of-errors>。

  2. 生成自簽名 CA，以設定叢集中每個元件的身份。使用者可以透過將 CA 證書和/或金鑰放入透過 --cert-dir（預設為 /etc/kubernetes/pki）配置的證書目錄中來提供自己的 CA 證書和/或金鑰。API Server 證書將為任何 --apiserver-cert-extra-sans 引數包含其他 SAN 條目，必要時將進行小寫處理。

  3. 在 /etc/kubernetes/ 中為 kubelet、controller-manager 和 scheduler 寫入 kubeconfig 檔案，以便它們連線到 API Server，每個檔案都有自己的身份。此外，還會寫入其他 kubeconfig 檔案，用於 kubeadm 作為管理員實體（admin.conf）以及一個可以繞過 RBAC 的超級管理員使用者（super-admin.conf）。

  4. 為 API Server、controller-manager 和 scheduler 生成靜態 Pod manifest。如果未提供外部 etcd，則會為 etcd 生成額外的靜態 Pod manifest。

    靜態 Pod manifest 寫入 /etc/kubernetes/manifests；kubelet 會監視此目錄以在啟動時建立 Pod。

    一旦控制平面 Pod 啟動並執行，kubeadm init 序列就可以繼續。

  5. 將標籤和汙點應用於控制平面節點，以便不會在那裡執行其他工作負載。

  6. 生成附加節點將來可以使用該令牌來向控制平面註冊自己的令牌。可以選擇，使用者可以透過 --token 提供令牌，如 kubeadm token 文件中所述。

  7. 進行所有必要配置，以允許使用 Bootstrap Tokens 和 TLS Bootstrap 機制進行節點加入。

    • 寫入一個 ConfigMap，用於提供加入所需的所有資訊，並設定相關的 RBAC 訪問規則。

    • 允許 Bootstrap Tokens 訪問 CSR 簽名 API。

    • 配置對新 CSR 請求的自動批准。

    有關更多資訊，請參閱 kubeadm join。

  8. 透過 API Server 安裝 DNS 伺服器 (CoreDNS) 和 kube-proxy 附加元件。在 Kubernetes 1.11 及更高版本中，CoreDNS 是預設 DNS 伺服器。請注意，儘管 DNS 伺服器已部署，但它要到 CNI 安裝後才能排程。

使用 kubeadm 的 Init 階段

kubeadm 允許您使用 kubeadm init phase 命令分階段建立控制平面節點。

要檢視階段和子階段的有序列表，您可以呼叫 kubeadm init --help。列表將位於幫助螢幕的頂部，每個階段旁邊都將有一個描述。請注意，透過呼叫 kubeadm init，所有階段和子階段將按此確切順序執行。

有些階段有獨特的標誌，因此如果您想檢視可用選項列表，請新增 --help，例如

sudo kubeadm init phase control-plane controller-manager --help

您還可以使用 --help 檢視特定父階段的子階段列表。

sudo kubeadm init phase control-plane --help

kubeadm init 還公開了一個名為 --skip-phases 的標誌，可用於跳過特定階段。該標誌接受階段名稱列表，名稱可從上述有序列表中獲取。

一個示例

sudo kubeadm init phase control-plane all --config=configfile.yaml
sudo kubeadm init phase etcd local --config=configfile.yaml
# you can now modify the control plane and etcd manifest files
sudo kubeadm init --skip-phases=control-plane,etcd --config=configfile.yaml

此示例將根據 configfile.yaml 中的配置，在 /etc/kubernetes/manifests 中為控制平面和 etcd 編寫 manifest 檔案。這允許您修改檔案，然後使用 --skip-phases 跳過這些階段。透過呼叫最後一個命令，您將建立一個具有自定義 manifest 檔案的控制平面節點。

功能狀態： Kubernetes v1.22 [beta]

或者，您可以在 InitConfiguration 下使用 skipPhases 欄位。

使用 kubeadm init 和配置檔案

可以使用配置檔案而不是命令列標誌來配置 kubeadm init，並且一些更高階的功能可能僅作為配置檔案選項可用。此檔案透過 --config 標誌傳遞，並且必須包含 ClusterConfiguration 結構，並可選擇地包含由 ---\n 分隔的其他結構。在某些情況下，混合使用 --config 和其他標誌可能不允許。

可以使用 kubeadm config print 命令列印預設配置。

如果您的配置未使用最新版本，建議您使用 kubeadm config migrate 命令進行遷移。

有關配置的欄位和用法的更多資訊，您可以導航到我們的 API 參考頁面。

使用 kubeadm init 和功能門

kubeadm 支援一組僅對 kubeadm 獨特的功能門，這些功能門只能在透過 kubeadm init 建立叢集時應用。這些功能可以控制叢集的行為。功能門在功能畢業到 GA 後將被移除。

要傳遞功能門，您可以選擇使用 kubeadm init 的 --feature-gates 標誌，或者在透過 --config 使用 配置檔案 時將專案新增到 featureGates 欄位。

直接將 核心 Kubernetes 元件的功能門 傳遞給 kubeadm 不受支援。相反，可以透過 使用 kubeadm API 自定義元件 來傳遞它們。

功能門列表

kubeadm 功能門
特性預設AlphaBetaGA
ControlPlaneKubeletLocalModetrue1.311.33-
NodeLocalCRISockettrue1.321.34-
WaitForAllControlPlaneComponentstrue1.301.331.34

功能門描述

ControlPlaneKubeletLocalMode
啟用此功能門後，在加入新的控制平面節點時，kubeadm 將配置 kubelet 連線到本地 kube-apiserver。這可確保在滾動升級期間不會違反版本偏差策略。
NodeLocalCRISocket
啟用此功能門後，kubeadm 將從檔案 /var/lib/kubelet/instance-config.yaml 讀取/寫入每個節點的 CRI 套接字，而不是從/寫入節點物件上的註解 kubeadm.alpha.kubernetes.io/cri-socket。新檔案將作為例項配置補丁應用，在 --patches 標誌用於任何其他使用者管理的補丁之前。它包含 KubeletConfiguration 檔案格式 中的單個欄位 containerRuntimeEndpoint。如果在升級期間啟用了功能門，但檔案 /var/lib/kubelet/instance-config.yaml 尚不存在，kubeadm 將嘗試從檔案 /var/lib/kubelet/kubeadm-flags.env 讀取 CRI 套接字值。
WaitForAllControlPlaneComponents
啟用此功能門後，kubeadm 將等待控制平面節點上的所有控制平面元件（kube-apiserver、kube-controller-manager、kube-scheduler）在其 /livez 或 /healthz 端點上報告狀態 200。這些檢查是在 https://ADDRESS:PORT/ENDPOINT 上執行的。
  • PORT 取自元件的 --secure-port。
  • ADDRESS 是 kube-apiserver 的 --advertise-address，以及 kube-controller-manager 和 kube-scheduler 的 --bind-address。
  • ENDPOINT 僅是 kube-controller-manager 的 /healthz，直到它也支援 /livez。

如果您在 kubeadm 配置中指定了自定義 ADDRESS 或 PORT，它們將被遵守。在啟用功能門的情況下，kubeadm 只會等待控制平面節點上的 kube-apiserver 準備就緒。等待過程在 kubeadm 啟動主機上的 kubelet 後立即開始。建議您啟用此功能門，以在 kubeadm init 或 kubeadm join 命令執行期間觀察所有控制平面元件的就緒狀態。

已棄用的功能門列表

kubeadm 已棄用的功能門
特性預設AlphaBetaGA已棄用
PublicKeysECDSAfalse1.19--1.31
RootlessControlPlanefalse1.22--1.31

功能門描述

PublicKeysECDSA
可用於建立使用 ECDSA 證書而非預設 RSA 演算法的叢集。使用 kubeadm certs renew 也可以支援續訂現有的 ECDSA 證書，但您不能在執行時或升級過程中切換 RSA 和 ECDSA 演算法。Kubernetes 版本早於 v1.31 時存在一個 bug，其中生成的 kubeconfig 檔案中的金鑰被設定為使用 RSA，即使您啟用了 PublicKeysECDSA 功能門。此功能門因 kubeadm v1beta4 中可用的 encryptionAlgorithm 功能而被棄用。
RootlessControlPlane
設定此標誌會將 kubeadm 部署的控制平面元件靜態 Pod 容器（用於 kube-apiserver、kube-controller-manager、kube-scheduler 和 etcd）配置為以非 root 使用者身份執行。如果未設定該標誌，這些元件將以 root 使用者身份執行。您可以在升級到更新版本的 Kubernetes 之前更改此功能門的值。

已移除的功能門列表

kubeadm 已移除的功能門
特性AlphaBetaGA已移除
EtcdLearnerMode1.271.291.321.33
IPv6DualStack1.161.211.231.24
UnversionedKubeletConfigMap1.221.231.251.26
UpgradeAddonsBeforeControlPlane1.28--1.31

功能門描述

EtcdLearnerMode
在加入新的控制平面節點時，將建立一個新的 etcd 成員作為 learner，並在 etcd 資料完全對齊後才提升為投票成員。
IPv6DualStack
此標誌有助於在功能進行中配置元件的雙棧。有關 Kubernetes 雙棧支援的更多詳細資訊，請參閱 帶有 kubeadm 的雙棧支援。
UnversionedKubeletConfigMap
此標誌控制 kubeadm 儲存 kubelet 配置資料的 ConfigMap 的名稱。如果未指定此標誌或設定為 true，則 ConfigMap 名為 kubelet-config。如果您將此標誌設定為 false，則 ConfigMap 的名稱將包含 Kubernetes 的主次版本（例如：kubelet-config-1.34）。Kubeadm 確保讀取和寫入該 ConfigMap 的 RBAC 規則適合您設定的值。當 kubeadm 寫入此 ConfigMap 時（在 kubeadm init 或 kubeadm upgrade apply 期間），kubeadm 會遵守 UnversionedKubeletConfigMap 的值。當讀取該 ConfigMap 時（在 kubeadm join、kubeadm reset、kubeadm upgrade... 期間），kubeadm 會首先嚐試使用未版本化的 ConfigMap 名稱。如果失敗，kubeadm 將回退到使用該 ConfigMap 的舊（版本化）名稱。
UpgradeAddonsBeforeControlPlane
此功能門已被移除。它在 v1.28 中作為已棄用的功能引入，然後在 v1.31 中移除。有關舊版本的資訊，請切換到相應的網站版本。

新增 kube-proxy 引數

有關 kubeadm 配置中 kube-proxy 引數的資訊，請參閱

有關使用 kubeadm 啟用 IPVS 模式的資訊，請參閱

傳遞自定義標誌給控制平面元件

有關將標誌傳遞給控制平面元件的資訊，請參閱

在沒有 Internet 連線的情況下執行 kubeadm

要在沒有 Internet 連線的情況下執行 kubeadm，您需要預先拉取所需的控制平面鏡像。

您可以使用 kubeadm config images 子命令列出和拉取映象。

kubeadm config images list
kubeadm config images pull

您可以使用 --config 將上述命令與 kubeadm 配置檔案 一起使用，以控制 kubernetesVersion 和 imageRepository 欄位。

registry.k8s.io 的所有預設 registry.k8s.io 映象都支援多架構。

使用自定義映象

預設情況下，kubeadm 從 registry.k8s.io 拉取映象。如果請求的 Kubernetes 版本是 CI 標籤（例如 ci/latest），則使用 gcr.io/k8s-staging-ci-images。

您可以透過使用 kubeadm 和配置檔案 來覆蓋此行為。允許的自定義包括：

  • 提供 kubernetesVersion，它會影響映象的版本。
  • 提供一個替代的 imageRepository 來代替 registry.k8s.io。
  • 為 etcd 或 CoreDNS 提供特定的 imageRepository 和 imageTag。

出於向後相容的原因，預設 registry.k8s.io 和使用 imageRepository 指定的自定義儲存庫之間的映象路徑可能不同。例如，一個映象可能在 registry.k8s.io/subpath/image 下有一個子路徑，但在使用自定義儲存庫時預設為 my.customrepository.io/image。

為確保您將映象推送到您的自定義儲存庫，您必須：

  • 使用 kubeadm config images {list|pull} 從 registry.k8s.io 的預設路徑拉取映象。
  • 將映象推送到 kubeadm config images list --config=config.yaml 的路徑，其中 config.yaml 包含 etcd 和 CoreDNS 的自定義 imageRepository 和/或 imageTag。
  • 將相同的 config.yaml 傳遞給 kubeadm init。

自定義沙盒 (pause) 映象

要為這些設定自定義映象，您需要在您的 容器執行時 中進行配置以使用該映象。請查閱您的容器執行時的文件，瞭解如何更改此設定；對於選定的容器執行時，您也可以在 容器執行時 主題中找到建議。

將控制平面證書上傳到叢集

透過將 --upload-certs 標誌新增到 kubeadm init，您可以臨時將控制平面證書上傳到叢集中的 Secret。請注意，此 Secret 將在 2 小時後自動過期。證書使用 --certificate-key 指定的 32 位元組金鑰進行加密。當附加的控制平面節點加入時，可以使用相同的金鑰下載證書，方法是將 --control-plane 和 --certificate-key 傳遞給 kubeadm join。

以下階段命令可用於在過期後重新上傳證書

kubeadm init phase upload-certs --upload-certs --config=SOME_YAML_FILE

如果未將預定義的證書金鑰傳遞給 kubeadm init 和 kubeadm init phase upload-certs，將自動生成一個新的金鑰。

以下命令可用於按需生成新金鑰

kubeadm certs certificate-key

使用 kubeadm 進行證書管理

有關使用 kubeadm 進行證書管理的詳細資訊，請參閱 使用 kubeadm 進行證書管理。該文件包含有關使用外部 CA、自定義證書和證書續訂的資訊。

管理 kubelet 的 kubeadm drop-in 檔案

kubeadm 包附帶一個用於讓 systemd 執行 kubelet 的配置檔案。請注意，kubeadm CLI 永遠不會觸及此 drop-in 檔案。此 drop-in 檔案是 kubeadm DEB/RPM 包的一部分。

有關更多資訊，請參閱 管理 systemd 的 kubeadm drop-in 檔案。

將 kubeadm 與 CRI 執行時一起使用

預設情況下，kubeadm 會嘗試檢測您的容器執行時。有關此檢測的更多詳細資訊，請參閱 kubeadm CRI 安裝指南。

設定節點名稱

預設情況下，kubeadm 根據機器的主機地址分配節點名稱。您可以使用 --node-name 標誌覆蓋此設定。該標誌會將適當的 --hostname-override 值傳遞給 kubelet。

請注意，覆蓋主機名可能會 干擾雲提供商。

自動化 kubeadm

與其將從 kubeadm init 獲取的令牌複製到每個節點，如 基本 kubeadm 教程 中所示，您還可以並行分發令牌以方便自動化。要實現此自動化，您必須知道控制平面節點啟動後將擁有的 IP 地址，或使用 DNS 名稱或負載均衡器的地址。

  1. 生成一個令牌。此令牌必須具有 <6 個字元的字串>.<16 個字元的字串> 的形式。更正式地說，它必須匹配正則表示式：[a-z0-9]{6}\.[a-z0-9]{16}。

    kubeadm 可以為您生成一個令牌

    kubeadm token generate

  2. 同時使用此令牌啟動控制平面節點和工作節點。它們啟動後，應該會找到彼此並形成叢集。可以在 kubeadm init 和 kubeadm join 上使用相同的 --token 引數。

  3. 在加入附加控制平面節點時，對於 --certificate-key 也可以進行類似操作。可以使用以下命令生成金鑰：

    kubeadm certs certificate-key

叢集啟動後，您可以使用控制平面節點上的 /etc/kubernetes/admin.conf 檔案以管理員憑據與叢集進行通訊，或 生成其他使用者的 kubeconfig 檔案。

請注意，這種引導方式存在一些放鬆的安全保證，因為它不允許使用 --discovery-token-ca-cert-hash 驗證根 CA 雜湊（因為它在節點配置時未生成）。有關詳細資訊，請參閱 kubeadm join。

下一步

  • kubeadm init phase 以瞭解更多關於 kubeadm init 階段的資訊。
  • kubeadm join 以引導 Kubernetes 工作節點並將其加入叢集。
  • kubeadm upgrade 以將 Kubernetes 叢集升級到新版本。
  • kubeadm reset 以撤銷 kubeadm init 或 kubeadm join 對此主機所做的任何更改。
最後修改時間：2025 年 7 月 4 日太平洋標準時間晚上 11:28：新增 NodeLocalCRISocket 升級到 Beta 版的文件 (0135b1b08b)