gke-ai-troubleshooting-tpu-vm-repair-stuck

排查卡在 Compute Engine 修复状态（REPAIRING）的 GKE TPU VM

此技能会检查 VM 状态、主机事件和 GKE 修复状态，并通过 GKE 而非直接修改 Compute Engine 来执行恢复。

归属信息

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

前提条件

• 工具：
  • 如需安装和初始化 gcloud（包括身份验证和项目选择），请参阅 开始之前。
  • 如需安装 kubectl 和所需插件，请参阅 安装 kubectl 和 安装所需插件。
• Cloud Billing 和项目配置：确保项目拥有有效的 Cloud Billing 账号。请参阅 开始之前 初始化 gcloud 并启用 Google Kubernetes Engine API （container.googleapis.com），确保已启用 Compute Engine API （compute.googleapis.com）和 Cloud Logging API（logging.googleapis.com），并参阅 为 kubectl 存储集群信息 配置 kubectl 集群凭据。
• 所需 IAM 角色：
  • Kubernetes Engine Viewer（roles/container.viewer）
  • Compute Viewer（roles/compute.viewer）
  • Logs Viewer（roles/logging.viewer）
  • 对于在第 5 步第 1 项中启用节点自动修复的用户：Kubernetes Engine Cluster Admin（roles/container.clusterAdmin）
• 文档：
  • 查看有关 MIG 和托管实例的信息 （章节：“列出 MIG”、“检查托管实例的状态”）
  • Compute Engine 实例生命周期 （章节：“REPAIRING 状态”）
  • 排查 VM 关机和重启问题 （章节：“查询 Cloud Audit Logs”、“查看 Cloud Audit Logs”）
  • 配置 kubectl 的集群访问权限 （章节：“安装 kubectl”、“安装所需插件”、“为 kubectl 存储集群 信息”）
  • 添加和管理节点池 （章节：“查看 Standard 集群中的节点池”、“将 Pod 部署到 特定节点池”）
  • 排查 NodeNotReady 状态 （章节：“检查节点状态和状况”、“确认节点 抢占”）
  • 关于 GKE 中的 TPU （章节：“多主机 TPU 切片节点池”）
  • 使用自定义调度器进行动态切片 （章节：“要求”、“验证节点和分区的状态”、“监控 Slice 自定义资源的状态”、“硬件 维护和故障”）
  • 关于 GKE 动态切片 （章节：“动态切片配置的主要特征”）
  • 在 GKE 中以 All Capacity 模式部署 TPU （章节：“管理节点故障”、“节点故障和恢复”）
  • 在 All Capacity 模式下报告并修复故障 TPU 主机 （章节：“了解故障主机报告流程”、“查看故障主机报告 操作”）
  • 自动修复节点 （章节：“Autopilot 和 Standard 的设置”、“修复条件”、 “节点修复流程”、“验证 Standard 节点池是否已启用节点自动修复”、“为现有 Standard 节点池启用自动修复”、“获取近期自动修复事件的 信息”、“TPU 切片节点中的节点自动修复”）
  • 在 GKE Standard 中部署 TPU 工作负载 （章节：“开始之前”、“配置 TPU 切片节点的自动修复”）
  • 获取支持 （章节：“联系支持之前”、“高效获取支持的建议”）
  • REST 资源：projects.locations.clusters.nodePools （章节：“资源：NodePool”）

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

推荐修复方法时，请链接到说明该方法的文档部分。

---

诊断工作流

步骤 0：收集上下文 [Low Risk]

收集目标参数：

• {project_id}：Google Cloud 项目 ID
• {cluster_name}：GKE 集群名称
• {location}：集群所在区域或可用区
• {cluster_mode}：集群模式（Autopilot 或 Standard）
• {tpu_version}：TPU 版本（例如 Ironwood tpu7x、TPU v6e、v5p、v5e 或 v4），以及节点池是单主机还是多主机 TPU 切片节点池
• {nodepool_name}：TPU 节点池名称
• {group_name} 和 {zone}：支撑该节点池的托管实例组（MIG）的名称和可用区：
  • 对于 Standard 集群，请按照 查看 Standard 集群中的节点池 的说明，描述 {nodepool_name} 并读取其 instanceGroupUrls 字段（参见 资源：NodePool）。
  • 对于 Autopilot 集群（或未知 {nodepool_name} 的情况），请按照 列出 MIG 的说明，列出 {project_id} 中的托管实例组，并找到 {group_name} 和 {zone}。
