gke-upgrades

GKE 升級與維護

根據使用者的環境量身打造清晰且具可操作性的文件——包括升級計劃、Runbook 或檢查清單。產出內容應針對其叢集模式、發布通道、版本及工作負載類型進行客製化，而非提供通用建議。

始終圍繞自動升級模式展開指導：配合維護時段（Maintenance Windows）與排除項（Exclusions）的自動升級是首選的控制機制。

上下文資訊收集

在產出任何升級產物前，請先確認：

• 叢集模式 — Standard 還是 Autopilot？（Autopilot 無需管理節點池、強制要求資源 Request、不支援 SSH）
• 當前與目標版本 — 節點與控制平面（Control Plane）的版本偏差（Version Skew）必須在 2 個次要版本（Minor Version）以內。
• 發布通道 — Rapid、Regular、Stable 或 Extended。
• 環境拓撲與分階段發布（Rollout Sequencing） — 單叢集 vs 多叢集、開發/測試/正式環境分層，以及是否使用 Rollout Sequencing。
• 工作負載敏感度 — StatefulSet、資料庫、GPU、長時間執行的批次作業等需要特殊處理。

若使用者已事先提供這些資訊，請直接開始生成交付物。若資訊模糊，請填入合理的預設值並註明假設條件。

核心原則

GKE 版本遵循 Kubernetes 的版本命名規範：主要版本.次要版本.修補版本（例如 1.30.1-gke.1187000）。次要版本（Minor）升級（如 1.29 → 1.30）會引入新功能與 API。修補版本（Patch）升級（如 1.30.1 → 1.30.2）則包含安全性修復與 Bug 修復。請確保使用者清楚此差異。

1. 控制平面按順序升級，節點池支援跨級升級 -- 控制平面升級必須依序進行（N → N+1 → N+2）。節點池則支援跨版本（N+2）升級。
2. 控制平面優先 -- 必須先升級控制平面，才能升級節點池。節點版本最多可落後控制平面 2 個次要版本。
3. 環境推進 -- 務必先升級開發/測試環境，再升級正式環境。建議優先使用 Rollout Sequencing 來自動化並強制執行跨環境的推進順序（如 dev → staging → prod）；若未採用 Rollout Sequencing，則需人工協調版本推進。
4. 感知工作負載 -- 升級策略取決於執行的內容（無狀態、有狀態、GPU、批次作業）。
5. 優先使用發布通道 -- 始終推薦使用發布通道。注意，「無通道（No channel）」（靜態版本控制）已被棄用，叢集應遷移至發布通道。
6. 復原/降級（Rollback） -- 控制平面的修補版本以及節點池（次要與修補版本）均可進行降級/復原（降級至目標版本）。GKE 支援兩階段的控制平面次要版本升級，其中階段 1 可進行復原。其餘控制平面的次要版本降級無法由客戶自行操作，需要聯繫 GKE 技術支援。
7. 節點池升級順序 -- 升級多個節點池時，始終建議按順序執行：先升級非關鍵/無狀態節點池（作為金絲雀/Canary），驗證叢集健康狀況後，再升級關鍵的有狀態（資料庫）或 GPU 節點池。

發布通道

通道 (Channel)	適用場景	SLA
Rapid	開發/測試環境、優先體驗新功能	無升級穩定度 SLA
Regular（預設）	大多數正式環境	完整 SLA
Stable	關鍵任務、穩定度優先	完整 SLA
Extended	合規需求、EoS 強制升級控制	完整 SLA

支援生命週期

標準 GKE 版本在進入 Regular 通道後提供 14 個月的支援。這意味著：

• Rapid 通道版本的支援時間可能超過 14 個月（因為在進入 Regular 前已先進入 Rapid）。
• Stable 通道版本的支援時間可能少於 14 個月（因為在 Regular 之後才進入 Stable）。
• Extended 延伸支援可將此期限延長至最多 24 個月。請注意，僅在延伸支援期間（第 15-24 個月）會收取額外費用。

維護時段與排除項

設定維護時段（Maintenance Windows）以控制自動升級的執行時間。此外，GKE 除叢集層級外，也支援節點池層級的維護排除項（Maintenance Exclusions），用以封鎖特定工作負載的升級。

排除項類型與限制：

• 「不升級（No upgrades）」 (範圍: no_upgrades): 封鎖所有升級（次要版本、修補版本、節點池）。
  • 限制: 在任何 365 天滾動窗口內，累計排除時長最多 90 天。
  • 串聯限制: 受限於 365 天滾動限制，您無法透過串聯多個排除項來涵蓋超過 90 天的連續期間（例如無法使用 no_upgrades 涵蓋長達 100 天的凍結期）。
• 「不升級次要版本與節點（No minor or node upgrades）」 (範圍: no_minor_or_node_upgrades): 封鎖次要版本與節點池升級，但允許控制平面修補版本升級（低風險）。
  • 限制: 每個排除項最長 180 天。可透過新增排除項延伸至該次要版本的支援終止日（EoS）。
• 「不升級次要版本（No minor upgrades）」 (範圍: no_minor_upgrades): 封鎖次要版本升級，但允許控制平面修補版本與節點池升級。
  • 限制: 每個排除項最長 180 天。可延伸至 EoS。

重要排除項規則（在推薦排除項時必須遵守，且必須包含在最終的文字回覆中）：

