使用 kubeadm 建立叢集

使用 kubeadm，您可以建立符合最佳實務的最低可行 Kubernetes 叢集。事實上，您可以使用 kubeadm 來設定一個可以通過 Kubernetes 一致性測試 的叢集。 kubeadm 也支援其他叢集生命週期功能，例如 bootstrap 權杖 和叢集升級。

如果您需要以下功能，kubeadm 工具會很有用

  • 一種簡單的方式讓您嘗試 Kubernetes，可能是第一次嘗試。
  • 一種讓現有使用者自動化設定叢集並測試其應用程式的方式。
  • 在具有更大範圍的其他生態系統和/或安裝程式工具中的建構區塊。

您可以在各種機器上安裝和使用 kubeadm：您的筆記型電腦、一組雲端伺服器、Raspberry Pi 等等。無論您是要部署到雲端還是內部部署，都可以將 kubeadm 整合到佈建系統中，例如 Ansible 或 Terraform。

開始之前

若要遵循本指南，您需要

  • 一部或多部執行 deb/rpm 相容 Linux 作業系統的機器；例如：Ubuntu 或 CentOS。
  • 每部機器 2 GiB 或更多的 RAM - 任何更少的 RAM 都會為您的應用程式留下很少的空間。
  • 在您用作控制平面節點的機器上至少 2 個 CPU。
  • 叢集中所有機器之間的完整網路連線能力。您可以使用公用或私有網路。

您還需要使用一個 kubeadm 版本，該版本可以部署您想要在新叢集中使用的 Kubernetes 版本。

Kubernetes 的版本和版本偏差支援政策適用於 kubeadm 以及整體的 Kubernetes。請查看該政策以了解支援哪些 Kubernetes 和 kubeadm 版本。本頁面是為 Kubernetes v1.32 編寫的。

kubeadm 工具的整體功能狀態為正式發行 (GA)。某些子功能仍在積極開發中。建立叢集的實作方式可能會隨著工具的演進而略有變化，但整體實作應相當穩定。

目標

  • 安裝單一控制平面的 Kubernetes 叢集
  • 在叢集上安裝 Pod 網路，以便您的 Pod 可以互相通訊

說明

準備主機

元件安裝

在所有主機上安裝容器執行期和 kubeadm。如需詳細說明和其他先決條件，請參閱安裝 kubeadm。

網路設定

kubeadm 與其他 Kubernetes 元件類似，會嘗試在與主機上的預設閘道相關聯的網路介面上找到可用的 IP。此 IP 隨後會用於元件執行的廣播和/或監聽。

若要找出 Linux 主機上的 IP 位址，您可以使用

ip route show # Look for a line starting with "default via"

Kubernetes 元件不接受自訂網路介面作為選項，因此必須將自訂 IP 位址作為標記傳遞給所有需要此自訂組態的元件執行個體。

若要為使用 init 和 join 建立的控制平面節點設定 API 伺服器廣告位址，可以使用標記 --apiserver-advertise-address。最好在 kubeadm API 中將此選項設定為 InitConfiguration.localAPIEndpoint 和 JoinConfiguration.controlPlane.localAPIEndpoint。

對於所有節點上的 kubelet，可以在 kubeadm 組態檔（InitConfiguration 或 JoinConfiguration）內的 .nodeRegistration.kubeletExtraArgs 中傳遞 --node-ip 選項。

對於雙堆疊，請參閱使用 kubeadm 的雙堆疊支援。

您指派給控制平面元件的 IP 位址會成為其 X.509 憑證的主體別名欄位的一部分。變更這些 IP 位址將需要簽署新的憑證並重新啟動受影響的元件，以便反映憑證檔案中的變更。有關此主題的更多詳細資訊，請參閱手動憑證續約。

準備所需的容器映像檔

此步驟是選用的，僅在您希望 kubeadm init 和 kubeadm join 不下載託管在 registry.k8s.io 的預設容器映像檔時適用。

當在節點上建立沒有網際網路連線的叢集時，Kubeadm 具有可以協助您預先提取所需映像檔的指令。有關更多詳細資訊，請參閱在沒有網際網路連線的情況下執行 kubeadm。

