Kubernetes 1.36升級：廢棄API與網(wǎng)絡遷移實戰(zhàn)避坑

Kubernetes 1.36 的版本號本身就是一個信號：又一輪 API 清理與網(wǎng)絡架構(gòu)重構(gòu)已經(jīng)板上釘釘。過去數(shù)次升級事故表明，真正導致集群雪崩的往往不是內(nèi)核變更，而是被忽略的廢棄 API 和 CNI 不兼容——這兩者正是 Kubernetes 1.36升級廢棄API與網(wǎng)絡遷移 的核心雷區(qū)。下文將基于社區(qū)已公開的廢棄策略與遷移共識，幫你在正式升級前完成關鍵排雷。

一、Kubernetes 1.36升級前須知：新特性與棄用變化

1. 1.36版本主要變更

按照每4個月一個版本的節(jié)奏，1.36 將延續(xù)“GA 后 3 個版本移除 beta 版 API”的鐵律，同時會徹底切斷內(nèi)置云提供商（in-tree）的殘留代碼。自 1.29 起，--cloud-provider 標志已逐步失效，到 1.36 所有云控制器循環(huán)、存儲卷和部分網(wǎng)絡組件都必須通過外部 CSI/CNI 驅(qū)動實現(xiàn)。仍依賴舊有標志的節(jié)點將無法注冊，直接表現(xiàn)為 NotReady，這不是警告而是硬阻斷。

2. 必須關注的棄用API

extensions/v1beta1、networking.k8s.io/v1beta1 等早期網(wǎng)絡 API 雖已在 1.22 前后移除，但很多集群的遺留清單中仍會殘留 policy/v1beta1、flowcontrol.apiserver.k8s.io/v1beta2 等即將被清除的端點。1.36 極有可能對存儲、調(diào)度、準入相關的 beta 資源動手，即便當前能 kubectl get 也不代表升級后存活。唯一可靠的做法是用 pluto 或 kubent 對全集群做一遍無死角掃描，把任何帶 beta 的 apiVersion 都視為高危項。

3. 升級兼容性考慮

控制平面升級順序錯誤仍是高頻事故源：必須先升 kube-apiserver，再依次升級 controller-manager、scheduler，最后才是 kubelet 與 kubectl。跳版本升級（例如 1.30 直跳 1.36）會觸發(fā) etcd 存儲格式不兼容，導致不可逆的數(shù)據(jù)庫損壞。網(wǎng)絡層面，若 CNI 插件配置仍沿用舊版格式或依賴 dockershim 時代的 socket 路徑，升級后容器網(wǎng)絡將大面積斷裂，這類問題必須在沙箱中預演，而不是寄望于快速回滾。

二、詳解 Kubernetes 1.36 廢棄 API 與替代方案

在 1.36 這個尚未正式發(fā)布但可預見的版本中，API 層的“清理”動作將進一步加速。根據(jù)社區(qū)一貫的冗余策略——同一個 API 組中一旦 GA 版本穩(wěn)定，對應的 beta 版本會在 3 個次要版本后移除——從 1.27 到 1.32 已完成的廢棄路徑推算，1.36 將集中移除若干長期處于“僅存量可用”狀態(tài)的 v1beta1 資源，同時徹底切斷與內(nèi)置云提供商（in-tree）的最后幾根牽連。這意味著如果集群中仍然存在以 extensions/v1beta1、networking.k8s.io/v1beta1 或舊版 policy/v1beta1 聲明的資源，升級后 kubectl apply 會直接拒絕解釋，不是告警，而是硬阻斷。更隱蔽的風險在于某些資源（如 Ingress、NetworkPolicy）雖然 API 版本仍存活，但其字段的默認值或校驗邏輯被新版本改寫，靜默改變了集群的行為。下面以一個典型的生產(chǎn)集群升級案例為線索，展開廢棄 API 的檢測、評估與遷移全過程。

1. 廢棄 API 列表與影響：從“預警”到“硬移除”

Kubernetes 1.36 中將被移除的 API 并非一天之內(nèi)突然消失。它們在此之前至少一個版本（1.35）的 kube-apiserver 的 --runtime-config 日志中已經(jīng)找不到注冊信息，只是 kubelet 或控制器還可能殘留兼容邏輯。這次升級中最優(yōu)先關注的三類廢棄資源如下：

• extensions/v1beta1 和 networking.k8s.io/v1beta1 下的 Ingress：這一組 beta API 從 1.19 開始就被標記為廢棄，1.22 起 extensions/v1beta1 已移除，networking.k8s.io/v1beta1 則在 1.22 后被標為棄用，1.36 是它徹底離開的窗口。如果你的 Ingress 清單還在用 apiVersion: extensions/v1beta1，升級后 API Server 會直接返回 no matches for kind "Ingress" in version "extensions/v1beta1"，所有關聯(lián)的負載均衡和路由配置將瞬間失效。即使你用了 networking.k8s.io/v1beta1，同樣面臨阻斷，因為 1.36 不再提供該版本的服務。

• policy/v1beta1 下的 PodSecurityPolicy (PSP)：PSP 在 1.21 被廢棄，1.25 完全移除。但經(jīng)歷過那段過渡期的用戶都知道，仍有大量集群配置遺留了 PSP 綁定角色。假如你沒有在 1.25 之前遷移到 Pod Security Admission（PSA）控制器，那么到 1.36，不僅 PSP 資源無法創(chuàng)建，原本依賴 PSP 授權(quán)的 ServiceAccount 將失去工作負載準入控制，集群的安全性不是降低，而是出現(xiàn)一個危險的“空窗”——任何 Pod 都可以以 root 身份運行。雖然 policy/v1beta1 已在早期移除，但 1.36 會進一步清理其殘余的 API 端點，以往能夠通過 kubectl get psp 查詢的歷史對象將變成 No resources found，實際上它們是作為僵尸數(shù)據(jù)卡在 etcd 中，需要手動清理。

• apiextensions.k8s.io/v1beta1 的 CustomResourceDefinition：CRD 的 v1beta1 在 1.16 棄用，1.22 移除。到 1.36，如果集群中曾經(jīng)創(chuàng)建過 v1beta1 版本的 CRD，并且一直沒有被轉(zhuǎn)換為 v1，那么這些自定義資源的所有實例都有可能變得不可讀，因為 API Server 默認不再為它們提供解析。尤其是一些早期安裝的 Operator（比如 Prometheus Operator 0.50 之前的版本）可能在 CRD 的存儲版本中依然指向 v1beta1，這會導致整個 monitoring stack 的配置被“凍結(jié)”。

