클러스터 상태 스캐너 문제 해결

이 문서에서는 클러스터 상태 스캐너의 일반적인 문제와 해결 방법을 설명합니다.

활성 워크로드가 감지되어 스캔이 노드를 건너뛰거나 중지됨

문제: 스캔이 일부 GPU 노드를 건너뛰거나 TPU 노드 풀의 사전 점검 중에 중지되고 활성 워크로드가 감지되었다고 보고합니다.

원인: 하나 이상의 대상 노드에서 워크로드를 실행 중입니다.

해결 방법: 대상 노드에서 워크로드를 드레이닝하거나 중지한 후 스캔을 다시 실행합니다. 자세한 내용은 대상 노드가 유휴 상태인지 확인을 참조하세요.

혼합 머신 유형으로 인해 스캔이 중지됨

문제: 사전 점검 중에 스캔이 중지되고 대상 노드가 다른 머신 유형을 사용한다고 보고합니다.

원인: --nodepools 플래그에 지정한 노드 풀 또는 --partitions 플래그에 지정한 파티션이 모두 동일한 머신 유형을 사용하지 않습니다. 예를 들어 단일 스캔에서 GPU 및 TPU 노드 풀 또는 A3 Mega 및 A4 노드를 혼합할 수 없습니다.

해결 방법: 머신 유형별로 별도의 스캔을 실행합니다.

저장용량 권한 오류로 인해 스캔이 중지됨

문제: 사전 점검 중에 스캔이 중지되고 Cloud Storage 오류가 보고됩니다.

원인: 버킷이 없거나 보고서를 작성하는 주 구성원에게 버킷에 쓸 수 있는 권한이 없습니다.

해결 방법: 버킷이 존재하고 주 구성원에게 버킷에 대한 스토리지 객체 관리자 역할이 있는지 확인합니다. 자세한 내용은 보고서용 Cloud Storage 버킷 설정을 참조하세요.

명령줄 도구가 클러스터에 연결할 수 없음

문제: chs 명령줄 도구에서 인증 또는 연결 오류를 반환합니다.

원인: 클러스터의 kubeconfig 항목이 누락되었거나 컨테이너 내에서 사용자 인증 정보를 사용할 수 없습니다.

해결 방법: 클러스터 또는 인스턴스에 연결에 설명된 대로 gcloud container clusters get-credentials 명령어를 실행합니다. 그런 다음 클러스터 상태 스캐너 설치에 설명된 대로 kubeconfig 파일과 Google Cloud 사용자 인증 정보가 컨테이너에 마운트되었는지 확인합니다.

호출자에게 프로젝트에 액세스할 수 있는 권한이 없습니다.

문제: chs 명령어가 다음 오류를 반환합니다.

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

원인: 사용자 인증 정보가 누락되었거나 만료되었거나 활성 ID에 프로젝트에 필요한 Identity and Access Management(IAM) 권한이 없습니다.

해결 방법: 사용자 계정으로 애플리케이션 기본 사용자 인증 정보를 설정합니다.

gcloud auth application-default login

서비스 계정이 아닌 사용자 계정으로 Google Cloud CLI를 인증해야 하는 경우 다음 명령어를 실행합니다.

gcloud auth login --no-browser

GPU 테스트에서 드라이버 또는 하드웨어 오류를 보고함

문제: nvidia-smi 또는 dcgm 테스트가 실행된 후 상태 보고서에 일부 노드의 DEGRADED 또는 INCOMPLETE 상태가 표시됩니다.

원인: 노드의 GPU가 감지되지 않거나, GPU 드라이버가 작동하지 않거나, NVIDIA Data Center GPU Manager(DCGM)에서 하드웨어 오류를 감지했습니다.

해결 방법: 로컬 출력 디렉터리 또는 Cloud Storage 버킷의 작업공간 디렉터리에 있는 진단 로그를 검토합니다. 그런 다음 비정상 노드 해결에서 환경에 해당하는 단계를 따릅니다.

네트워크 테스트에서 대역폭이 낮거나 지연 시간이 길다고 보고함

문제: 상태 보고서에 일부 노드의 집합 통신 대역폭이 낮거나 지연 시간이 긴 것으로 표시됩니다.

원인: GPU에서 이 문제는 하나 이상의 노드에 있는 결함이 있는 GPU, NVLink 연결 또는 네트워크 인터페이스로 인해 발생합니다. TPU에서는 하나 이상의 노드에 있는 결함이 있는 ICI 링크 또는 TPU 칩으로 인해 발생합니다.

