gke-ai-troubleshooting-tpu-reservation-stockout

排查由泄漏的节点池容量导致的 GKE TPU 预留容量不足问题

使用此技能诊断并解决 GKE TPU 节点池创建或扩容失败的问题：错误为 GCE_STOCKOUT、ZONE_RESOURCE_POOL_EXHAUSTED 或 ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS（或因容量不足而进入排队状态），即使目标是特定的 Compute Engine TPU 预留也会发生。

如果现有 TPU 节点池已停用节点自动修复功能，当节点变为 NotReady 时，GKE 不会修复这些节点。只要这些节点的 VM 仍在运行，就会继续占用预留中的槽位（inUseCount 是占用预留的运行中实例数量）。根据确保预留容量可用，创建节点池时预留必须有足够的可用 TPU 芯片；根据多主机 TPU 切片节点池，如果 GKE 无法在切片中部署一个节点，就不会部署 TPU 切片节点池中的任何节点。当预留中的空闲槽位（specificReservation.count - specificReservation.inUseCount；参见预留中的可用实例）少于新 TPU 节点池所需的节点数时，创建就会失败，并报错 GCE_STOCKOUT 或 ZONE_RESOURCE_POOL_EXHAUSTED（或因容量不足而进入排队状态）。

归属标记

务必阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须先阅读使用情况归属标记。对于直接在终端中执行的命令（绝不可在生成的脚本、Terraform 或用户代码中使用），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-ai-troubleshooting-tpu-reservation-stockout)"，并将 agent-skills/1.0 (skill:gke-ai-troubleshooting-tpu-reservation-stockout) 添加到 User-Agent 标头中。

先决条件

• 所需的 IAM 角色：
  • 日志查看者（roles/logging.viewer）：在 Cloud Logging 中查询 Cloud Audit Logs。
  • Monitoring 查看者（roles/monitoring.viewer）：在 Cloud Monitoring 中查询 GKE 节点就绪状态指标。
  • Kubernetes Engine 查看者（roles/container.viewer）：检查 GKE 节点池（management.autoRepair）、集群操作和节点状况。
  • Compute 查看者（roles/compute.viewer）：检查 Compute Engine 预留的使用情况（specificReservation.inUseCount 与 specificReservation.count）、使用预留的实例以及 VM 标签（如果使用共享预留，还包括其所有者项目中的信息）。
  • 如需进行修复（[High Risk] 步骤）：Kubernetes Engine 集群管理员（roles/container.clusterAdmin）
• API 启用与结算：
  • 确保目标项目已关联有效的 Google Cloud 结算账号：gcloud billing projects describe {project_id}。
  • 启用所需的 API：container.googleapis.com、compute.googleapis.com、logging.googleapis.com 和 monitoring.googleapis.com。
• CLI 与身份验证设置：
  • 安装 Google Cloud SDK（gcloud）和 kubectl： https://cloud.google.com/sdk/docs/install。
• 集群模式：此技能适用于 Standard 集群。Autopilot 集群始终会自动修复节点，且无法关闭此功能（请参阅Autopilot 和 Standard 的设置）。
• 参考文档：
  • 自动修复节点 （章节：“Autopilot 和 Standard 的设置”“修复条件”“节点修复流程”“验证 Standard 节点池是否启用了节点自动修复”“TPU 切片节点中的节点自动修复”“为现有 Standard 节点池启用自动修复”“获取近期自动修复事件的信息”）
  • 排查 GKE Standard 节点池问题 （章节：“问题：节点池因资源不足而创建失败”）
  • 排查 GKE 中的 TPU 问题 （章节：“GKE 如何处理容量问题”“TPU 资源不足，无法满足 TPU 请求”）
  • 关于 GKE 中的 TPU （章节：“多主机 TPU 切片节点池”）
  • 使用预留的可用区资源 （章节：“使用特定的共享预留”）
  • 关于预留 （章节：“预留的工作方式”）
  • 查看预留或未来的预留请求 （章节：“限制”“查看预留”“预留中的可消费实例”“查看使用预留的实例列表”）
  • 使用标签整理资源 （章节：“查看标签”）
  • 创建和管理集群及节点池标签 （章节：“自动应用的标签”）
  • 在 GKE Standard 中部署 TPU 工作负载 （章节：“确保预留可用”“监控 TPU 节点和节点池的运行状况指标”“为 TPU 切片节点配置自动修复”）
  • 添加和管理节点池 （章节：“删除节点池”）