Kubeadm 允許您使用自訂映像檔儲存庫來儲存所需的映像檔。有關更多詳細資訊，請參閱使用自訂映像檔。

初始化您的控制平面節點

控制平面節點是執行控制平面元件的機器，包括 etcd（叢集資料庫）和 API 伺服器（kubectl 指令列工具與之通訊）。

  1. （建議）如果您計劃將此單一控制平面 kubeadm 叢集升級到高可用性，您應該指定 --control-plane-endpoint 以設定所有控制平面節點的共用端點。此端點可以是 DNS 名稱或負載平衡器的 IP 位址。
  2. 選擇 Pod 網路附加元件，並驗證它是否需要將任何引數傳遞給 kubeadm init。根據您選擇的協力廠商供應商，您可能需要將 --pod-network-cidr 設定為供應商特定的值。請參閱安裝 Pod 網路附加元件。
  3. （選用）kubeadm 嘗試透過使用已知端點列表來偵測容器執行期。若要使用不同的容器執行期，或者在佈建的節點上安裝了多個容器執行期，請將 --cri-socket 引數指定給 kubeadm。請參閱安裝執行期。

若要初始化控制平面節點，請執行

kubeadm init <args>

關於 apiserver-advertise-address 和 ControlPlaneEndpoint 的考量

雖然 --apiserver-advertise-address 可用於設定此特定控制平面節點的 API 伺服器的廣告位址，但 --control-plane-endpoint 可用於設定所有控制平面節點的共用端點。

--control-plane-endpoint 允許 IP 位址和可以對應到 IP 位址的 DNS 名稱。請聯絡您的網路管理員以評估關於此對應的可能解決方案。

以下是一個對應範例

192.168.0.102 cluster-endpoint

其中 192.168.0.102 是此節點的 IP 位址，而 cluster-endpoint 是對應到此 IP 的自訂 DNS 名稱。這將允許您將 --control-plane-endpoint=cluster-endpoint 傳遞給 kubeadm init，並將相同的 DNS 名稱傳遞給 kubeadm join。稍後，您可以修改 cluster-endpoint 以指向高可用性情境中負載平衡器的位址。

kubeadm 不支援將在沒有 --control-plane-endpoint 的情況下建立的單一控制平面叢集轉換為高可用性叢集。

更多資訊

有關 kubeadm init 引數的更多資訊，請參閱 kubeadm 參考指南。

若要使用組態檔組態 kubeadm init，請參閱使用具有組態檔的 kubeadm init。

若要自訂控制平面元件，包括將選用的 IPv6 指派給控制平面元件和 etcd 伺服器的存活探測，請為每個元件提供額外的引數，如自訂引數中所述。

若要重新組態已建立的叢集，請參閱重新組態 kubeadm 叢集。

若要再次執行 kubeadm init，您必須先拆解叢集。

如果您將具有不同架構的節點加入到您的叢集中，請確保您部署的 DaemonSet 具有對此架構的容器映像檔支援。

kubeadm init 首先執行一系列預檢，以確保機器已準備好執行 Kubernetes。這些預檢會顯示警告並在錯誤時退出。然後，kubeadm init 會下載並安裝叢集控制平面元件。這可能需要幾分鐘。完成後，您應該會看到

Your Kubernetes control-plane has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

You should now deploy a Pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
  /docs/concepts/cluster-administration/addons/

You can now join any number of machines by running the following on each node
as root:

  kubeadm join <control-plane-host>:<control-plane-port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>

若要讓 kubectl 為您的非 root 使用者工作，請執行以下指令，這些指令也是 kubeadm init 輸出的一部分

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

或者，如果您是 root 使用者，您可以執行

export KUBECONFIG=/etc/kubernetes/admin.conf

記錄 kubeadm init 輸出的 kubeadm join 指令。您需要此指令才能將節點加入到您的叢集。

權杖用於控制平面節點和加入節點之間的相互驗證。此處包含的權杖是機密的。請妥善保管，因為任何擁有此權杖的人都可以將經過驗證的節點新增到您的叢集。可以使用 kubeadm token 指令列出、建立和刪除這些權杖。請參閱 kubeadm 參考指南。

安裝 Pod 網路附加元件

