gke-upgrades

GKE 集群升级与运维指南

根据用户的实际环境，产出清晰、可落地的文档——包括升级方案、Runbook 或检查清单。输出内容应当针对用户的集群模式、发布渠道、具体版本及工作负载类型量身定制，避免给出泛泛而谈的通用建议。

务必始终围绕自动升级（Auto-upgrade）模型来展开指导：结合维护窗口（Maintenance Windows）和排除项（Exclusions）的自动升级，是 GKE 中最推荐的管控机制。

信息收集

在生成任何升级相关的交付物之前，需先明确以下信息：

• 集群模式（Cluster mode） — Standard 标准模式还是 Autopilot 托管模式？（Autopilot 没有节点池管理，强制要求资源 Request，且不支持 SSH）
• 当前版本与目标版本（Current and target versions） — 节点版本与控制平面的版本偏差（Skew）必须控制在 2 个 Minor（次要）版本以内。
• 发布渠道（Release channel） — Rapid（快速）、Regular（常规）、Stable（稳定）还是 Extended（扩展）。
• 环境拓扑与发布顺序（Environment topology & Rollout Sequencing） — 单集群还是多集群，Dev/Staging/Prod 多套环境的层级划分，以及是否使用了 Rollout Sequencing（发布顺序控制）。
• 工作负载敏感度（Workload sensitivity） — StatefulSet、数据库、GPU、长时间运行的批处理任务需要特殊关注和处理。

如果用户提前提供了这些信息，可直接跳转至具体交付物的生成。如果描述模糊，请填入合理的默认假设，并对相关假设进行明确标注。

核心原则

GKE 版本遵循 Kubernetes 的版本命名规范：主版本.次版本.补丁版本（Major.Minor.Patch，例如 1.30.1-gke.1187000）。**Minor（次版本）**升级（如 1.29 → 1.30）会引入新功能和新 API；**Patch（补丁版本）**升级（如 1.30.1 → 1.30.2）则侧重于安全修复与 Bug 修复。需确保用户理解这一区别。

1. 控制平面逐级升，节点池支持跨级升 —— 控制平面（Control plane）升级必须按顺序逐级推进（N → N+1 → N+2）；而节点池（Node pools）支持跨级（N+2）升级。
2. 控制平面优先 —— 必须先升级控制平面，再升级节点池。节点池的版本最多允许落后控制平面 2 个 Minor 版本。
3. 环境逐级推进 —— 始终遵循先 Dev/Staging 后 Production 的升级顺序。优先推荐使用 Rollout Sequencing 在多环境中自动且强制执行该升级路径（如 Dev → Staging → Prod）；若未启用 Rollout Sequencing，则需要手动协调各环境的版本推进。
4. 工作负载感知 —— 升级策略取决于集群中运行的服务类型（无状态、有状态、GPU、批处理）。
5. 发布渠道优先 —— 始终优先推荐使用发布渠道（Release Channels）。注意：“无渠道（No channel / 静态版本ing）”已被废弃，已有集群应尽快迁移至发布渠道。
6. 回滚/降级（Rollback/Downgrade） —— 控制平面的 Patch 补丁以及节点池（包括 Minor 和 Patch）均支持回滚（降级到指定版本）。GKE 支持控制平面 Minor 升级的“两步走”模式，其中第 1 步支持回滚；而其他控制平面的 Minor 版本回滚用户无法自行操作，需联系 GKE 官方技术支持。
7. 节点池升级顺序 —— 在升级多个节点池时，务必推荐按顺序升级：先升级非核心/无状态节点池（作为灰度金丝雀）来验证集群健康状况，确认无误后再升级核心有状态（数据库）或 GPU 节点池。

发布渠道

发布渠道	适用场景	SLA
Rapid	开发/测试环境、优先尝鲜新特性	无升级稳定性 SLA
Regular（默认）	绝大多数生产环境	提供完整 SLA
Stable	核心业务、稳定性第一	提供完整 SLA
Extended	具备合规要求、需控制停服 End of Support (EoS) 节奏	提供完整 SLA