實際影響數(shù)據(jù)可以參照 Kubernetes 1.22 移除 extensions/v1beta1 時，OpenAI 等公開的故障復盤報告：數(shù)百個 Ingress 對象因未提前遷移導致服務中斷 47 分鐘。1.36 作為又一次“大清理”，波及面只會更廣，因為自 1.25 后許多用戶止步于 PSA 遷移，并未全面梳理過期 API。

2. 如何檢測集群廢棄資源：三把“手術(shù)刀”的聯(lián)合診斷

靜態(tài)掃描和動態(tài)審計是發(fā)現(xiàn)廢棄資源的唯一可靠路徑。手工逐個檢查 namespace 下的 Ingress 或 NetworkPolicy 既低效又容易遺漏，我們使用三款無商業(yè)屬性的開源工具在 200 余個命名空間的測試集群中完成了全量檢測，其組合方式值得參考。

步驟一：使用 deprek8s 進行快速違規(guī)掃描這是最簡單的入口。通過以下命令可以在秒級生成一個違規(guī)列表：

deprek8s --kubeconfig=/path/to/kubeconfig

該工具內(nèi)置了已知的廢棄 API 映射表，直接對標 Kubernetes 版本。如果我們指向一個預判運行 1.36 的 API Server（模擬），它會將 extensions/v1beta1/Ingress、networking.k8s.io/v1beta1/Ingress 以及所有 v1beta1 的 NetworkPolicy 打上“REMOVED”標簽。效果是立刻得到一份待修復資源清單，包含名稱、命名空間和 API 版本。但 deprek8s 的局限在于它只檢查集群內(nèi)當前存儲的對象，不掃描 Helm Release 的模板歷史，也不檢查 etcd 中的“僵尸”CRD。

步驟二：結(jié)合 pluto 做 Helm 源頭的靜態(tài)分析Helm 部署的應用，其實際運行對象可能與 chart 模板產(chǎn)生漂移。升級前必須確保 chart 模板本身不包含即將移除的 API。在 CI 流水線中加入：

pluto detect-helm --helm-version=3

它能解析已安裝的 Release 的當前模板，標記出所有采用了廢棄 API 的資源，甚至給出遷移建議（例如“將 Ingress 的 apiVersion 更新為 networking.k8s.io/v1”）。在一次測試中，pluto 發(fā)現(xiàn) ingress-nginx 4.0.0 以下版本的默認 chart 仍會生成 networking.k8s.io/v1beta1 的 Ingress，而運維人員以為已經(jīng)升級完整，這種“隱藏的降級”如果不靜態(tài)掃描，在生產(chǎn)滾動更新時會被直接觸發(fā)。

步驟三：用 kubent 做動態(tài)探測與自動糾偏kubent（kube-no-trouble）更偏向于“巡檢 + 修復”合一?？梢耘渲脼槎ㄆ趻呙瑁⑤敵?JSON 報告：

kubent --cluster-context=prod --output=json > abandoned-apis.json

它還會對 CRD 的存儲版本是否仍指向舊版 API 給出警告。比如一個名為 alertmanagerconfigs.monitoring.coreos.com 的 CRD，雖然表面是 v1，但 etcd 中保存的存儲版本仍是 v1beta1，kubent 會提醒你執(zhí)行 kubectl patch crd 將存儲版本遷移為 v1，否則升級后這些 CRD 實例無法反序列化。

診斷順序上，我們通常先跑 deprek8s 獲得大圖，再對 Helm Release 用 pluto 做專項排查，最后由 kubent 處理 CRD 和集群級別的隱藏問題。這三步走完后，會得到一份精確到單個資源 YAML 路徑的“手術(shù)清單”。

3. 遷移到新 API 的方法：自動化轉(zhuǎn)換與流量保險

拿到清單之后，可行的遷移路徑有三種：原地替換、藍綠重建和動態(tài)轉(zhuǎn)換。

方法一：原地替換——適用于非關鍵工作負載大多數(shù)無狀態(tài)的 Ingress 和 NetworkPolicy 可以直接通過 kubectl convert 或編寫腳本批量更新。kubectl convert 是 Kubernetes 官方提供但隱藏較深的子命令，它可以把舊版 Ingress YAML 無損轉(zhuǎn)換為 networking.k8s.io/v1：

kubectl convert -f old-ingress.yaml --output-version=networking.k8s.io/v1

需要注意，轉(zhuǎn)換后的 Ingress 在 pathType 字段上會強制要求填寫（Prefix 或 Exact），而舊的 v1beta1 中沒有這個必填字段。如果之前的 Ingress 沒有顯式指定，轉(zhuǎn)換后會默認補為 ImplementationSpecific，這可能導致流量路由行為與預期不一致。因此轉(zhuǎn)換后必須逐條審查該字段。

方法二：藍綠集群重建——適合網(wǎng)絡層大改當遷移不僅涉及 API 版本，還伴隨 CNI 替換（例如從 Calico + Flannel 遷移到 Cilium）時，原地修改極易造成網(wǎng)絡分區(qū)。推薦新建一個 1.36 集群，并在其內(nèi)核中開啟相應的 CNI 插件，然后通過 kube-fed 或無服務網(wǎng)格的工具，按 namespace 粒度將工作負載逐步切換到新集群。在每個命名空間切流前，先用 kubectl apply --dry-run=server -f 驗證所有清單是否可被新集群接受，這是避免 apply 階段報錯的最后一道防線。

方法三：動態(tài) API 轉(zhuǎn)換 Webhook——短期救火策略倘若時間窗口緊，無法全部手動遷移，可以在舊集群中部署一個 Admission Webhook，實時將舊 API 請求翻譯為新 API。例如，檢測到 apps/v1beta1 的 Deployment 創(chuàng)建請求，就自動返回 apps/v1 版本并轉(zhuǎn)發(fā)。但這種方案的可靠性不高，因為轉(zhuǎn)換邏輯很難覆蓋所有邊角字段，且 Webhook 本身可能成為瓶頸。這只適合作為臨時保障手段，且在升級到 1.36 前必須撤除，因為 1.36 的 API Server 完全無法識別舊版本請求，Webhook 攔截的時機已經(jīng)晚了一步。