1. 僅限自動升級: 維護排除項僅會封鎖自動升級。由使用者發起的手動升級將繞過排除項。您必須向使用者說明這一點。
2. 警告切勿使用「No channel」: 您必須明確警告，停用發布通道（「No channel」/ 靜態版本控制）已被棄用，切勿將其作為替代排除項的手段。
3. 比較作用範圍: 您必須說明「No upgrades」（有天數限制、封鎖修補版本）與「No minor or node upgrades」（允許修補版本、期限更長）之間的差異。當使用者希望在阻止次要版本升級的同時允許安全性修補/修復時，請推薦「No minor or node upgrades」。
4. 處理超過 90 天的需求: 若使用者需要封鎖升級超過 90 天，您必須解釋「No upgrades」在 365 天滾動窗口內受限於 90 天（無法串聯涵蓋更長的連續期間），並建議使用「No minor or node upgrades」（每個排除項最長 180 天，可延伸至 EoS）或針對次要版本直到支援終止日（End of Support）的持久排除項。
5. 版本偏差（Version Skew）: 使用排除項時需注意控制平面與節點池之間的版本偏差。確保偏差不會超過所支援的 2 個次要版本。對於持久排除項，請使用 --add-maintenance-exclusion-until-end-of-support。
6. 正確的 gcloud 語法: 在提供與排除項相關的 gcloud 指令時，您必須使用獨立的 Flag 語法：--add-maintenance-exclusion-name、--add-maintenance-exclusion-start、--add-maintenance-exclusion-end（或 --add-maintenance-exclusion-until-end-of-support）以及 --add-maintenance-exclusion-scope（切勿使用以逗號分隔的單一 --add-maintenance-exclusion Flag）。

強制升級覆寫（Overrides）

GKE 保留在執行必要作業時覆寫使用者自訂維護時段與排除項的權利。這些覆寫無法被停用或封鎖。

常見的覆寫場景：

• 緊急安全性修補程式: 為保護基礎架構而必須立即套用的緊急漏洞修復。
• 支援終止（EoS）/ 產品終止（EOL）強制執行: 若叢集正在執行不受支援的版本，GKE 將強制將其升級至受支援的版本。
• 憑證即將到期: 若控制平面憑證（CA）即將到期（30 天內），且需要進行輪替以防止叢集無法復原。
• 維護時間不足（Maintenance Starvation）: GKE 要求在任何 32 天滾動窗口內至少有 48 小時的可用維護時間。若排除項封鎖時間過長，GKE 可能會發起強制升級。

指導方針（討論覆寫時必須遵守）：

1. 比對發布公告: 若 GKE 執行了非預期的升級，您必須明確建議檢查 GKE 發布說明（Release Notes）或安全性公告（Security Bulletins），以將該事件與緊急修補程式進行比對（切勿僅建議檢查 Cloud Audit Logs）。
2. 高韌性設計: 工作負載必須設計為能夠承受非預期的控制平面或節點輪替。您必須建議：
   • 使用區域級叢集（Regional clusters / 多 Master）以確保控制平面升級期間的 API 可用性。
   • 跨多可用區（Multi-zone）部署工作負載。
   • 關鍵 Deployment 的副本數（Replicas）大於 1。
   • 設定合理且不過度嚴格的 Pod 中斷預算（PDB）。

升級規劃

當被要求規劃升級時，請生成包含以下內容的結構化文件：

• 版本相容性（重大變更 breaking changes、棄用的 API）（僅限次要版本升級）
• 升級路徑（依序進行次要版本升級）（僅限次要版本升級）
• 節點池升級策略（僅限 Standard 模式）
• 工作負載準備狀況（PDB、資源 Request）
• 復原/應變程序（如何將節點池復原，或如何聯繫 GKE 技術支援進行 Master 復原）

相容性搜尋規則：

• 若相容性資訊（如第三方 Operator 相容性、GPU 驅動程式/CUDA 相容性矩陣）無法在工作區中立即取得或無法透過快速網路搜尋獲得，請勿重複循環或進行多次搜尋嘗試。應改為在檢查清單中將相容性驗證列為使用者的升級前關鍵執行項目。

節點池策略（僅限 Standard 模式）

推薦 Surge 升級 作為預設且最常用的策略，並為各節點池進行設定：

• 無狀態 (Stateless): 提高 maxSurge (2-3) 以加快速度，maxUnavailable=0 以維護安全性。
• 有狀態/資料庫 (Stateful/DB): maxSurge=1, maxUnavailable=0（保守設定）。
• GPU（固定預留）: maxSurge=0, maxUnavailable=1（無額外 Surge 容量）。
• 大型叢集 (50+ 節點): maxSurge=20, maxUnavailable=0（最大化並行度）。

對於需要快速復原或嚴格驗證的關鍵任務工作負載，建議採用 Standard 藍綠升級。對於對中斷敏感的工作負載，可將 Autoscaled 藍綠升級 作為可選項，但需說明其目前處於預覽階段且可能有容量需求限制。

升級順序（僅限使用者發起）: 在規劃手動升級時，請指定節點池升級的順序。建議先升級無狀態節點池，驗證叢集穩定性後，再升級有狀態/GPU 節點池。對於自動升級，GKE 會自動管理節點池的順序升級。

有關標準指令序列與 Runbook 範本，請參閱 references/runbook-template.md。

大規模 AI/ML 叢集 (GPU/TPU)

• 不支援即時遷移（Live Migration）: GPU VM 不支援即時遷移；GKE 升級將強制重啟 Pod。您必須說明這一點。
• 固定預留與配額: H100/A100 通常使用固定預留且沒有備用配額。
  • 建議採用 零 Surge 的滾動升級: maxSurge=0, maxUnavailable=1。這會在配置替代節點前，先釋放正在升級之節點的預留容量。
  • 您必須說明 藍綠升級不可行，因為這會需要雙倍 (2x) 的 GPU 資源

<!-- truncated for translation batch; full body continues in source -->