生命周期支持

GKE 标准版本在进入 Regular 渠道后，官方将提供 14 个月的支持服务。这意味着：

• Rapid 渠道中的版本支持周期可能会超过 14 个月（因为版本先进入 Rapid，后进入 Regular）。
• Stable 渠道中的版本支持周期可能会少于 14 个月（因为进入 Stable 的时间晚于 Regular）。
• Extended（扩展支持）可以将支持周期进一步延长至 24 个月。需要注意的是，仅在扩展支持期（第 15-24 个月）会产生额外的服务费用。

维护窗口与排除项

通过配置维护窗口来管控自动升级的时间。除了集群层级之外，GKE 还支持在节点池层级设置维护排除项（Exclusions），以阻断特定工作负载的升级操作。

排除项类型与限制：

• “禁止所有升级”（作用域：no_upgrades）：阻断一切升级（包括 Minor 次版本、Patch 补丁和节点升级）。
  • 时长限制：在任意滚动 365 天窗口内，累计排除时长上限为 90 天。
  • 链式连续限制：受限于 365 天滚动限制，你无法通过串联多个排除项来覆盖超过 90 天的连续封网期（例如：无法使用 no_upgrades 来实现长达 100 天的连续封网）。
• “禁止次版本及节点升级”（作用域：no_minor_or_node_upgrades）：阻断 Minor 次版本和节点升级，但允许执行低风险的控制平面 Patch 补丁升级。
  • 时长限制：单个排除项最长可设 180 天。可以通过添加新的排除项进行续期，最长可延长至该 Minor 版本的 End of Support (EoS)。
• “仅禁止次版本升级”（作用域：no_minor_upgrades）：仅阻断 Minor 次版本升级，允许执行控制平面 Patch 补丁和节点升级。
  • 时长限制：单个排除项最长可设 180 天，同样可续期延长至 EoS。

重要排除项规则（在推荐排除项时必须遵守，且必须包含在最终的文本回复中）：

1. 仅适用于自动升级：维护排除项仅能阻断自动升级。由用户主动发起的手动升级会直接绕过排除项。必须向用户明确说明这一点。
2. 警惕“无渠道”陷阱：必须明确警告用户，禁用发布渠道（“No channel”/ 静态版本ing）已被废弃，绝对不能将其作为替代排除项的手段。
3. 对比不同作用域：必须解释清楚“禁止所有升级”（有时长限制且会阻断 Patch 补丁）与“禁止次版本及节点升级”（允许安全 Patch、支持更长时长）的区别。当用户希望阻断跨版本跳跃同时允许安全补丁/修复安装时，推荐使用 no_minor_or_node_upgrades。
4. 处理超过 90 天的封网需求：如果用户需要在 90 天以上的时间段内阻断升级，必须说明 no_upgrades 在 365 天滚动窗口内有 90 天的硬性限制（无法通过串联实现更长的连续封网），并建议改用 no_minor_or_node_upgrades（单个排除项最长 180 天，且可续期至 EoS），或者使用针对 Minor 版本的持久排除项直到 EoS。
5. 版本偏差（Version Skew）控制：使用排除项时，需时刻关注控制平面与节点池之间的版本偏差，确保偏差不超过官方支持的 2 个 Minor 版本。如需设置持久排除项，可使用 --add-maintenance-exclusion-until-end-of-support 参数。
6. 正确的 gcloud 命令语法：在提供排除项相关的 gcloud 命令时，必须使用独立的参数语法：--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 参数）。

强制升级覆盖

针对必要的运维操作，GKE 保留覆盖用户自定义维护窗口和排除项的权利。此类强制覆盖无法被禁用或阻断。

常见的强制覆盖场景：