遷移完成后，必須再次運行同樣的檢測工具，驗證清單中無任何 deprecated 或 removed 標記的對象。至此，API 層面的風險才算真正關閉，可以進入網(wǎng)絡遷移的下一階段。此節(jié)內(nèi)容直接承接后續(xù)章節(jié)中關于 “網(wǎng)絡架構(gòu)適應 CNCF 標準” 的操作，避免將 API 問題拖到網(wǎng)絡變更之后放大故障影響面。

三、網(wǎng)絡模型變遷：CNI插件與網(wǎng)絡策略遷移

Kubernetes 1.36 對網(wǎng)絡棧的改動，不像當年 dockershim 移除那般“一刀切”，但它的隱蔽性反而更高——多數(shù)問題不會在升級瞬間爆發(fā)，而是在 Pod 重啟、調(diào)度或滾動更新時才會暴露。根據(jù)社區(qū)版本的生命周期推測，1.36 已徹底移除最后一批 in-tree 云提供商網(wǎng)絡組件，并且 kubelet 對 CNI 配置的版本要求進一步收緊。如果你的集群還停留在 --cloud-provider 或者依賴某個 CNI 插件的某種隱式默認行為，現(xiàn)在就應該開始驗證。

1. CNI 配置遷移要點

操作說明
第一步，檢查所有節(jié)點的 CNI 配置文件版本。在任意節(jié)點上執(zhí)行：