• {instance_name}：受影响的 TPU VM 名称（如果已知）。如果用户不知道 {instance_name}，步骤 1 会查找处于 REPAIRING 状态的实例。
• {issue_time}：事件发生时间戳（RFC3339 UTC 格式），如果已知

---

步骤 1：检查托管实例组中的 VM 状态 [Low Risk]

如需列出 {group_name} 中实例的状态（STATUS / instanceStatus）和当前操作（ACTION / currentAction），请按照 检查托管实例的状态 中的说明操作。

• 分析：
  • STATUS（instanceStatus）为 REPAIRING：Compute Engine 正在修复 该 VM，因为遇到了内部错误，或者其宿主服务器因维护而不可用。修复期间无法使用该 VM。请参阅 REPAIRING 状态。 记录 {instance_name}，然后继续步骤 2。
  • 没有实例处于 REPAIRING 状态（所有实例均报告 RUNNING，且 ACTION 为 NONE；或者某个实例报告其他状态或操作，例如 ACTION 为 RECREATING，根据 检查托管实例的状态， 这表示“正在替换实例”）： 按照 检查节点的状态和状况 检查每个节点的状态和状况，并转交给对应的同级技能：
    • 如果节点的 Ready 状况为 Unknown（NodeStatusUnknown），请转交给 gke-ai-troubleshooting-node-unresponsive-timeout。
    • 如果节点因其他原因未处于 Ready 状态，请转交给 gke-node-notready。
    • 如果所有节点均处于 Ready 状态（根据 修复条件， “报告为 Ready 状态的节点被视为健康”），但工作负载的 Pod 仍处于 Pending 状态，请转交给 gke-workload-troubleshooting。

---

步骤 2：检查 Compute Engine 系统事件 [Low Risk]

若要列出 {instance_name} 在 {issue_time} 前后的系统事件，请按照 查询 Cloud Audit Logs 一节中的说明操作。将 method 字段与同一文档中 查看 Cloud Audit Logs 一节中的表格进行比较：

• compute.instances.hostError、 compute.instances.terminateOnHostMaintenance 或 compute.instances.automaticRestart：记录匹配的系统事件日志条目 和时间戳，然后继续执行步骤 3 和 4。
• compute.instances.preempted：Compute Engine 抢占了 Spot VM 或 可抢占 VM。如果受影响的工作负载是 JobSet，则转交给 gke-ai-troubleshooting-jobset-interruption。否则，请按照 确认节点抢占中的说明操作。
• 表格中没有对应的方法，或出现其他方法：根据 查看 Cloud Audit Logs 中的说明，如果 VM 已重启，但查询结果中没有出现任何列出的方法， 则重启很可能是由 VM 的操作系统发起的。如果在步骤 1 中 VM 仍处于 REPAIRING 状态（或出现了 compute.instances.reportHostAsFaulty 等方法），则继续执行步骤 3 和 4。

---

步骤 3：检查节点状态和切片影响 [Low Risk]

按照 检查节点的状态和状况 中的说明，检查集群中节点的状态和状况，并使用节点的 ProviderID 字段匹配 {instance_name}。若要将节点筛选到 {nodepool_name}，请使用 将 Pod 部署到特定节点池 中记载的 cloud.google.com/gke-nodepool 节点标签。

