Systemdiagnosen auf GPUs und TPUs ausführen

Der Cluster-Zustandsscanner ist ein Self-Service-Diagnosetool, mit dem die Bereitschaft Ihrer GPU- und Cloud TPU-Kapazität überprüft wird, bevor Sie eine Arbeitslast planen. Der Cluster-Zustandsscanner führt Benchmarks aus, die echten Arbeitslast-Traffic auf Ihren Beschleunigerknoten simulieren, um die Leistung der Beschleuniger, ihres Arbeitsspeichers und der Verbindungen zwischen ihnen zu messen. Anhand der Ergebnisse können Sie fehlerhafte Knoten identifizieren und entfernen, bevor sie dazu führen, dass Ihre Trainings- oder Inferenzjobs nicht mehr reagieren, langsam ausgeführt werden oder fehlschlagen.

Bei TPUs ergänzt der Cluster-Integritätsscanner das TPU-Integritätsmonitoring, das kontinuierlich Hardware-Integritätssignale meldet. Der Cluster-Integritätsscanner führt aktiv Arbeitslasten auf ungenutzter Kapazität aus, um die Leistung zu messen und Fehler aufzudecken, die nur unter Last auftreten.

Der Cluster-Zustandsscanner ist vollständig Open Source. Wenn Sie den Quellcode ansehen, einen Beitrag leisten oder Probleme melden möchten, rufen Sie das GitHub-Repository für den Cluster-Zustandsscanner auf.

In diesem Dokument wird beschrieben, wie Sie den Cluster-Zustandsscanner installieren, einen Zustandsscan für GPU- und TPU-Reservierungen ausführen, die Ergebnisse interpretieren und fehlerhafte Knoten reparieren.

Unterstützte Umgebungen

Der Cluster-Zustandsscanner unterstützt die folgenden Bereitstellungsumgebungen:

Umgebung Unterstützte Beschleuniger Clientumgebung Installationsoptionen
GKE-Cluster (Google Kubernetes Engine) GPUs und TPUs (Knotenpools, die statisches oder dynamisches Slicing verwenden) Einen Linux-Computer mit kubectl-Zugriff auf den Zielcluster Python-Paket oder Container-Image
Slurm-Cluster Nur GPUs Der Slurm-Controller oder Login-Knoten, auf dem die Befehle sinfo und sbatch verfügbar sind Nur Python-Paket
Eigenständige TPU-Instanzen Nur TPUs Die TPU-Instanz selbst Python-Paket oder Container-Image (Container-Optimized OS)