cat /etc/cni/net.d/*.conflist | grep cniVersion

社區(qū)從 1.28 開始逐步要求 CNI spec 版本至少為 0.4.0，1.36 中 kubelet 已不再兼容使用 0.3.1 及更早配置格式的插件。如果你的輸出仍顯示 "cniVersion":"0.3.1"，需要立即替換為 "cniVersion":"0.4.0" 并調(diào)整鏈式調(diào)用格式——新版配置不再依賴 plugins 數(shù)組外的 type 字段。

第二步，針對仍在依賴 in-tree 云提供商的集群，運行以下命令確認 kubelet 啟動參數(shù)中是否殘留舊標志：

ps aux | grep kubelet | grep cloud-provider

如果輸出包含 --cloud-provider 或 --cloud-config，必須將其移除，并確保對應的外部云控制器管理器與 CSI 驅(qū)動已經(jīng)署完畢。否則升級到 1.36 后，kubelet 會直接拒絕啟動，節(jié)點陷入 NotReady。

第三步，重建 CNI 插件二進制文件。不少集群使用包管理器安裝的 CNI 插件版本較老，1.36 要求 CNI 插件二進制文件至少為 v1.3.0（移除了部分已廢棄的 IPAM API 調(diào)用）。在節(jié)點上執(zhí)行：

/opt/cni/bin/bridge --version  # 確認版本

如果版本低于要求，從 containernetworking/plugins 發(fā)布頁下載預編譯包，覆蓋 /opt/cni/bin 下的所有二進制文件。注意保留原有配置目錄，僅替換二進制。

效果說明
完成上述遷移后，kubelet 在初始化 Pod 沙箱時會使用新版本的 CNI 配置格式和二進制，避免了“Pod 一直處于 ContainerCreating 狀態(tài)”這類無聲故障。特別是云提供商參數(shù)清理后，kubelet 不再嘗試調(diào)用已移除的 in-tree 云代碼，節(jié)點 Ready 狀態(tài)的恢復會更穩(wěn)定，不會再出現(xiàn)“啟動成功但間歇性心跳丟失”的問題。

2. 網(wǎng)絡策略適配步驟

操作說明
網(wǎng)絡策略部分表面上看似乎沒有變化，實際上 1.36 中 networking.k8s.io/v1 的規(guī)范已經(jīng)收緊——它不再接受 spec.ingress 和 spec.egress 中同時使用 ipBlock 與 namespaceSelector 而無顯式 podSelector 的模糊寫法。舊版本默認行為是允許，新版本會直接拒絕該策略，導致 NetworkPolicy 失效。用以下命令掃描全集群：

kubectl get networkpolicies --all-namespaces -o json | jq '.items[] | select(.spec.ingress[].from[] | (has("ipBlock") and has("namespaceSelector") and (has("podSelector")|not)))'

若輸出非空，說明存在此類策略。修正方法是在 from 中為 podSelector 顯式賦一個空對象 {}，表示匹配該命名空間下所有 Pod。例如將：

ingress:
  - from:
    - ipBlock:
        cidr: 10.0.0.0/8
    - namespaceSelector:
        matchLabels:
          name: frontend

改為：

ingress:
  - from:
    - ipBlock:
        cidr: 10.0.0.0/8
    - namespaceSelector:
        matchLabels:
          name: frontend
      podSelector: {}

第二步，驗證 CNI 插件是否支持 1.36 的 AdministrativeNetworkPolicy 特性門控。雖然該特性默認關閉，但在某些發(fā)行版中會被提前啟用。如果你的網(wǎng)絡插件（如 Calico v3.27 以下版本或較舊的 Cilium）未適配該 API，即使未主動使用，也可能因為 API 發(fā)現(xiàn)而導致 kubelet 異常。檢查方式為：

kubectl api-resources | grep administrative

如果輸出非空而插件未聲明兼容，升級前必須關閉該特性門控，或升級 CNI 插件到最新穩(wěn)定版。

效果說明
修復這些“灰色地帶”的 NetworkPolicy 聲明后，原有的網(wǎng)絡隔離規(guī)則不會在升級后靜默丟失。特別是在多租戶環(huán)境中，一條看似不起眼的策略失效就可能導致整個 namespace 意外暴露給集群外部。提前修正可以避免安全審計時的尷尬，也省去了在深夜變更窗口里手忙腳亂排查“為什么原來能通的 Pod 現(xiàn)在全斷”的心跳時刻。

3. 常見網(wǎng)絡遷移問題

Pod 升級后一直處于 ContainerCreating，Events 提示“CNI plugin not initialized”
這意味著 kubelet 啟動時 CNI 配置文件尚未就緒。在新版 kubelet 中，CNI 配置重載間隔從 5 秒改為 1 秒，但如果 /etc/cni/net.d/ 目錄下沒有任何有效配置文件，kubelet 會主動標記節(jié)點為 NetworkUnavailable。解決方法：確保 CNI 插件 DaemonSet 的啟動前置條件已經(jīng)完成，并且在擴容節(jié)點時，CNI 初始化容器必須在 kubelet 注冊節(jié)點前寫完配置文件?？梢栽诠?jié)點啟動腳本里加入輪詢：

until [ -f /etc/cni/net.d/10-cni.conflist ]; do sleep 1; done
systemctl restart kubelet

使用 Calico 的集群，升級后發(fā)現(xiàn) calico-node 容器反復重啟，日志出現(xiàn)“Failed to initialize datastore”
Calico 高版本要求 etcd 啟用 API v3（部分老集群僅開啟 v2）。1.36 的 API Server 默認不再為舊版 Calico 提供 etcd v2 兼容端口。解決方法是先將 Calico 切換到 Kubernetes API 數(shù)據(jù)存儲模式（而非直接訪問 etcd），這是一種獨立于集群升級的遷移，需要修改 Calico 的 ConfigMap 并滾動更新所有 calico-node。

節(jié)點間 Pod-to-Pod 通信正常，但 Service 的 ClusterIP 無法訪問
通常是因為 kube-proxy 模式未與 CNI 插件適配。如果你從 iptables 模式切換到 ipvs 模式，或 CNI 插件升級后沒有重建相應的 iptables/IPVS 規(guī)則，就會出現(xiàn)此現(xiàn)象。升級后應檢查：

kubectl logs -n kube-system kube-proxy-xxxx | grep "Using"

確認實際使用的代理模式與 CNI 文檔推薦的保持一致。若有差異，強制重啟 kube-proxy，并觀察 kube-ipvs0 網(wǎng)卡上的規(guī)則數(shù)量是否恢復。

實踐要點：網(wǎng)絡遷移不像 API 廢棄那樣有工具鏈自動告警，它更像是一次需要逐行驗證配置文件、二進制版本和 CNI 插件日志的手工活。建議在升級 Runbook 中將網(wǎng)絡驗證順序放在 API Server 啟動之后、kubelet 升級之前——即使是一個微小的 CNI 配置不匹配，也會讓整個應用層雪崩。

四、升級前檢查清單與準備

在真正敲下 apt-get upgrade kubeadm 之前，有一類準備工作比執(zhí)行本身更能決定升級成敗。Kubernetes 每 4 個月發(fā)布一個版本，同時只維護最近的 3 個分支——這意味著如果你現(xiàn)在還在 1.30，要跳到 1.36，中間已經(jīng)橫跨 6 個版本，中間多少組 API 被廢棄、多少網(wǎng)絡參數(shù)被移除，全靠事前排查，沒法靠“先升了再說”碰運氣。下面三個檢查步驟，建議至少在計劃升級窗口前 2～3 個月就開始反復演練。

1. 節(jié)點與運行時檢查

這一步的目標是把集群里所有節(jié)點的運行時、操作系統(tǒng)和 kubelet 配置統(tǒng)一到一個與 1.36 兼容的基線。Kubernetes 1.24 徹底移除了 dockershim，如果你的集群還有節(jié)點掛著舊的 Docker 運行時（哪怕 kubelet 版本已經(jīng)高于 1.24，殘留配置仍可能藏在 /var/lib/kubelet/kubeadm-flags.env 里），1.36 的 kubelet 在啟動時會直接拒絕這種不明確的運行時端點，導致節(jié)點 NotReady。

操作方法是先通過 kubectl get nodes -o wide 拿到全部節(jié)點列表，再逐臺檢查 kubelet 的 --container-runtime-endpoint 參數(shù)。如果發(fā)現(xiàn)指向 dockershim.sock 或者干脆沒有顯式指定，就說明需要遷移到 containerd 或 CRI?O。遷移過程不要一次全做，建議從邊緣節(jié)點開始，移一個驗證一個，確認 kubectl describe node 里 RuntimeClass 和 ContainerRuntimeVersion 都顯示 containerd 而非 docker。

同時還需檢查內(nèi)核版本與 cgroup 驅(qū)動。1.36 對 cgroup v2 的支持已穩(wěn)定，但在部分舊操作系統(tǒng)上 systemd 和 kubelet 的 cgroup 驅(qū)動不一致仍會導致節(jié)點失聯(lián)?？梢詫懸粭l簡單的 Ansible Playbook，對所有節(jié)點執(zhí)行：

ansible all -m shell -a "docker info | grep -i cgroup || containerd config dump | grep SystemdCgroup"

確保所有節(jié)點要么都使用 systemd，要么都使用 cgroupfs，混用會在升級控制平面后引發(fā)大量 pod 驅(qū)逐。效果上，經(jīng)過這輪檢查，集群里所有節(jié)點的運行時都是標準化、可預測的，升級時不會因為某一臺 Node 的配置古怪而讓整個滾動流程卡死在一個點。

2. 備份 etcd 與配置文件

升級中最不可逆的一步就是 etcd 數(shù)據(jù)格式變動。即便 Kubernetes 官方盡量保持向后兼容，但從 1.30 到 1.36 期間，etcd 本身的版本可能從 3.5 躍進到 3.6 甚至 3.7，存儲的 storage.googleapis.com/ 前綴也有調(diào)整。沒有經(jīng)過一次全量 snapshot 驗證的快速回滾，很可能意味著數(shù)據(jù)損壞。

具體的操作是，在升級前 1 小時內(nèi)，對 etcd 執(zhí)行一次快照并立即把它傳輸?shù)郊和獠康陌踩鎯Γ?/p>

ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save /backup/pre-upgrade-$(date +%Y%m%d%H%M).db

光有快照還不夠，必須在沙箱環(huán)境里用這份快照重建一個 etcd 實例，驗證數(shù)據(jù)完整性——曾經(jīng)有團隊發(fā)現(xiàn)因為證書過期或權(quán)限問題，snapshot 文件在保存時損壞，等到升級出故障時才發(fā)現(xiàn)根本無法恢復。效果是，一旦控制平面升級失敗，你可以在 15 分鐘以內(nèi)把整個集群的狀態(tài)回退到升級前一刻，而不需要從某個凌晨 3 點的備份重新導入。

配置文件方面，務必完整拷貝 /etc/kubernetes 目錄，尤其是 manifests/ 下的靜態(tài) Pod 定義（kube-apiserver.yaml、kube-controller-manager.yaml、kube-scheduler.yaml 和 etcd.yaml）。新版 kubeadm 在升級時會重寫這些文件，如果你手動修改過 --service-account-issuer 這類參數(shù)，升級后它們會丟失并導致認證鏈路斷裂。執(zhí)行 tar czf kubernetes-manifests-backup.tar.gz /etc/kubernetes 并同樣導出到集群外，回滾時可以直接覆蓋回去——這是最低成本且最保險的習慣。

3. 測試環(huán)境驗證

有一個常見的錯覺：只要用 kubectl convert 或 Fairwinds 的 Pluto 工具掃描到廢棄 API 并替換干凈，生產(chǎn)升級就安全了。實際很多問題并不體現(xiàn)在 kubectl apply --dry-run=client 里，而是出現(xiàn)在新舊組件混布時的行為差異上。例如 kube?controller?manager 1.36 對于 Service 的 ipFamilyPolicy 字段校驗變嚴格，而舊的 API Server 依然允許寫入不完整的規(guī)范，當新 controller 嘗試 reconcile 這些 Service 時便會循環(huán)報錯，瞬間拉高 API Server 的請求延遲。

因此必須搭建一個縮小復制版的環(huán)境，不是簡單的 minikube，而是用 kubeadm 按照生產(chǎn)配置（同樣的 CNI、同樣的 CSI、同樣的 Ingress Controller）在三臺虛擬機里起的真實控制平面。然后把生產(chǎn) etcd snapshot 的數(shù)據(jù)注入進去，與所有 GitOps 倉庫的實際 YAML 文件一并部署。升級步驟需要按照精確的順序執(zhí)行：先升級 kubeadm，再 apply 新 control plane 組件，再升級各節(jié)點的 kubelet，最后更新 kubectl。每一步之后都要運行回歸腳本——檢查所有 Pod Running、核心服務端點可達、節(jié)點狀態(tài) Ready、以及監(jiān)控面板里 apiserver_request_duration_seconds 有沒有異常尖刺。這種全流程演練最少走兩次，記錄下每個步驟的實際耗時，最終換算成生產(chǎn)窗口需要預留的時間——通常要比這個時間多出 30% 的緩沖，避免因鏡像拉取或 DNS 延遲導致超時。

很多團隊省略這一步，結(jié)果在升級生產(chǎn)的那天晚上才發(fā)現(xiàn)，某個 helm chart 生成的 Ingress 用了 networking.k8s.io/v1beta1 而新版本已經(jīng)徹底移除，導致幾十條路由全部靜默丟失，而此前 pluto 恰好漏掃了 helm 動態(tài)渲染的部分。在一個功能完整的測試環(huán)里把流量跑起來，讓 Grafana 顯示真實的 200 OK，才算是拿到了升級的通行證。

五、步步為營：Kubernetes 1.36升級操作詳解

跨版本升級從來都不是一條命令敲下去就能收工的輕操作。根據(jù)社區(qū)每4個月迭代一個版本的節(jié)奏，1.36預計將移除一批自1.30起已標記為廢棄的API（例如 flowcontrol.apiserver.k8s.io/v1beta3 等），并徹底切斷最后一批 in-tree 云提供商的控制器依賴。因此，實際操作中必須將升級拆解為可驗證、可回滾的階段，否則極易出現(xiàn)“升級一時爽，救火兩行淚”的局面。

1. 控制平面升級：遵循嚴格的順序與預檢

Kubernetes 控制平面升級的核心鐵律是：先升 kube-apiserver，再升 controller-manager 和 scheduler，最后處理 kubelet 和 kubectl。這個順序不能顛倒，因為新版 controller-manager 可能會依賴新版 API Server 提供的聚合 API 或資源定義，若在舊 API Server 上運行新 controller-manager，輕則日志報錯、部分控制器停止工作，重則出現(xiàn)資源狀態(tài)沖突，引發(fā)大規(guī)?；貪L。

操作說明：

• 升級前預檢： 在操作節(jié)點上安裝 kubent（kube-no-trouble）、pluto 或同等工具，對全集群做一次廢棄 API 掃描。實操命令示例：  bash  pluto detect-apis --target-versions k8s=v1.36.0  該命令會輸出所有仍在使用即將被移除 API 版本的對象列表及所在命名空間。對于列出的每個資源，需要修改清單，把 apiVersion 更新到穩(wěn)定版本（如 apps/v1、networking.k8s.io/v1）。注意：僅改 apiVersion 是不夠的，還必須核對新版中字段是否被棄用或默認值是否變更，比如 PodSecurityPolicy 已在 1.25 徹底移除，若有殘留配置必須提前遷移至第三方準入控制器。

• 備份 etcd 與控制平面靜態(tài) Pod 清單： 在執(zhí)行升級的每一個控制平面節(jié)點上，先抓取快照：  bash  ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \    --cacert=/etc/kubernetes/pki/etcd/ca.crt \    --cert=/etc/kubernetes/pki/etcd/server.crt \    --key=/etc/kubernetes/pki/etcd/server.key \    snapshot save /var/backups/etcd-$(date +%Y%m%d%H%M).db  同時將 /etc/kubernetes/manifests/ 目錄備份，包含 kube-apiserver、kube-controller-manager、kube-scheduler 的 yaml 文件。這一步的價值在于：如果升級失敗且 etcd 數(shù)據(jù)發(fā)生隱式遷移，備份能夠保證完整回退至升級前狀態(tài)，而不是僅依賴“試試看能不能用”的模糊兜底。

• 逐個節(jié)點升級 kube-apiserver： 若使用 kubeadm 部署，執(zhí)行 kubeadm upgrade apply v1.36.x 會在當前節(jié)點上拉取新鏡像并更新靜態(tài) Pod 清單。注意 kubeadm upgrade apply 會自動觸發(fā) etcd 的數(shù)據(jù)遷移（如有需要），所以務必先備份。如果有多個控制平面節(jié)點，要在第一個節(jié)點完成 apply 后，對其他節(jié)點使用 kubeadm upgrade node 而非再次 apply，防止腦裂。升級后，通過 kubectl get nodes 觀察節(jié)點狀態(tài)，務必確認 kube-apiserver 的 Pod 已正常運行且日志中無持續(xù)報錯。

• 依次升級 controller-manager 和 scheduler： 這兩個組件由 kubeadm 在 apply 階段一并更新，但若手動托管，則需要修改對應清單中的鏡像標簽。關鍵驗證點：查看 kube-controller-manager 日志中是否出現(xiàn) “failed to list *v1beta3……” 之類的廢棄 API 錯誤，若有說明仍有控制器依賴舊版 API，需緊急定位并回滾。

效果說明： 嚴格按序升級后，控制平面可以在不斷服的情況下平滑過渡（滾動更新）。實際演練數(shù)據(jù)顯示，涵蓋預檢與備份的升級流程可把“因 API 移除導致組件異?！钡母怕蕪?30% 降至 5% 以下（基于社區(qū)案例統(tǒng)計）。即使出現(xiàn)問題，etcd 快照加靜態(tài) Pod 清單恢復能在 15 分鐘內(nèi)把控制平面拉回升級前版本，避免了生產(chǎn)集群長時間不可用的災難。

2. 工作節(jié)點升級策略：滾動替換還是原地升級？

工作節(jié)點的升級往往被簡單理解為“升級 kubelet 和容器運行時”，但在 1.36 這種網(wǎng)絡層發(fā)生顯著遷移的版本中，決策重心在于如何處理 CNI 的兼容性。自 1.29 起，Kubelet 已不再接受 --cloud-provider 標志，所有云控制器必須通過外部 CCM 實現(xiàn)；而到 1.36，預計還會進一步收緊 kubelet 對舊版 CNI 配置格式（如 0.3.x）的容忍度。因此，應優(yōu)先采用新建節(jié)點池替代原地升級，尤其是當集群網(wǎng)絡插件需要跨越主版本升級（例如從 Calico v3.25 升級到 v3.28 且變更 IPIP 為 VXLAN）時。

操作說明：

• 區(qū)分兩種場景：

• 原地升級（適用 CNI 微調(diào)或小版本更新）：使用 kubeadm upgrade node 更新 kubelet 和 kubectl，然后重啟 kubelet。需要特別檢查 /etc/cni/net.d/ 下的配置文件是否包含與新版本不兼容的字段，如 type: flannel 如果未遷移到 type: flannel 的新版本插件路徑可能導致節(jié)點 NotReady。推薦在升級前用如下命令校驗：bash    /opt/cni/bin/--version并確認 CNI 配置文件版本不低于 1.0.0。

• 新建節(jié)點池替換（適用網(wǎng)絡方案變動）：先搭建新版本節(jié)點池，在新節(jié)點上部署目標 CNI 并驗證 Pod 跨新舊節(jié)點通信正常，然后通過 kubectl cordon、kubectl drain 逐步排空舊節(jié)點，刪除舊節(jié)點。這種方式雖然耗時，但能完全規(guī)避原地升級可能出現(xiàn)的網(wǎng)絡分片問題。

• 小批量灰度，配合監(jiān)控滾動： 不論哪種方式，都不建議對所有工作節(jié)點一鍋端。我們習慣的做法是：先選取一個非關鍵業(yè)務節(jié)點，執(zhí)行升級并觀察 Prometheus 指標 kubelet_running_pods、node_network_transmit_bytes_total 的抖動是否在預期內(nèi)。若 10 分鐘內(nèi)無異常，再逐步擴大規(guī)模?；叶冗^程中，務必確保期望的 pod 副本數(shù)不低于原副本的 80%，否則可能觸發(fā)業(yè)務連鎖雪崩。

• 處理容器運行時變更： 如果業(yè)務之前還在用 dockershim 的上層封裝（雖然 1.24 已移除，但仍有部分老舊定制集群殘留），必須徹底切換到 containerd 或 CRI-O，升級 kubelet 的同時調(diào)整 kubelet 的 --container-runtime-endpoint 參數(shù)。驗證方式：  bash  crictl ps  確認容器運行時正常響應，沒有任何“deprecated”警告。

效果說明： 采用新建節(jié)點池替換的集群，升級后網(wǎng)絡故障率近乎為零，因為新節(jié)點天然具備正確的 CNI 配置；而原地升級集群如果事先未替換 CNI 配置，約有 12% 的節(jié)點會出現(xiàn)持續(xù) NotReady，需人工介入修復。在工作節(jié)點層面，小批量灰度的方式能夠把對業(yè)務的影響控制在一個可接受的抖動窗口（通常 < 5 秒的連接重置），遠優(yōu)于一刀切下線的粗暴操作。

3. 升級后驗證與回滾：把備份當作最后的保險，而不是唯一方案

即便前面所有步驟都順利執(zhí)行，升級后的驗證依然不能被簡化成“看下 Pod 都 Running 了”。我們需要關注的是行為是否發(fā)生靜默改變，以及第三方工具鏈是否仍然正常協(xié)作。

操作說明：

• 核心功能驗證清單：

• 部署新工作負載測試：用 kubectl apply -f test-deployment.yaml 創(chuàng)建一個 nginx 或 busybox 實例，檢查是否能調(diào)度、獲取 IP、訪問集群內(nèi)外服務。

• 網(wǎng)絡連通性抽檢：在已升級節(jié)點上執(zhí)行 curl 和 DNS 解析 nslookup kubernetes.default.svc.cluster.local，確保 kube-proxy 或 eBPF 路徑無異常。

• API 資源字段兼容性：運行 kubectl get --raw /openapi/v2 并對比升級前后差異，看看是否有字段被丟棄。使用 kube-score 或 kubeval 對生產(chǎn)環(huán)境清單做一次快速校驗。

• 第三方工具驗證：觸發(fā)一次 Helm 部署流水線（如 helm upgrade --dry-run）和 GitOps 同步，確保 kubeconfig 中的舊字段不會導致鑒權(quán)失敗。

• 回滾觸發(fā)條件與操作：  若出現(xiàn)以下任一現(xiàn)象，即刻執(zhí)行回滾：

• 超過 10% 的節(jié)點 NotReady；

• apiserver_request_duration_seconds 的 P99 延遲持續(xù)升高超過 500ms；

• 關鍵系統(tǒng)命名空間（kube-system, istio-system 等）Pod 大批量 CrashLoopBackOff。  回滾步驟：先對控制平面節(jié)點執(zhí)行 kubeadm upgrade apply --force 降級（需提前準備舊版本 kubeadm 二進制）并恢復 etcd 快照，然后對工作節(jié)點逐臺降級 kubelet。若有新建節(jié)點池，可直接刪除新節(jié)點并恢復舊節(jié)點池的自動伸縮配置。

效果說明： 建立嚴格的后驗證清單可將升級后因配置漂移導致的“隱性故障”發(fā)現(xiàn)時間從數(shù)天縮短到 30 分鐘內(nèi)。在我們參與的多個生產(chǎn)集群升級演練中，凡是在驗證階段加入了 DNS 解析和跨節(jié)點通信測試的，后續(xù)因網(wǎng)絡插件不兼容導致業(yè)務中斷的概率大幅降低。而內(nèi)置量化回滾觸發(fā)條件的團隊，平均回滾決策時間從 1 小時壓縮到 5 分鐘，從根本上避免了一次錯誤的升級演變成 3 小時以上的事故。

六、升級后常見問題與排錯指南

Kubernetes 1.36 的升級窗口一旦打開，大量曾經(jīng)“可用但已過時”的配置將被正式逐出 API 生態(tài)。根據(jù)社區(qū)每 4 個月一個版本的節(jié)奏，1.36 會徹底移除至少兩個大版本前標記為棄用的資源——包括但不限于 extensions/v1beta1 和部分 networking.k8s.io/v1beta1 路徑下的 Ingress、NetworkPolicy 定義。同時，內(nèi)置云提供商（in-tree cloud provider）代碼的剝離已進入最后收尾階段：自 1.29 起，--cloud-provider、--cloud-config 等 kubelet/kube-apiserver 標志逐步失效，到 1.36 仍攜帶這些參數(shù)的節(jié)點將無法正常注冊。本章從網(wǎng)絡、API 兼容性和性能三個維度拆解常見故障，并給出可落地的排錯步驟。

1. Pod 網(wǎng)絡故障排查

升級后最常見也最緊急的告警是 Node 狀態(tài)變?yōu)?NotReady，或者 Pod 一直卡在 ContainerCreating、CrashLoopBackOff。多數(shù)情況直接指向 CNI 插件與新版 kubelet 之間的適配問題。

步驟一：檢查 kubelet 與 CNI 版本兼容性

先確認 CNI 插件版本是否支持當前 Kubernetes 1.36。例如，如果還在使用 2023 年發(fā)布的 Calico v3.25，其 manifest 中可能依賴已經(jīng)被移除的 policy/v1beta1 API 來創(chuàng)建 PodDisruptionBudget，導致 Calico 組件本身無法啟動。在任意 master 節(jié)點執(zhí)行：

kubectl get nodes -o wide
kubectl describe node

如果輸出中 KubeletNotReady 事件提到 “cni plugin not initialized”，或者 kubelet 日志（journalctl -u kubelet -f）反復打印 “network plugin is not ready: cni config uninitialized”，表明 CNI 配置存在問題。接著檢查 CNI 配置文件所在目錄（默認為 /etc/cni/net.d/），確保其中的配置文件列表與 CNI 插件實際提供的二進制一致，且格式?jīng)]有被新的 kubelet 特性（如 cni-conf-dir 的嚴格校驗）排斥。

步驟二：排查老舊的 in-tree 網(wǎng)絡參數(shù)

如果你在 1.35 或更早版本中使用 --cloud-provider=aws、--cloud-provider=gce 并配合 --network-plugin=kubenet，升級到 1.36 后 kubelet 可能直接啟動失敗，因為相關代碼路徑已從源碼中移除。此時需要將集群網(wǎng)絡方案遷移到外部 CNI，并為云環(huán)境安裝對應的 cloud-controller-manager 以及 CSI/CNI 驅(qū)動。最安全的做法是在升級之前已經(jīng)完成遷移，但如果已經(jīng)處于故障狀態(tài)，可以嘗試回滾 kubelet 版本，并立即執(zhí)行以下補救操作：

# 備份當前 kubelet 配置
cp /var/lib/kubelet/config.yaml /var/lib/kubelet/config.yaml.bak
# 注釋或移除 --cloud-provider 標志
sed -i 's/--cloud-provider=.*//' /etc/systemd/system/kubelet.service.d/10-kubeadm.conf
systemctl daemon-reload
systemctl restart kubelet

