使用 kubeadm 建立叢集

使用 kubeadm，你可以建立一個符合最佳實踐的最小化可用的 Kubernetes 叢集。事實上，你可以使用 kubeadm 設定一個可以透過 Kubernetes 一致性測試的叢集。kubeadm 還支援其他叢集生命週期功能，例如引導令牌和叢集升級。

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

  • 一種簡單的方式來嘗試 Kubernetes，可能這是你第一次使用。
  • 一種現有使用者自動化設定叢集和測試應用程式的方式。
  • 作為其他生態系統和/或範圍更廣的安裝工具中的構建模組。

你可以在各種機器上安裝和使用 kubeadm：你的筆記型電腦、一組雲伺服器、Raspberry Pi 等。無論你是部署到雲端還是本地環境，你都可以將 kubeadm 整合到 Ansible 或 Terraform 等配置系統中。

準備工作

要遵循本指南，你需要

  • 一臺或多臺執行 deb/rpm 相容 Linux 作業系統的機器；例如：Ubuntu 或 CentOS。
  • 每臺機器 2 GiB 或更多 RAM——少於此量會為你的應用程式留下很少空間。
  • 作為控制平面節點的機器上至少有 2 個 CPU。
  • 叢集中所有機器之間的完全網路連通性。你可以使用公共或專用網路。

你還需要使用與你想要在新叢集中使用的 Kubernetes 版本相容的 kubeadm 版本。

Kubernetes 的版本和版本偏差支援策略適用於 kubeadm 和整個 Kubernetes。請查閱該策略以瞭解支援的 Kubernetes 和 kubeadm 版本。此頁面針對 Kubernetes v1.34 編寫。

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 嘗試透過使用已知端點列表來檢測容器執行時。要使用不同的容器執行時，或者如果在已配置的節點上安裝了多個容器執行時，請為 kubeadm 指定 --cri-socket 引數。請參閱安裝執行時。

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

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。

要自定義控制平面元件，包括為控制平面元件和 etcd 伺服器的活躍性探針可選地分配 IPv6，請按照自定義引數中的文件為每個元件提供額外的引數。

要重新配置已建立的叢集，請參閱重新配置 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 Server 代理到 localhost

如果你想從叢集外部連線到 API Server，可以使用 kubectl proxy

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

你現在可以透過 https://: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 可以與與 kubeadm 版本相同或舊一個版本的 Kubernetes 元件一起使用。可以使用 kubeadm init 的 --kubernetes-version 標誌或在使用 --config 時使用 ClusterConfiguration.kubernetesVersion 欄位向 kubeadm 指定 Kubernetes 版本。此選項將控制 kube-apiserver、kube-controller-manager、kube-scheduler 和 kube-proxy 的版本。

示例

  • kubeadm 版本為 1.34
  • kubernetesVersion 必須是 1.34 或 1.33

kubeadm 與 kubelet 的偏差

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

示例

  • kubeadm 版本為 1.34
  • 主機上的 kubelet 必須是 1.34、1.33、1.32 或 1.31

kubeadm 之間的偏差

kubeadm 命令在由 kubeadm 管理的現有節點或整個叢集上操作時存在某些限制。

如果新節點加入叢集，用於 kubeadm join 的 kubeadm 二進位制檔案必須與用於透過 kubeadm init 建立叢集或透過 kubeadm upgrade 升級同一節點的最後一個 kubeadm 版本匹配。類似的規則適用於除 kubeadm upgrade 之外的所有 kubeadm 命令。

kubeadm join 的示例

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

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

kubeadm upgrade 的示例

  • kubeadm 版本 1.33 用於建立或升級節點
  • 用於升級節點的 kubeadm 版本必須是 1.33 或 1.34

要了解有關不同 Kubernetes 元件之間的版本偏差的更多資訊，請參閱版本偏差策略。

限制

叢集彈性

此處建立的叢集具有單個控制平面節點，其上執行單個 etcd 資料庫。這意味著如果控制平面節點發生故障，你的叢集可能會丟失資料，並且可能需要從頭開始重新建立。

變通方法

平臺相容性

kubeadm deb/rpm 軟體包和二進位制檔案是為 amd64、arm (32-bit)、arm64、ppc64le 和 s390x 構建的，遵循多平臺提案。

自 v1.12 起，還支援控制平面和外掛的多平臺容器映象。

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

故障排除

如果你在使用 kubeadm 時遇到困難，請查閱我們的故障排除文件。

下一步

  • 使用 Sonobuoy 驗證你的叢集是否正常執行
  • 請參閱 升級 kubeadm 叢集，瞭解使用 kubeadm 升級叢集的詳細資訊。
  • 在 kubeadm 參考文件 中瞭解高階 kubeadm 用法
  • 詳細瞭解 Kubernetes 概念和 kubectl。
  • 請參閱叢集網路頁面，瞭解更長的 Pod 網路外掛列表。
  • 請參閱外掛列表，探索其他外掛，包括用於日誌記錄、監控、網路策略、Kubernetes 叢集視覺化和控制的工具。
  • 配置你的叢集如何處理叢集事件和 Pod 中執行的應用程式的日誌。請參閱日誌架構以瞭解所涉及的概述。

反饋

最後修改於 2024 年 10 月 16 日太平洋標準時間上午 9:28：調整並清理了四個 kubeadm 檔案 (67c5917e32)