gke-ai-troubleshooting-tpu-slice-mig-stuck-updating

排查不稳定的 MIG 导致 GKE TPU Slice 创建受阻的问题

此技能可帮助诊断 GKE TPU Dynamic Slice 创建失败以及 JobSet 调度延迟问题，原因是为 TPU 节点池提供支持的 Compute Engine 托管实例组（MIG）不稳定（status.isStable: false）。

SliceCreationFailed 状态原因表示 Slice 创建失败，因为未满足前置条件（例如，缺少所需的 Compute Engine 资源）或预检检查失败（请参阅 使用自定义调度器进行动态切片）。 仍在创建、更新或修复实例的 MIG 是需要检查的原因之一。此技能会先检查 Slice 状态，然后检查其后端 MIG 的稳定性。

归属信息

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

前置条件

• Google Cloud SDK 和工具：
  • 如需安装和初始化 gcloud（选择项目并进行身份验证）以及启用 GKE API，请参阅 开始之前。
  • 如需安装 kubectl 并配置集群凭据，请参阅 安装 kubectl 并配置集群访问权限中的“安装 kubectl”“安装所需插件”和“存储 kubectl 的集群信息”部分。
• API 启用和结算：
  • 确认项目拥有有效的 Cloud Billing 账号。
  • 启用以下 API：container.googleapis.com、compute.googleapis.com 和 logging.googleapis.com。
• 所需的 IAM 角色：
  • Logs Viewer（roles/logging.viewer）：检查 Cloud Audit Logs 中的 MIG 错误。
  • Compute Viewer（roles/compute.viewer）：检查 MIG 稳定性（isStable）和实例进度。
  • Kubernetes Engine Viewer（roles/container.viewer）：检查 Slice 自定义 资源（slices.accelerator.gke.io）、节点和集群操作。
• 文档：
  • 使用自定义调度器进行动态切片 （部分：“开始之前”“创建 Slice 自定义资源”“监控 Slice 自定义资源的状态”“验证节点和分区的状态”“升级节点池”）
  • 安装 kubectl 并配置集群访问权限 （部分：“安装 kubectl”“安装所需插件”“存储 kubectl 的集群信息”）
  • 添加和管理节点池 （部分：“查看 Standard 集群中的节点池”）
  • 查看 MIG 和托管实例的信息 （部分：“检查 MIG 是否稳定”“检查托管实例的状态”“列出实例错误”）
  • 在 MIG 中自动应用 VM 配置更新 （部分：“验证更新发布是否完成”）
  • 手动升级集群控制平面或节点池 （部分：“检查节点池升级状态”“取消节点池升级” “恢复节点池升级”“回滚节点池升级”）
  • 自动修复节点 （部分：“获取近期自动修复事件的信息”）
  • 排查 GKE Standard 节点池问题 （部分：“问题：由于资源不足，节点池创建失败”）
  • 排查 GKE 中的 TPU 问题 （部分：“配额不足，无法满足 TPU 请求”“TPU 资源不足，无法满足 TPU 请求”）
  • REST 资源：projects.locations.clusters.nodePools （部分：“资源：NodePool”）
  • 使用 Kueue 和 TAS 调度动态切片 （部分：“监控切片的状态”）
  • 关于 GKE 中的 TPU
  • 获取支持 （部分：“联系支持团队之前”）

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

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

---

诊断工作流

步骤 0：收集上下文并设置调查时间范围 [Low Risk]

从用户提示或环境中收集必要的上下文参数：

• {project_id}、{cluster_name}、{location}、{nodepool_name} 和 {issue_time}。
• {mig_name} 和 {zone}：为 {nodepool_name} 提供支持的托管实例组的名称和区域，取自节点池的 instanceGroupUrls 字段（请参阅 在 Standard 集群中查看节点池 和 资源：NodePool）。 如果尚未从发生故障的 Slice 中得知 {nodepool_name} 或 {mig_name}，请按照 验证节点和分区的状态 找出受影响的分区、节点和后端 MIG。
• 时间范围：默认查询 60 分钟的时间范围 [{issue_time} - 30m, {issue_time} + 30m]（{start_time} 到 {end_time}）。

---

步骤 1：检测切片创建失败和 MIG 错误 [Low Risk]

1. 检查 Slice 状态和分区节点：按照 使用自定义调度器进行动态切片 中的“监控 Slice 自定义资源的状态”和“验证节点和分区的状态”部分，以及 监控切片状态，检查 Slice 自定义资源的 Status.Conditions 中是否存在 SliceCreationFailed 状态原因，并找出受影响的分区、节点和 {mig_name}。
2. 在 Cloud Logging 中查询 MIG 错误：确定 {mig_name} 后（也可先查询，再在得知 {mig_name} 后缩小结果范围），运行以下 Cloud Logging 查询，以检测 [{start_time}, {end_time}] 时间范围内后端实例组管理器上的错误：

   resource.type="gce_instance_group_manager"
   resource.labels.instance_group_manager_name="{mig_name}"
   severity>=ERROR
   timestamp >= "{start_time}" AND timestamp <= "{end_time}"
   

