对 GPU 和 TPU 运行健康状况扫描

集群健康状况扫描器是一款自助诊断工具,可在您安排工作负载之前验证 GPU 和 Cloud TPU 容量是否已准备就绪。集群健康状况扫描器会运行基准测试,在加速器节点上模拟实际工作负载流量,以衡量加速器、其内存以及它们之间的互连的性能。您可以使用这些结果来识别和移除故障节点,以免它们导致训练或推理作业停止响应、运行缓慢或失败。

对于 TPU,集群健康状况扫描器是对 TPU 健康状况监控的补充,后者会持续报告硬件健康状况信号。集群健康扫描器会在空闲容量上主动运行工作负载,以衡量性能并暴露仅在负载下才会出现的故障。

集群健康扫描器完全开源。如需查看源代码、做出贡献或提交问题,请参阅集群健康状况扫描器 GitHub 代码库。

本文档介绍了如何安装集群健康扫描器、对 GPU 和 TPU 预留运行健康扫描、解读结果以及修复不健康的节点。

受支持的环境

集群健康状况扫描器支持以下部署环境:

环境 支持的加速器 客户端环境 安装选项
Google Kubernetes Engine (GKE) 集群 GPU 和 TPU(使用静态或动态切片的节点池) 对目标集群具有 kubectl 访问权限的 Linux 机器 Python 软件包或容器映像
Slurm 集群 仅限 GPU Slurm 控制器或登录节点,其中 sinfo 和 sbatch 命令可用 仅限 Python 软件包
独立 TPU 实例 仅限 TPU TPU 实例本身 Python 软件包或容器映像(Container-Optimized OS)

集群健康状况扫描器支持以下 GPU 和 TPU 机器类型:

  • GPU 机器类型:
    • A5X:a5x-highgpu-4g-metal(仅限 GKE)
    • A4X Max:a4x-maxgpu-4g-metal
    • A4X:a4x-highgpu-4g
    • A4: a4-highgpu-8g
    • A3 Ultra:a3-ultragpu-8g
    • A3 Mega:a3-megagpu-8g
  • TPU 机器类型:

诊断套件

您可以将集群健康扫描器安装为 Python 软件包或容器映像。这两个选项都提供 chs 命令行界面 (CLI) 和诊断基准。您可以在可访问 GKE 集群的机器上、Slurm 控制器或登录节点上,或直接在独立 TPU 实例上运行 CLI。然后,CLI 会在目标 GPU 或 TPU 节点上运行诊断测试。

集群健康扫描器为每种加速器类型提供两个诊断套件:

  • 精简版:运行快速筛查。在 GPU 和独立 TPU 实例上,Lite 套件会检查各个主机。在 GKE TPU 节点池上,它还会对 TPU 切片运行快速集体检查 (tpu-collectives)。集合运算是一种通信模式,其中所有加速器都会交换数据,例如 AllReduce,它会合并每个加速器的值,并与所有加速器共享结果。在运行单主机工作负载之前,您可以使用 Lite 套件进行快速健康检查。
  • 标准:针对目标容量运行全面验证。在 GPU 上,标准套件会跨多个节点运行集体操作,并测量 GPU 内存带宽。在 TPU 上,它会运行所有 Lite 测试,以及持续计算、内存和网络压力测试。在运行多主机训练或推理工作负载之前,请使用标准套件,因为持续负载下的网络性能和稳定性会直接影响作业性能。
套件 加速器 测试 突出焦点
lite GPU nvidia-smi、dcgm、gemm、nccl-single-node 快速验证 GPU 和驱动程序的健康状况、计算吞吐量以及节点内 GPU 通信。
TPU tpu-info、tpu-gemm、tpu-hbm、tpu-host-device、tpu-collectives 快速验证设备健康状况、计算吞吐量、高带宽内存 (HBM) 带宽、主机到设备带宽以及芯片间互连 (ICI) 集合带宽。
standard GPU nvidia-smi、dcgm、gemm、nccl-cluster、nccl-pairwise、stream 跨目标节点的多节点网络验证,以及内存带宽。
TPU 所有 TPU lite 测试,以及 tpu-compute-stress、tpu-hbm-stress 和 tpu-network-stress 持续压力测试,可暴露不稳定性、静默数据损坏和 ICI 位错误。

