gke-upgrades

GKE 升级与维护

生成清晰、可执行且针对用户环境量身定制的文档，例如升级计划、操作手册或检查清单。内容应具体说明集群模式、发布渠道、版本和工作负载类型，而不是提供通用建议。

始终围绕自动升级模型提供指导：首选通过维护时段和维护排除项控制自动升级。

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读 使用归属信息。对于直接在终端中执行的命令（绝不能放入生成的脚本、Terraform 或用户代码中），请为 gcloud 添加前缀 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-upgrades)" 并在 User-Agent 标头中追加 agent-skills/1.0 (skill:gke-upgrades)。

收集上下文

生成任何升级文档前，先明确以下信息：

• 集群模式——Standard 还是 Autopilot？（Autopilot 不支持节点池管理，要求设置资源请求，且不支持 SSH）
• 当前版本和目标版本——节点版本与控制平面版本的差距必须在 2 个次要版本以内。
• 发布渠道——Rapid、Regular、Stable 还是 Extended。
• 环境拓扑与发布顺序——单集群还是多集群、dev/staging/prod 环境层级，以及是否使用 Rollout Sequencing。
• 工作负载敏感性——StatefulSets、数据库、GPU、长时间运行的批处理任务需要特殊处理。

如果用户已提供这些信息，请直接生成所需文档。如果信息含糊不清，则采用合理的默认值并标明假设。

核心原则

GKE 版本遵循 Kubernetes 版本术语：Major.Minor.Patch（例如 1.30.1-gke.1187000）。Minor 版本升级（例如 1.29 → 1.30）会引入新功能和 API。Patch 版本升级（例如 1.30.1 → 1.30.2）会引入安全修复和错误修复。确保用户理解两者的区别。

1. 控制平面按顺序升级，节点池可跨级升级——控制平面必须按顺序升级（N → N+1 → N+2）。节点池支持跨级升级（N+2）。
2. 先升级控制平面——必须先升级控制平面，再升级节点池。节点版本最多可落后 2 个次要版本。
3. 按环境推进——始终先升级 dev/staging，再升级生产环境。首选使用 Rollout Sequencing，在各环境间自动执行并强制落实此推进顺序（例如 dev → staging → prod）；如果不使用 Rollout Sequencing，则需手动协调版本推进。
4. 考虑工作负载——升级策略取决于运行的工作负载（无状态、有状态、GPU、批处理）。
5. 优先选择发布渠道——始终建议使用发布渠道。请注意，“No channel”（静态版本控制）已弃用，集群应迁移到发布渠道。
6. 回滚/降级——控制平面补丁版本和节点池（次要版本及补丁版本）可以回滚（降级到目标版本）。GKE 支持分两步进行控制平面次要版本升级，其中第 1 步可以回滚。其他控制平面次要版本回滚无法由客户自行执行，必须联系 GKE 支持。
7. 节点池升级顺序——升级多个节点池时，始终建议按顺序升级：先升级非关键/无状态节点池作为试运行组，确认集群运行正常后，再升级关键的有状态（数据库）或 GPU 节点池。

发布渠道

渠道	适用场景	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 个月）才会产生额外费用。

当前功能

• Extended 渠道期限：14 个月标准支持 + 约 10 个月扩展支持 ≈ 每个次要版本总计 24 个月。即使使用 Extended，仍会强制升级：如果不采取任何操作，GKE 会在支持期结束时自动升级集群——平均每约 4 个月升级一个次要版本，与其他渠道的节奏相同（只是功能会稍晚推出）。
• 升级可靠性（KubeCon NA 2025）：Google 报告称，GKE 控制平面和节点的升级成功率为 99.99%；安全回滚和跳过版本升级功能旨在让团队减少升级频率（例如，从每季度升级改为每年升级）。请先在非生产集群中试用跳过版本升级。
• 自动扩缩蓝绿节点升级（预览版）：蓝绿升级的一种变体，按需扩展绿色节点池，而不是预先配置一个完整的重复节点池，适用于无法预留 2 倍容量且对中断敏感的工作负载。
• 集群计划升级通知（预览版）：选择接收计划中的次要版本升级通知，并将通知接入告警系统。
• 排空期间的优雅终止和 PDB：蓝绿升级（包括自动扩缩蓝绿升级，预览版）是唯一会将 terminationGracePeriodSeconds 期限延长至最多 24 小时的策略；激增升级最多支持 60 分钟。节点排空期间，GKE 最多遵守 PDB 60 分钟，之后会强制删除 Pod（并发送通知）。

维护窗口与排除项

配置维护窗口以控制自动升级时间。除了集群级别的维护排除项，GKE 还支持节点池级别的维护排除项，以阻止特定工作负载的升级。

排除项类型与限制：

• “不进行升级”（范围：no_upgrades）：阻止所有升级（次要版本、补丁、节点）。
  • 限制：每个排除项最多 90 天，每个集群最多可设置 3 个此类排除项。所有排除项必须确保在任意滚动 92 天窗口内仍至少有 48 小时的维护可用时间，因此不能将它们连续串联起来，形成超过 90 天的冻结期。GKE 建议将排除时间控制在 30 天以内。