• 调查结果：
  • 如果 Slice 状态报告 SliceCreationFailed，或日志显示实例组错误，请继续执行步骤 2。
  • 如果没有匹配的错误日志，且 TPU Slice 状态为 ACTIVE，则可排除 MIG 不稳定问题，并检查工作负载配置。

---

第 2 步：检查 MIG 稳定性（status.isStable）[Low Risk]

按照 检查 MIG 是否稳定 检查 {mig_name} 的稳定性（status.isStable）和版本目标状态 （status.versionTarget.isReached）：

• 字段含义：
  • status.isStable: false：更改正在进行或等待处理，或者 MIG 本身正在修改。继续执行第 3 步。
  • status.versionTarget.isReached: false：至少有一个实例尚未运行目标版本（参见 在 MIG 中自动应用 VM 配置更新）。 继续执行第 3 步。
  • status.isStable: true 且 status.versionTarget.isReached: true：没有实例正在进行更改或已安排更改（所有实例的 currentAction 均为 NONE），并且 MIG 本身未在修改。这说明 MIG 不稳定并非问题原因。如果 Slice 仍处于 SliceCreationFailed 状态，请转交给 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring，或者按照 使用自定义调度器进行动态切片 中的“创建 Slice 自定义资源”和“验证节点和分区的状态”部分进行操作。

---

第 3 步：查找失败或停滞的实例操作 [Low Risk]

请用户按照 查看 MIG 和托管实例的信息 中的“检查托管实例的状态”和“列出实例错误”部分（包括这两个部分的名称和文档标题），检查 {mig_name} 中各个实例的状态（currentAction 和 instanceStatus），并列出最新的错误：

• 如果错误显示容量或配额问题，例如 ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS 或 QUOTA_EXCEEDED，请转到第 5 步第 2 项。
• 否则，继续执行第 4 步，检查节点池升级或自动修复操作。

---

第 4 步：检查节点池操作 [Low Risk]

MIG 仍在更改实例，可能是由节点池升级或修复导致的：

1. 检查节点池升级：按照 检查节点池升级状态 列出集群操作，并查找在 [{start_time}, {end_time}] 内针对 {nodepool_name} 的升级操作。另请查看 升级节点池， 了解动态切片的升级要求（所需的 surge 设置，以及升级前删除活跃的超切片）。
   • 如果升级操作仍在运行，请转到第 5 步第 1 项或第 3 项。
   • 如果升级操作已取消、失败或未完成，请转到第 5 步第 4 项。
2. 检查自动节点修复：按照 获取近期自动修复事件的信息 检查 {nodepool_name} 是否有修复操作。
   • 如果节点自动修复操作正在运行，请转到第 5 步第 1 项。
3. 如果没有操作或错误可以解释 MIG 不稳定的原因：转到第 5 步第 5 项，联系 Cloud Customer Care。

---

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

防护措施：不要直接通过 Compute Engine 修改由 GKE 管理的实例组或 VM。请通过 GKE 管理节点池。

1. 等待正在进行的更新或自动修复完成：如果节点池升级或自动修复仍在进行，用户可以等待 MIG 稳定（status.isStable: true），具体请参阅 检查 MIG 是否稳定。
2. 解决容量或配额错误：如果步骤 3 显示 ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS 或 QUOTA_EXCEEDED，回滚升级无法解决资源短缺问题。请参阅 问题：节点池创建因资源不足而失败，以及 排查 GKE 中的 TPU 问题中的“配额不足，无法满足 TPU 请求”和“TPU 资源不足，无法满足 TPU 请求”部分。
3. 取消正在进行的节点池升级：如果用户希望停止仍在进行的升级，请参阅 取消节点池升级。 对于动态切片节点池，还请参阅 升级节点池，了解所需的激增设置，以及升级前删除活动超级切片的要求。
4. 恢复或回滚已取消、失败或未完成的节点池升级：
   • 请参阅 手动升级集群的控制平面或节点池中的“恢复节点池升级”或“回滚节点池升级”部分。 如文档所述，如果正在进行的升级已取消、升级失败，或因维护时段超时而未完成，则可以回滚（节点池成功升级后无法回滚）；或者，可以恢复已取消或失败且仅部分完成的升级。
   • 随后，请参阅 检查 MIG 是否稳定，验证 MIG 是否稳定。
5. 上报原因不明的 MIG 不稳定问题：如果没有节点池升级、修复操作或容量／配额错误能够解释 {mig_name} 为何仍不稳定，请引导用户按照 获取支持的说明联系 Cloud Customer Care。
6. 验证节点池和切片是否恢复：实例组稳定（status.isStable: true）后，请参阅 使用自定义调度器进行动态切片中的“监控 Slice 自定义资源的状态”和“创建 Slice 自定义资源”部分，验证 Slice 是否达到 ACTIVE 状态。如果 MIG 稳定后 Slice 仍处于 SliceCreationFailed 状态，请检查 Slice 上是否设置了“创建 Slice 自定义资源”部分中所述的重试注解。