gke-ai-troubleshooting-node-unresponsive-timeout

排查无响应的 GKE TPU 和 GPU 节点（NodeStatusUnknown）

当 TPU 或 GPU 节点的 Compute Engine 主机发生严重硬件错误、内核崩溃或不可屏蔽中断（NMI）锁死时，来宾操作系统会停止响应。kubelet 无法再发送心跳，因此节点的 Ready 条件会变为 Unknown，并显示 Reason: NodeStatusUnknown（Kubelet stopped posting node status.）。如果节点池已停用节点自动修复，GKE 就不会修复该节点。该节点可能一直处于 NotReady 状态，其上的 Pod 也可能一直处于 Terminating 状态，导致多主机 JobSet 工作负载无法恢复。

归属信息

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

前提条件

• 工具：安装 Google Cloud SDK（gcloud）和 kubectl。
• Cloud Billing 和项目配置：确认已关联有效的结算账号（gcloud billing projects describe {project_id}），完成身份验证（gcloud auth login），设置目标项目（gcloud config set project {project_id}），并确保已启用 container.googleapis.com、compute.googleapis.com、logging.googleapis.com 和 monitoring.googleapis.com。
• 所需 IAM 角色：
  • Kubernetes Engine Viewer（roles/container.viewer）
  • Compute Viewer（roles/compute.viewer）
  • Logs Viewer（roles/logging.viewer）
  • Monitoring Viewer（roles/monitoring.viewer）
  • 用于修复（[High Risk] 步骤）：Kubernetes Engine Cluster Admin（roles/container.clusterAdmin）
• 文档：
  • 排查 GKE 中状态为 NotReady 的节点 （章节：“检查节点的状态和条件”、“确认节点是否被抢占”、“验证节点是否已恢复”）
  • 在 GKE Standard 中部署 TPU 工作负载 （章节：“监控 TPU 节点和节点池的健康指标”、“为 TPU 切片节点配置自动修复”）
  • 排查 OOM 事件
  • 查看 GKE 日志 （章节：“系统日志”）
  • 查看串行端口输出
  • 排查因内核崩溃导致的 Linux VM 启动问题
  • 自动修复节点 （章节：“Autopilot 和 Standard 的设置”、“验证 Standard 节点池是否已启用节点自动修复”、“获取近期自动修复事件的信息”、“为现有 Standard 节点池启用自动修复”、“修复条件”、“节点修复流程”、“TPU 切片节点的节点自动修复”）
  • 排查 VM 关机和重启问题 （章节：“查询 Cloud Audit Logs”、“查看 Cloud Audit Logs”）

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

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

---

诊断工作流

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

收集目标参数。默认查询 {issue_time} 前后各 30 分钟的时间窗口 `[T - 30m, T

• 30m]`：

• {project_id}：Google Cloud 项目 ID
• {cluster_name}：GKE 集群名称
• {location}：集群区域或可用区
• {nodepool_name}：目标 TPU 或 GPU 节点池名称
• {node_name}：无响应的 GKE 节点名称（及其 Compute Engine {zone}）
• {issue_time}：符合 RFC3339 格式的 UTC 事故时间戳
• {start_time}：{issue_time} - 30m
• {end_time}：{issue_time} + 30m

---

步骤 1：验证 NodeStatusUnknown 心跳超时 [Low Risk]

1. 检查 Kubernetes 节点条件：若要检查节点状态并验证 Ready 条件是否为 Unknown，且原因为 Reason: NodeStatusUnknown （Kubelet stopped posting node status.），请按照 检查节点的状态和条件 部分中的说明操作。
2. 查询 Cloud Logging（只读 LQL）：查询 [{start_time}, {end_time}] 范围内的 k8s_node 和 k8s_cluster 日志，确认控制平面何时失去与 {node_name} 的心跳联系：

(resource.type="k8s_node" OR resource.type="k8s_cluster")
resource.labels.cluster_name="{cluster_name}"
("{node_name}" AND ("NodeNotReady" OR "NodeStatusUnknown" OR "Kubelet stopped posting node status"))
timestamp >= "{start_time}" AND timestamp <= "{end_time}"

3. 查询 Cloud Monitoring（只读 PromQL）：使用 GKE 系统指标 kubernetes.io/node/status_condition（kubernetes_io:node_status_condition， GKE 1.32.1-gke.1357001+），并按照 监控 TPU 节点和节点池的健康指标 中的说明，以 condition="Ready" 和 status="Unknown" 为筛选条件，关联分析 Unknown 状态的持续时间：

kubernetes_io:node_status_condition{
  monitored_resource="k8s_node",
  cluster_name="{cluster_name}",
  node_name="{node_name}",
  condition="Ready",
  status="Unknown"
}