• “不进行次要版本或节点升级”（范围：no_minor_or_node_upgrades）：阻止次要版本和节点升级，但允许控制平面补丁升级（风险较低）。
  • 限制：没有固定天数上限，但受次要版本的**支持终止（EoS）**时间限制。建议控制在约 6 个月以内。
• “不进行次要版本升级”（范围：no_minor_upgrades）：阻止次要版本升级，但允许控制平面补丁和节点升级。
  • 限制：没有固定天数上限，但受 EoS 时间限制。建议控制在约 6 个月以内。

重要排除规则（在推荐排除项时必须遵守，并且必须在最终回复中说明）：

1. 仅适用于自动升级：维护排除项只能阻止自动升级。用户手动发起的升级会绕过排除项。必须向用户说明这一点。
2. 警告不要使用“No channel”：必须明确警告，停用发布渠道（“No channel”／静态版本管理）已弃用，不得将其用作排除项的替代方案。
3. 比较范围：必须说明“不进行升级”（有限制，会阻止补丁）与“不进行次要版本或节点升级”（允许补丁，持续时间更长）的区别。如果用户希望允许安全补丁和修复，同时阻止次要版本跳跃，建议使用“不进行次要版本或节点升级”。
4. 处理超过 90 天的时段：如果用户需要阻止升级超过 90 天，必须说明“不进行升级”每个排除项最长为 90 天（每个集群最多 3 个，并且任意滚动 92 天窗口内必须保留 48 小时的维护可用时间，因此不能串联排除项形成更长的连续冻结期），并建议使用范围限定的排除项（“不进行次要版本或节点升级”／“不进行次要版本升级”），这些排除项没有固定天数上限，可持续到次要版本的支持终止时间。
5. 版本偏差：使用排除项时，请注意控制平面与节点池之间的版本偏差。确保偏差不超过受支持的 2 个次要版本。使用 --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 天内过期，且必须轮换以防止集群无法恢复。
• 维护时段不足：GKE 要求在任意滚动 92 天窗口内至少有 48 小时的可用维护时间。如果维护排除项限制过多，GKE 可能会强制升级。

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

1. 结合公告核实：如果 GKE 执行了意外升级，必须明确建议检查 GKE 发行说明或安全公告，将该事件与紧急补丁对应起来（不能只建议检查 Cloud Audit Logs）。
2. 按韧性设计：工作负载必须能够承受意外的控制平面或节点轮换。必须建议：
   • 使用区域集群（多主节点），确保控制平面升级期间 API 仍可用。
   • 在多个可用区部署工作负载。
   • 关键部署的副本数 > 1。
   • 正确配置 Pod Disruption Budgets（PDB），且限制不能过于严格。

升级规划

用户要求规划升级时，请生成一份结构化文档，涵盖：

• 版本兼容性（重大变更、已弃用的 API）（仅适用于次要版本升级）
• 升级路径（按顺序升级次要版本）（仅适用于次要版本升级）
• 节点池升级策略（仅适用于 Standard）
• 工作负载就绪情况（PDB、资源请求）
• 回滚／应急预案（如何回退节点池，或如何与 GKE 支持团队协调回滚主节点）

兼容性搜索规则：

• 如果工作区中或通过快速网络搜索无法立即找到兼容性信息（例如第三方运算符兼容性、GPU 驱动程序／CUDA 兼容性矩阵），不要反复搜索或多次尝试搜索。请改为在清单中将兼容性验证列为用户升级前必须执行的关键行动项。

节点池策略（仅适用于 Standard）

默认推荐最常见的 Surge 升级，并按节点池设置：

• 无状态：设置较高的 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 也是对中断敏感型工作负载的一种选择，但需说明它目前仍处于预览阶段，并且可能有容量要求。

**升级顺序（仅适用于用户发起的升级）：**规划手动升级时，请注明节点池的升级顺序。建议先升级无状态节点池，确认集群稳定后，再升级有状态／GPU 节点池。对于自动升级，GKE 会自动管理节点池的顺序升级。

标准命令序列和运行手册模板，请参阅 references/runbook-template.md。

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

在提供 GPU/TPU 升级建议时，必须涵盖以下所有内容：

• 不支持实时迁移：GPU 虚拟机不支持实时迁移；GKE 升级会强制重启 Pod。请向用户说明这一点。
• 固定预留量和配额：H100/A100 通常使用固定预留量，且没有富余配额。建议采用零额外节点的滚动升级（maxSurge=0, maxUnavailable=1），先释放待升级节点的预留量，再配置其替代节点。请说明，这种情况下无法进行蓝绿升级，因为升级期间需要双倍（2x）的 GPU 资源（配额和预留量都需要）。
• 驱动耦合：GPU 驱动与节点 OS 镜像紧密耦合，因此节点升级会引入新的 Linux 内核和 NVIDIA 驱动，可能导致 CUDA 兼容性问题。建议先在预发布环境／集群中升级并测试 CUDA 兼容性，并更新工作负载依赖项（容器镜像中的 CUDA 版本），使其与新驱动匹配，然后再尝试升级。要诊断驱动回归问题，请比较旧节点（正常运行）和新节点（运行异常）的 OS 镜像、内核版本（uname -r）和驱动版本，并部署测试 Pod（例如执行向量加法），以验证 GPU 访问。如果生产环境受阻，将节点池回滚到先前版本是最快的缓解措施。
• 运维安全：建议使用 GKE 维护排除项，在训练任务运行期间阻止自动升级。手动升级前，将 GPU 节点设为不可调度，并等待正在运行的训练任务完成检查点保存或运行完毕。
• TPU 注意事项：TPU 切片会以原子方式重新创建（而非滚动重建）；对一个切片进行维护会重启环境中的所有切片。