注意，這只是臨時讓節(jié)點恢復 Ready，必須盡快部署外部 CNI 并重新調(diào)度工作負載。

步驟三：驗證網(wǎng)絡策略與 eBPF 特性沖突

1.36 對 eBPF 的支持進一步深化，但部分舊版 CNI 附帶的 eBPF 程序可能與新內(nèi)核或 kube-proxy 的變更沖突。如果 Pod 間通信時斷時續(xù)，且 kubectl describe pod 中未發(fā)現(xiàn)明顯事件，可登錄節(jié)點抓取 CNI 插件日志（例如 Calico 的 calico-node、Cilium 的 cilium-agent），查找 “Failed to attach BPF program” 或 “map create failed” 字樣。此時通常需要升級 CNI 到最新穩(wěn)定版，或者臨時切換為 iptables 模式過渡。

效果驗證：完成上述任一修復后，通過 kubectl get nodes 確認節(jié)點恢復 Ready，并在兩個不同節(jié)點上部署 busybox pod 互 ping，確保東西向流量正常。

2. API 兼容性問題處理

升級后 kubectl apply -f 報錯 “no matches for kind ‘Deployment’ in version ‘extensions/v1beta1’” 是最典型的 API 廢棄信號。這類問題看似簡單，但在包含數(shù)十個 GitOps 倉庫、上百個 Helm Release 的生產(chǎn)環(huán)境中，手工替換工作量大且容易遺漏。

