升級 kubeadm 叢集

本頁面解釋如何將使用 kubeadm 建立的 Kubernetes 叢集從版本 1.33.x 升級到版本 1.34.x，以及從版本 1.34.x 升級到版本 1.34.y (其中 y > x)。不支援跳過次要版本進行升級。更多詳細資訊，請訪問 版本偏差策略。

要檢視有關使用舊版 kubeadm 建立的叢集的升級資訊，請參閱以下頁面：

Kubernetes 專案建議及時升級到最新的補丁版本，並確保你正在執行受支援的 Kubernetes 次要版本。遵循此建議有助於你保持安全。

高階升級工作流如下：

  1. 升級主控制平面節點。
  2. 升級附加控制平面節點。
  3. 升級工作節點。

準備工作

  • 請務必仔細閱讀 釋出說明。
  • 叢集應使用靜態控制平面和 etcd Pod 或外部 etcd。
  • 請務必備份任何重要元件，例如儲存在資料庫中的應用程式級狀態。kubeadm upgrade 不會觸及你的工作負載，只觸及 Kubernetes 內部元件，但備份始終是最佳實踐。
  • 必須停用 Swap.

其他資訊

  • 下面的說明概述了在升級過程中何時排空每個節點。如果你正在對任何 kubelet 執行次要版本升級，則必須首先排空你正在升級的節點。對於控制平面節點，它們可能正在執行 CoreDNS Pod 或其他關鍵工作負載。有關更多資訊，請參閱 排空節點。
  • Kubernetes 專案建議你匹配 kubelet 和 kubeadm 版本。你也可以使用比 kubeadm 舊的 kubelet 版本，只要它在支援的版本範圍內。更多詳細資訊，請訪問 kubeadm 與 kubelet 的版本偏差。
  • 所有容器在升級後都會重新啟動，因為容器規約的雜湊值已更改。
  • 要驗證 kubelet 升級後是否已成功重新啟動，你可以執行 systemctl status kubelet 或使用 journalctl -xeu kubelet 檢視服務日誌。
  • kubeadm upgrade 支援帶有 UpgradeConfiguration API 型別 的 --config，可用於配置升級過程。
  • kubeadm upgrade 不支援重新配置現有叢集。請改為按照 重新配置 kubeadm 叢集 中的步驟進行操作。

升級 etcd 時的注意事項

由於 kube-apiserver 靜態 Pod 始終在執行（即使你已排空節點），當你執行包含 etcd 升級的 kubeadm 升級時，在新 etcd 靜態 Pod 重啟期間，正在進行中的對伺服器的請求將暫停。作為一種變通方法，可以在啟動 kubeadm upgrade apply 命令前幾秒主動停止 kube-apiserver 程序。這允許完成正在進行中的請求並關閉現有連線，從而最大程度地減少 etcd 停機時間的影響。這可以在控制平面節點上按如下方式完成：

killall -s SIGTERM kube-apiserver # trigger a graceful kube-apiserver shutdown
sleep 20 # wait a little bit to permit completing in-flight requests
kubeadm upgrade ... # execute a kubeadm upgrade command

更改軟體包倉庫

如果你正在使用社群擁有的軟體包倉庫 (pkgs.k8s.io)，則需要為所需的 Kubernetes 次要版本啟用軟體包倉庫。這在 更改 Kubernetes 軟體包倉庫 文件中進行了解釋。

確定要升級到的版本

使用作業系統軟體包管理器查詢 Kubernetes 1.34 的最新補丁版本

# Find the latest 1.34 version in the list.
# It should look like 1.34.x-*, where x is the latest patch.
sudo apt update
sudo apt-cache madison kubeadm


# Find the latest 1.34 version in the list.
# It should look like 1.34.x-*, where x is the latest patch.
sudo yum list --showduplicates kubeadm --disableexcludes=kubernetes

如果你沒有看到預期的升級版本，請驗證是否使用了 Kubernetes 軟體包倉庫。

升級控制平面節點

控制平面節點上的升級過程應一次一個節點地執行。選擇一個你希望首先升級的控制平面節點。它必須具有 /etc/kubernetes/admin.conf 檔案。

呼叫 "kubeadm upgrade"

對於第一個控制平面節點

  1. 升級 kubeadm

    # replace x in 1.34.x-* with the latest patch version
sudo apt-mark unhold kubeadm && \
sudo apt-get update && sudo apt-get install -y kubeadm='1.34.x-*' && \
sudo apt-mark hold kubeadm


    # replace x in 1.34.x-* with the latest patch version
sudo yum install -y kubeadm-'1.34.x-*' --disableexcludes=kubernetes

  2. 驗證下載是否有效並具有預期版本

    kubeadm version

  3. 驗證升級計劃

    sudo kubeadm upgrade plan

    此命令檢查你的叢集是否可以升級，並獲取你可以升級到的版本。它還顯示一個包含元件配置版本狀態的表格。

  4. 選擇要升級到的版本，然後執行相應的命令。例如：

    # replace x with the patch version you picked for this upgrade