只读规则：仅运行只读诊断命令。切勿排空、删除或重新创建节点，也不要运行任何其他会更改集群的命令。 告诉用户可由他们自行应用的修复方法。

建议修复方法时，请链接到说明该方法的文档章节。

---

诊断工作流

步骤 0：收集背景信息并设置调查时间范围

从用户提示或集群背景信息中确定以下环境参数：

• {project_id}、{cluster_name}、{location}、{failing_nodepool_name}、 {reservation_name}、{reservation_project_id}（拥有 {reservation_name} 的项目；对于单项目预留，默认为 {project_id}；对于共享预留，则为所有者项目；请参阅 使用特定的共享预留）、 {zone}（预留所在区域）以及 {issue_time}。
• 时间范围：默认查询 60 分钟的时间范围 [{issue_time} - 30m, {issue_time} + 30m]（{start_time} 至 {end_time}）。

---

步骤 1：确认资源耗尽错误和预留使用情况 [Low Risk]

1. 检查 Cloud Audit Logs 和 GKE 操作中是否存在资源耗尽或容量错误：
   • 在 [{start_time}, {end_time}] 时间范围内运行 问题：节点池创建因资源不足而失败 中的查询，并查找文档列出的错误消息，例如 ZONE_RESOURCE_POOL_EXHAUSTED 或 ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS。
   • 根据 TPU 资源不足，无法满足 TPU 请求， TPU 错误也可能包含 GCE_STOCKOUT。
   • 根据 GKE 如何处理容量问题， GKE 有时会将 TPU 节点池创建请求排队，而不是立即失败，并显示 ... cannot be created ... due to lack of capacity 消息，而不是 GCE_STOCKOUT。使用 gcloud container operations list 列出节点池创建操作（--filter="operationType=CREATE_NODE_POOL"）。
2. 检查 Compute Engine 预留使用情况：
   • 根据 限制， 在共享预留的所有者项目（{reservation_project_id}）中查询共享预留。
   • 按照 查看预留 章节运行 gcloud compute reservations describe {reservation_name} --zone={zone} --project={reservation_project_id} 或 gcloud compute reservations list --project={reservation_project_id}，并比较 specificReservation.inUseCount 与 specificReservation.count。

解读结果

• 在确定哪些现有 VM 和节点池占用了预留容量之前（步骤 2），不要建议删除任何节点池。
• 确认资源耗尽：根据 确保预留可用 和 多主机 TPU 切片节点池， 如果 GKE 无法在多主机切片中部署一个节点，则不会部署该切片中的任何节点。如果存在资源耗尽或容量不足消息，且可用槽位数（specificReservation.count - specificReservation.inUseCount；请参阅 预留中的可用实例） 少于 {failing_nodepool_name} 所需的节点数，则继续执行步骤 2。

---

第 2 步：查找哪些 VM 和节点池占用了预留资源 [Low Risk]

1. 检查哪些 VM 正在使用 {reservation_name}：
   • 根据 预留资源的工作原理， 定向到特定资源的预留可供预留所在项目（{reservation_project_id}）中的 VM 使用；对于共享预留，也可供与其共享的任何项目中的 VM 使用。
   • 按照 查看正在使用预留资源的实例列表 列出使用 {reservation_name} 的 VM。
   • 按照 查看标签 查看每个 VM 的标签，并检查 自动应用的标签 中的 GKE 标签（goog-k8s-cluster-name、goog-k8s-cluster-location 和 goog-k8s-node-pool-name），以查明每个 VM 所属的集群和节点池。
2. 检查 {cluster_name} 中节点的就绪状态：
   • 查询 Cloud Monitoring 指标 kubernetes_io:node_status_condition （monitored_resource="k8s_node"、cluster_name="{cluster_name}"、 condition="Ready"），相关说明见 监控 TPU 节点和节点池的运行状况指标。 status 标签值为 True、False 或 Unknown（首字母大写）； 使用 status!="True" 查找 Ready 条件为 False 或 Unknown 的节点。
   • 使用 kubectl get nodes -l cloud.google.com/gke-tpu-accelerator -L cloud.google.com/gke-nodepool 列出 TPU 节点及其节点池标签。