• 决策逻辑：
  • 如果节点的 Ready 条件为 True，且不存在 NodeStatusUnknown，则排除 无响应节点超时的可能性，转而排查工作负载级问题（例如， 排查 OOM 事件）， 而不是修复或排空节点。
  • 如果 Ready 为 Unknown（NodeStatusUnknown），则继续执行步骤 2。

---

步骤 2：检查串行端口输出，排查内核崩溃 [Low Risk]

严重的内核冻结发生后，来宾操作系统无法发送日志，因此请检查节点 VM 的串行端口输出：

• Cloud Logging：如果已启用串行端口日志记录（即 VM 元数据 serial-port-logging-enable 设置为 true），Cloud Logging 中的 GKE 系统日志会包含节点的串行端口输出。请参阅 系统日志 部分。当 VM 已停止或已由自动修复替换，或者需要查看最新输出之外的更多内容时，请使用 Cloud Logging。
• 正在运行的 VM：按照 查看串行端口输出 中的说明，检索 {zone} 中 {node_name} 的串行端口 1 输出（使用 gcloud compute instances get-serial-port-output 和 --port=1）。此方法只返回每个端口最新的 1 MB 输出。

请参阅 排查因内核崩溃导致的 Linux VM 启动问题， 以识别串行端口输出中有文档记录的内核崩溃和硬件崩溃模式（例如 Fatal Machine check、hung_task: blocked tasks 或 NMI: Not continuing）。

---

步骤 3：检查节点自动修复状态 [Low Risk]

查明 GKE 为什么没有修复无响应的节点：

• Autopilot 集群：Autopilot 始终会修复节点，且无法关闭此功能（请参阅 Autopilot 和 Standard 的设置）。 跳过配置检查，检查修复历史记录。
• Standard 集群：按照 验证 Standard 节点池是否启用了节点自动修复 检查 {nodepool_name} 上是否启用了 autoRepair。
• 修复历史记录（两种模式均适用）：即使启用了自动修复，修复仍可能失败。根据 配置 TPU 切片节点的自动修复，请在 获取近期自动修复事件的信息 中所述的操作历史记录里检查修复状态，包括失败原因。 如果失败是由于配额不足，请告知用户联系其 Google Cloud 客户代表以提高配额。

---

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

如需列出 {issue_time} 前后 {node_name} 的系统事件，请按照 查询 Cloud Audit Logs 一节中的说明操作。 将 method 字段与同一文档「查看 Cloud Audit Logs」一节中的表格进行比较，并查找以下事件：

• compute.instances.hostError：物理主机上的硬件或软件问题导致 VM 崩溃。
• compute.instances.preempted：Compute Engine 抢占了 Spot VM 或可抢占 VM。对于被抢占的节点，请同时参阅 确认节点抢占。
• compute.instances.automaticRestart：在发生 hostError 或 terminateOnHostMaintenance 事件后，Compute Engine 重启了 VM。
• compute.instances.guestTerminate：VM 的操作系统发起了关机。

---

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

防护措施：

• 切勿在无响应的节点上强制删除卡在 Terminating 状态的 Pod。 强制删除不会等待 kubelet 确认 Pod 已停止，因此旧 Pod 仍在运行时就可能启动替代 Pod。 请参阅 强制删除 StatefulSet Pod。
• 切勿直接删除由 GKE 管理的 Compute Engine VM 实例（gcloud compute instances delete）。请改为检查节点报告 NodeStatusUnknown 的时长（步骤 1），查看串行控制台输出（步骤 2），并按后续步骤所述依靠节点自动修复。

1. 启用节点自动修复（仅限 Standard 集群）：
   • Autopilot 集群始终会自动修复节点，因此请跳过此步骤。
   • 在用户为多主机 TPU 切片节点池启用自动修复之前，请告知他们：当该节点池中的节点需要修复时，GKE 会重新创建整个节点池（见步骤 2）。
   • 如果 {nodepool_name} 上的 autoRepair 已停用，请将用户引导至 为现有 Standard 节点池启用自动修复 和 配置 TPU 切片节点的自动修复， 以便他们自行应用更改。
2. 让 GKE 修复节点：
   • 说明对于报告 NotReady 状态或在文档规定的时间阈值内没有状态报告的节点，GKE 会通过排空并重新创建节点来修复它，并将用户引导至 自动修复节点中的“修复条件”和“节点修复流程”部分。 GKE 会等待一小时让排空完成。如果排空未能完成，GKE 会关闭该节点并创建新节点。请告知用户，在 GKE 重新创建节点之前，需预留一小时等待排空。
   • 对于多主机 TPU 切片节点池，请根据 TPU 切片节点中的节点自动修复 说明，整个节点池都会被重新创建。
3. 验证节点恢复情况：
   • 修复完成后，按照 验证节点是否已恢复 部分中的说明，确认修复后的节点已恢复为 Ready 状态，然后确认 JobSet Pod 再次运行。