排查集群健康状况扫描器问题

本文档介绍了集群健康状况扫描器的常见问题以及解决方法。

由于检测到活跃工作负载,扫描跳过节点或停止

问题:扫描跳过了一些 GPU 节点,或在 TPU 节点池的预检期间停止,并报告检测到活跃工作负载。

原因:一个或多个目标节点正在运行工作负载。

解决方案:排空或停止目标节点上的工作负载,然后重新运行扫描。如需了解详情,请参阅验证目标节点是否处于空闲状态。

由于机器类型不一致,扫描停止

问题:扫描在预检期间停止,并报告目标节点使用不同的机器类型。

原因:您在 --nodepools 标志中指定的节点池或在 --partitions 标志中指定的分区并非都使用相同的机器类型。例如,单次扫描不能混合使用 GPU 和 TPU 节点池,也不能混合使用 A3 Mega 和 A4 节点。

解决方法:为每种机器类型分别运行扫描。

由于存储权限错误,扫描停止

问题:扫描在预检期间停止,并报告 Cloud Storage 错误。

原因:存储桶不存在,或者写入报告的主账号无权写入存储桶。

解决方法:验证存储桶是否存在,以及主账号是否对该存储桶拥有 Storage Object Admin 角色。如需了解详情,请参阅为报告设置 Cloud Storage 存储桶。

命令行工具无法连接到集群

问题:chs 命令行工具返回身份验证或连接错误。

原因:缺少集群的 kubeconfig 条目,或者您的凭据在容器内不可用。

解决方法:运行 gcloud container clusters get-credentials 命令,如连接到集群或实例中所述。然后,验证您的 kubeconfig 文件和 Google Cloud 凭据是否已装载到容器中,如安装集群健康状况扫描器中所述。

调用方无权访问项目

问题:chs 命令返回以下错误:

ERROR: The caller doesn't have permission to access the project PROJECT_ID

原因:您的凭据缺失或已过期,或者活跃身份不具有项目所需的 Identity and Access Management (IAM) 权限。

解决方法:使用您的用户账号设置应用默认凭证:

gcloud auth application-default login

如果您还需要使用用户账号(而非服务账号)对 Google Cloud CLI 进行身份验证,请运行以下命令:

gcloud auth login --no-browser

GPU 测试报告驱动程序或硬件错误

问题:在 nvidia-smi 或 dcgm 测试运行后,健康报告会显示某些节点的 DEGRADED 或 INCOMPLETE 状态。

原因:未检测到节点上的 GPU、GPU 驱动程序无法正常运行,或者 NVIDIA 数据中心 GPU 管理器 (DCGM) 检测到硬件故障。

解决方法:查看本地输出目录或 Cloud Storage 存储桶的工作区目录中的诊断日志。然后,按照修复运行状况不佳的节点中适用于您的环境的步骤操作。

网络测试报告带宽低或延迟高

问题:健康报告显示某些节点的集体通信带宽较低或延迟较高。

原因:在 GPU 上,这是由一个或多个节点上的 GPU、NVLink 连接或网络接口故障引起的。在 TPU 上,这是由一个或多个节点上的 ICI 链路或 TPU 芯片故障引起的。

解决方法:对于 GPU,请使用 nccl-pairwise 测试结果来确定哪些节点涉及慢速节点对。对于 TPU,请查看健康报告中的 tpu-collectives 和 tpu-network-stress 结果。然后,按照修复不健康的节点中适用于您的环境的步骤操作。

扫描停止后,资源仍保留在集群中

问题:chs 进程终止后,诊断作业或资源仍保留在 Google Kubernetes Engine (GKE) 集群中。

原因:在 GKE 上,chs 进程必须在扫描期间保持运行,以便在扫描完成时清理资源。

解决方法:取消已停止的运行或集群上的所有运行,以移除剩余作业并释放节点:

chs cancel RUN_ID

如需取消集群上的所有运行,请运行 chs cancel --all。

当 TPU 忙碌时,独立 TPU 实例上的扫描会失败

问题:在独立 TPU 实例上运行扫描时,chs 命令行工具会返回 TPUs are busy 错误。

原因:TPU 实例上的另一个进程正在使用 TPU 设备。

解决方法:等待其他进程完成或停止该进程,然后重新运行扫描。

在独立 TPU 实例上,扫描失败并显示 memlock 限制错误

问题:在独立 TPU 实例上运行扫描时,chs 命令行工具会报告 memlock 限制过低,或者 TPU 测试需要 root 或无限制的 memlock 限制。

原因:当前用户会话具有受限的锁定内存地址空间 (memlock) 限制。

解决方法:以 root 用户身份运行集群健康状况扫描器,或在运行扫描之前提高 memlock 限制:

ulimit -l unlimited

容器在无法访问主机的独立 TPU 实例上失败

问题:当您使用容器映像在独立 TPU 实例上运行扫描时,chs 命令行工具会失败并显示以下错误:

CHS runs in a container without access to the host

原因:在 TPU 实例上的独立模式下,容器必须共享主机 PID 命名空间并装载主机文件系统,才能检查和使用 /dev/vfio 下的 TPU 设备。

解决方法:使用 --privileged、--pid=host 和 -v /:/host 标志启动容器。如需查看完整的 docker run 命令,请参阅容器映像。

软件包安装失败,并显示 Python 版本错误

问题:运行 pip install 失败,并显示错误:Package 'chs' requires a different Python。

原因:您机器上的 python3 版本低于 3.12,这在 Slurm 登录节点和 TPU 实例上很常见。

解决方法:使用 uv 创建 Python 3.12 虚拟环境,并在没有 root 权限的情况下安装集群健康扫描器:

python3 -m venv uv-venv
uv-venv/bin/pip install uv
uv-venv/bin/uv venv --python 3.12 chs-venv
source chs-venv/bin/activate
uv-venv/bin/uv pip install git+https://github.com/GoogleCloudPlatform/cluster-health-scanner.git

由于未安装 TPU 测试依赖项,扫描跳过了独立 TPU 实例

问题:在独立 TPU 实例上运行扫描时,chs run 会跳过该实例并返回以下警告:

The TPU test dependencies are not installed. CHS installs them only on Linux x86_64 with Python 3.12.

原因:集群健康扫描器 Python 软件包是使用 3.12 以外的 Python 版本(例如 Python 3.13)安装的。在独立 TPU 实例上,TPU 基准依赖项仅安装在具有 Python 3.12 的 Linux x86_64 上。

解决方法:使用 uv 在 Python 3.12 虚拟环境中重新安装集群健康扫描器(请参阅软件包安装失败,并显示 Python 版本错误),或使用集群健康扫描器容器映像。