Ce document décrit les problèmes courants liés au scanner d'état du cluster et explique comment les résoudre.
L'analyse ignore des nœuds ou s'arrête, car des charges de travail actives ont été détectées
Problème : l'analyse ignore certains nœuds GPU ou s'arrête lors des vérifications préalables d'un pool de nœuds TPU, et signale que des charges de travail actives ont été détectées.
Cause : un ou plusieurs nœuds cibles exécutent des charges de travail.
Résolution : drainez ou arrêtez les charges de travail sur les nœuds cibles, puis relancez l'analyse. Pour en savoir plus, consultez Vérifier que les nœuds cibles sont inactifs.
L'analyse s'arrête en raison de types de machines mixtes
Problème : l'analyse s'arrête lors des vérifications préalables et indique que les nœuds cibles utilisent différents types de machines.
Cause : Les pools de nœuds que vous avez spécifiés dans l'option --nodepools ou les partitions que vous avez spécifiées dans l'option --partitions n'utilisent pas tous le même type de machine. Par exemple, une seule analyse ne peut pas combiner des pools de nœuds GPU et TPU, ni des nœuds A3 Mega et A4.
Solution : exécutez une analyse distincte pour chaque type de machine.
L'analyse s'arrête en raison d'une erreur d'autorisation de stockage
Problème : l'analyse s'arrête lors des vérifications préalables et signale une erreur Cloud Storage.
Cause : Le bucket n'existe pas ou le compte principal qui écrit le rapport n'est pas autorisé à écrire dans le bucket.
Résolution : vérifiez que le bucket existe et que le compte principal dispose du rôle "Administrateur des objets Storage" sur le bucket. Pour en savoir plus, consultez Configurer un bucket Cloud Storage pour les rapports.
L'outil de ligne de commande ne peut pas se connecter au cluster
Problème : l'outil de ligne de commande chs renvoie une erreur d'authentification ou de connexion.
Cause : l'entrée kubeconfig du cluster est manquante ou vos identifiants ne sont pas disponibles dans le conteneur.
Solution : exécutez la commande gcloud container clusters get-credentials, comme décrit dans Se connecter à votre cluster ou à votre instance. Vérifiez ensuite que votre fichier kubeconfig et vos identifiants Google Cloud sont installés dans le conteneur, comme décrit dans Installer l'outil d'analyse de l'état du cluster.
L'appelant n'est pas autorisé à accéder au projet
Problème : une commande chs renvoie l'erreur suivante :
ERROR: The caller doesn't have permission to access the project PROJECT_ID
Cause : vos identifiants sont manquants ou ont expiré, ou l'identité active ne dispose pas des autorisations IAM (Identity and Access Management) requises sur le projet.
Résolution : Configurez les Identifiants par défaut de l'application avec votre compte utilisateur :
gcloud auth application-default login
Si vous devez également authentifier la Google Cloud CLI avec votre compte utilisateur plutôt qu'avec un compte de service, exécutez la commande suivante :
gcloud auth login --no-browser
Les tests de GPU signalent des erreurs de pilote ou de matériel
Problème : Le rapport d'état affiche l'état DEGRADED ou INCOMPLETE pour certains nœuds après l'exécution du test nvidia-smi ou dcgm.
Cause : Un GPU sur le nœud n'est pas détecté, le pilote du GPU ne fonctionne pas ou le gestionnaire de GPU du centre de données (DCGM) NVIDIA a détecté une défaillance matérielle.
Résolution : examinez les journaux de diagnostic dans le répertoire de l'espace de travail de votre répertoire de sortie local ou de votre bucket Cloud Storage. Suivez ensuite la procédure correspondant à votre environnement dans Corriger les nœuds non opérationnels.
Les tests réseau indiquent une bande passante faible ou une latence élevée
Problème : Le rapport d'état indique une faible bande passante de communication collective ou une latence élevée pour certains nœuds.
Cause : sur les GPU, ce problème est dû à un GPU, une connexion NVLink ou une interface réseau défectueux sur un ou plusieurs nœuds. Sur les TPU, cela est dû à une liaison ICI ou à une puce TPU défectueuse sur un ou plusieurs nœuds.
Résolution : pour les GPU, utilisez les résultats du test nccl-pairwise pour identifier les nœuds impliqués dans les paires de nœuds lents. Pour les TPU, examinez les résultats tpu-collectives et tpu-network-stress dans le rapport d'état. Suivez ensuite les étapes correspondant à votre environnement dans Remédier aux problèmes des nœuds non opérationnels.
Les ressources restent sur le cluster après l'arrêt d'une analyse
Problème : Les tâches ou ressources de diagnostic restent sur votre cluster Google Kubernetes Engine (GKE) après l'arrêt du processus chs.
Cause : Sur GKE, le processus chs doit rester en cours d'exécution pendant toute la durée d'une analyse pour nettoyer les ressources une fois l'analyse terminée.
Résolution : Annulez l'exécution arrêtée ou toutes les exécutions sur le cluster pour supprimer les jobs restants et libérer les nœuds :
chs cancel RUN_ID
Pour annuler toutes les exécutions sur le cluster, exécutez chs cancel --all.
Échec de l'analyse sur une instance TPU autonome lorsque les TPU sont occupés
Problème : Lorsque vous exécutez une analyse sur une instance TPU autonome, l'outil de ligne de commande chs renvoie une erreur TPUs are busy.
Cause : un autre processus de l'instance TPU utilise les appareils TPU.
Résolution : attendez que l'autre processus se termine ou arrêtez-le, puis relancez l'analyse.
L'analyse échoue avec une erreur de limite de memlock sur une instance TPU autonome
Problème : Lorsque vous exécutez une analyse sur une instance TPU autonome, l'outil de ligne de commande chs indique que la limite de memlock est trop faible ou que les tests TPU nécessitent root ou une limite de memlock illimitée.
Cause : La session utilisateur actuelle dispose d'une limite d'espace d'adressage verrouillé en mémoire (memlock) restreinte.
Résolution : exécutez l'outil d'analyse de l'état du cluster en tant qu'utilisateur root ou augmentez la limite de memlock avant d'exécuter l'analyse :
ulimit -l unlimited
Échec du conteneur sur une instance TPU autonome sans accès à l'hôte
Problème : Lorsque vous exécutez une analyse sur une instance TPU autonome à l'aide de l'image de conteneur, l'outil de ligne de commande chs échoue avec l'erreur suivante :
CHS runs in a container without access to the host
Cause : En mode autonome sur une instance TPU, le conteneur doit partager l'espace de noms PID de l'hôte et installer le système de fichiers hôte pour inspecter et utiliser les appareils TPU sous /dev/vfio.
Résolution : Démarrez le conteneur avec les options --privileged, --pid=host et -v /:/host. Pour obtenir la commande docker run complète, consultez Image de conteneur.
Échec de l'installation du package avec une erreur de version Python
Problème : l'exécution de pip install échoue avec l'erreur Package 'chs' requires a
different Python.
Cause : La version de python3 sur votre machine est antérieure à la version 3.12, ce qui est courant sur les nœuds de connexion Slurm et les instances TPU.
Solution : utilisez uv pour créer un environnement virtuel Python 3.12 et installer l'outil d'analyse de l'état du cluster sans droits 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
L'analyse ignore une instance TPU autonome, car les dépendances de test TPU ne sont pas installées
Problème : Lorsque vous exécutez une analyse sur une instance TPU autonome, chs run ignore l'instance et renvoie l'avertissement suivant :
The TPU test dependencies are not installed. CHS installs them only on Linux x86_64 with Python 3.12.
Cause : Le package Python de l'outil d'analyse de l'état du cluster a été installé avec une version de Python autre que la version 3.12 (par exemple, Python 3.13). Sur les instances TPU autonomes, les dépendances de benchmark TPU ne sont installées que sur Linux x86_64 avec Python 3.12.
Résolution : Réinstallez l'outil d'analyse de l'état du cluster dans un environnement virtuel Python 3.12 à l'aide de uv (voir Échec de l'installation du package avec une erreur de version de Python) ou utilisez l'image de conteneur de l'outil d'analyse de l'état du cluster.