• 紧急安全补丁：必须立即应用以保护基础架构安全的紧急漏洞修复。
• 停止支持（EoS / EOL）强制执行：若集群运行在已停止支持的版本上，GKE 将强制将其升级至受支持的版本。
• 证书即将过期：若控制平面的证书（CA）即将在 30 天内过期，需要通过轮换避免集群进入不可恢复状态。
• 维护窗口严重不足（Maintenance Starvation）：GKE 要求在任意滚动 32 天内，必须至少留出 48 小时的可维护时间。如果排除项设置过于严苛导致维护时间不足，GKE 可能会触发强制升级。

指导原则（讨论强制覆盖时必须遵循）：

1. 关联安全公告：若 GKE 触发了意料之外的升级，必须明确建议用户查阅 GKE Release Notes（发布说明）或 Security Bulletins（安全公告），以排查是否与紧急补丁相关（而不能仅仅建议检查 Cloud Audit Logs）。
2. 架构韧性设计：工作负载本身必须具备抵御突发控制平面或节点轮换的能力。必须推荐以下最佳实践：
   • 采用 Regional（多主节点）集群，确保控制平面升级期间 API 的高可用。
   • 跨多可用区（Multi-zone）部署工作负载。
   • 针对核心服务设置 Replica 副本数大于 1。
   • 合理配置 Pod Disruption Budget (PDB)，避免条件过于苛刻限制调度。

升级规划

在受邀制定升级规划时，需产出包含以下内容的结构化文档：

• 版本兼容性评估（破坏性变更、废弃 API）（仅适用于 Minor 次版本升级）
• 升级路径规划（按顺序逐级推进 Minor 升级）（仅适用于 Minor 次版本升级）
• 节点池升级策略（仅适用于 Standard 模式）
• 工作负载就绪度评估（PDB、资源 Request 请求量）
• 回滚与应急预案（如何对节点池执行回滚，或如何与 GKE 官方支持人员协调 Master 控制平面回滚）

兼容性排查规则：

• 若兼容性信息（如第三方 Operator 兼容性、GPU 驱动与 CUDA 兼容性矩阵等）在当前工作区或通过快速搜索无法立即获取，切勿循环或多次进行网络搜索。应直接将兼容性核验项作为升级前核心待办事项列在检查清单中，由用户自行核实。

节点池升级策略（仅限 Standard 模式）

默认且最推荐使用**浪涌升级（Surge upgrade）**策略，并根据节点池特性调整配置：

• 无状态应用节点池：采用较大的 maxSurge（如 2-3）以提升升级速度，设置 maxUnavailable=0 保证安全性。
• 有状态应用/数据库节点池：采用保守策略 maxSurge=1, maxUnavailable=0。
• GPU 节点池（固定预留）：采用无浪涌容量策略 maxSurge=0, maxUnavailable=1。
• 大规模节点池（50+ 节点）：采用最大并行度策略 maxSurge=20, maxUnavailable=0。

对于需要快速回滚或极其严苛校验的极重要工作负载，推荐使用**标准蓝绿（Standard Blue-Green）升级策略。对于业务中断极敏感的工作负载，可提及自动扩缩蓝绿升级（Autoscaled Blue-Green）**作为一个选项，但需指出该功能目前处于 Preview 预览阶段且可能受限于配额与容量。

升级顺序（仅针对手动触发升级）： 在规划手动升级时，需明确节点池的升级顺序。推荐先升级无状态节点池，验证集群整体稳定性后，再升级有状态或 GPU 节点池。对于自动升级，GKE 会自动接管并按顺序管理节点池的升级。

关于标准命令序列和 Runbook 模板，请参阅 references/runbook-template.md。

大规模 AI/ML 集群（GPU/TPU）

• 不支持热迁移（No Live Migration）：GPU 虚拟机不支持热迁移；GKE 升级会强制重启 Pod。必须向用户明确说明这一点。
• 固定预留与配额限制（Fixed Reservations & Quota）：H100/A100 通常采用固定预留且无额外冗余配额。
  • 推荐采用零浪涌滚动升级：maxSurge=0, maxUnavailable=1。该策略会在创建新节点之前，优先释放待升级节点的预留资源。
  • 必须解释清楚蓝绿升级不可行，因为蓝绿升级需要双倍（2x）的 GPU 资源