Neste documento, descrevemos problemas comuns com o verificador de integridade do cluster e como resolvê-los.
A verificação ignora nós ou é interrompida porque cargas de trabalho ativas foram detectadas
Problema: a verificação ignora alguns nós de GPU ou é interrompida durante as verificações prévias de um pool de nós de TPU e informa que cargas de trabalho ativas foram detectadas.
Causa: um ou mais nós de destino estão executando cargas de trabalho.
Resolução: drene ou interrompa as cargas de trabalho nos nós de destino e execute novamente a verificação. Para mais informações, consulte Verificar se os nós de destino estão ociosos.
A verificação é interrompida devido a tipos de máquina mistos
Problema: a verificação é interrompida durante as verificações prévias e informa que os nós de destino usam tipos de máquina diferentes.
Causa: os pools de nós especificados na flag --nodepools ou as partições especificadas na flag --partitions não usam o mesmo tipo de máquina. Por exemplo, uma única verificação não pode misturar pools de nós de GPU e TPU ou nós A3
Mega e A4.
Resolução: execute uma verificação separada para cada tipo de máquina.
A verificação é interrompida devido a um erro de permissão de armazenamento
Problema: a verificação é interrompida durante as verificações prévias e informa um erro do Cloud Storage.
Causa: o bucket não existe ou o principal que grava o relatório não tem permissão para gravar no bucket.
Resolução: verifique se o bucket existe e se o principal tem o papel de Administrador de objetos do Storage no bucket. Para mais informações, consulte Configurar um bucket do Cloud Storage para relatórios.
A ferramenta de linha de comando não consegue se conectar ao cluster
Problema: a ferramenta de linha de comando chs retorna um erro de autenticação ou conexão.
Causa: a entrada kubeconfig do cluster está ausente ou suas credenciais não estão disponíveis no contêiner.
Resolução: execute o comando gcloud container clusters get-credentials, conforme
descrito em Conectar-se ao cluster ou à
instância. Em seguida,
verifique se o arquivo kubeconfig e as credenciais Google Cloud estão montados no
contêiner, conforme descrito em Instalar o verificador de integridade do
cluster.
O autor da chamada não tem permissão para acessar o projeto
Problema: um comando chs retorna o seguinte erro:
ERROR: The caller doesn't have permission to access the project PROJECT_ID
Causa: suas credenciais estão ausentes ou expiraram, ou a identidade ativa não tem as permissões necessárias do Identity and Access Management (IAM) no projeto.
Resolução: configure o Application Default Credentials com sua conta de usuário:
gcloud auth application-default login
Se você também precisar autenticar a Google Cloud CLI com sua conta de usuário, em vez de uma conta de serviço, execute o seguinte comando:
gcloud auth login --no-browser
Os testes de GPU relatam erros de driver ou hardware
Problema: o relatório de integridade mostra um status DEGRADED ou INCOMPLETE para alguns
nós após as execuções de teste nvidia-smi ou dcgm.
Causa: uma GPU no nó não foi detectada, o driver da GPU não está funcionando ou o NVIDIA Data Center GPU Manager (DCGM) detectou uma falha de hardware.
Resolução: revise os registros de diagnóstico no diretório do espaço de trabalho do seu diretório de saída local ou bucket do Cloud Storage. Em seguida, siga as etapas para seu ambiente em Corrigir nós não íntegros.
Os testes de rede relatam baixa largura de banda ou alta latência
Problema: o relatório de integridade mostra uma baixa largura de banda de comunicação coletiva ou alta latência para alguns nós.
Causa: em GPUs, isso é causado por uma GPU, conexão NVLink ou interface de rede com defeito em um ou mais nós. Nas TPUs, isso é causado por um link de ICI ou chip de TPU com defeito em um ou mais nós.
Resolução: para GPUs, use os resultados do teste nccl-pairwise para identificar quais
nós estão envolvidos nos pares de nós lentos. Para TPUs, analise os resultados de tpu-collectives e tpu-network-stress no relatório de integridade. Em seguida,
siga as etapas do seu ambiente em Corrigir nós
não íntegros.
Os recursos permanecem no cluster após a interrupção de uma verificação
Problema: os jobs ou recursos de diagnóstico permanecem no cluster do Google Kubernetes Engine (GKE) após o encerramento do processo chs.
Causa: no GKE, o processo chs precisa continuar em execução durante
uma verificação para limpar os recursos quando ela for concluída.
Resolução: cancele a execução interrompida ou todas as execuções no cluster para remover jobs restantes e liberar os nós:
chs cancel RUN_ID
Para cancelar todas as execuções no cluster, execute chs cancel --all.
A verificação falha em uma instância de TPU independente quando as TPUs estão ocupadas
Problema: ao executar uma verificação em uma instância de TPU independente, a ferramenta de linha de comando chs retorna um erro TPUs are busy.
Causa: outro processo na instância da TPU está usando os dispositivos de TPU.
Resolução: aguarde a conclusão do outro processo ou interrompa-o e, em seguida, execute a verificação novamente.
A verificação falha com um erro de limite de memlock em uma instância de TPU independente
Problema: ao executar uma verificação em uma instância de TPU independente, a ferramenta de linha de comando chs informa que o limite de memlock é muito baixo ou que os testes de TPU exigem root ou um limite de memlock ilimitado.
Causa: a sessão do usuário atual tem um limite restrito de espaço de endereço bloqueado na memória (memlock).
Resolução: execute o verificador de integridade do cluster como o usuário root ou aumente o
limite de memlock antes de executar a verificação:
ulimit -l unlimited
O contêiner falha em uma instância de TPU independente sem acesso ao host
Problema: ao executar uma verificação em uma instância de TPU independente usando a
imagem do contêiner, a ferramenta de linha de comando chs falha com o seguinte erro:
CHS runs in a container without access to the host
Causa: no modo independente em uma instância de TPU, o contêiner precisa compartilhar o
namespace do PID do host e montar o sistema de arquivos do host para inspecionar e usar os dispositivos
de TPU em /dev/vfio.
Resolução: inicie o contêiner com as flags --privileged, --pid=host e
-v /:/host. Para ver o comando docker run completo, consulte Imagem de contêiner.
A instalação do pacote falha com um erro de versão do Python
Problema: a execução de pip install falha com o erro: Package 'chs' requires a
different Python.
Causa: a versão do python3 na sua máquina é anterior à 3.12, o que é
comum em nós de login do Slurm e instâncias de TPU.
Resolução: use uv para criar um ambiente virtual do Python 3.12 e instalar
o verificador de integridade do cluster sem privilégios 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
A verificação ignora uma instância de TPU independente porque as dependências de teste de TPU não estão instaladas
Problema: quando você executa uma verificação em uma instância de TPU independente, o chs run pula a
instância e retorna o seguinte aviso:
The TPU test dependencies are not installed. CHS installs them only on Linux x86_64 with Python 3.12.
Causa: o pacote Python do verificador de integridade do cluster foi instalado com uma versão do Python diferente da 3.12 (por exemplo, Python 3.13). Em instâncias de TPU independentes,
as dependências de comparativo de mercado de TPU são instaladas apenas no Linux x86_64 com o Python
3.12.
Resolução: reinstale o verificador de integridade do cluster em um ambiente virtual do Python 3.12 usando uv (consulte A instalação do pacote falha com um erro de versão do Python) ou use a imagem de contêiner do verificador de integridade do cluster.