nccl-domain GPU 测试不属于任何套件。如需运行 nccl-domain,请使用 --tests 标志。

GPU 套件和测试

集群健康状况扫描器为 GPU 节点提供以下套件:

  • Lite:验证 GPU 驱动程序和硬件,测量计算吞吐量,并在每个节点内运行 NVIDIA Collective Communications Library (NCCL) 测试。
  • 标准:在所有目标节点之间以及节点对之间运行 NCCL 集合操作,以衡量节点间网络的性能,并衡量内存带宽。

下表介绍了每项 GPU 测试:

测试 说明 套件
nccl-single-node 在单个节点内的 GPU 之间运行 NCCL 集合测试。 lite
nvidia-smi 使用 NVIDIA 系统管理接口检查基本 GPU 运行状况和 GPU 驱动程序。 lite,standard
dcgm 运行 NVIDIA 数据中心 GPU 管理器 (DCGM) 诊断,对每个 GPU 执行深度硬件检查。 lite,standard
gemm 运行通用矩阵乘法 (GEMM) 以测量 GPU 计算吞吐量。 lite,standard
nccl-cluster 在所有目标节点上运行 NCCL 集合测试,以测量整个集群的网络带宽。 standard
nccl-pairwise 在节点对之间运行 NCCL 测试,以测量节点到节点的延迟时间,并找出故障节点或链路。 standard
stream 运行 STREAM 基准测试,以测量 GPU 内存带宽。 standard
nccl-domain 在每个多节点 NVLink 网域中运行 NCCL 集合测试。仅支持具有多节点 NVLink 网域的机器类型。 无(使用 --tests 运行)

TPU 套件和测试

集群健康扫描器为 TPU 节点提供以下套件:

  • Lite:验证每个主机上的 TPU 芯片和 HBM 的性能,测量主机到设备的带宽,并运行集合操作测试来测量 ICI 带宽。
  • 标准:在切片中的 TPU 芯片上运行集合操作,并对 TPU 芯片、HBM 和 ICI 链路进行持续压力测试。

下表介绍了每项 TPU 测试:

测试 说明 套件
tpu-info 检查基本 TPU 运行状况,包括设备数量、LibTPU 版本和 TPU 设备类型。 lite,standard
tpu-gemm 运行通用矩阵乘法 (GEMM) 以测量持续峰值 TFLOPS。 lite,standard
tpu-hbm 测量 HBM 读写带宽。 lite,standard
tpu-collectives 对集体操作(例如 AllReduce 和 AllGather)进行计时,以测量 ICI 带宽(仅限 GKE 集群)。 lite,standard
tpu-host-device 测量主机到设备的带宽。 lite,standard
tpu-compute-stress 运行持续的矩阵乘法,以验证计算稳定性并暴露静默数据损坏。 standard
tpu-hbm-stress 对 HBM 进行压力测试,以测量最大带宽并验证数据完整性。 standard
tpu-network-stress 通过 ICI 链路发送大型随机载荷,以测量持续带宽并检测位错误(仅限 GKE 集群)。 standard

准备工作

在使用集群健康扫描器之前,请安装所需的工具、配置权限并连接到集群或实例。

安装次数

在运行运行状况扫描之前,请完成部署环境的安装。

GKE 集群

如需在 GKE 集群上运行健康状况扫描,请确保您有目标集群,并在计划运行扫描的机器上安装所需的工具:

Slurm 集群

如需在 Slurm 集群上运行健康扫描,请确保您有目标 GPU 集群,并在 Slurm 控制器或登录节点上安装所需工具,其中 sinfo 和 sbatch 命令可用:

对于 Slurm 集群,请使用 Python 软件包安装选项。Slurm 不支持容器映像选项。

独立 TPU 实例