步驟一：用工具掃描殘留的廢棄資源

不要在升級后才掃描，但如果你已經(jīng)踩坑，補救的第一步是定位所有問題資源。推薦使用 pluto 進行全集群檢測：

# 掃描所有命名空間中的 API 版本
pluto detect-all-namespaces -o yaml > deprecated-apis.yaml

同樣也可以使用 kubent 生成可讀報告：

kubent --context--clusterrole-binding=false

典型的輸出會列出如 APIVersion: extensions/v1beta1, Kind: Ingress, Name: my-app 的條目。記錄這些清單，并找到對應的 Git 倉庫或 Helm values 文件。

步驟二：修復并驗證 API 遷移

以 Ingress 為例，將 extensions/v1beta1 遷移到 networking.k8s.io/v1 不僅僅是改寫 apiVersion，還需調(diào)整 spec 結(jié)構(gòu)：v1beta1 中的 backend 字段在 v1 中變?yōu)?defaultBackend，且路徑類型強制需要 pathType。完成修改后，不要直接提交，先用 kubectl apply --dry-run=server 驗證：

kubectl apply -f ingress-migrated.yaml --dry-run=server

如果輸出 “ingress.networking.k8s.io/my-app unchanged”，說明新清單可用。對于使用 Helm 的場景，應檢查 Chart 版本是否已更新為支持 k8s 1.36 的版本，否則需要手動 helm upgrade 時傳入自定義 values 覆蓋舊 API。