3. 排除故障节点池：不要将 {failing_nodepool_name} 纳入 不健康列表。它是无法获取容量的节点池，而不是占用预留资源的节点池。

解读结果

• 位于 {cluster_name} 之外的 VM：如果使用 {reservation_name} 的部分 VM 并非 {cluster_name} 中的节点（例如，其 标签显示它们属于其他 GKE 集群，或者它们是没有 GKE 标签的 Compute Engine VM），请告知用户哪些 VM 或其他集群占用了这些预留名额。
• 列出的 VM 少于 specificReservation.inUseCount：根据 查看正在使用预留资源的实例列表， 列表仅包含一个项目中的 VM。如果列表中的 VM 少于 specificReservation.inUseCount，请告知用户，共享 {reservation_name} 的其他项目中的 VM 正在使用剩余名额。
• {cluster_name} 中的不健康节点池（{leaking_nodepool_name}）：如果使用 {reservation_name} 的 VM 属于 {cluster_name} 中现有的 NotReady 节点池 （{leaking_nodepool_name}），请继续执行第 3 步。
• 预留资源正常（排除资源泄漏）：如果预留名额由正常且正在使用的节点池占用，则不存在资源泄漏。请说明正常的节点池占用了预留名额，因此留给 {failing_nodepool_name} 的空闲名额过少。告知用户不要删除或重启这些正常的节点池，并引导用户查看 TPU 资源不足，无法满足 TPU 请求 中的使用选项。

---

第 3 步：验证泄漏节点池是否启用了节点自动修复 [Low Risk]

对于 {leaking_nodepool_name}，请按照 验证 Standard 节点池是否启用了节点自动修复操作：

• 自动修复已停用（management.autoRepair: false）：GKE 不会修复 {leaking_nodepool_name} 中的 NotReady 节点。这些节点上正在运行的 VM 会继续计入 {reservation_name} 中的 specificReservation.inUseCount，因此 {failing_nodepool_name} 无法获得预留容量。请继续执行第 4 步。
• 自动修复已启用（management.autoRepair: true），但节点仍为 NotReady：
  • 根据修复条件，检查节点处于 NotReady 状态的时间是否少于修复时间阈值（约 10 分钟）。
  • 根据为 TPU 切片节点配置自动修复和获取近期自动修复事件的信息，检查操作历史记录中的修复状态和失败原因。

---

第 4 步：恢复或释放预留容量 [High Risk]

安全措施：不要直接通过 Compute Engine 修改由 GKE 管理的实例组或 VM。请通过 GKE 管理节点池。绝不要删除运行活动作业的健康节点池。

1. 如果用户希望就地修复 {leaking_nodepool_name}，请启用节点自动修复（不会为 {failing_nodepool_name} 释放槽位）：
   • 根据节点修复流程，GKE 会排空并重新创建不健康的节点。
   • 根据TPU 切片节点中的节点自动修复和为 TPU 切片节点配置自动修复，当多主机 TPU 切片节点池中的节点需要修复时，GKE 会重新创建整个节点池。重新创建的 VM 仍会占用 {reservation_name}，因此 specificReservation.inUseCount 不会减少：启用自动修复会让 {leaking_nodepool_name} 中的节点恢复健康，但 {failing_nodepool_name} 仍无法获得这些槽位。
   • 请将用户引导至为现有 Standard 节点池启用自动修复，为 {leaking_nodepool_name} 启用自动修复。
2. 如果 {leaking_nodepool_name} 已过时，或者用户希望为 {failing_nodepool_name} 释放其槽位，请通过 GKE 删除该节点池：请将用户引导至删除节点池，以删除 {leaking_nodepool_name}，从而释放其 VM 占用的预留槽位。
3. 用户删除 {leaking_nodepool_name} 后，请确认有足够的预留槽位可用：按照查看预留操作，运行 gcloud compute reservations describe {reservation_name} --zone={zone} --project={reservation_project_id}，并确认 specificReservation.inUseCount 已减少，使可用槽位（specificReservation.count - specificReservation.inUseCount）至少达到 {failing_nodepool_name} 所需的节点数量，然后再重试 {failing_nodepool_name}。