多個外部專案使用 CNI 提供 Kubernetes Pod 網路，其中一些專案也支援網路原則。

請參閱實作Kubernetes 網路模型的附加元件列表。

請參閱安裝附加元件頁面，以取得 Kubernetes 支援的網路附加元件的非詳盡列表。您可以使用以下指令在控制平面節點或具有 kubeconfig 憑證的節點上安裝 Pod 網路附加元件

kubectl apply -f <add-on.yaml>

每個叢集只能安裝一個 Pod 網路。

安裝 Pod 網路後，您可以透過檢查 CoreDNS Pod 在 kubectl get pods --all-namespaces 的輸出中是否為 Running 來確認它是否正常運作。一旦 CoreDNS Pod 啟動並執行，您就可以繼續加入您的節點。

如果您的網路無法運作或 CoreDNS 未處於 Running 狀態，請查看 kubeadm 的疑難排解指南。

託管節點標籤

預設情況下，kubeadm 啟用 NodeRestriction 許可控制器，該控制器限制 kubelet 在節點註冊時可以自我套用的標籤。許可控制器文件涵蓋了允許與 kubelet --node-labels 選項一起使用的標籤。node-role.kubernetes.io/control-plane 標籤是這樣一個受限的標籤，kubeadm 在建立節點後使用特權用戶端手動套用它。若要手動執行此操作，您可以使用 kubectl label 執行相同的操作，並確保它使用特權 kubeconfig，例如 kubeadm 管理的 /etc/kubernetes/admin.conf。

控制平面節點隔離

預設情況下，基於安全性考量，您的叢集不會在控制平面節點上排程 Pod。如果您想要能夠在控制平面節點上排程 Pod，例如對於單一機器 Kubernetes 叢集，請執行

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

輸出看起來會像這樣

node "test-01" untainted
...

這將從任何具有它的節點（包括控制平面節點）中移除 node-role.kubernetes.io/control-plane:NoSchedule 污點，這表示排程器隨後將能夠在任何地方排程 Pod。

此外，您可以執行以下指令從控制平面節點中移除 node.kubernetes.io/exclude-from-external-load-balancers 標籤，這會將其從後端伺服器列表中排除。

kubectl label nodes --all node.kubernetes.io/exclude-from-external-load-balancers-

新增更多控制平面節點

請參閱使用 kubeadm 建立高可用性叢集，以取得透過新增更多控制平面節點來建立高可用性 kubeadm 叢集的步驟。

新增工作節點

工作節點是您執行工作負載的地方。

以下頁面說明如何使用 kubeadm join 指令將 Linux 和 Windows 工作節點新增到叢集中

（選用）從控制平面節點以外的機器控制您的叢集

為了讓其他電腦（例如筆記型電腦）上的 kubectl 與您的叢集通訊，您需要將管理員 kubeconfig 檔案從您的控制平面節點複製到您的工作站，如下所示

scp root@<control-plane-host>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf get nodes

（選用）將 API 伺服器代理到 localhost

如果您想要從叢集外部連線到 API 伺服器，您可以使用 kubectl proxy

scp root@<control-plane-host>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf proxy

您現在可以透過 http://localhost:8001/api/v1 在本機存取 API 伺服器

清理

如果您將可拋棄式伺服器用於叢集進行測試，您可以關閉這些伺服器，而無需進一步清理。您可以使用 kubectl config delete-cluster 刪除您對叢集的本機參考。

但是，如果您想要更乾淨地解除佈建您的叢集，您應該先排空節點並確保節點為空，然後解除組態節點。

移除節點

使用適當的憑證與控制平面節點通訊，執行

kubectl drain <node name> --delete-emptydir-data --force --ignore-daemonsets

在移除節點之前，重設 kubeadm 安裝的狀態

kubeadm reset

重設程序不會重設或清理 iptables 規則或 IPVS 表格。如果您想要重設 iptables，您必須手動執行此操作

iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X

如果您想要重設 IPVS 表格，您必須執行以下指令

ipvsadm -C

現在移除節點

kubectl delete node <node name>

如果您想要重新開始，請使用適當的引數執行 kubeadm init 或 kubeadm join。

清理控制平面

