Soluciona problemas del escáner de estado del clúster

En este documento, se describen los problemas habituales con el escáner de estado del clúster y cómo resolverlos.

La exploración omite nodos o se detiene porque se detectaron cargas de trabajo activas

Problema: El análisis omite algunos nodos de GPU o se detiene durante las verificaciones preliminares de un grupo de nodo TPU y, además, informa que se detectaron cargas de trabajo activas.

Causa: Uno o más nodos de destino ejecutan cargas de trabajo.

Resolución: Desvía o detén las cargas de trabajo en los nodos de destino y, luego, vuelve a ejecutar el análisis. Para obtener más información, consulta Verifica que los nodos de destino estén inactivos.

La exploración se detiene debido a tipos de máquinas mixtos

Problema: El análisis se detiene durante las verificaciones preliminares y se informa que los nodos de destino usan diferentes tipos de máquinas.

Causa: Los grupos de nodos que especificaste en la marca --nodepools o las particiones que especificaste en la marca --partitions no usan el mismo tipo de máquina. Por ejemplo, un solo análisis no puede mezclar grupos de nodos de GPU y TPU, ni nodos A3 Mega y A4.

Resolución: Ejecuta un análisis independiente para cada tipo de máquina.

El escaneo se detiene debido a un error de permiso de almacenamiento

Problema: El análisis se detiene durante las verificaciones preliminares y se informa un error de Cloud Storage.

Causa: El bucket no existe o la principal que escribe el informe no tiene permiso para escribir en el bucket.

Resolución: Verifica que el bucket exista y que la principal tenga el rol de administrador de objetos de almacenamiento en el bucket. Para obtener más información, consulta Configura un bucket de Cloud Storage para los informes.

La herramienta de línea de comandos no se puede conectar al clúster

Problema: La herramienta de línea de comandos de chs devuelve un error de autenticación o conexión.

Causa: Falta la entrada kubeconfig del clúster o tus credenciales no están disponibles dentro del contenedor.

Resolución: Ejecuta el comando gcloud container clusters get-credentials, como se describe en Conéctate a tu clúster o instancia. Luego, verifica que el archivo kubeconfig y las credenciales de Google Cloud estén activados en el contenedor, como se describe en Instala el analizador de estado del clúster.

El emisor no tiene permiso para acceder al proyecto

Problema: Un comando chs devuelve el siguiente error:

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

Causa: Faltan tus credenciales o vencieron, o la identidad activa no tiene los permisos de Identity and Access Management (IAM) necesarios en el proyecto.

Resolución: Configura las credenciales predeterminadas de la aplicación con tu cuenta de usuario:

gcloud auth application-default login

Si también necesitas autenticar Google Cloud CLI con tu cuenta de usuario en lugar de una cuenta de servicio, ejecuta el siguiente comando:

gcloud auth login --no-browser

Las pruebas de GPU informan errores de hardware o del controlador

Problema: El informe de estado de salud muestra un estado DEGRADED o INCOMPLETE para algunos nodos después de que se ejecutan las ejecuciones de prueba nvidia-smi o dcgm.

Causa: No se detecta una GPU en el nodo, el controlador de GPU no funciona o el administrador de GPU del centro de datos de NVIDIA (DCGM) detectó una falla de hardware.

Resolución: Revisa los registros de diagnóstico en el directorio del lugar de trabajo de tu directorio de salida local o bucket de Cloud Storage. Luego, sigue los pasos para tu entorno en Corrige los nodos en mal estado.

Las pruebas de red informan un ancho de banda bajo o una latencia alta

Problema: El informe de estado muestra un ancho de banda de comunicación colectiva bajo o una latencia alta para algunos nodos.

Causa: En las GPU, esto se debe a una GPU, una conexión de NVLink o una interfaz de red defectuosas en uno o más nodos. En las TPU, esto se debe a un vínculo de ICI o un chip TPU defectuoso en uno o más nodos.

Resolución: En el caso de las GPU, usa los resultados de la prueba nccl-pairwise para identificar qué nodos están involucrados en los pares de nodos lentos. En el caso de las TPU, revisa los resultados de tpu-collectives y tpu-network-stress en el informe de estado. Luego, sigue los pasos para tu entorno en Corrige los nodos en mal estado.

Los recursos permanecen en el clúster después de que se detiene un análisis

Problema: Los trabajos o recursos de diagnóstico permanecen en tu clúster de Google Kubernetes Engine (GKE) después de que se finalizó el proceso chs.

Causa: En GKE, el proceso chs debe permanecer en ejecución durante un análisis para limpiar los recursos cuando finalice.

Resolución: Cancela la ejecución detenida o todas las ejecuciones en el clúster para quitar los trabajos restantes y liberar los nodos:

chs cancel RUN_ID

Para cancelar todas las ejecuciones en el clúster, ejecuta chs cancel --all.

La exploración falla en una instancia de TPU independiente cuando las TPU están ocupadas

Problema: Cuando ejecutas un análisis en una instancia de TPU independiente, la herramienta de línea de comandos de chs devuelve un error TPUs are busy.

Causa: Otro proceso en la instancia de TPU está usando los dispositivos de TPU.

Resolución: Espera a que finalice el otro proceso o detenlo y, luego, vuelve a ejecutar el análisis.

La exploración falla con un error de límite de memlock en una instancia de TPU independiente

Problema: Cuando ejecutas un análisis en una instancia de TPU independiente, la herramienta de línea de comandos de chs informa que el límite de memlock es demasiado bajo o que las pruebas de TPU requieren root o un límite de memlock ilimitado.

Causa: La sesión del usuario actual tiene un límite de espacio de direcciones restringido y bloqueado en la memoria (memlock).

Solución: Ejecuta el análisis de estado del clúster como el usuario root o aumenta el límite de memlock antes de ejecutar el análisis:

ulimit -l unlimited

El contenedor falla en una instancia de TPU independiente sin acceso al host

Problema: Cuando ejecutas un análisis en una instancia de TPU independiente con la imagen de contenedor, la herramienta de línea de comandos de chs falla con el siguiente error:

CHS runs in a container without access to the host

Causa: En el modo independiente en una instancia de TPU, el contenedor debe compartir el espacio de nombres del PID del host y activar el sistema de archivos del host para inspeccionar y usar los dispositivos TPU en /dev/vfio.

Resolución: Inicia el contenedor con las marcas --privileged, --pid=host y -v /:/host. Para obtener el comando docker run completo, consulta Imagen de contenedor.

La instalación del paquete falla con un error de versión de Python

Problema: La ejecución de pip install falla con el error: Package 'chs' requires a different Python.

Causa: La versión de python3 en tu máquina es anterior a la 3.12, lo que es común en los nodos de acceso de Slurm y las instancias de TPU.

Resolución: Usa uv para crear un entorno virtual de Python 3.12 y, luego, instala el analizador de estado del clúster sin privilegios de 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

El análisis omite una instancia de TPU independiente porque no se instalaron las dependencias de prueba de TPU

Problema: Cuando ejecutas un análisis en una instancia de TPU independiente, chs run omite la instancia y devuelve la siguiente advertencia:

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

Causa: El paquete de Python del escáner de estado del clúster se instaló con una versión de Python distinta de la 3.12 (por ejemplo, Python 3.13). En las instancias de TPU independientes, las dependencias de comparativas de TPU solo se instalan en Linux x86_64 con Python 3.12.

Resolución: Reinstala el analizador de estado del clúster en un entorno virtual de Python 3.12 con uv (consulta La instalación del paquete falla con un error de versión de Python) o usa la imagen de contenedor del analizador de estado del clúster.