Der Cluster-Integritätsscanner unterstützt die folgenden GPU- und TPU-Maschinentypen:

  • GPU-Maschinentypen:
    • A5X: a5x-highgpu-4g-metal (nur 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-Maschinentypen:

Diagnose-Suites

Sie können den Cluster-Zustandsscanner als Python-Paket oder als Container-Image installieren. Beide Optionen bieten die chs-Befehlszeile (CLI) und die Diagnose-Benchmarks. Sie führen die Befehlszeile von einem Computer mit Zugriff auf Ihren GKE-Cluster, auf einem Slurm-Controller oder Login-Knoten oder direkt auf einer eigenständigen TPU-Instanz aus. Die Befehlszeile führt dann die Diagnosetests auf den Ziel-GPU- oder TPU-Knoten aus.

Der Cluster-Zustandsscanner bietet zwei Diagnosesuiten für jeden Beschleunigertyp:

  • Lite: Führt eine schnelle Überprüfung durch. Auf GPUs und eigenständigen TPU-Instanzen prüft die Lite-Suite einzelne Hosts. In GKE-TPU-Knotenpools wird außerdem eine schnelle kollektive Prüfung (tpu-collectives) für das TPU-Slice ausgeführt. Ein kollektiver Vorgang ist ein Kommunikationsmuster, bei dem alle Beschleuniger Daten austauschen, z. B. AllReduce, das Werte von jedem Beschleuniger kombiniert und das Ergebnis mit allen Beschleunigern teilt. Verwenden Sie die Lite-Suite für schnelle Systemdiagnosen oder vor dem Ausführen von Arbeitslasten auf einem einzelnen Host.
  • Standard: Führt eine umfassende Validierung für Ihre Zielkapazität durch. Auf GPUs führt die Standard-Suite kollektive Vorgänge über mehrere Knoten hinweg aus und misst die GPU-Speicherbandbreite. Auf TPUs werden alle Lite-Tests sowie Tests zur dauerhaften Rechen-, Speicher- und Netzwerkbelastung ausgeführt. Verwenden Sie die Standard-Suite, bevor Sie Trainings- oder Inferenzarbeitslasten mit mehreren Hosts ausführen, bei denen die Netzwerkleistung und -stabilität unter anhaltender Last die Jobleistung direkt beeinflussen.
Suite Beschleuniger Tests Schwerpunkt
lite GPU nvidia-smi, dcgm, gemm, nccl-single-node Schnelle Validierung des GPU- und Treiberzustands, des Rechendurchsatzes und der GPU-Kommunikation innerhalb des Knotens.
TPU tpu-info: tpu-gemm, tpu-hbm, tpu-host-device, tpu-collectives Schnelle Validierung des Gerätezustands, des Rechendurchsatzes, der HBM-Bandbreite (High Bandwidth Memory), der Host-zu-Gerät-Bandbreite und der kollektiven ICI-Bandbreite (Inter-Chip Interconnect).
standard GPU nvidia-smi, dcgm, gemm, nccl-cluster, nccl-pairwise, stream Netzwerkvalidierung für mehrere Knoten auf den Zielknoten sowie Speicherbandbreite.
TPU Alle TPU-lite-Tests sowie tpu-compute-stress, tpu-hbm-stress und tpu-network-stress Dauerhafte Stresstests, die Instabilität, unbemerkte Datenbeschädigung und ICI-Bitfehler aufdecken.

Der GPU-Test nccl-domain ist nicht Teil einer Suite. Verwenden Sie das Flag --tests, um nccl-domain auszuführen.

GPU-Suites und -Tests

Der Cluster-Integritätsscanner bietet die folgenden Suites für GPU-Knoten:

  • Lite: Validiert den GPU-Treiber und die Hardware, misst den Rechendurchsatz und führt einen NCCL-Test (NVIDIA Collective Communications Library) auf jedem Knoten aus.
  • Standard: Führt NCCL-Kollektive auf allen Zielknoten und zwischen Knotenpaaren aus, um die Leistung des Netzwerks zwischen Knoten zu messen, und misst die Speicherbandbreite.

In der folgenden Tabelle werden die einzelnen GPU-Tests beschrieben:

Test Beschreibung Suites
nccl-single-node Führt NCCL-Kollektivtests zwischen den GPUs innerhalb eines einzelnen Knotens aus. lite
nvidia-smi Prüft den grundlegenden GPU-Zustand und den GPU-Treiber mithilfe der NVIDIA System Management Interface. lite, standard
dcgm Führt NVIDIA Data Center GPU Manager (DCGM)-Diagnosen aus, um umfassende Hardwareprüfungen für jede GPU durchzuführen. lite, standard
gemm Führt allgemeine Matrixmultiplikationen (GEMM) aus, um den GPU-Berechnungsdurchsatz zu messen. lite, standard
nccl-cluster Führt kollektive NCCL-Tests auf allen Zielknoten aus, um die clusterweite Netzwerkbandbreite zu messen. standard
nccl-pairwise Führt NCCL-Tests zwischen Knotenpaaren aus, um die Latenz zwischen Knoten zu messen und fehlerhafte Knoten oder Verbindungen zu isolieren. standard
stream Führt den STREAM-Benchmark aus, um die GPU-Arbeitsspeicherbandbreite zu messen. standard
nccl-domain Führt kollektive NCCL-Tests innerhalb jeder NVLink-Domain mit mehreren Knoten aus. Wird nur auf Maschinentypen mit NVLink-Domains mit mehreren Knoten unterstützt. Keine (mit --tests ausführen)

TPU-Suites und ‑Tests

Der Cluster-Integritätsscanner bietet die folgenden Suites für TPU-Knoten:

  • Lite: Validiert die Leistung der TPU-Chips und des HBM auf jedem Host, misst die Bandbreite zwischen Host und Gerät und führt einen Test für kollektive Vorgänge aus, um die ICI-Bandbreite zu messen.
  • Standard: Führt kollektive Vorgänge auf den TPU-Chips in einem Slice sowie dauerhafte Stresstests auf den TPU-Chips, HBM- und ICI-Links aus.

In der folgenden Tabelle werden die einzelnen TPU-Tests beschrieben:

Test Beschreibung Suites
tpu-info Prüft den grundlegenden TPU-Zustand, einschließlich der Anzahl der Geräte, der LibTPU-Version und des TPU-Gerätetyps. lite, standard
tpu-gemm Führt allgemeine Matrixmultiplikationen (GEMM) aus, um die anhaltenden Spitzen-TFLOPS zu messen. lite, standard
tpu-hbm Misst die HBM-Lese- und Schreibbandbreite. lite, standard
tpu-collectives Misst die Zeit für kollektive Vorgänge wie AllReduce und AllGather, um die ICI-Bandbreite zu messen (nur GKE-Cluster). lite, standard
tpu-host-device Misst die Bandbreite von Host zu Gerät. lite, standard
tpu-compute-stress Führt kontinuierliche Matrixmultiplikationen aus, um die Rechenstabilität zu überprüfen und unbemerkte Datenbeschädigungen aufzudecken. standard
tpu-hbm-stress Beansprucht HBM, um die maximale Bandbreite zu messen und die Datenintegrität zu prüfen. standard
tpu-network-stress Sendet große zufällige Nutzlasten über ICI-Links, um die dauerhafte Bandbreite zu messen und Bitfehler zu erkennen (nur GKE-Cluster). standard

Hinweis

Bevor Sie den Cluster-Zustandsscanner verwenden, müssen Sie die erforderlichen Tools installieren, Berechtigungen konfigurieren und eine Verbindung zu Ihrem Cluster oder Ihrer Instanz herstellen.

Installationen

Bevor Sie einen Integritätsscan ausführen, müssen Sie die Installationen für Ihre Bereitstellungsumgebung abschließen.

GKE-Cluster

Wenn Sie Integritätsscans für einen GKE-Cluster ausführen möchten, benötigen Sie einen Zielcluster und müssen die erforderlichen Tools auf dem Computer installieren, auf dem Sie Scans ausführen möchten:

Slurm-Cluster

Wenn Sie Integritätsscans auf einem Slurm-Cluster ausführen möchten, benötigen Sie einen Ziel-GPU-Cluster. Installieren Sie die erforderlichen Tools auf dem Slurm-Controller oder Login-Knoten, auf dem die Befehle sinfo und sbatch verfügbar sind:

Verwenden Sie für Slurm-Cluster die Option zur Installation von Python-Paketen. Slurm unterstützt die Container-Image-Option nicht.

Eigenständige TPU-Instanzen

Wenn Sie Diagnosescans auf einer eigenständigen TPU-Instanz ausführen möchten, benötigen Sie eine Ziel-TPU-Instanz und müssen die erforderlichen Tools direkt auf der Instanz installieren:

  • gcloud CLI: gcloud CLI installieren und initialisieren
  • Voraussetzungen für den Clusterintegritätsscanner: Installieren Sie die Tools für die Installationsoption für den Clusterintegritätsscanner, die Sie verwenden möchten:
    • Python-Paket: Python 3.12 (insbesondere Python 3.12 unter Linux x86_64, nicht 3.13 oder höher) und Git. Wenn die Standardversion von python3 auf Ihrer Instanz älter oder neuer als 3.12 ist, können Sie mit uv eine virtuelle Python 3.12-Umgebung erstellen (siehe Fehlerbehebung beim Cluster-Zustandsscanner).
    • Container-Image: Docker. In Container-Optimized OS ist das Container-Image die einzige unterstützte Installationsoption.
  • Eigenständige TPU-Instanz: Sie benötigen eine eigenständige TPU-Instanz (TPU7x oder TPU v6e), die ihre TPU-Geräte unter /dev/vfio bereitstellt. Sie können dies auf der Instanz mit ls /dev/vfio prüfen. Weitere Informationen finden Sie unter Cloud TPU-VMs erstellen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die Rolle roles/compute.viewer für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen eines Integritätsscans benötigen. Mit dieser Rolle kann der Cluster-Integritätsscanner Compute Engine-Metadaten und Topologieinformationen für Ihre Knoten lesen.

Je nach Bereitstellungsumgebung benötigen Sie außerdem die folgenden IAM-Rollen (Identity and Access Management):

Umgebung Erforderliche Rollen
GKE-Cluster Kubernetes Engine-Entwickler (roles/container.developer)
Slurm-Cluster
  • Compute OS Login (roles/compute.osLogin) oder Compute OS-Administrator-Login (roles/compute.osAdminLogin)
  • Nutzer IAP-gesicherter Tunnel (roles/iap.tunnelResourceAccessor), wenn die Verbindung über Identity-Aware Proxy (IAP) hergestellt wird
Eigenständige TPU-Instanzen
  • TPU-Administrator (roles/tpu.admin)
  • Nutzer IAP-gesicherter Tunnel (roles/iap.tunnelResourceAccessor), wenn die Verbindung über IAP hergestellt wird

Wenn Sie einen Cloud Storage-Bucket für Berichte konfigurieren, benötigen Sie außerdem die Rolle „Storage-Objekt-Administrator“ (roles/storage.objectAdmin) für den Bucket. Mit dieser Rolle kann der Cluster-Integritätsscanner Ergebnisartefakte wie den Integritätsbericht in den Bucket hochladen.

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Mit dem Cluster oder der Instanz verbinden

Stellen Sie eine Verbindung zu der Umgebung her, in der Sie Integritätsscans ausführen möchten.

GKE-Cluster

Richten Sie Standardanmeldedaten für Anwendungen ein und konfigurieren Sie kubectl für die Kommunikation mit Ihrem GKE-Cluster:

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

Slurm-Cluster

Stellen Sie über SSH eine Verbindung zu Ihrem Slurm-Controller oder Login-Knoten her:

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

Eigenständige TPU-Instanzen

Stellen Sie über SSH eine Verbindung zu Ihrer eigenständigen TPU-Instanz her:

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

Cluster-Zustandsscanner installieren

Installieren Sie den Cluster-Integritätsscanner auf dem Computer, auf dem Sie Scans ausführen. Dies hängt von Ihrer Umgebung ab:

  • GKE-Cluster: Jede Maschine, die kubectl-Zugriff auf Ihren Cluster hat.
  • Slurm-Cluster: Der Slurm-Controller oder Login-Knoten.
  • Eigenständige TPU-Instanzen: Die TPU-Instanz selbst.

In GKE- und Slurm-Clustern ruft der Cluster-Integritätsscanner automatisch die Diagnose-Container-Images ab, die Ihren GPU- oder TPU-Knoten entsprechen, und plant sie im Cluster. Sie müssen also keine Software auf den einzelnen Compute-Knoten installieren. Auf einer eigenständigen TPU-Instanz installieren und führen Sie den Cluster Health Scanner direkt auf der Instanz aus.

Sie können den Cluster-Zustandsscanner als Python-Paket oder als Container-Image installieren. Die chs-Befehle im weiteren Verlauf dieses Dokuments funktionieren mit beiden Installationsoptionen. Wenn Sie detaillierte Nutzungsinformationen zu einem Befehl aufrufen möchten, hängen Sie das Flag --help an.

Python-Paket

Erstellen Sie eine virtuelle Python-Umgebung und installieren Sie das Cluster-Zustandsscanner-Paket von GitHub. Verwenden Sie auf GKE- und Slurm-Clustern Python 3.12 oder höher. Auf eigenständigen TPU-Instanzen (x86_64) müssen Sie Python 3.12 verwenden. Mit Python 3.13 oder höher werden die TPU-Benchmark-Abhängigkeiten nicht mit pip install installiert und die Instanz wird mit chs run übersprungen:

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

Wenn Sie einen bestimmten Release installieren möchten, hängen Sie @VERSION an die Repository-URL an:

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

Eine Liste der Releases finden Sie auf GitHub unter Cluster Health Scanner-Releases.

Container-Image

Der Cluster-Integritätsscanner wird als Container-Image in Artifact Registry bereitgestellt. Das Image unterstützt sowohl GPUs als auch TPUs. Sie können das Container-Image für GKE-Cluster und eigenständige TPU-Instanzen verwenden, aber nicht für Slurm-Cluster.

  1. Konfigurieren Sie Docker für die Authentifizierung bei Artifact Registry und rufen Sie das Container-Image für den Cluster-Zustandsscanner ab:

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

    Wenn Sie einen bestimmten Release anstelle von latest abrufen möchten, ersetzen Sie latest durch die Versionsnummer. Beispiel: 0.3.0 für GitHub-Release v0.3.0. Eine Liste der Releases finden Sie auf GitHub unter Cluster Health Scanner-Releases.

  2. Erstellen Sie einen Shell-Alias, um chs-Befehle direkt auszuführen. Der Alias, den Sie erstellen, hängt von Ihrer Umgebung ab:

    • GKE-Cluster: Der Alias stellt Ihre kubeconfig-Datei und die Google Cloud -Anmeldedaten im Lesemodus bereit. Der Alias speichert auch den Status Ihrer Ausführungen im Docker-Volume chs-local-state und schreibt Ausgabedateien in das Verzeichnis chs-output in Ihrem aktuellen Verzeichnis:

      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'
      
    • Eigenständige TPU-Instanzen: Auf einer TPU-Instanz, auf der Container-Optimized OS ausgeführt wird, ist das Container-Image die einzige unterstützte Installationsoption. Der Alias gewährt dem Container Zugriff auf die TPU-Geräte und den Host-PID-Namespace der Instanz, stellt das Host-Stammdateisystem unter /host bereit und stellt Ihre Google Cloud-Anmeldedaten im Lesemodus bereit. Der Alias speichert auch den Status Ihrer Ausführungen im Docker-Volume chs-local-state und schreibt Ausgabedateien in das Verzeichnis chs-output in Ihrem aktuellen Verzeichnis:

      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'
      

Optional: Cloud Storage-Bucket für Berichte einrichten

Standardmäßig speichert der Cluster-Zustandsscanner Berichte und Diagnoselogs in einem lokalen Ausgabeverzeichnis. Sie können einen Cloud Storage-Bucket so konfigurieren, dass sie auch remote gespeichert werden.

  1. Wenn Sie noch keinen Bucket für Berichte zu Integritätsscans haben, erstellen Sie einen:

    gcloud storage buckets create gs://BUCKET_NAME \
        --location=BUCKET_LOCATION \
        --project=PROJECT_ID
    
  2. Weisen Sie Ihrem Hauptnutzerkonto oder Dienstkonto die Rolle „Storage-Objekt-Administrator“ (roles/storage.objectAdmin) zu:

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

    Das Mitglied PRINCIPAL ist das Hauptkonto, das den Bericht schreibt. Beispiel: user:EMAILoder serviceAccount:SERVICE_ACCOUNT_EMAIL.

  3. Legen Sie den Bucket fest, in dem der Cluster-Zustandsscanner Berichte speichert. Der Bucket muss bereits vorhanden sein, da er vom Cluster-Integritätsscanner nicht automatisch erstellt wird. Sie müssen diesen Befehl nur einmal für jede Umgebung ausführen:

    chs configure storage gcs BUCKET_NAME
    

    Wenn Sie Berichte unter einem Ordnerpräfix im Bucket speichern möchten, hängen Sie das Präfix an den Bucket-Namen an:

    chs configure storage gcs BUCKET_NAME/PREFIX
    

Zustandsscan ausführen

In diesem Abschnitt wird beschrieben, wie Sie prüfen, ob Ihre Knoten inaktiv sind, einen Scan starten und den Fortschritt überwachen.

Prüfen, ob die Zielknoten inaktiv sind

Der Cluster-Integritätsscanner wird nur bei inaktiver Kapazität ausgeführt und beendet oder entfernt Ihre Arbeitslasten nicht automatisch. Bevor Sie einen Scan starten, müssen Sie alle Arbeitslasten, die auf Ihren Zielknoten oder Ihrer Zielinstanz ausgeführt werden, per Drain beenden oder stoppen.

Wenn der Cluster-Integritätsscanner aktive Arbeitslasten auf einem Zielknoten oder einer Zielinstanz erkennt, wird die Kapazität so behandelt:

  • GPU: Der Cluster-Integritätsscanner überspringt die ausgelasteten Knoten und führt den Scan auf den verbleibenden inaktiven Knoten aus.
  • TPU: Wie der Cluster-Integritätsscanner mit ausgelasteter Kapazität umgeht, hängt von der Umgebung ab:
    • GKE-Cluster: TPU-Tests mit mehreren Hosts (tpu-collectives und tpu-network-stress) erfordern ein vollständiges inaktives Slice, während TPU-Tests mit einem einzelnen Host auf einzelnen inaktiven Knoten ausgeführt werden können:
      • Knotenpools mit statischem Slicing (--nodepools oder --nodes): Wenn einige Knoten in einem Pool ausgelastet sind, während Sie die Suite lite oder standard ausführen, protokolliert der Cluster-Integritätsscanner eine Warnung, lässt die Tests mit mehreren Hosts aus und führt die TPU-Tests mit einem einzelnen Host auf den verbleibenden inaktiven Knoten aus.
      • Knotenpools mit dynamischem Slicing (--nodepools oder --nodes): Wenn Sie einen Pool mit --nodepools als Ziel verwenden, muss der gesamte Knotenpool inaktiv sein, damit der Cluster-Integritätsscanner eine Slice-Ressource für den gesamten Pool bereitstellen kann. Wenn Sie mit --nodes (in GKE-Version 1.36.0-gke.3712000 oder höher) bestimmte Knoten anvisieren, stellt der Cluster-Zustandsscanner für jeden inaktiven Knoten ein einzelnes 2x2x1-Sub-Slice bereit, überspringt ausgelastete Knoten und führt TPU-Tests mit einem einzelnen Host auf den inaktiven Knoten aus.
    • Eigenständige TPU-Instanzen: Der Cluster-Zustandsscanner kann nicht ausgeführt werden, wenn ein anderer Prozess die TPU-Geräte unter /dev/vfio verwendet.

Führen Sie die Schritte für Ihre Umgebung aus, um sicherzustellen, dass Ihre Zielkapazität inaktiv ist.

GKE-Cluster

  1. Beenden oder löschen Sie alle aktiven Arbeitslastjobs oder Pods im Zielknotenpool oder warten Sie, bis die laufenden Arbeitslasten abgeschlossen sind.

    Wenn Sie kubectl drain verwenden, um Arbeitslasten aus dem Knotenpool zu entfernen, müssen Sie die Knoten vor dem Start des Scans entsperren, damit der Cluster Health Scanner Diagnose-Pods auf ihnen planen kann. Der Cluster Health Scanner überspringt gesperrte Knoten:

    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
    

    Achten Sie darauf, dass während des Scans keine neuen Arbeitslasten im Knotenpool geplant werden.

  2. Prüfen Sie, ob im Knotenpool keine Arbeitslast-Pods mehr vorhanden sind:

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

    System-Pods, z. B. solche, die von DaemonSets im Namespace kube-system verwaltet werden, können weiterhin ausgeführt werden.

Slurm-Cluster

  1. Prüfen Sie, ob in der Zielpartition Jobs ausgeführt werden:

    squeue --partition=PARTITION_NAME
    

    Wenn Jobs in der Partition ausgeführt werden, warten Sie, bis sie abgeschlossen sind, oder brechen Sie sie mit scancel JOB_ID ab.

  2. Prüfen Sie, ob die Knoten in der Zielpartition den Status idle haben:

    sinfo --partition=PARTITION_NAME
    

Eigenständige TPU-Instanzen

Prüfen Sie, ob keine anderen Prozesse die TPU-Geräte auf der Instanz verwenden:

sudo fuser -v /dev/vfio/*

Wenn Prozesse aufgeführt sind, warten Sie, bis die Arbeitslasten abgeschlossen sind, oder beenden Sie die Prozesse, bevor Sie einen Scan starten.

Scan starten

Die Flags, die Sie an den Befehl chs run übergeben, hängen von der Umgebung ab, in der Sie den Cluster-Integritätsscanner ausführen. Der Cluster-Integritätsscanner erkennt den Planer und den Beschleunigertyp automatisch, sodass Sie sie nicht angeben müssen.

Führen Sie die folgenden Befehle aus, um die verfügbaren Diagnosesuites und Tests für einen Beschleunigertyp aufzulisten:

  • Für GPUs:

    chs list suites --gpu
    chs list tests --gpu
    
  • Für TPUs:

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

GKE-Knotenpools

Führen Sie den Cluster-Zustandsscanner auf einem beliebigen Computer aus, der kubectl-Zugriff auf Ihren Cluster hat, z. B. auf Ihrem lokalen Computer oder in Cloud Shell.

Führen Sie den folgenden Befehl aus, um einen Scan für einen oder mehrere Knotenpools zu starten:

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

Ersetzen Sie Folgendes:

  • NODE_POOL_NAMES: eine durch Kommas getrennte Liste der zu scannenden GPU- oder TPU-Knotenpools. Beispiel: a4-pool-1,a4-pool-2 oder tpu7x-pool-1,tpu7x-pool-2 Alle Zielknotenpools müssen denselben Maschinentyp verwenden.
  • SUITE: Die auszuführende Diagnosesuite, entweder lite oder standard. Weitere Informationen zu den einzelnen Suites finden Sie unter Diagnose-Suites.

Wenn Sie bestimmte Tests anstelle einer vollständigen Suite ausführen möchten, ersetzen Sie das Flag --suite durch das Flag --tests und geben Sie eine durch Kommas getrennte Liste von Testnamen an:

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

Wenn Sie bestimmte Knoten anstelle eines gesamten Knotenpools scannen möchten, ersetzen Sie das Flag --nodepools durch das Flag --nodes und geben Sie eine durch Kommas getrennte Liste von Knotennamen an.

Wenn Sie mehrere Knotenpools im Flag --nodepools angeben, werden sie vom Cluster-Integritätsscanner basierend auf dem Beschleunigertyp verarbeitet:

  • GPU-Knotenpools: Kombiniert alle inaktiven GPU-Knoten in den angegebenen Knotenpools zu einem einzigen Zielsatz und führt Tests mit mehreren Knoten (nccl-cluster und nccl-pairwise) für alle Knoten zusammen aus.
  • TPU-Knotenpools: Jeder Knotenpool (TPU-Slice) wird unabhängig und parallel in einem einzigen Durchlauf ausgewertet, ohne Slice-übergreifende Tests (Multislice).

Slurm-Partitionen

Führen Sie den Cluster-Systemdiagnose-Scanner auf dem Slurm-Controller oder dem Login-Knoten aus, auf dem die Befehle sinfo und sbatch verfügbar sind. Slurm erfordert die Option zur Installation des Python-Pakets. Eine Installationsanleitung finden Sie unter Python-Paket.

Bevor Sie einen Scan starten, konfigurieren Sie Enroot-Anmeldedaten im Cluster, damit die Knoten Benchmark-Images aus us-docker.pkg.dev abrufen können:

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

Starten Sie einen Scan für eine oder mehrere Partitionen:

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

Ersetzen Sie Folgendes:

  • PARTITION_NAMES: eine durch Kommas getrennte Liste der zu scannenden Slurm-Partitionen.
  • SUITE: Die auszuführende Diagnosesuite, entweder lite oder standard. Weitere Informationen zu den einzelnen Suites finden Sie unter Diagnose-Suites.

Wenn Sie bestimmte GPU-Tests anstelle einer vollständigen Suite ausführen möchten, ersetzen Sie das Flag --suite durch das Flag --tests und geben Sie eine durch Kommas getrennte Liste von Testnamen an (z. B. nccl-pairwise,gemm oder nccl-domain):

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

Eigenständige TPU-Instanzen

Führen Sie den Cluster-Zustandsscanner direkt auf der TPU-Instanz aus. Die TPU-Instanz muss ihre TPU-Geräte unter /dev/vfio verfügbar machen. Sie können dies auf der Instanz mit ls /dev/vfio prüfen.

Wenn Sie den Cluster-Zustandsscanner nicht als root-Nutzer ausführen, erhöhen Sie das Memlock-Limit, bevor Sie TPU-Tests ausführen:

ulimit -l unlimited

Führen Sie den folgenden Befehl aus, um einen Scan auf der TPU-Instanz zu starten:

chs run --suite=SUITE

Ersetzen Sie SUITE durch die auszuführende Diagnosesuite, entweder lite oder standard. Weitere Informationen zu den einzelnen Suites finden Sie unter Diagnose-Suites.

Wenn Sie bestimmte TPU-Tests anstelle einer vollständigen Suite ausführen möchten, ersetzen Sie das Flag --suite durch das Flag --tests und geben Sie eine durch Kommas getrennte Liste von Testnamen an (z. B. tpu-host-device,tpu-hbm-stress):

chs run --tests=TEST_NAMES

Ausführungen und Ergebnisse ansehen

Der Cluster-Integritätsscanner speichert den Ausführungsverlauf und die Konfigurationseinstellungen lokal auf dem Clientcomputer, auf dem Sie chs-Befehle ausführen (in ~/.local/share/chs/ oder im Docker-Volume chs-local-state, wenn Sie das Container-Image verwenden). Daher werden mit den Befehlen chs history und chs results nur Ausführungen aufgelistet, die in dieser Umgebung gestartet wurden.

Führen Sie den folgenden Befehl aus, um Ihre vorherigen Ausführungen und deren Ausführungs-IDs aufzulisten:

chs history

Führen Sie den folgenden Befehl aus, um die Ergebnisse für eine Ausführung und die Speicherorte des interaktiven HTML-Berichts (bill_of_health.html) und des JSON-Berichts (bill_of_health.json) anzuzeigen:

chs results RUN_ID

Wenn Sie RUN_ID weglassen, werden Sie vom Cluster-Integritätsscanner aufgefordert, eine Ausführung auszuwählen. Der Befehl gibt lokale Pfade oder Cloud Storage-URIs aus, wenn Sie einen Bucket konfiguriert haben. Dabei werden die gespeicherten Ergebnisse einer früheren Ausführung gelesen und es werden keine neuen Jobs auf Ihrem Cluster oder Ihrer Instanz gestartet.

Scan abbrechen

Wenn Sie einen Scan abbrechen, seine Jobs beenden und die Ressourcen entfernen möchten, die er auf Ihrem Cluster oder Ihrer Instanz erstellt hat, führen Sie einen der folgenden Befehle aus:

  • Letzten Lauf abbrechen:

    chs cancel
    
  • Bestimmte Ausführung abbrechen:

    chs cancel RUN_ID
    
  • Brechen Sie alle Cluster-Integritätsscans ab, die auf dem Cluster oder der Instanz ausgeführt werden, einschließlich der von anderen Nutzern gestarteten Ausführungen:

    chs cancel --all
    

Ergebnisse interpretieren

Wenn ein Scan abgeschlossen ist, speichert der Cluster-Integritätsscanner die folgenden Artefakte in Ihrem lokalen Ausgabeverzeichnis und lädt sie in Ihren Cloud Storage-Bucket hoch, wenn Sie Speicher konfiguriert haben:

  • Interaktiver HTML-Bericht (bill_of_health.html): Zeigt jeden Test, die gemessenen Messwerte und den Status an.
  • JSON-Bericht (bill_of_health.json): enthält die Parameter-Sweeps und die gemessenen Messwerte für jeden Test.
  • Workspace-Verzeichnis: enthält die Diagnoselogs.

Bericht zum Systemzustand ansehen

Führen Sie den folgenden Befehl aus, um die genauen lokalen Pfade oder Cloud Storage-URIs (gs://BUCKET/PREFIX/bills_of_health/RUN_ID.html und gs://BUCKET/PREFIX/bills_of_health/RUN_ID.json) für die Berichte eines Scans zu ermitteln:

chs results RUN_ID

Wenn Sie einen Cloud Storage-Bucket konfiguriert haben, können Sie den JSON-Bericht direkt über den von chs results zurückgegebenen URI aufrufen:

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

Inhalt des Berichts

Im Zustandsbericht werden alle Knoten aufgeführt, die vom Cluster-Zustandsscanner getestet wurden, sowie die Benchmark-Ergebnisse für jeden Knoten. GPU- und TPU-Scans verwenden dasselbe Berichtsformat. Jeder Knoten erhält einen der folgenden Status:

Status Beschreibung
HEALTHY Alle Tests haben die erwartete Leistung für den Maschinentyp erreicht.
DEGRADED Der Knoten hat die Tests abgeschlossen, aber ein oder mehrere Ergebnisse lagen unter der erwarteten Leistung.
POTENTIALLY DEGRADED Ein Screening-Test lag unter der erwarteten Leistung und der entsprechende Belastungstest wurde nicht ausgeführt, um das Ergebnis zu bestätigen.
INCOMPLETE Mindestens ein Test konnte nicht ausgeführt werden, wurde abgebrochen, hat das Zeitlimit überschritten oder hat keine Messwerte auf dem Knoten gemeldet.

Die Datei bill_of_health.json enthält die folgenden Felder auf oberster Ebene:

  • report_id: die eindeutige Kennung für die Scanausführung.
  • chs_version: die Version des Cluster-Zustandsscanners, der den Bericht generiert hat.
  • created_at: der Zeitstempel, der angibt, wann der Bericht generiert wurde.
  • system_info: Metadaten zum getesteten System, z. B. Clustertyp und Maschinentyp.
  • test_results: Eine Liste von Testergebnisobjekten. Jeder Eintrag enthält die folgenden Felder:
    • test_name: der Name des Diagnosetests.
    • result_status: das Ergebnis des Tests, z. B. RESULT_STATUS_SUCCESS oder RESULT_STATUS_FAILED.
    • target_resources: die Knoten (node_name und instance_id), auf denen der Test ausgeführt wurde.
    • metrics: die gemessenen Messwerte und Validierungskriterien für den Test.

Der Zustandsbericht verwendet ein einheitliches, strukturiertes JSON-Format. Sie können Berichte in BigQuery oder andere Analysetools laden und Berichte aus aufeinanderfolgenden Scans derselben Kapazität vergleichen, um eine allmähliche Leistungsabweichung zu erkennen.

Fehlerhafte Knoten korrigieren

Wenn im Zustandsbericht ein Knoten oder eine Instanz mit dem Status DEGRADED, POTENTIALLY DEGRADED oder INCOMPLETE aufgeführt ist, gehen Sie so vor:

  1. Um ein vorübergehendes Problem auszuschließen, führen Sie den Scan auf dem GKE-Knotenpool oder -Knoten, der Slurm-Partition oder der eigenständigen TPU-Instanz noch einmal aus, bevor Sie den Knoten sperren oder leeren. Der Cluster-Integritätsscanner überspringt gesperrte GKE-Knoten und geleerte Slurm-Knoten. Eine Anleitung finden Sie unter Scan starten.

  2. Wenn das Problem weiterhin besteht, verhindern Sie, dass neue Arbeitslasten auf dem betroffenen Knoten oder der betroffenen Instanz geplant werden:

    • GKE-Cluster: Sperren Sie den fehlerhaften Knoten:

      kubectl cordon NODE_NAME
      
    • Slurm-Cluster: Leeren Sie den fehlerhaften Knoten:

      sudo scontrol update NodeName=NODE_NAME State=DRAIN Reason="CHS unhealthy"
      
    • Eigenständige TPU-Instanzen: Starten Sie keine neuen Arbeitslasten auf der TPU-Instanz, bis das Problem behoben ist.

  3. Reparieren oder ersetzen Sie den Knoten oder die Instanz mit einer der folgenden Optionen, je nach Beschleunigertyp und Umgebung:

    Wenn Sie sich an den Support wenden, hängen Sie das Arbeitsbereichsverzeichnis aus Ihrem lokalen Ausgabeverzeichnis oder Cloud Storage-Bucket an, das die Diagnoselogs enthält, und geben Sie die Ausführungs-ID an.

  4. Nachdem der Knoten oder die Instanz repariert oder ersetzt wurde, machen Sie ihn bzw. sie wieder planbar, damit der Cluster-Integritätsscanner ihn bzw. sie nicht überspringt. Führen Sie dann einen neuen Scan aus, um zu bestätigen, dass die Kapazität fehlerfrei ist:

    • GKE-Cluster: Heben Sie die Sperrung des Knotens auf und führen Sie den Scan noch einmal aus, bevor Sie neue Arbeitslasten planen:

      kubectl uncordon NODE_NAME
      
    • Slurm-Cluster: Setzen Sie den Knoten fort, damit er in den Status idle zurückkehrt, und führen Sie den Scan noch einmal aus, bevor Sie neue Jobs planen:

      sudo scontrol update NodeName=NODE_NAME State=RESUME
      
    • Eigenständige TPU-Instanzen: Führen Sie den Scan auf der Instanz noch einmal aus und setzen Sie die Ausführung Ihrer Arbeitslasten fort, sobald der Scan bestätigt, dass die Instanz fehlerfrei ist.

Telemetrie

Der Cluster-Integritätsscanner sendet anonyme Nutzungsmesswerte an Google, um das Tool zu verbessern. Es werden keine personenidentifizierbaren Informationen erfasst. Die Telemetrie ist standardmäßig aktiviert. Wenn Sie die Funktion deaktivieren möchten, führen Sie chs configure telemetry disable aus oder legen Sie die Umgebungsvariable CHS_TELEMETRY=0 fest.

Nächste Schritte

Informationen zur Behebung häufiger Probleme mit dem Cluster-Zustandsscanner finden Sie unter Fehlerbehebung für den Cluster-Zustandsscanner.