检查清单

提供可复制的 Markdown 检查清单，并包含复选框。完整的升级前和升级后检查清单模板请参阅 references/checklists.md。请根据用户的环境调整。

有状态工作负载： 存在有状态工作负载（数据库）时，升级前检查清单必须始终包含 PV 备份完成情况，以及 PV 回收策略（例如 Retain 与 Delete）的验证。

Autopilot 检查清单： 对于 Autopilot 集群，请确保检查清单包含：

• 验证所有容器中的 resources.requests（Autopilot 要求）。
• 必须包含用于检查 API 弃用情况的具体 kubectl 命令，特别是：kubectl get --raw /metrics | grep apiserver_request_total | grep deprecated，用于检查是否有任何活动工作负载正在使用已弃用的 API。
• 验证 PDB，确保其不会阻止节点清空（尽管 GKE 会管理节点，但仍会遵守 PDB）。
• 找出并删除“裸 Pod”（未由 ReplicaSet/Deployment/StatefulSet 管理的 Pod），因为节点重新创建时不会重新调度这些 Pod。
• 验证 terminationGracePeriodSeconds，确保 Pod 在节点重新创建期间有足够时间正常关闭。

维护操作手册

提供包含实际 gcloud 和 kubectl 命令的分步操作手册。标准命令序列请参阅 references/runbook-template.md。

任何放宽安全控制的操作手册都必须在同一份操作手册中恢复这些控制。 这尤其适用于节点池迁移或回滚期间的 PDB：排空节点前备份 PDB，并将重新应用 PDB 作为带编号的步骤，且单独进行验证，而不是仅在结尾提一句。若操作手册将 maxUnavailable: 100% 打补丁以解除排空阻塞，却始终不恢复该设置，就会使集群失去中断保护，而这一风险要到下次自愿驱逐时才会显现。相同规则也适用于维护排除项、不可调度标记，以及为完成操作而添加的自动扩缩器 minNodes 覆盖值。

维护时段暂停

诊断“卡住”的升级时，请考虑它是否因维护时段而暂停：

• 静默暂停行为： 如果维护时段在升级（自动或手动）完成前结束，GKE 会有意暂停发布，以避免在允许时段之外造成中断。
• 混合版本状态： 集群会保持在稳定的混合版本状态（部分节点已升级，部分节点尚未升级）。你必须明确说明，这是受支持且安全的预期结果。
• 恢复： 下一次维护时段开始时，升级会自动恢复。
• 立即完成的缓解措施： 如果用户希望立即完成升级，你必须建议临时延长维护时段，使其涵盖当前时间（例如，使用 gcloud container clusters update ... --maintenance-window-start ... --maintenance-window-duration ...）。不要建议重新触发手动升级或绕过维护时段。

故障排查

当用户报告升级卡住或失败时，你必须在最终回复中系统地分析并处理所有 5 种潜在原因。即使你怀疑其中一种是主要原因，也不得省略其他检查：

1. PDB 阻止驱逐： 使用 kubectl get pdb -A，确认是否有任何 PDB 的 ALLOWED DISRUPTIONS = 0。
2. 资源限制： 检查是否有 Pod 因容量限制而卡在 Pending 状态。
3. 裸 Pod： 找出没有所有者引用、阻止驱逐的 Pod（建议删除这些 Pod）。
4. 准入 Webhook： 检查 Validating/Mutating Webhook 是否拒绝在新节点上创建 Pod。
5. PVC 挂载问题： 检查卷挂载失败情况（尤其是区域限制）。

资源耗尽／配额用尽规则：

• 如果升级因 ZONE_RESOURCE_POOL_EXHAUSTED（资源短缺）或 Compute Engine 资源的 QUOTA_EXCEEDED 而卡住：
  1. 建议将升级策略改为 maxSurge=0（原地滚动升级），以绕过配额限制。
  2. 对于 QUOTA_EXCEEDED，建议向 Google Cloud 申请提高配额。
  3. 你必须建议将工作负载迁移到其他区域，或在有可用容量／配额的其他区域或地域创建新的节点池，以此作为缓解措施。

有关每个步骤的确切诊断命令和修复流程，请参阅 references/troubleshooting.md。

参考资料

• GKE 发行说明
• 升级 GKE 集群
• 排查 GKE 升级问题
• 获取升级信息（升级辅助工具）
• 节点池升级策略（激增式与蓝绿）
• 维护时段与例外
• 发布顺序概念
• 配置发布顺序