• 如果 {instance_name} 对应的节点报告为 Ready（根据 修复标准， “报告 Ready 状态的节点被视为健康”），且 VM 不再处于 REPAIRING 状态，请继续执行第 5 步第 4 项。
• 否则，根据节点池配置确定不健康节点对节点池的影响：
  • 单主机 TPU 切片节点池：根据 配置 TPU 切片节点的自动修复， “在单主机 TPU 切片节点池中，系统只会自动修复不健康的 TPU 节点。”
  • 动态切片节点池：如需检查 {nodepool_name} 是否使用动态切片，请参阅 要求： 动态切片要求使用 Standard 集群、Ironwood（tpu7x）和 All Capacity 模式预留。对于使用 Ironwood（tpu7x）的 Standard 集群，请检查节点是否具有 cloud.google.com/gke-accelerator-topology-mode: PROVISION_ONLY，如 验证节点和分区的状态 中的第 2 步所示（根据 动态切片配置的主要特征， “动态切片使用增量预配”）。根据 硬件维护和故障， “如果您触发客户发起的维护，或者发生硬件故障转移，受影响的将只是目标节点，而不是整个节点池。”对于活跃的动态子切片，Slice 自定义资源会转换为 FAILED，调度器会尝试在其他可用的健康节点上重新创建该切片。请按照 监控 Slice 自定义资源的状态 检查 Slice 状态；如果 Slice 自定义资源处于 FAILED 或其他非活跃状态，请将 Slice 故障排查转交给 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring，同时检查第 4 步中的 VM 修复情况。
  • TPU All Capacity 模式节点池：根据 管理节点故障 和 节点故障与恢复， 在 TPU All Capacity 模式下，如果 VM 因硬件故障等问题而失败，Google Cloud“会尝试在同一主机上恢复 VM（就地修复）”；失败节点的状态为 NotReady，且节点池的状态不会变为 ERROR。
  • 多主机 TPU 切片节点池（不使用动态切片或 All Capacity 模式）：根据 多主机 TPU 切片节点池 一节，多主机 TPU 切片节点池中的 VM 会被视为一个不可分割的整体。当切片中的节点需要修复时，GKE 会关闭 TPU 切片中的所有 VM，强制驱逐工作负载中的所有 Kubernetes Pod。只有切片中的所有 VM 均已启动并运行后，才能再次调度这些 Pod。

---

第 4 步：检查节点自动修复状态和故障主机报告 [Low Risk]

确认 GKE 或 Compute Engine 是否正在修复节点：

1. 检查是否启用了节点自动修复：
   • Autopilot 集群：Autopilot 始终会修复节点，且无法关闭此功能（参见 Autopilot 和 Standard 的设置）。
   • Standard 集群：按照 验证 Standard 节点池是否启用了节点自动修复 检查 {nodepool_name} 上是否启用了 autoRepair。
2. 检查 GKE 修复操作历史记录：根据 配置 TPU 切片节点的自动修复， 在 获取近期自动修复事件的信息 中查看修复状态，包括任何失败原因：
   • 如果修复操作因配额不足而失败，请告知用户联系其 Google Cloud 客户代表以提高配额。
   • 如果已启用 autoRepair，但尚未出现修复操作，请检查节点处于不健康状态的时长（从 {issue_time} 或第 3 步中 Ready 条件的 LastTransitionTime 获取）。根据 修复条件， 如果节点持续报告 NotReady 状态，或完全未报告任何状态，达到约 10 分钟的时间阈值，GKE 就会启动修复。如果节点报告 NotReady（或未报告任何状态）的时间还不到约 10 分钟，请在超过此阈值后再次检查操作历史记录。如果已超过约 10 分钟，但仍没有修复操作（且第 3 项中也没有 All Capacity 模式故障主机报告），请在第 5 步的第 3 项中升级处理。
3. 对于 TPU All Capacity 模式节点池，检查是否有故障主机报告： 根据 了解故障主机报告流程， 用户报告主机故障后，TPU VM 会停止运行，其状态会变为 REPAIRING，且“主机修复流程可能需要 3 至 14 天，或更长时间。”在升级处理 All Capacity 模式预留中处于 REPAIRING 状态的 VM 之前，请按照 查看故障主机报告操作 检查 {instance_name} 上是否有 compute.instances.reportHostAsFaulty 操作。

---

第 5 步：解决问题 [High Risk]

防护措施：

