gke-ai-troubleshooting-tpu-partition-overlap

排查由分区重叠导致的 TPU slice 创建失败

当 slice 的任一节点已被其他 slice 使用时，动态 slice 会创建失败，状态原因为 SliceCreationFailed。本技能会确认故障、排除其他已记录的原因、找出使用相同节点的 slice，并通过 GKE 修复问题。

归属信息

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

前置条件

• 工具：
  • 如需安装和初始化 gcloud（包括身份验证和项目选择），请参阅 开始之前。
  • 如需安装 kubectl 和所需插件，请参阅 安装 kubectl 和 安装所需插件。
• Cloud Billing 和项目配置：确保项目已关联有效的 Cloud Billing 账号。请参阅 开始之前 初始化 gcloud 并启用 Google Kubernetes Engine API (container.googleapis.com)，确保 Cloud Monitoring API (monitoring.googleapis.com) 已启用，并参阅 为 kubectl 存储集群信息 配置 kubectl 集群凭据。
• 所需 IAM 角色：
  • Kubernetes Engine Viewer (roles/container.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
• 文档：
  • 使用自定义调度器进行动态切片 （章节：“开始之前”、“将节点池配置为属于一个块或子块”、 “验证节点和分区的状态”、“创建 Slice 自定义资源”、 “监控 Slice 自定义资源的状态”、“删除切片”）
  • 配置 kubectl 集群访问权限 （章节：“安装 kubectl”、“安装所需插件”、“为 kubectl 存储集群 信息”）
  • Slice （章节：“Slice 状态”、“Slice 规范”）
  • 使用 Kueue 和 TAS 调度动态切片 （章节：“将节点池配置为属于一个块或子块”、 “使用 Kueue 和 TAS 创建动态切片”、“定义分区运行状况 选择”、“通过重复使用切片优化工作负载调度”、“启用 Slice 重复使用”、“按工作负载强制删除切片”、“监控切片的状态”、 “监控切片指标”、“清理”）
  • GKE 系统指标 （章节：“Kubernetes 指标”）
  • 受监控的资源类型 （章节：“k8s_node_pool”）
  • 关于 GKE 动态切片 （章节：“动态切片配置”）
  • 获取支持 （章节：“联系支持人员之前”、“高效获取支持的建议”）

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

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

---

诊断工作流

步骤 0：收集上下文 [低风险]

收集目标参数：

• {project_id}：Google Cloud 项目 ID
• {cluster_name}：GKE 集群名称
• {location}：集群所在的区域或可用区
• {slice_name}：未能创建的 Slice 自定义资源的名称
• {node_pool_name}：支持 {slice_name} 中分区的 TPU 节点池名称（如果已知）。如果用户不知道 {node_pool_name}，请在步骤 1 后，对 {partition_ids} 中的分区 ID 运行步骤 3 中的 Cloud Monitoring 查询，并读取 k8s_node_pool 监控资源上的 node_pool_name 标签。
• {issue_time}：事件发生时间戳（RFC3339 UTC 格式，如果已知）。如果用户不知道 {issue_time}，请使用步骤 1 中 Ready 条件的 Last Transition Time （lastTransitionTime，即 Slice 状态 中所说的“最近一次状态更改的时间戳”）。默认情况下，在 {issue_time} 前后 60 分钟的时间范围内查询 Cloud Monitoring。

---

步骤 1：确认 SliceCreationFailed 状态 [低风险]

如需描述 {slice_name}，请按照 监控 Slice 自定义资源的状态 一节中的说明操作。

• 在 Status > Conditions 中，检查 Ready 条件的 Reason 是否为 SliceCreationFailed，并记录其 Last Transition Time（如有需要，将其用作 {issue_time}）。
• 将 Spec > Partition Ids 中的 ID 记录为 {partition_ids}，同时记录 Topology，以及 {slice_name} 上的所有 Labels 和 Annotations。
• 如果 Ready 原因为 SliceCreationFailed 以外的值，则此技能不适用。请参阅 Slice 状态 了解各原因的含义，并转交给 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring。

---

步骤 2：排除其他已记录的原因 [Low Risk]

根据 创建 Slice 自定义资源， 以下情况也会导致 Slice 创建失败，并出现 SliceCreationFailed：

• 所选节点不存在。
• 拓扑与分区数量不匹配。动态子 Slice 恰好列出一个分区 ID。动态超 Slice 列出 (A × B × C) / 64 个分区 ID。

如果符合上述任一原因，请转交给 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring。

否则，按照 验证节点和分区的状态 检查 {node_pool_name}：

• 验证节点是否存在，并且是否包含 {partition_ids} 中的每个 ID。
• 在包含 {partition_ids} 的节点上，记录 cloud.google.com/gke-tpu-partition-.*-id 标签中 每种形状（4x4x4、2x4x4、2x2x4、2x2x2 和 2x2x1）的所有分区 ID。根据 动态切片配置， 动态子切片会将 4x4x4 子块划分为同一物理节点池上的更小拓扑，因此不同形状的分区会共用相同的节点。
• 读取每个分区的 cloud.google.com/gke-tpu-partition-.*-state 标签。根据 验证节点和分区的状态 和 定义分区健康状态选择， 将状态为 HEALTHY 的分区和状态为 DEGRADED 的 4x4x4 分区（“仍可用于动态 Slice 构建”；“较小拓扑没有降级状态”）计为可用。状态为 UNHEALTHY（“无法用于构建 Slice”）、UNSET 或 INCOMPLETE 的分区不可用。如果请求的分区状态为 UNHEALTHY、UNSET 或 INCOMPLETE，请建议使用节点未被其他 Slice 使用的可用分区（步骤 4，第 2 项），转交给 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring，或升级至 Cloud Customer Care（步骤 4，第 4 项）。

---

第 3 步：查找使用相同节点的切片 [Low Risk]

根据 创建 Slice 自定义资源， 如果自定义资源上的任何节点已被其他切片使用，切片创建就会失败，并显示 SliceCreationFailed。由于同一子块上不同形状的分区会共享节点（请参阅 动态切片配置）， 如果其他切片列出了第 2 步中 {slice_name} 节点上记录的任意分区 ID（任何形状），就会与 {slice_name} 冲突。

1. 列出集群中的 Slice 自定义资源（如 删除切片 中所示），并按照 监控 Slice 自定义资源的状态 中的说明描述每个资源，以查看 Spec > Partition Ids、Metadata > Labels 和 Status > Conditions（Ready 原因）：
   • 如果除 {slice_name} 以外的任意切片，其 Spec > Partition Ids 包含第 2 步中 {slice_name} 节点上记录的任意分区 ID（无论是 {partition_ids} 中的确切 ID，还是同一节点上其他形状的分区 ID），则将其视为冲突切片。记录其名称、Ready 原因（例如 ACTIVE），以及它是否由 Kueue 管理（第 4 步，第 1 项）。
2. 如需在 Cloud Monitoring 中检查分区与切片的关联（包括 {issue_time} 附近的情况），请查询 监控切片指标 中列出的 kubernetes.io/accelerator/partition/state 指标。根据 Kubernetes 指标， 此指标“检测到分区状态时为 1，否则为 0”，其标签包括 partition_id、slice_id（“关联切片的 ID”）和 state（“分区的运行状况，例如 HEALTHY、UNHEALTHY”）。对第 2 步中 {slice_name} 节点上记录的每个 {partition_id} 运行查询：

kubernetes_io:accelerator_partition_state{
  monitored_resource="k8s_node_pool",
  cluster_name="{cluster_name}",
  partition_id="{partition_id}"
}

• 只读取值为 1 的时间序列（根据 验证节点和分区的状态， state="HEALTHY" 表示分区健康且正常运行）。
• 由于 Kubernetes 指标 将 slice_id 定义为“关联切片的 ID”，因此务必通过集群中的 Slice 自定义资源确认冲突切片，而不要仅凭 slice_id 判断：如 删除切片 中所示，列出 Slice 自定义资源；按照 监控 Slice 自定义资源的状态 中的说明描述每个资源；检查哪个切片的 Spec > Partition Ids 包含该分区 ID（或第 2 步中同一节点上任何其他形状的分区 ID）。

3. 根据第 3 步结果采取后续措施：
   • 现在有其他切片正在使用这些节点：继续执行第 4 步。
   • 现在没有其他切片使用这些节点，但指标（值为 1）显示 {issue_time} 附近存在关联的 slice_id：冲突可能已经结束。继续执行第 4 步第 1 项（重新创建或重试 {slice_name}），然后执行第 4 步第 4 项。
   • 当前的 Slice 自定义资源和 {issue_time} 附近的指标均未显示其他切片：无法确认节点重叠。移交给 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring，或上报 Cloud Customer Care（第 4 步第 4 项）。

---

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

防护措施：

• 切勿为了腾出节点而删除或更改另一个切片，也不要停止其工作负载。删除 Slice 自定义资源会开始拆除该切片（DEACTIVATING，请参阅监控 Slice 自定义资源的状态）。何时释放该切片由其所有者决定。
• 切勿手动修改或删除由 Kueue 创建的 Slice 自定义资源。根据将节点池指定为属于某个块或子块中的说明，“避免手动修改由 Kueue 创建的 Slice 自定义资源。”
• 切勿通过 Compute Engine 直接更改由 GKE 管理的实例组或 VM，也不要为了腾出分区而删除节点池。请通过 GKE 管理节点池和切片。

首先，检查 {slice_name} 或发生冲突的切片是否由 Kueue 管理：

• 根据监控切片的状态，创建切片或工作负载正在使用切片时，切片控制器会附加 kueue.gke.io/tpu-slice-used-by-namespace 和 kueue.gke.io/tpu-slice-used-by-workload 标签。
• 根据通过切片复用优化工作负载调度和启用 Slice 复用，启用切片复用后，“作业结束时，Kueue 会将切片标记为空闲，而不是删除它”，并且“可复用切片会动态命名，名称以 s-<topology> 为前缀，从而使其与特定工作负载名称脱钩。”

然后应用相应的选项：

1. 等待冲突切片释放节点，然后重试：
   • 如果冲突切片由 Kueue 管理（它带有 kueue.gke.io/... 标签，或名称前缀为 s-<topology>）：不要建议直接删除 Slice 自定义资源。请让工作负载所有者参阅 清理 （删除 JobSet 会触发 Kueue 删除关联的 Slice 自定义资源）；如果切片复用导致作业结束后空闲的 s-<topology> 切片仍保持分配状态，也请参阅 按工作负载强制删除切片 （kueue.gke.io/tpu-enforce-slice-deletion: "true"）。
   • 如果冲突切片由自定义调度器或用户直接创建： 所有者可以在使用完毕后将其删除，具体请参阅 删除切片。
   • {slice_name} 如何重试：检查 {slice_name} 是否已在 Metadata > Annotations 中设置 slice.gke.io/retry-on-failure: "true"。根据 创建 Slice 自定义资源， 创建 Slice 自定义资源时若带有此注解，“如果因 SliceCreationFailed 状态原因而未能创建切片，控制器会持续重试，直到切片成功形成。”由于文档只展示了创建 Slice 自定义资源时如何在 Slice 清单中配置 slice.gke.io/retry-on-failure: "true"（并未说明为已有且处于 SliceCreationFailed 状态的切片添加注解会启动重试），如果 {slice_name} 不是由 Kueue 创建且缺少此注解，请告知用户按照 删除切片 删除 {slice_name}，然后按照 创建 Slice 自定义资源 在清单中设置 slice.gke.io/retry-on-failure: "true" 后重新创建。
2. 使用节点未被其他切片使用的可用分区：如果用户直接管理 Slice 自定义资源（而非通过 Kueue 管理）且无法等待，请引导他们参阅 验证节点和分区的状态 和 创建 Slice 自定义资源， 以便选择节点未被任何其他切片使用的可用分区（HEALTHY 分区，或 DEGRADED 4x4x4 分区；需检查这些节点上的所有分区形状），并使用这些分区创建 Slice 自定义资源。
3. 使用 Kueue 和 TAS 调度动态切片，而不是直接创建 Slice 自定义资源：根据 将节点池设为块或子块的一部分 和 使用 Kueue 和 TAS 创建动态切片， 团队可以使用 Kueue 和拓扑感知调度（TAS）来调度 GKE 工作负载，而不是直接创建 Slice 自定义资源。此时，“Kueue 会自动处理 Slice 自定义资源的创建和删除”，并在切片变为活动状态后接纳工作负载。
4. 验证或升级处理：按照 监控 Slice 自定义资源的状态 再次执行步骤 1：
   • ACTIVE：切片已完全形成，状态健康，可以运行工作负载。
   • ACTIVE_DEGRADED：切片已形成，可以运行工作负载，但性能可能会受到影响。
   • 在没有其他切片使用这些节点后仍为 SliceCreationFailed，或状态为 FAILED：转交给 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring，或建议用户按照 联系支持团队前的准备工作 和 高效获取支持的建议 联系 Cloud Customer Care。