해결 방법: GPU의 경우 nccl-pairwise 테스트 결과를 사용하여 느린 노드 쌍에 관련된 노드를 식별합니다. TPU의 경우 상태 보고서에서 tpu-collectives 및 tpu-network-stress 결과를 검토합니다. 그런 다음 비정상 노드 해결에서 환경에 맞는 단계를 따릅니다.

스캔이 중지된 후에도 리소스가 클러스터에 남아 있음

문제: chs 프로세스가 종료된 후 Google Kubernetes Engine(GKE) 클러스터에 진단 작업 또는 리소스가 남아 있습니다.

원인: GKE에서 스캔이 완료되면 리소스를 삭제하기 위해 스캔 기간 동안 chs 프로세스가 계속 실행되어야 합니다.

해결 방법: 중지된 실행 또는 클러스터의 모든 실행을 취소하여 남은 작업을 삭제하고 노드를 해제합니다.

chs cancel RUN_ID

클러스터의 모든 실행을 취소하려면 chs cancel --all를 실행합니다.

TPU가 사용 중일 때 독립형 TPU 인스턴스에서 스캔이 실패함

문제: 독립형 TPU 인스턴스에서 스캔을 실행하면 chs 명령줄 도구에서 TPUs are busy 오류를 반환합니다.

원인: TPU 인스턴스의 다른 프로세스가 TPU 기기를 사용하고 있습니다.

해결 방법: 다른 프로세스가 완료될 때까지 기다리거나 프로세스를 중지한 후 스캔을 다시 실행합니다.

독립형 TPU 인스턴스에서 memlock 한도 오류로 인해 스캔이 실패함

문제: 독립형 TPU 인스턴스에서 스캔을 실행하면 chs 명령줄 도구에서 memlock 한도가 너무 낮거나 TPU 테스트에 root 또는 무제한 memlock 한도가 필요하다고 보고합니다.

원인: 현재 사용자 세션에 제한된 메모리 고정 주소 공간(memlock) 한도가 있습니다.

해결 방법: 클러스터 상태 스캐너를 root 사용자로 실행하거나 스캔을 실행하기 전에 memlock 한도를 높입니다.

ulimit -l unlimited

호스트에 액세스할 수 없는 독립형 TPU 인스턴스에서 컨테이너가 실패함

문제: 컨테이너 이미지를 사용하여 독립형 TPU 인스턴스에서 스캔을 실행하면 chs 명령줄 도구가 다음 오류와 함께 실패합니다.

CHS runs in a container without access to the host

원인: TPU 인스턴스의 독립형 모드에서 컨테이너는 호스트 PID 네임스페이스를 공유하고 호스트 파일 시스템을 마운트하여 /dev/vfio에서 TPU 기기를 검사하고 사용해야 합니다.

해결 방법: --privileged, --pid=host, -v /:/host 플래그를 사용하여 컨테이너를 시작합니다. 전체 docker run 명령어는 컨테이너 이미지를 참조하세요.

Python 버전 오류로 인해 패키지 설치가 실패함

문제: pip install를 실행하면 Package 'chs' requires a different Python 오류가 발생합니다.

원인: 머신의 python3 버전이 3.12 이전 버전입니다. 이는 Slurm 로그인 노드 및 TPU 인스턴스에서 일반적입니다.

해결 방법: uv를 사용하여 Python 3.12 가상 환경을 만들고 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

TPU 테스트 종속 항목이 설치되지 않아 스캔에서 독립형 TPU 인스턴스를 건너뜀

문제: 독립형 TPU 인스턴스에서 스캔을 실행하면 chs run에서 인스턴스를 건너뛰고 다음 경고를 반환합니다.

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

원인: 클러스터 상태 스캐너 Python 패키지가 3.12 이외의 Python 버전(예: Python 3.13)으로 설치되었습니다. 독립형 TPU 인스턴스에서 TPU 벤치마크 종속 항목은 Python 3.12를 사용하는 Linux x86_64에만 설치됩니다.

해결 방법: uv를 사용하여 Python 3.12 가상 환경에 클러스터 상태 스캐너를 다시 설치하거나(Python 버전 오류로 인해 패키지 설치 실패 참조) 클러스터 상태 스캐너 컨테이너 이미지를 사용합니다.