• 切勿直接通过 Compute Engine 更改由 GKE 管理的实例组或 VM，例如运行 gcloud compute instances delete，或运行会更改实例组的 gcloud compute instance-groups managed 命令。请通过 GKE 管理节点池。
• 切勿对节点池中的节点运行 kubectl delete node。根据 Autopilot 和 Standard 的设置， 如果自动修复已停用时使用 kubectl 删除不健康的节点，底层 VM 可能会与集群脱离，而且您仍需为其付费。

1. 启用节点自动修复（仅限 Standard 集群）：
   • Autopilot 集群始终会自动修复节点，因此跳过此步骤。
   • 在用户为多主机 TPU 切片节点池启用自动修复之前，如果该节点池未使用动态切片或 All Capacity 模式，请告知用户：当其中一个节点需要修复时，GKE 会重新创建整个节点池（参见此步骤的第 2 项）。
   • 如果 {nodepool_name} 上的 autoRepair 已停用，请将用户（需要具备 Kubernetes Engine Cluster Admin 角色 roles/container.clusterAdmin）引导至 为现有 Standard 节点池启用自动修复 和 为 TPU 切片节点配置自动修复， 以便他们自行应用更改。
2. 让 GKE 或 All Capacity 模式修复节点或切片：
   • 单主机 TPU 切片节点池：根据 为 TPU 切片节点配置自动修复， “在单主机 TPU 切片节点池中，只有运行状况不佳的 TPU 节点会自动修复。”根据 节点修复流程， 对于单节点修复，GKE 会排空该节点，并等待一小时以完成排空；如果未能完成排空，GKE 会关闭该节点并创建新节点。
   • 多主机 TPU 切片节点池（未使用动态切片或 All Capacity 模式）：根据 TPU 切片节点中的节点自动修复 和 为 TPU 切片节点配置自动修复， 如果多主机 TPU 切片节点池中的 TPU 切片节点运行状况不佳且需要自动修复，整个节点池都会重新创建。
   • 动态切片节点池：根据 硬件维护和故障， 受影响的只有目标节点，而非整个节点池；对于动态子切片，调度器会尝试在其他可用且运行状况良好的节点上重新创建故障切片。如果 Slice 自定义资源无法创建或一直处于 FAILED 状态，请移交给 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring。
   • 存在故障主机报告的 TPU All Capacity 模式：如果步骤 4 的第 3 项发现 {instance_name} 存在 compute.instances.reportHostAsFaulty 操作（通过 查看故障主机报告操作 跟踪），请勿将该 VM 作为卡住的 VM 升级处理。请告知用户，根据 了解故障主机报告流程， VM 会在修复期间停止，并在修复完成后于同一主机上重新启动；“主机修复流程可能需要 3 到 14 天，甚至更长时间。”
3. 如果修复未开始或未完成，请联系 Cloud Customer Care：
   • 如果 VM 一直处于 REPAIRING 状态（且并非正在等待需要 3 到 14 天的 All Capacity 模式故障主机修复），如果启用了 autoRepair，但节点处于 NotReady 状态（或没有报告状态）超过 修复条件 中约 10 分钟的阈值，且步骤 4 中没有修复操作，或者操作历史记录显示修复失败且原因并非配额问题，请引导用户参阅 联系支持之前 和 高效获取支持的建议， 联系 Cloud Customer Care。除了 高效获取支持的建议 中列出的详细信息外，还请提供节点池名称、实例名称、步骤 2 中的系统事件日志条目，以及步骤 4 中的修复操作名称。
4. 验证恢复情况：
   • 重复步骤 1 和步骤 3。恢复完成后，{group_name} 中的每个实例都应报告 RUNNING，且操作为 NONE；{nodepool_name} 中的每个节点都应处于 Ready 状态。
   • 如果实例报告 RUNNING 且操作为 NONE（或报告其他状态或操作），但节点仍未处于 Ready 状态，请按照步骤 1 中的移交指引（gke-ai-troubleshooting-node-unresponsive-timeout 或 gke-node-notready）处理，或根据此步骤的第 3 项升级给 Cloud Customer Care。