sudo kubeadm upgrade apply v1.34.x

    命令完成後，你應該會看到：

    [upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.34.x". Enjoy!

[upgrade/kubelet] Now that your control plane is upgraded, please proceed with upgrading your kubelets if you haven't already done so.

  5. 手動升級你的 CNI 提供商外掛。

    你的容器網路介面 (CNI) 提供商可能有自己的升級說明。請檢視 附加元件 頁面，找到你的 CNI 提供商並檢視是否需要額外的升級步驟。

    如果 CNI 提供商作為 DaemonSet 執行，則在附加控制平面節點上不需要此步驟。

對於其他控制平面節點

與第一個控制平面節點相同，但使用

sudo kubeadm upgrade node

而不是

sudo kubeadm upgrade apply

也不再需要呼叫 kubeadm upgrade plan 和升級 CNI 提供商外掛。

排空節點

透過將其標記為不可排程並驅逐工作負載，為節點維護做準備：

# replace <node-to-drain> with the name of your node you are draining
kubectl drain <node-to-drain> --ignore-daemonsets

升級 kubelet 和 kubectl

  1. 升級 kubelet 和 kubectl

    # replace x in 1.34.x-* with the latest patch version
sudo apt-mark unhold kubelet kubectl && \
sudo apt-get update && sudo apt-get install -y kubelet='1.34.x-*' kubectl='1.34.x-*' && \
sudo apt-mark hold kubelet kubectl


    # replace x in 1.34.x-* with the latest patch version
sudo yum install -y kubelet-'1.34.x-*' kubectl-'1.34.x-*' --disableexcludes=kubernetes

  2. 重啟 kubelet

    sudo systemctl daemon-reload
sudo systemctl restart kubelet

恢復排程節點

透過將其標記為可排程來使節點重新上線。

# replace <node-to-uncordon> with the name of your node
kubectl uncordon <node-to-uncordon>

升級工作節點

工作節點上的升級過程應一次一個節點或一次幾個節點地執行，而不會損害執行工作負載所需的最小容量。

以下頁面顯示瞭如何升級 Linux 和 Windows 工作節點：

驗證叢集狀態

在所有節點上的 kubelet 升級後，透過從任何可以訪問叢集的 kubectl 位置執行以下命令，驗證所有節點是否再次可用：

kubectl get nodes

STATUS 列應對所有節點顯示 Ready，並且版本號應已更新。

從故障狀態恢復

如果 kubeadm upgrade 失敗並且沒有回滾（例如，由於執行過程中意外關機），你可以再次執行 kubeadm upgrade。此命令是冪等的，最終會確保實際狀態是你宣告的期望狀態。

要從錯誤狀態恢復，你還可以執行 sudo kubeadm upgrade apply --force，而無需更改叢集正在執行的版本。

在升級期間，kubeadm 會在 /etc/kubernetes/tmp 下寫入以下備份資料夾：

  • kubeadm-backup-etcd-<日期>-<時間>
  • kubeadm-backup-manifests-<日期>-<時間>

kubeadm-backup-etcd 包含此控制平面節點本地 etcd 成員資料的備份。如果 etcd 升級失敗且自動回滾不起作用，則此資料夾的內容可以手動恢復到 /var/lib/etcd。如果使用外部 etcd，此備份資料夾將為空。

kubeadm-backup-manifests 包含此控制平面節點靜態 Pod 清單檔案的備份。如果升級失敗且自動回滾不起作用，則此資料夾的內容可以手動恢復到 /etc/kubernetes/manifests。如果由於某種原因，某個元件的升級前和升級後清單檔案沒有區別，則不會為其寫入備份檔案。

工作原理

kubeadm upgrade apply 執行以下操作：

  • 檢查你的叢集是否處於可升級狀態：
    • API 伺服器可訪問
    • 所有節點都處於 Ready 狀態
    • 控制平面健康
  • 強制執行版本偏差策略。
  • 確保控制平面鏡像可用或可拉取到機器上。
  • 如果元件配置需要版本升級，則生成替換和/或使用使用者提供的覆蓋。
  • 升級控制平面元件，如果其中任何一個啟動失敗則回滾。
  • 應用新的 CoreDNS 和 kube-proxy 清單，並確保建立所有必要的 RBAC 規則。
  • 建立 API 伺服器的新證書和金鑰檔案，如果它們將在 180 天內過期，則備份舊檔案。

kubeadm upgrade node 在附加控制平面節點上執行以下操作：

  • 從叢集中獲取 kubeadm ClusterConfiguration。
  • （可選）備份 kube-apiserver 證書。
  • 升級控制平面元件的靜態 Pod 清單。
  • 升級此節點的 kubelet 配置。

kubeadm upgrade node 在工作節點上執行以下操作：

  • 從叢集中獲取 kubeadm ClusterConfiguration。
  • 升級此節點的 kubelet 配置。
上次修改時間：2025 年 7 月 3 日下午 2:05 PST：修復 kubeadm 升級指南中的拼寫錯誤：刪除重複的“to”(5575d62223)