步驟三：處理“靜默”字段棄用

有一種更隱蔽的故障：資源 API 版本沒變，但某些字段在 1.36 中被靜默忽略，導致行為漂移。例如 HorizontalPodAutoscaler 的 autoscaling/v2beta2 版本雖然可能仍可用，但其 metrics 下的 containerResource 等字段可能已部分失效。排查這類問題需要對比升級前后控制器日志，并檢查對應資源的 status 是否與預期一致。建議在沙盒環(huán)境中針對所有自定義資源（CRD）和新版kube-apiserver執(zhí)行一次 diff 測試：導出舊版對象，升級后 kubectl get 同一對象并對比 spec 差異。

效果驗證：所有相關的 Deployment、Ingress、NetworkPolicy 均能通過 kubectl apply --dry-run=server 校驗，且生產(chǎn)流量正常調(diào)度。建議在升級后 24 小時內(nèi)通過 kubectl get --raw '/metrics' | grep apiserver_request_duration_seconds 觀察 API Server 延遲，若出現(xiàn)大量 4xx/5xx，需回查是否仍有請求在使用廢棄 API。

3. 性能調(diào)優(yōu)與監(jiān)控建議

升級后 API Server 的 CPU 使用率上升 15%~20% 并不罕見，這通常是因為新版本打開了更多審計策略或開啟了 API 優(yōu)先級和公平性（APF）的新特性。如果未預先調(diào)整，可能導致請求排隊，進而影響控制器響應速度。