您可以在控制平面主機上使用 kubeadm reset 來觸發盡力清理。

請參閱 kubeadm reset 參考文件，以取得關於此子指令及其選項的更多資訊。

版本偏差政策

雖然 kubeadm 允許對其管理的一些元件進行版本偏差，但建議您將 kubeadm 版本與控制平面元件、kube-proxy 和 kubelet 的版本相符。

kubeadm 相對於 Kubernetes 版本的偏差

kubeadm 可以與 Kubernetes 元件一起使用，這些元件的版本與 kubeadm 相同或舊一個版本。可以使用 kubeadm init 的 --kubernetes-version 標記或使用 --config 時的 ClusterConfiguration.kubernetesVersion 欄位，將 Kubernetes 版本指定給 kubeadm。此選項將控制 kube-apiserver、kube-controller-manager、kube-scheduler 和 kube-proxy 的版本。

範例

  • kubeadm 版本為 1.32
  • kubernetesVersion 必須為 1.32 或 1.31

kubeadm 相對於 kubelet 的偏差

與 Kubernetes 版本類似，kubeadm 可以與 kubelet 版本一起使用，該版本與 kubeadm 版本相同或舊三個版本。

範例

  • kubeadm 版本為 1.32
  • 主機上的 kubelet 必須為 1.32、1.31、1.30 或 1.29

kubeadm 相對於 kubeadm 的偏差

關於 kubeadm 指令如何在 kubeadm 管理的現有節點或整個叢集上運作，存在某些限制。

如果將新節點加入到叢集中，用於 kubeadm join 的 kubeadm 二進位檔案必須與用於使用 kubeadm init 建立叢集或使用 kubeadm upgrade 升級相同節點的 kubeadm 最後一個版本相符。類似的規則適用於其餘的 kubeadm 指令，但 kubeadm upgrade 除外。

kubeadm join 的範例

  • kubeadm 版本 1.32 用於使用 kubeadm init 建立叢集
  • 加入節點必須使用版本為 1.32 的 kubeadm 二進位檔案

正在升級的節點必須使用與用於管理節點的 kubeadm 版本相同的 MINOR 版本或更新一個 MINOR 版本的 kubeadm 版本。

kubeadm upgrade 的範例

  • kubeadm 版本 1.31 用於建立或升級節點
  • 用於升級節點的 kubeadm 版本必須為 1.31 或 1.32

若要深入了解不同 Kubernetes 元件之間的版本偏差，請參閱版本偏差政策。

限制

叢集復原能力

此處建立的叢集具有單一控制平面節點，並在其上執行單一 etcd 資料庫。這表示如果控制平面節點發生故障，您的叢集可能會遺失資料，並且可能需要從頭開始重新建立。

解決方法

平台相容性

kubeadm deb/rpm 套件和二進位檔案是針對 amd64、arm (32 位元)、arm64、ppc64le 和 s390x 根據多平台提案建置的。

自 v1.12 起，也支援控制平面和附加元件的多平台容器映像檔。

只有部分網路供應商為所有平台提供解決方案。請查閱上述網路供應商列表或每個供應商的文件，以找出供應商是否支援您選擇的平台。

疑難排解

如果您在使用 kubeadm 時遇到困難，請參閱我們的疑難排解文件。

下一步

  • 使用 Sonobuoy 驗證您的叢集是否正常運作
  • 請參閱升級 kubeadm 叢集，以了解關於使用 kubeadm 升級叢集的詳細資訊。
  • 在 kubeadm 參考文件中了解關於進階 kubeadm 用法。
  • 深入了解 Kubernetes 概念和 kubectl。
  • 請參閱叢集網路頁面，以取得更大的 Pod 網路附加元件列表。
  • 請參閱附加元件列表，以探索其他附加元件，包括用於記錄、監控、網路原則、視覺化和控制 Kubernetes 叢集的工具。
  • 組態您的叢集如何處理叢集事件和從 Pod 中執行的應用程式產生的記錄。請參閱記錄架構，以概述所涉及的內容。

意見反應

上次修改時間：2024 年 10 月 16 日上午 9:28 PST：調整和清理四個 kubeadm 檔案 (67c5917e32)