如需在独立 TPU 实例上运行健康状况扫描,请确保您有目标 TPU 实例,并直接在实例上安装所需工具:

  • gcloud CLI:安装并初始化 gcloud CLI。
  • 集群健康扫描器前提条件:安装您计划使用的集群健康扫描器安装选项所需的工具:
    • Python 软件包:Python 3.12(具体而言,是 Linux x86_64 上的 Python 3.12,而不是 3.13 或更高版本)和 Git。如果实例上的默认 python3 版本早于或晚于 3.12,您可以使用 uv 创建 Python 3.12 虚拟环境(请参阅排查集群健康扫描器问题)。
    • 容器映像:Docker。 在 Container-Optimized OS 上,容器映像是唯一受支持的安装选项。
  • 独立 TPU 实例:确保您有一个独立 TPU 实例(TPU7x 或 TPU v6e),该实例会在 /dev/vfio 下公开其 TPU 设备(您可以通过在实例上运行 ls /dev/vfio 来验证这一点)。如需了解详情,请参阅创建 Cloud TPU 虚拟机。

所需的角色

如需获取运行健康状况扫描所需的权限,请让管理员为您授予项目的 roles/compute.viewer 角色。此角色可让集群健康扫描器读取节点的 Compute Engine 元数据和拓扑信息。

您还需要拥有以下 Identity and Access Management (IAM) 角色,具体取决于您的部署环境:

环境 所需的角色
GKE 集群 Kubernetes Engine Developer (roles/container.developer)
Slurm 集群
  • Compute OS Login (roles/compute.osLogin) 或 Compute OS Admin Login (roles/compute.osAdminLogin)
  • IAP-Secured Tunnel User (roles/iap.tunnelResourceAccessor)(如果通过 Identity-Aware Proxy [IAP] 进行连接)
独立 TPU 实例
  • TPU Admin (roles/tpu.admin)
  • IAP-Secured Tunnel User (roles/iap.tunnelResourceAccessor)(如果通过 IAP 连接)

如果您为报告配置 Cloud Storage 存储桶,则还需要对该存储桶拥有 Storage Object Admin 角色 (roles/storage.objectAdmin)。此角色允许集群健康扫描器将结果工件(例如健康报告)上传到存储桶。

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

连接到集群或实例

连接到您计划运行健康扫描的环境。

GKE 集群

设置应用默认凭据 (ADC) 并配置 kubectl 以与 GKE 集群通信:

gcloud auth application-default login
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID

Slurm 集群

使用 SSH 连接到 Slurm 控制器或登录节点:

gcloud compute ssh SLURM_NODE_NAME \
    --zone=ZONE \
    --project=PROJECT_ID

独立 TPU 实例

使用 SSH 连接到独立 TPU 实例:

gcloud compute tpus tpu-vm ssh TPU_NAME \
    --zone=ZONE \
    --project=PROJECT_ID

安装集群健康扫描器

在运行扫描的机器上安装集群健康扫描器,具体取决于您的环境:

  • GKE 集群:对您的集群具有 kubectl 访问权限的任何机器。
  • Slurm 集群:Slurm 控制器或登录节点。
  • 独立 TPU 实例:TPU 实例本身。

在 GKE 和 Slurm 集群上,集群健康扫描器会自动拉取与 GPU 或 TPU 节点匹配的诊断容器映像,并在集群上安排这些映像,因此您无需在各个计算节点上安装任何软件。在独立 TPU 实例上,您可以直接在实例上安装并运行集群健康扫描器。

您可以将集群健康扫描器安装为 Python 软件包或容器映像。本文档其余部分中的 chs 命令适用于任一安装选项。如需查看任何命令的详细使用情况信息,请附加 --help 标志。

Python 软件包

创建 Python 虚拟环境,并从 GitHub 安装集群健康状况扫描器软件包。在 GKE 和 Slurm 集群上,使用 Python 3.12 或更高版本。在独立 TPU 实例 (x86_64) 上,您必须使用 Python 3.12(如果使用 Python 3.13 或更高版本,pip install 不会安装 TPU 基准依赖项,并且 chs run 会跳过该实例):

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

如需安装特定版本,请将 @VERSION 附加到代码库网址:

pip install git+https://github.com/GoogleCloudPlatform/cluster-health-scanner.git@VERSION

如需查看版本列表,请参阅 GitHub 上的集群健康扫描器版本。

容器映像