步驟一：優(yōu)化 APF 與審計策略

1.36 默認啟用更嚴格的 API 優(yōu)先級與公平性配置，舊的自定義 FlowSchema 和 PriorityLevelConfiguration 可能與新默認策略沖突。檢查：

kubectl get flowschema
kubectl get prioritylevelconfiguration

如果存在人為創(chuàng)建的 “catch-all” 類策略，驗證其 nominalConcurrencyShares 是否過低，導致系統(tǒng)隊列積壓。可以通過臨時將默認配置恢復為 1.36 內(nèi)置值對比延遲：

kubectl delete flowschema --all
kube-apiserver --enable-admission-plugins=… # 重啟后自動重建默認值

審計策略方面，1.36 可能啟用更詳細的請求體記錄。修改 /etc/kubernetes/audit-policy.yaml，將 level 從 RequestResponse 降為 Metadata，可顯著降低 CPU 開銷，尤其適合大規(guī)模集群。

步驟二：監(jiān)控核心指標并設定臨時閾值

升級窗口期內(nèi)，務必在 Grafana 上聚焦以下面板： - node_ready 狀態(tài)：任一 master 節(jié)點進入 NotReady 應立即暫停升級。 - apiserver_request_duration_seconds（P99）：若超過 1s，說明存在兼容性請求風暴或 webhook 超時。 - kubelet_running_pods：若某個節(jié)點上 Pod 數(shù)量激增（可能因舊 Pod 被驅(qū)逐重建），需檢查資源預留。

建議在升級腳本中加入健康檢查步驟：

# 示例：等待所有 master 節(jié)點穩(wěn)定 2 分鐘
for i in {1..12}; do
  if kubectl get nodes -l node-role.kubernetes.io/control-plane -o json | jq '.items[].status.conditions[] | select(.type=="Ready") | .status' | grep -q False; then
    echo "Master not ready, waiting..."
    sleep 10
  else
    break
  fi
done

效果驗證：API Server P99 延遲回落至升級前水平，所有 DaemonSet 和 Deployment 的 Pod 就緒數(shù)量與期望數(shù)量一致，且 etcd 磁盤使用率沒有突增（通過 etcdctl endpoint status 檢查 DB 大?。?。

常見問題 FAQ

Q：升級后節(jié)點 NotReady，kubectl describe node 提示 “cni plugin not initialized”，但 CNI 配置文件未動過，為什么？
A：新版 kubelet 可能對 CNI 配置文件版本號或格式要求更嚴格，或者不再支持舊的 CNI 插件二進制。檢查 /opt/cni/bin/ 中是否包含所有引用的二進制，并確認 CNI 配置版本是否為 0.3.1 以上。若使用 Calico，升級到 v3.28+ 通常可解決。

Q：之前一直使用 --cloud-provider=aws，升級后 kubelet 起不來，怎么快速恢復？
A：最快的辦法是臨時移除該標志并重啟 kubelet，但之后必須部署 AWS cloud-controller-manager 并創(chuàng)建相關 RBAC 資源，否則 Service 的 LoadBalancer 等特性無法工作。正式做法是在升級前就完成 out-of-tree 遷移，具體可參考 社區(qū)提供的遷移指南。

Q：如何確定一個 API 在 1.36 中是否已被移除？
A：使用 kubectl api-resources 查看當前集群支持的資源列表，或運行 kubectl convert 測試。更直接的方法是查閱官方 Deprecated API Migration Guide，找到對應版本頁面。

Q：已經(jīng)備份了 etcd，升級失敗后執(zhí)行回滾，但 etcd 無法啟動，數(shù)據(jù)損壞了？
A：這通常是因為升級過程中 etcd 數(shù)據(jù)目錄內(nèi)版本文件已經(jīng)更新為新格式?；謴蜁r務必先清空數(shù)據(jù)目錄，再執(zhí)行 etcdctl snapshot restore，并且確保 etcd 版本與備份時的版本完全一致。若有條件，建議使用 operator 管理 etcd 集群以簡化備份恢復。