GKE 集群升级/维护：需要制定升级计划、runbook…

适用于 GKE Standard/Autopilot 的版本升级、节点池维护、发布渠道选择、维护窗口/排除、卡住升级排查与回滚预案。

适用场景

解决思路

1. 产出清晰可执行的升级计划、runbook 或 checklist；按用户的集群模式、发布渠道、版本和工作负载类型定制，避免泛泛建议；始终围绕自动升级模型，把维护窗口与排除项作为首选控制机制。
2. 制作任何升级产物前收集：集群模式是 Standard 还是 Autopilot（Autopilot 无节点池管理、强制资源请求、无 SSH）；当前与目标版本，节点版本偏移不得超过控制平面 2 个小版本；发布渠道是 Rapid、Regular、Stable 还是 Extended；环境拓扑与发布顺序，单集群还是多集群、dev/staging/prod 分层、是否使用 Rollout Sequencing；工作负载敏感性，StatefulSets、数据库、GPU、长批处理需要特殊处理。
3. 如果用户已提供上述信息，直接产出交付物；如果信息模糊，填入合理默认值并标注假设。
4. 解释版本术语：GKE 版本遵循 Major.Minor.Patch，例如 1.30.1-gke.1187000；Minor 版本升级例如 1.29 → 1.30 引入新功能和 API；Patch 版本升级例如 1.30.1 → 1.30.2 引入安全和 bug 修复。
5. 控制平面顺序升级，节点池可跳级：控制平面升级是顺序的 N → N+1 → N+2；节点池支持跳级到 N+2 升级。
6. 控制平面先升级，再升级节点池；节点最多落后控制平面 2 个小版本。
7. 环境推进：始终先升级 dev/staging 再升级生产；优先用 Rollout Sequencing 自动化并强制 dev → staging → prod；如果不用 Rollout Sequencing，则手动协调版本推进。
8. 工作负载感知：升级策略取决于运行内容，如无状态、有状态、GPU、批处理。
9. 发布渠道优先：始终推荐 release channels；说明 No channel（静态版本）已废弃，集群应迁移到发布渠道。
10. 回滚/降级：控制平面 patch 和节点池（minor 与 patch）可以回滚到目标版本；GKE 支持 2 步控制平面 minor 升级，其中第 1 步可回滚；其他控制平面 minor 回滚客户不可自行执行，需要 GKE Support。
11. 多节点池升级顺序：建议顺序升级，先升级非关键/无状态池作为 canary，验证集群健康后再升级关键有状态数据库或 GPU 池。
12. 按发布渠道选择：Rapid 适合 dev/test、早期功能访问，无升级稳定性 SLA；Regular 是默认、适合多数生产，完整 SLA；Stable 适合任务关键、稳定优先，完整 SLA；Extended 适合合规、EoS 执行控制，完整 SLA。
13. 生命周期：标准 GKE 版本在进入 Regular 渠道后支持 14 个月；Rapid 渠道版本可能支持超过 14 个月，Stable 渠道版本可能少于 14 个月；Extended 支持延长到最多 24 个月，额外费用仅适用于扩展支持期（第 15-24 个月）。
14. Extended 渠道算法：14 个月标准支持 + 约 10 个月扩展支持 ≈ 每个 minor 版本共 24 个月；即使在 Extended，EoS 仍会发生强制升级：如果不采取行动，GKE 会在 End of Support 自动升级集群，平均约每 4 个月 bump 一个 minor 版本，与其他渠道节奏相同，只是功能到达更晚。
15. 升级可靠性：Google 报告 GKE 控制平面和节点升级成功率 99.99%，支持安全回滚和跳版本升级，目标是让团队可以减少升级频率（例如每年一次而非每季度一次）；跳版本升级先在非生产集群试点。
16. Autoscaled blue-green 节点升级（Preview）：green 池按需扩容，而不是预置完整重复池，适合不能预留 2 倍容量的扰动敏感工作负载。
17. Scheduled cluster upgrade notifications（Preview）：选择接收计划 minor 升级前通知，并把通知接入告警。
18. 终止与 PDB：blue-green（包括 autoscaled blue-green，Preview）是唯一在排水时可尊重 terminationGracePeriodSeconds 最多 24 小时的策略；surge 升级最多尊重 60 分钟；节点排水时 GKE 最多尊重 PDB 60 分钟，之后 Pod 会被强制删除并发送通知。
19. 配置维护窗口来控制自动升级时间；GKE 除集群级维护排除项外，还支持节点池级维护排除项，用于阻止特定工作负载升级。
20. 配置 No upgrades（Scope: no_upgrades）：阻止所有升级（minor、patch、node）；限制为每个排除项最多 90 天，每集群最多 3 个；任意滚动 92 天窗口内仍需至少 48 小时维护可用时间，因此不能串联成超过 90 天的连续冻结；GKE 建议保持低于 30 天。
21. 配置 No minor or node upgrades（Scope: no_minor_or_node_upgrades）：阻止 minor 和节点升级，但允许控制平面 patch 升级（低风险）；没有固定天数上限，受 minor 版本 End of Support（EoS）限制；建议保持低于约 6 个月。
22. 配置 No minor upgrades（Scope: no_minor_upgrades）：阻止 minor 升级，但允许控制平面 patch 和节点升级；没有固定天数上限，受 EoS 限制；建议保持低于约 6 个月。
23. 推荐排除项时必须遵守并写入最终回复：维护排除项只阻止自动升级；用户手动发起的升级会绕过排除项，必须向用户解释这一点。
24. 必须明确警告：禁用发布渠道（No channel / 静态版本）已废弃，不能用作排除项的替代方案。
25. 必须比较 scope：解释 No upgrades（有限制、阻止 patch）与 No minor or node upgrades（允许 patch、可持续更久）的区别；当用户想允许安全补丁/修复但阻止 minor 版本跳变时，推荐 No minor or node upgrades。
26. 处理超过 90 天的阻断需求：必须说明 No upgrades 每个排除项限 90 天、每集群最多 3 个、任意滚动 92 天窗口内必须保留 48 小时维护可用时间，不能串联成长于 90 天的连续冻结；建议使用作用域排除项 No minor or node upgrades / No minor upgrades，它们没有固定天数上限，可运行到 minor 版本 EoS。
27. 使用排除项时注意版本偏移：控制平面与节点池之间的偏移不得超过支持的 2 个小版本；使用 --add-maintenance-exclusion-until-end-of-support 做持久排除。
28. 提供排除项 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。
29. 告知用户 GKE 保留对强制操作覆盖用户维护窗口和排除项的权利，这些覆盖不能禁用或阻止。
30. 常见强制覆盖场景：关键安全补丁、End of Support（EoS）/End of Life（EOL）强制执行、控制平面证书即将到期（30 天内）且需要轮换以防集群不可恢复、维护饥饿，即任意滚动 92 天窗口内需要至少 48 小时维护可用时间，排除项阻止过多时 GKE 可能强制升级。
31. 讨论覆盖时：如果 GKE 执行了意外升级，必须明确建议检查 GKE Release Notes 或 Security Bulletins，以将该事件与紧急补丁关联，而不要只建议检查 Cloud Audit Logs。
32. 讨论覆盖时：必须建议为弹性而设计：使用区域集群（multi-master）确保控制平面升级期间 API 可用；多可用区部署工作负载；关键 Deployment 副本数 > 1；配置合理且不过度严格的 Pod Disruption Budgets（PDBs）。
33. 规划升级时产出结构化文档，覆盖：版本兼容性（破坏性变更、废弃 API，仅 minor 版本升级）；升级路径（顺序 minor 版本升级，仅 minor 版本升级）；节点池升级策略（仅 Standard）；工作负载就绪（PDB、资源请求）；回滚/应急流程（如何回滚节点池，或如何协调 GKE Support 做 master 回滚）。
34. 兼容性搜索规则：如果兼容性信息（例如第三方 operator 兼容性、GPU driver/CUDA 兼容矩阵）不能立刻从工作区或快速网络搜索获得，不要循环或多次搜索；改为在 checklist 中把兼容性验证列为关键升级前行动项。
35. Standard 节点池策略默认推荐 Surge upgrade，并按池设置：无状态用较高 maxSurge（2-3）提速，maxUnavailable=0 保安全；有状态/DB 用 maxSurge=1、maxUnavailable=0 保守；GPU（固定预留）用 maxSurge=0、maxUnavailable=1，不使用 surge 容量；大型池（50+ 节点）用 maxSurge=20、maxUnavailable=0 实现最大并行。
36. 对需要快速回滚或严格验证的任务关键工作负载，推荐 Standard Blue-Green 升级；Autoscaled Blue-Green 可作为扰动敏感工作负载的选项，但要说明它目前是 Preview 且可能有容量要求。
37. 手动升级排序：规划手动升级时指定节点池升级顺序；先升级无状态池，验证集群稳定，再升级有状态/GPU 池；自动升级时 GKE 会自动管理顺序节点池升级。
38. 参考 references/runbook-template.md 获取标准命令序列和 runbook 模板。
39. 大规模 AI/ML GPU/TPU 升级必须覆盖：GPU VM 不支持 live migration，GKE 升级会强制重启 Pod，必须向用户解释。
40. GPU/TPU 固定预留与配额：H100/A100 通常使用固定预留且没有闲置配额；推荐零 surge 滚动升级（maxSurge=0、maxUnavailable=1），先释放待升级节点的预留，再创建替代节点；说明 Blue-Green 升级在此不可行，因为过渡期间需要双倍 GPU 资源（配额和预留）。
41. GPU 驱动耦合：GPU driver 与节点 OS 镜像紧耦合，节点升级会引入新 Linux kernel 和 NVIDIA driver，可能破坏 CUDA 兼容性；建议先在 staging 环境/集群升级并测试 CUDA 兼容性，更新工作负载依赖（容器镜像中的 CUDA 版本）以匹配新 driver，再重试升级；诊断驱动回归时，比较旧（可用）和新（不可用）节点的 OS 镜像、内核版本（uname -r）和驱动版本，并部署测试 Pod（例如向量加法）验证 GPU 访问；如果生产被阻塞，将节点池回滚到上一版本是最快缓解措施。
42. GPU/TPU 操作安全：建议使用 GKE maintenance exclusions 在活跃训练期间阻止自动升级；手动升级前 cordon GPU 节点，并等待活跃训练作业 checkpoint/完成。
43. TPU：TPU slice 是原子重建而非滚动；一个 slice 维护会重启环境中所有 slice。
44. 生成 checklist：输出可复制 markdown 复选框；参考 references/checklists.md 的完整升级前和升级后 checklist 模板，并按用户环境调整。
45. 有状态工作负载：存在数据库等有状态工作负载时，升级前 checklist 始终包含 PV 备份完成检查，以及 PV reclaim policy 验证（例如 Retain vs Delete）。
46. Autopilot checklist 必须包含：验证所有容器都有 resources.requests（Autopilot 要求）；必须包含 API 废弃检查的具体 kubectl 命令：kubectl get --raw /metrics | grep apiserver_request_total | grep deprecated，用于检查活跃工作负载是否使用废弃 API；验证 PDB 不会阻塞节点排水（即使 GKE 管理节点，PDB 仍被尊重）；识别并删除 bare pods（不由 ReplicaSet/Deployment/StatefulSet 管理的 Pod），因为节点重建时它们不会被重新调度；验证 terminationGracePeriodSeconds，确保 Pod 有足够时间优雅关闭。
47. 生成维护 runbook：包含实际 gcloud 和 kubectl 命令的逐步步骤；参考 references/runbook-template.md 的标准命令序列。
48. 任何放宽安全控制的 runbook 必须在同一 runbook 中恢复该控制；尤其适用于节点池迁移或回滚期间的 PDB：排水前备份 PDB，并将重新应用 PDB 作为带独立验证的编号步骤，而不是结尾说明；例如为解除排水而 patch maxUnavailable: 100% 后不恢复，会让集群失去扰动保护，直到下一次自愿驱逐才暴露；同样规则适用于维护排除项、cordon、为完成流程添加的 autoscaler minNodes 覆盖。
49. 诊断卡住升级时考虑维护窗口暂停：如果维护窗口在升级（自动或手动）完成前关闭，GKE 会故意暂停 rollout，避免允许时间外扰动；集群会处于稳定的混合版本状态（部分节点已升级、部分未升级），必须明确说明这是受支持且安全的预期结果；下次维护窗口打开时升级会自动恢复。
50. 如果用户想立即完成升级，必须建议临时扩大维护窗口以包含当前时间，例如使用 gcloud container clusters update ... --maintenance-window-start ... --maintenance-window-duration ...；不要建议重新触发手动升级或绕过窗口。
51. 用户报告卡住或失败升级时，必须在最终回复中系统分析并处理全部 5 个潜在原因，即使怀疑主要原因是某一个也不能省略：1）PDB 阻塞排水，用 kubectl get pdb -A 找出 ALLOWED DISRUPTIONS = 0；2）资源约束，检查 Pod 是否因容量限制卡在 Pending；3）bare pods，找出没有 owner references 且阻塞排水的 Pod，建议删除；4）Admission webhooks，检查 Validating/Mutating webhooks 是否拒绝在新节点创建 Pod；5）PVC 挂载问题，检查卷挂载失败，尤其是可用区约束。
52. Stockout/配额耗尽规则：如果升级因 ZONE_RESOURCE_POOL_EXHAUSTED（stockout）或 Compute Engine 资源 QUOTA_EXCEEDED 卡住：1）建议把升级策略改为 maxSurge=0（原地滚动）以绕过配额限制；2）对 QUOTA_EXCEEDED，建议向 Google Cloud 申请配额增加；3）必须建议将工作负载迁移或新建节点池到有容量/配额的其他可用区或区域作为缓解。
53. 参考 references/troubleshooting.md 获取每个步骤的精确诊断命令和修复流程。
54. 参考 GKE Release Notes、Upgrading GKE Clusters、Maintenance Windows & Exclusions、Rollout Sequencing Concepts、Configure Rollout Sequencing 文档。

适用边界 · 注意事项

• 不用于 GKE 集群创建、应用接入/onboarding。
• 不用于通用网络/路由设置、安全策略配置；这些应使用 gke-basics 或相关 GKE 技能。
• 不适用于非 GKE 的 Kubernetes 升级规划与维护。