集群健康扫描器作为容器映像在 Artifact Registry 中分发。 该映像同时支持 GPU 和 TPU。您可以将容器映像用于 GKE 集群和独立 TPU 实例,但不能用于 Slurm 集群。

  1. 配置 Docker 以向 Artifact Registry 进行身份验证,并拉取集群健康状况扫描器容器映像:

    gcloud auth configure-docker us-docker.pkg.dev
    docker pull us-docker.pkg.dev/gce-ai-infra/chs/chs:latest
    

    如需拉取特定版本(而非 latest),请将 latest 替换为版本号。例如,GitHub 版本 v0.3.0 的 0.3.0。如需查看版本列表,请参阅 GitHub 上的集群健康扫描器版本。

  2. 创建 shell 别名以直接运行 chs 命令。您创建的别名取决于您的环境:

    • GKE 集群:别名会以只读模式装载 kubeconfig 文件和 Google Cloud 凭据。该别名还会将运行状态存储在 chs-local-state Docker 卷中,并将输出文件写入当前目录中的 chs-output 目录:

      alias chs='docker run --rm -it --network host \
          -v ~/.kube:/workspace/.kube:ro \
          -v ~/.config/gcloud:/workspace/.config/gcloud:ro \
          -v chs-local-state:/workspace/.local/share \
          -v "$(pwd)/chs-output":/workspace/chs-output \
          us-docker.pkg.dev/gce-ai-infra/chs/chs:latest'
      
    • 独立 TPU 实例:在运行 Container-Optimized OS 的 TPU 实例上,容器映像是唯一受支持的安装选项。该别名会向容器授予对实例的 TPU 设备和主机 PID 命名空间的访问权限,在 /host 处装载主机根文件系统,并以只读模式装载您的 Google Cloud凭据。该别名还会将运行状态存储在 chs-local-state Docker 卷中,并将输出文件写入当前目录中的 chs-output 目录:

      alias chs='docker run --rm -it --privileged --pid=host \
          -v /:/host \
          -v ~/.config/gcloud:/workspace/.config/gcloud:ro \
          -v chs-local-state:/workspace/.local/share \
          -v "$(pwd)/chs-output":/workspace/chs-output \
          us-docker.pkg.dev/gce-ai-infra/chs/chs:latest'
      

可选:为报告设置 Cloud Storage 存储桶

默认情况下,集群健康扫描器会将报告和诊断日志保存到本地输出目录。您还可以配置 Cloud Storage 存储桶,以便远程存储这些文件。

  1. 如果您还没有用于存储健康扫描报告的存储桶,请创建一个:

    gcloud storage buckets create gs://BUCKET_NAME \
        --location=BUCKET_LOCATION \
        --project=PROJECT_ID
    
  2. 向您的主用户账号或服务账号授予 Storage Object Admin 角色 (roles/storage.objectAdmin):

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
        --member=PRINCIPAL \
        --role=roles/storage.objectAdmin
    

    PRINCIPAL 成员是写入报告的主账号。例如 user:EMAIL 或 serviceAccount:SERVICE_ACCOUNT_EMAIL。

  3. 设置集群健康扫描器存储报告的存储桶。该存储桶必须已经存在,因为集群健康扫描器不会自动创建它。您只需为每个环境运行一次此命令:

    chs configure storage gcs BUCKET_NAME
    

    如需将报告存储在存储桶中的文件夹前缀下,请将前缀附加到存储桶名称:

    chs configure storage gcs BUCKET_NAME/PREFIX
    

运行健康扫描

本部分介绍如何验证节点是否处于空闲状态、启动扫描以及监控其进度。

验证目标节点是否处于空闲状态

集群健康状况扫描器仅在空闲容量上运行,不会自动停止或逐出工作负载。在开始扫描之前,请排空或停止在目标节点或实例上运行的所有工作负载。

