gke-ai-troubleshooting-tpu-dynamic-slices-monitoring

GKE TPU 动态切片监控与管理

监控 TPU Slice 自定义资源的状态，排查配置失败问题，验证动态切片上的工作负载清单，并执行清理。

归属信息

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

前提条件

• 项目已启用 Cloud Logging。
• 已配置 kubectl 和 gcloud CLI，以访问 GKE 集群。

诊断工作流

步骤 0：获取上下文并定义时间范围

使用集群工具或以下参数收集项目、集群和切片上下文：

• 项目 ID：{project_id}（例如，my-gcp-project）
• 集群名称：{cluster_name}（例如，tpu-cluster）
• 区域/可用区：{location}（例如，us-central1-a）
• 切片名称：{slice_name}（例如，test-slice）
• 问题时间：{timestamp}（可选；默认采用最近 30 分钟的时间范围 [T - 30m] 至 [T + 30m]）

---

步骤 1：描述切片自定义资源 [低风险]

如果用户要求检查、排查或查看切片状态，请立即使用可用的集群工具执行 kubectl describe slice {slice_name} 进行检查。将输出中的 Status.Conditions 与下方的条件表进行比对，诊断具体状态并提供明确的建议。

• 命令：

  kubectl describe slice {slice_name}
  

状态与原因分析

分析 Status.Conditions（尤其是 Type: Ready 及其 Reason 和 Status）：

生命周期状态 / 原因	含义	建议操作
SliceNotCreated	GKE Slice Controller 正在初始化切片并执行资源检查。	等待几分钟，然后重新检查切片状态。
SliceCreationFailed	前置条件验证失败（例如，所选节点不存在、节点已被其他切片使用，或者拓扑与分区数量不匹配）。	验证所选节点是否存在、尚未分配，并且拓扑与分区数量匹配。
ACTIVATING	GKE 正在积极组建和配置 TPU 切片。	监控节点配置情况。
ACTIVE	TPU 切片已成功组建，可承载工作负载。	继续部署或检查工作负载。
ACTIVE_DEGRADED	切片可用，但一个或多个子块状态降级。	监控工作负载日志中的互连或设备错误。检查故障节点 VM。
FAILED	GKE 未能组建 TPU 切片（例如，所选节点不属于同一个预留块）。	确保所有所选节点都属于同一个预留块。
DEACTIVATING	切片正在拆除（由用户删除或严重的系统故障触发）。	等待拆除完成；如果卡住，请修补 finalizer。
INCOMPLETE	Slice CR 从集群中删除前的最终阶段。	无需操作；该资源很快就会被移除。

资源调配失败故障排查清单

调查切片创建或资源调配失败（SliceCreationFailed 或 FAILED）时，请执行以下验证步骤：

1. 节点存在性与分配检查：确认所选 TPU 节点存在于集群中，且尚未分配给其他切片（kubectl get nodes -l cloud.google.com/gke-tpu-slice、kubectl get slice -A）。
2. 拓扑匹配：确认分区数量与请求的拓扑维度匹配（例如，拓扑 2x2 需要 4 个节点）。
3. 预留区块匹配检查：确认所有选定的 TPU 节点属于同一预留和预留区块。

---

步骤 2：验证工作负载规范 [低风险]

确保工作负载清单已正确配置为使用动态切片。

1. 单切片工作负载要求

检查 Pod 模板是否包含以下注解和选择器：

• 注解：
  • cloud.google.com/gke-tpu-slice-topology: "{topology}"（例如， "4x4x4"）
• NodeSelector：
  • cloud.google.com/gke-tpu-topology: "{topology}"（例如，"4x4x4"）
  • cloud.google.com/gke-tpu-accelerator: "{accelerator_type}"（例如， "tpu7x"）
  • cloud.google.com/gke-tpu-slice: "{slice_name}"（例如，"test-slice"）

2. 多切片（JobSet）工作负载要求

如果要部署多切片 JobSet，请确认：

• JobSet 注解：
  • alpha.jobset.sigs.k8s.io/exclusive-topology: cloud.google.com/gke-tpu-slice
• Pod 模板注解：
  • cloud.google.com/gke-tpu-slice-topology: "{topology}"
• Pod 模板 NodeSelector：
  • cloud.google.com/gke-tpu-topology: "{topology}"
  • cloud.google.com/gke-tpu-accelerator: "{accelerator_type}"
  • 注意：请勿在 nodeSelector 中手动指定 cloud.google.com/gke-tpu-slice；JobSet 会自动处理切片分配。

---

解决与管理工作流

解决方案 1：强制删除卡住的切片 [高风险]

如果切片卡在 DEACTIVATING 状态，或因 finalizer 卡住而导致删除无限期挂起：

1. 确定原因：说明切片资源上的 finalizer（metadata.finalizers）阻止 Kubernetes 完成资源删除。

2. 提出解决方案：建议使用 JSON patch 操作从元数据路径（/metadata/finalizers）移除 finalizer：

   kubectl patch slice {slice_name} --type json -p='[{"op": "remove", "path": "/metadata/finalizers"}]'
   

3. 提供警告：明确提醒用户，移除 finalizer 会绕过标准控制器拆除流程，可能导致底层 VM、网络或加速器资源未被清理，或成为孤儿资源。

4. 关键安全要求：回复必须明确询问用户是否确认（例如，“通过 JSON patch 移除 /metadata/finalizers 上的 finalizer 属于高风险操作，可能导致资源成为孤儿。确认要对切片 {slice_name} 应用此补丁吗？”），并在应用或执行补丁前暂停，等待用户确认。

---

解决方案 2：禁用并清理 Slice 控制器【高风险】

如果需要禁用动态切片：

1. 检查现有的 Slice：

   kubectl get slice -A
   

   禁用控制器前，确保已删除所有 Slice。

2. 通过 gcloud 禁用 Slice 控制器：

   gcloud container clusters update {cluster_name} \
       --location={location} \
       --no-enable-slice-controller
   

3. 删除 Slice CRD：

   kubectl delete crd slices.accelerator.gke.io
   

4. 清理节点标签：从集群中的所有节点移除 GKE TPU Slice 标签：

   kubectl label nodes --all cloud.google.com/gke-tpu-slice- cloud.google.com/gke-tpu-slice-topology-
   

• 安全规则：提出准确的命令，并在执行禁用或破坏性清理步骤前确认。