如果集群健康扫描器在目标节点或实例上检测到活跃工作负载,则会按如下方式处理容量:

  • GPU:集群健康状况扫描器会跳过忙碌节点,并在其余空闲节点上运行扫描。
  • TPU:集群健康状况扫描器如何处理繁忙容量取决于环境:
    • GKE 集群:多主机 TPU 测试(tpu-collectives 和 tpu-network-stress)需要完整的空闲切片,而单主机 TPU 测试可以在单个空闲节点上运行:
      • 静态切片节点池(--nodepools 或 --nodes):如果您在运行 lite 或 standard 套件时,池中的某些节点处于忙碌状态,则集群健康状况扫描器会记录警告,忽略多主机测试,并在其余空闲节点上运行单主机 TPU 测试。
      • 动态切片节点池(--nodepools 或 --nodes):定位到具有 --nodepools 的池需要整个节点池处于空闲状态,以便集群健康扫描器可以预配完整池 Slice 资源。如果您使用 --nodes(在 GKE 1.36.0-gke.3712000 或更高版本中)指定特定节点,集群健康扫描器会为每个空闲节点预配一个单独的 2x2x1 子切片,跳过繁忙节点,并在空闲节点上运行单主机 TPU 测试。
    • 独立 TPU 实例:如果另一个进程正在使用 /dev/vfio 下的 TPU 设备,则集群健康状况扫描器无法运行。

为确保目标容量处于空闲状态,请按照适用于您环境的步骤操作。

GKE 集群

  1. 停止或删除目标节点池中所有正在运行的工作负载作业或 Pod,或者等待正在运行的工作负载完成。

    如果您使用 kubectl drain 从节点池中逐出工作负载,请在开始扫描之前解除节点封锁,以便集群健康扫描器可以在这些节点上调度诊断 Pod(集群健康扫描器会跳过封锁的节点):

    kubectl drain -l cloud.google.com/gke-nodepool=NODE_POOL_NAME \
        --ignore-daemonsets --delete-emptydir-data
    kubectl uncordon -l cloud.google.com/gke-nodepool=NODE_POOL_NAME
    

    确保在扫描运行期间,节点池中没有安排新的工作负载。

  2. 验证节点池中是否没有剩余的工作负载 Pod:

    kubectl get pods --all-namespaces -o wide \
        --field-selector=status.phase=Running | grep NODE_POOL_NAME
    

    系统 Pod(例如由 kube-system 命名空间中的 DaemonSet 管理的 Pod)可以继续运行。

Slurm 集群

  1. 检查目标分区中是否有正在运行的作业:

    squeue --partition=PARTITION_NAME
    

    如果作业正在分区中运行,请等待其完成或使用 scancel JOB_ID 将其取消。

  2. 验证目标分区中的节点是否处于 idle 状态:

    sinfo --partition=PARTITION_NAME
    

独立 TPU 实例

验证没有其他进程正在使用实例上的 TPU 设备:

sudo fuser -v /dev/vfio/*

如果列出了任何进程,请等待工作负载完成或停止进程,然后再开始扫描。

开始扫描

您传递给 chs run 命令的标志取决于您运行集群健康状况扫描器的环境。集群健康状况扫描器会自动检测调度器和加速器类型,因此您无需指定它们。

如需列出加速器类型的可用诊断套件和测试,请运行以下命令:

  • 对于 GPU:

    chs list suites --gpu
    chs list tests --gpu
    
  • 对于 TPU:

    chs list suites --tpu
    chs list tests --tpu
    

GKE 节点池

从任何可以 kubectl 访问集群的机器(例如本地机器或 Cloud Shell)运行集群健康扫描器。

如需在一个或多个节点池上启动扫描,请运行以下命令:

chs run \
    --nodepools=NODE_POOL_NAMES \
    --suite=SUITE

替换以下内容:

  • NODE_POOL_NAMES:要扫描的 GPU 或 TPU 节点池的英文逗号分隔列表。例如:a4-pool-1,a4-pool-2 或 tpu7x-pool-1,tpu7x-pool-2。所有目标节点池都必须使用相同的机器类型。
  • SUITE:要运行的诊断套件,即 lite 或 standard。如需详细了解每个套件,请参阅诊断套件。

如需运行特定测试(而非完整套件),请将 --suite 标志替换为 --tests 标志,并指定逗号分隔列表的测试名称:

chs run \
    --nodepools=NODE_POOL_NAMES \
    --tests=TEST_NAMES

如需扫描特定节点(而非整个节点池),请将 --nodepools 标志替换为 --nodes 标志,并指定以英文逗号分隔的节点名称列表。

当您在 --nodepools 标志中指定多个节点池时,集群健康扫描器会根据加速器类型处理这些节点池:

  • GPU 节点池:将指定节点池中的所有空闲 GPU 节点合并为一个目标集,并对所有这些节点一起运行多节点测试(nccl-cluster 和 nccl-pairwise)。
  • TPU 节点池:在单次运行中独立且并行地评估每个节点池(TPU 切片),不进行跨切片(Multislice)测试。

Slurm 分区

在 Slurm 控制器或登录节点上运行集群健康扫描器,其中 sinfo 和 sbatch 命令可用。Slurm 需要 Python 软件包安装选项。如需了解安装说明,请参阅 Python 软件包。

在开始扫描之前,请在集群上配置 Enroot 凭据,以便节点可以从 us-docker.pkg.dev 拉取基准映像:

gcloud auth configure-docker us-docker.pkg.dev
mkdir -p ~/.enroot
cat <<EOF > "${HOME}/.enroot/.credentials"
machine us-docker.pkg.dev login oauth2accesstoken password $(gcloud auth application-default print-access-token)
EOF

在一个或多个分区上启动扫描:

chs run \
    --partitions=PARTITION_NAMES \
    --suite=SUITE

替换以下内容:

  • PARTITION_NAMES:要扫描的 Slurm 分区的逗号分隔列表。
  • SUITE:要运行的诊断套件,即 lite 或 standard。如需详细了解每个套件,请参阅诊断套件。

如需运行特定 GPU 测试(而非完整套件),请将 --suite 标志替换为 --tests 标志,并指定以英文逗号分隔的测试名称列表(例如 nccl-pairwise,gemm 或 nccl-domain):

chs run \
    --partitions=PARTITION_NAMES \
    --tests=TEST_NAMES

独立 TPU 实例

直接在 TPU 实例上运行集群健康状况扫描器。TPU 实例必须在 /dev/vfio 下公开其 TPU 设备(您可以通过运行 ls /dev/vfio 在实例上验证这一点)。

如果您不以 root 用户身份运行集群健康扫描器,请在运行 TPU 测试之前提高 memlock 限制:

ulimit -l unlimited

如需在 TPU 实例上启动扫描,请运行以下命令:

chs run --suite=SUITE

将 SUITE 替换为要运行的诊断套件,即 lite 或 standard。如需详细了解每个套件,请参阅诊断套件。

如需运行特定 TPU 测试(而非完整套件),请将 --suite 标志替换为 --tests 标志,并指定以英文逗号分隔的测试名称列表(例如 tpu-host-device,tpu-hbm-stress):

chs run --tests=TEST_NAMES

查看运行作业和结果

集群健康扫描器会将运行历史记录和配置设置存储在运行 chs 命令的客户端机器上(存储在 ~/.local/share/chs/ 中,或在使用容器映像时存储在 chs-local-state Docker 卷中)。因此,chs history 和 chs results 命令仅列出从该环境启动的运行。

如需列出之前的运行作业及其运行作业 ID,请运行以下命令:

chs history

如需显示运行结果以及交互式 HTML 报告 (bill_of_health.html) 和 JSON 报告 (bill_of_health.json) 的位置,请运行以下命令:

chs results RUN_ID

如果您省略 RUN_ID,集群健康扫描器会提示您选择运行。该命令会输出本地路径,如果您配置了存储桶,则会输出 Cloud Storage URI。它会读取过去运行的存储结果,而不会在集群或实例上启动新作业。

取消扫描

如需取消扫描、停止其作业并移除其在集群或实例上创建的资源,请运行以下命令之一:

  • 取消最近一次运行:

    chs cancel
    
  • 取消特定运行:

    chs cancel RUN_ID
    
  • 取消在集群或实例上运行的每个集群健康扫描程序,包括由其他用户启动的运行:

    chs cancel --all
    

解释结果

扫描完成后,集群健康状况扫描器会将以下工件保存到本地输出目录,并将其上传到 Cloud Storage 存储桶(如果您配置了存储空间):

  • 互动式 HTML 报告 (bill_of_health.html):显示每个测试、其测量的指标及其状态。
  • JSON 报告 (bill_of_health.json):包含每次测试的参数扫描和测量指标。
  • Workspace 目录:包含诊断日志。

查看健康报告

如需查找扫描报告的确切本地路径或 Cloud Storage URI(gs://BUCKET/PREFIX/bills_of_health/RUN_ID.html 和 gs://BUCKET/PREFIX/bills_of_health/RUN_ID.json),请运行以下命令:

chs results RUN_ID

如果您配置了 Cloud Storage 存储桶,则可以直接从 chs results 返回的 URI 查看 JSON 报告:

gcloud storage cat gs://BUCKET_NAME/PREFIX/bills_of_health/RUN_ID.json

报告内容

健康报告会列出集群健康扫描器测试的每个节点,以及每个节点的基准测试结果。GPU 和 TPU 扫描使用相同的报告格式。每个节点都会收到以下状态之一:

状态 说明
HEALTHY 所有测试均达到了相应机器类型的预期性能。
DEGRADED 节点已完成测试,但一个或多个结果低于预期性能。
POTENTIALLY DEGRADED 某项筛查测试的结果低于预期性能,并且未运行其对应的压力测试来确认结果。
INCOMPLETE 一个或多个测试未能运行、超时、被取消或未报告节点上的指标。

bill_of_health.json 文件包含以下顶级字段:

  • report_id:扫描运行的唯一标识符。
  • chs_version:生成报告的集群健康扫描器的版本。
  • created_at:报告生成时的时间戳。
  • system_info:有关被测系统的元数据,例如集群类型和机器类型。
  • test_results:测试结果对象的列表。每个条目都包含以下字段:
    • test_name:诊断测试的名称。
    • result_status:测试结果,例如 RESULT_STATUS_SUCCESS 或 RESULT_STATUS_FAILED。
    • target_resources:运行测试的节点(node_name 和 instance_id)。
    • metrics:测试的测量指标和验证标准。

健康状况报告采用一致的结构化 JSON 格式。您可以将报告加载到 BigQuery 或其他分析工具中,并比较对同一容量进行连续扫描的报告,以检测性能是否逐渐下降。

修复健康状况不佳的节点

如果健康报告发现节点或实例处于 DEGRADED、POTENTIALLY DEGRADED 或 INCOMPLETE 状态,请执行以下步骤:

  1. 为了排除暂时性问题,请在封锁或排空节点之前,在 GKE 节点池或节点、Slurm 分区或独立 TPU 实例上重新运行扫描(集群健康扫描器会跳过已封锁的 GKE 节点和已排空的 Slurm 节点)。如需查看相关说明,请参阅开始扫描。

  2. 如果问题仍然存在,请阻止在受影响的节点或实例上调度新的工作负载:

    • GKE 集群:封锁健康状况不佳的节点:

      kubectl cordon NODE_NAME
      
    • Slurm 集群:排空运行状况不佳的节点:

      sudo scontrol update NodeName=NODE_NAME State=DRAIN Reason="CHS unhealthy"
      
    • 独立 TPU 实例:在完成问题修复之前,请勿在 TPU 实例上启动新的工作负载。

  3. 根据加速器类型和环境,使用以下选项之一修复或更换节点或实例:

    与支持团队联系时,请附上本地输出目录或 Cloud Storage 存储桶中的工作区目录(其中包含诊断日志),并提供运行 ID。

  4. 修复或替换节点或实例后,请将其重新设为可调度,以便集群健康扫描器不会跳过它,然后运行新的扫描以确认容量是否健康:

    • GKE 集群:取消封锁节点,然后在安排新工作负载之前重新运行扫描:

      kubectl uncordon NODE_NAME
      
    • Slurm 集群:恢复节点,使其返回到 idle 状态,然后在安排新作业之前重新运行扫描:

      sudo scontrol update NodeName=NODE_NAME State=RESUME
      
    • 独立 TPU 实例:在实例上重新运行扫描,然后在扫描确认实例运行状况良好后继续运行工作负载。

Telemetry

集群健康扫描器会向 Google 发送匿名使用情况指标,以帮助改进该工具,并且不会收集个人身份信息 (PII)。遥测功能默认处于启用状态。如需停用,请运行 chs configure telemetry disable 或设置 CHS_TELEMETRY=0 环境变量。

后续步骤

如需解决集群健康扫描器的常见问题,请参阅排查集群健康扫描器问题。