클러스터 상태 스캐너는 워크로드를 예약하기 전에 GPU 및 Cloud TPU 용량의 준비 상태를 검증하는 셀프 서비스 진단 도구입니다. 클러스터 상태 스캐너는 가속기 노드에서 실제 워크로드 트래픽을 시뮬레이션하는 벤치마크를 실행하여 가속기, 메모리, 상호 연결의 성능을 측정합니다. 이 결과를 사용하여 결함이 있는 노드가 학습 또는 추론 작업의 응답 중지, 느린 실행 또는 실패를 유발하기 전에 이를 식별하고 삭제할 수 있습니다.
TPU의 경우 클러스터 상태 스캐너는 하드웨어 상태 신호를 지속적으로 보고하는 TPU 상태 모니터링을 보완합니다. 클러스터 상태 스캐너는 유휴 용량에서 워크로드를 적극적으로 실행하여 성능을 측정하고 부하가 있을 때만 나타나는 오류를 노출합니다.
클러스터 상태 스캐너는 완전한 오픈소스입니다. 소스 코드를 보거나, 참여하거나, 문제를 신고하려면 클러스터 상태 스캐너 GitHub 저장소를 참조하세요.
이 문서에서는 클러스터 상태 스캐너를 설치하고, GPU 및 TPU 예약에서 상태 스캔을 실행하고, 결과를 해석하고, 비정상 노드를 해결하는 방법을 설명합니다.
지원되는 환경
클러스터 상태 스캐너는 다음 배포 환경을 지원합니다.
| 환경 | 지원되는 가속기 | 클라이언트 환경 | 설치 옵션 |
|---|---|---|---|
| Google Kubernetes Engine(GKE) 클러스터 | GPU 및 TPU(정적 또는 동적 슬라이싱을 사용하는 노드 풀) | 대상 클러스터에 대한 kubectl 액세스 권한이 있는 Linux 머신 |
Python 패키지 또는 컨테이너 이미지 |
| Slurm 클러스터 | GPU만 | sinfo 및 sbatch 명령어를 사용할 수 있는 Slurm 컨트롤러 또는 로그인 노드 |
Python 패키지만 해당 |
| 독립형 TPU 인스턴스 | TPU만 해당 | TPU 인스턴스 자체 | Python 패키지 또는 컨테이너 이미지(Container-Optimized OS) |
클러스터 상태 스캐너는 다음 GPU 및 TPU 머신 유형을 지원합니다.
- GPU 머신 유형:
- TPU 머신 유형:
진단 도구
클러스터 상태 스캐너를 Python 패키지 또는 컨테이너 이미지로 설치할 수 있습니다. 두 옵션 모두 chs 명령줄 인터페이스(CLI)와 진단 벤치마크를 제공합니다. GKE 클러스터에 액세스할 수 있는 머신, Slurm 컨트롤러 또는 로그인 노드에서 또는 독립형 TPU 인스턴스에서 직접 CLI를 실행합니다. 그러면 CLI가 대상 GPU 또는 TPU 노드에서 진단 테스트를 실행합니다.
클러스터 상태 스캐너는 각 가속기 유형에 대해 두 가지 진단 도구를 제공합니다.
- 라이트: 빠른 선별 검사를 실행합니다. GPU 및 독립형 TPU 인스턴스에서 Lite 제품군은 개별 호스트를 확인합니다. GKE TPU 노드 풀에서는 TPU 슬라이스 전반에서 빠른 집합적 검사(
tpu-collectives)도 실행합니다. 수집 작업은 모든 가속기가 데이터를 교환하는 통신 패턴입니다(예:AllReduce). 이 작업은 모든 가속기의 값을 결합하고 결과를 모든 가속기와 공유합니다. 빠른 상태 점검을 수행하거나 단일 호스트 워크로드를 실행하기 전에 Lite 제품군을 사용하세요. - 표준: 타겟 용량 전반에 걸쳐 포괄적인 검증을 실행합니다. GPU에서 표준 제품군은 여러 노드에서 집단 작업을 실행하고 GPU 메모리 대역폭을 측정합니다. TPU에서는 모든 라이트 테스트와 지속적인 컴퓨팅, 메모리, 네트워크 스트레스 테스트를 실행합니다. 지속적인 부하에서 네트워크 성능과 안정성이 작업 성능에 직접적인 영향을 미치는 멀티 호스트 학습 또는 추론 워크로드를 실행하기 전에 표준 제품군을 사용하세요.
| Suite | 가속기 | 테스트 | 포커스 |
|---|---|---|---|
lite |
GPU | nvidia-smi, dcgm, gemm, nccl-single-node |
GPU 및 드라이버 상태, 컴퓨팅 처리량, 노드 내 GPU 통신을 빠르게 검증합니다. |
| TPU | tpu-info, tpu-gemm, tpu-hbm, tpu-host-device, tpu-collectives |
기기 상태, 컴퓨팅 처리량, 고대역폭 메모리(HBM) 대역폭, 호스트-기기 대역폭, 칩 간 상호 연결(ICI) 집합 대역폭을 빠르게 검증합니다. | |
standard |
GPU | nvidia-smi, dcgm, gemm, nccl-cluster, nccl-pairwise, stream |
대상 노드 전반의 다중 노드 네트워크 검증 및 메모리 대역폭 |
| TPU | 모든 TPU lite 테스트, tpu-compute-stress, tpu-hbm-stress, tpu-network-stress |
불안정성, 자동 데이터 손상, ICI 비트 오류를 노출하는 지속적인 스트레스 테스트 |
nccl-domain GPU 테스트는 모음에 포함되지 않습니다. nccl-domain를 실행하려면 --tests 플래그를 사용합니다.
GPU 도구 모음 및 테스트
클러스터 상태 스캐너는 GPU 노드에 다음 도구를 제공합니다.
- Lite: GPU 드라이버 및 하드웨어를 검증하고, 컴퓨팅 처리량을 측정하고, 각 노드 내에서 NVIDIA Collective Communications Library(NCCL) 테스트를 실행합니다.
- 표준: 모든 대상 노드와 노드 쌍 간에 NCCL 집합을 실행하여 노드 간 네트워크 성능을 측정하고 메모리 대역폭을 측정합니다.
다음 표에서는 각 GPU 테스트를 설명합니다.
| 테스트 | 설명 | 묶음 |
|---|---|---|
nccl-single-node |
단일 노드 내의 GPU 간에 NCCL 집합 테스트를 실행합니다. | lite |
nvidia-smi |
NVIDIA 시스템 관리 인터페이스를 사용하여 기본 GPU 상태와 GPU 드라이버를 확인합니다. | lite, standard |
dcgm |
NVIDIA Data Center GPU Manager(DCGM) 진단을 실행하여 각 GPU에서 심층 하드웨어 검사를 수행합니다. | lite, standard |
gemm |
일반 행렬 곱셈(GEMM)을 실행하여 GPU 컴퓨팅 처리량을 측정합니다. | lite, standard |
nccl-cluster |
모든 대상 노드에서 NCCL 집합 테스트를 실행하여 클러스터 전체 네트워크 대역폭을 측정합니다. | standard |
nccl-pairwise |
노드 쌍 간에 NCCL 테스트를 실행하여 노드 간 지연 시간을 측정하고 결함이 있는 노드 또는 링크를 격리합니다. | standard |
stream |
STREAM 벤치마크를 실행하여 GPU 메모리 대역폭을 측정합니다. | standard |
nccl-domain |
각 멀티 노드 NVLink 도메인 내에서 NCCL 집합 테스트를 실행합니다. 멀티 노드 NVLink 도메인이 있는 머신 유형에서만 지원됩니다. | 없음(--tests로 실행) |
TPU 제품군 및 테스트
클러스터 상태 스캐너는 TPU 노드에 대해 다음 도구를 제공합니다.
- Lite: 각 호스트에서 TPU 칩과 HBM의 성능을 검증하고, 호스트-기기 대역폭을 측정하고, 집합 연산 테스트를 실행하여 ICI 대역폭을 측정합니다.
- 표준: 슬라이스의 TPU 칩에서 집합 작업을 실행하고 TPU 칩, HBM, ICI 링크에서 지속적인 스트레스 테스트를 실행합니다.
다음 표에서는 각 TPU 테스트를 설명합니다.
| 테스트 | 설명 | 묶음 |
|---|---|---|
tpu-info |
기기 수, LibTPU 버전, TPU 기기 유형을 포함한 기본 TPU 상태를 확인합니다. | lite, standard |
tpu-gemm |
일반 행렬 곱셈(GEMM)을 실행하여 지속적인 최대 TFLOPS를 측정합니다. | lite, standard |
tpu-hbm |
HBM 읽기 및 쓰기 대역폭을 측정합니다. | lite, standard |
tpu-collectives |
AllReduce 및 AllGather와 같은 집단 연산의 시간을 측정하여 ICI 대역폭을 측정합니다(GKE 클러스터만 해당). | lite, standard |
tpu-host-device |
호스트-기기 대역폭을 측정합니다. | lite, standard |
tpu-compute-stress |
지속적인 행렬 곱셈을 실행하여 계산 안정성을 확인하고 자동 데이터 손상을 노출합니다. | standard |
tpu-hbm-stress |
HBM에 스트레스를 가하여 최대 대역폭을 측정하고 데이터 무결성을 검증합니다. | standard |
tpu-network-stress |
ICI 링크를 통해 대규모 무작위 페이로드를 전송하여 지속적인 대역폭을 측정하고 비트 오류를 감지합니다(GKE 클러스터만 해당). | standard |
시작하기 전에
클러스터 상태 스캐너를 사용하기 전에 필요한 도구를 설치하고 권한을 구성하고 클러스터 또는 인스턴스에 연결합니다.
설치
상태 검사를 실행하기 전에 배포 환경 설치를 완료합니다.
GKE 클러스터
GKE 클러스터에서 상태 스캔을 실행하려면 대상 클러스터가 있는지 확인하고 스캔을 실행할 머신에 필요한 도구를 설치합니다.
- Google Cloud CLI: gcloud CLI를 설치하고 초기화합니다.
kubectl및gke-gcloud-auth-plugin:kubectl설치 및 클러스터 액세스 구성- 클러스터 상태 스캐너 기본 요건:
- Python 패키지: Python 3.12 이상 및 Git
- 컨테이너 이미지: Docker.
- GKE 클러스터: 하나 이상의 GPU 또는 TPU 노드 풀이 있는 GKE 클러스터가 있는지 확인합니다. 자세한 내용은 GKE의 GPU 정보 및 GKE의 TPU 정보를 참조하세요.
Slurm 클러스터
Slurm 클러스터에서 상태 스캔을 실행하려면 대상 GPU 클러스터가 있는지 확인하고 sinfo 및 sbatch 명령어를 사용할 수 있는 Slurm 컨트롤러 또는 로그인 노드에 필요한 도구를 설치합니다.
- gcloud CLI: gcloud CLI를 설치하고 초기화합니다.
- Python 패키지 기본 요건: Python 3.12 이상 및 Git을 설치합니다.
- Slurm 클러스터: GPU 노드가 있는 Slurm 클러스터가 있는지 확인합니다. 자세한 내용은 AI 워크로드용 완전 관리형 Slurm 클러스터 만들기 및 AI 워크로드용 자체 관리형 Slurm 클러스터 만들기를 참조하세요.
Slurm 클러스터의 경우 Python 패키지 설치 옵션을 사용합니다. Slurm은 컨테이너 이미지 옵션을 지원하지 않습니다.
독립형 TPU 인스턴스
독립형 TPU 인스턴스에서 상태 스캔을 실행하려면 대상 TPU 인스턴스가 있는지 확인하고 인스턴스에 직접 필요한 도구를 설치합니다.
- gcloud CLI: gcloud CLI를 설치하고 초기화합니다.
- 클러스터 상태 스캐너 기본 요건: 사용하려는 클러스터 상태 스캐너 설치 옵션에 대한 도구를 설치합니다.
- Python 패키지: Python 3.12(특히 Linux
x86_64의 Python 3.12, 3.13 이상 아님) 및 Git 인스턴스의 기본python3버전이 3.12 이전 또는 이후인 경우uv를 사용하여 Python 3.12 가상 환경을 만들 수 있습니다(클러스터 상태 스캐너 문제 해결 참조). - 컨테이너 이미지: Docker Container-Optimized OS에서는 컨테이너 이미지가 유일하게 지원되는 설치 옵션입니다.
- Python 패키지: Python 3.12(특히 Linux
- 독립형 TPU 인스턴스:
/dev/vfio에서 TPU 기기를 노출하는 독립형 TPU 인스턴스(TPU7x 또는 TPU v6e)가 있는지 확인합니다(ls /dev/vfio를 실행하여 인스턴스에서 이를 확인할 수 있음). 자세한 내용은 Cloud TPU VM 만들기를 참조하세요.
필요한 역할
상태 스캔을 실행하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 roles/compute.viewer 역할을 부여해 달라고 요청하세요. 이 역할을 통해 클러스터 상태 스캐너는 노드의 Compute Engine 메타데이터 및 토폴로지 정보를 읽을 수 있습니다.
배포 환경에 따라 다음 Identity and Access Management(IAM) 역할도 필요합니다.
| 환경 | 필요한 역할 |
|---|---|
| GKE 클러스터 | Kubernetes Engine 개발자(roles/container.developer) |
| Slurm 클러스터 |
|
| 독립형 TPU 인스턴스 |
|
보고서용 Cloud Storage 버킷을 구성하는 경우 버킷에 대한 스토리지 객체 관리자 역할(roles/storage.objectAdmin)도 필요합니다. 이 역할을 통해 클러스터 상태 스캐너가 상태 보고서와 같은 결과 아티팩트를 버킷에 업로드할 수 있습니다.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
클러스터 또는 인스턴스에 연결
상태 검사를 실행할 환경에 연결합니다.
GKE 클러스터
애플리케이션 기본 사용자 인증 정보(ADC)를 설정하고 GKE 클러스터와 통신하도록 kubectl을 구성합니다.
gcloud auth application-default login
gcloud container clusters get-credentials CLUSTER_NAME \
--location=LOCATION \
--project=PROJECT_ID
Slurm 클러스터
SSH를 사용하여 Slurm 컨트롤러 또는 로그인 노드에 연결합니다.
gcloud compute ssh SLURM_NODE_NAME \
--zone=ZONE \
--project=PROJECT_ID
독립형 TPU 인스턴스
SSH를 사용하여 독립형 TPU 인스턴스에 연결합니다.
gcloud compute tpus tpu-vm ssh TPU_NAME \
--zone=ZONE \
--project=PROJECT_ID
클러스터 상태 스캐너 설치
환경에 따라 스캔을 실행하는 머신에 클러스터 상태 스캐너를 설치합니다.
- GKE 클러스터: 클러스터에 대한
kubectl액세스 권한이 있는 모든 머신입니다. - Slurm 클러스터: Slurm 컨트롤러 또는 로그인 노드입니다.
- 독립형 TPU 인스턴스: TPU 인스턴스 자체입니다.
GKE 및 Slurm 클러스터에서 클러스터 상태 스캐너는 GPU 또는 TPU 노드와 일치하는 진단 컨테이너 이미지를 자동으로 가져와 클러스터에 예약하므로 개별 컴퓨팅 노드에 소프트웨어를 설치할 필요가 없습니다. 독립형 TPU 인스턴스에서는 인스턴스에 직접 클러스터 상태 스캐너를 설치하고 실행합니다.
클러스터 상태 스캐너를 Python 패키지 또는 컨테이너 이미지로 설치할 수 있습니다. 이 문서의 나머지 부분에 있는 chs 명령어는 두 설치 옵션 모두에서 작동합니다. 명령어의 자세한 사용 정보를 보려면 --help 플래그를 추가합니다.
Python 패키지
Python 가상 환경을 만들고 GitHub에서 클러스터 상태 스캐너 패키지를 설치합니다. GKE 및 Slurm 클러스터에서 Python 3.12 이상을 사용합니다. 독립형 TPU 인스턴스(x86_64)에서는 Python 3.12를 사용해야 합니다(Python 3.13 이상에서는 pip install가 TPU 벤치마크 종속 항목을 설치하지 않고 chs run가 인스턴스를 건너뜀).
python3 -m venv chs-venv
source chs-venv/bin/activate
pip install git+https://github.com/GoogleCloudPlatform/cluster-health-scanner.git
특정 출시 버전을 설치하려면 저장소 URL에 @VERSION을 추가합니다.
pip install git+https://github.com/GoogleCloudPlatform/cluster-health-scanner.git@VERSION
출시 버전 목록은 GitHub의 클러스터 상태 스캐너 출시 버전을 참조하세요.
컨테이너 이미지
클러스터 상태 스캐너는 Artifact Registry에서 컨테이너 이미지로 배포됩니다. 이 이미지는 GPU와 TPU를 모두 지원합니다. GKE 클러스터 및 독립형 TPU 인스턴스에 컨테이너 이미지를 사용할 수 있지만 Slurm 클러스터에는 사용할 수 없습니다.
Artifact Registry로 인증하도록 Docker를 구성하고 클러스터 상태 스캐너 컨테이너 이미지를 가져옵니다.
gcloud auth configure-docker us-docker.pkg.dev docker pull us-docker.pkg.dev/gce-ai-infra/chs/chs:latestlatest대신 특정 출시 버전을 가져오려면latest를 버전 번호로 바꿉니다. 예를 들어 GitHub 출시 버전v0.3.0의 경우0.3.0입니다. 출시 목록은 GitHub의 클러스터 상태 스캐너 출시를 참조하세요.chs명령어를 직접 실행하는 셸 별칭을 만듭니다. 만드는 별칭은 환경에 따라 다릅니다.GKE 클러스터: 별칭은
kubeconfig파일과 Google Cloud 사용자 인증 정보를 읽기 전용 모드로 마운트합니다. 또한 이 별칭은chs-local-stateDocker 볼륨에 실행 상태를 저장하고 현재 디렉터리의chs-output디렉터리에 출력 파일을 작성합니다.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'독립형 TPU 인스턴스: Container-Optimized OS를 실행하는 TPU 인스턴스에서 컨테이너 이미지는 유일하게 지원되는 설치 옵션입니다. 이 별칭은 컨테이너에 인스턴스의 TPU 기기 및 호스트 PID 네임스페이스에 대한 액세스 권한을 부여하고,
/host에서 호스트 루트 파일 시스템을 마운트하고, Google Cloud사용자 인증 정보를 읽기 전용 모드로 마운트합니다. 또한 이 별칭은chs-local-stateDocker 볼륨에 실행 상태를 저장하고 현재 디렉터리의chs-output디렉터리에 출력 파일을 작성합니다.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'
선택사항: 보고서용 Cloud Storage 버킷 설정
기본적으로 클러스터 상태 스캐너는 보고서와 진단 로그를 로컬 출력 디렉터리에 저장합니다. Cloud Storage 버킷을 구성하여 원격으로 저장할 수도 있습니다.
상태 스캔 보고서용 버킷이 아직 없으면 버킷을 만듭니다.
gcloud storage buckets create gs://BUCKET_NAME \ --location=BUCKET_LOCATION \ --project=PROJECT_ID주 구성원 사용자 계정 또는 서비스 계정에 스토리지 객체 관리자 역할(
roles/storage.objectAdmin)을 부여합니다.gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \ --member=PRINCIPAL \ --role=roles/storage.objectAdminPRINCIPAL구성원은 보고서를 작성하는 주 구성원입니다. 예를 들면user:EMAIL또는serviceAccount:SERVICE_ACCOUNT_EMAIL입니다.클러스터 상태 스캐너가 보고서를 저장하는 버킷을 설정합니다. 클러스터 상태 스캐너는 버킷을 자동으로 만들지 않으므로 버킷이 이미 있어야 합니다. 이 명령어는 환경마다 한 번만 실행하면 됩니다.
chs configure storage gcs BUCKET_NAME버킷의 폴더 프리픽스 아래에 보고서를 저장하려면 버킷 이름에 프리픽스를 추가합니다.
chs configure storage gcs BUCKET_NAME/PREFIX
상태 검사 실행
이 섹션에서는 노드가 유휴 상태인지 확인하고, 스캔을 시작하고, 진행 상황을 모니터링하는 방법을 설명합니다.
대상 노드가 유휴 상태인지 확인
클러스터 상태 스캐너는 유휴 용량에서만 실행되며 워크로드를 자동으로 중지하거나 제거하지 않습니다. 스캔을 시작하기 전에 대상 노드 또는 인스턴스에서 실행되는 워크로드를 드레이닝하거나 중지합니다.
클러스터 상태 스캐너가 대상 노드 또는 인스턴스에서 활성 워크로드를 감지하면 다음과 같이 용량을 처리합니다.
- GPU: 클러스터 상태 스캐너는 사용 중인 노드를 건너뛰고 나머지 유휴 노드에서 스캔을 실행합니다.
- TPU: 클러스터 상태 스캐너가 사용 중인 용량을 처리하는 방식은 환경에 따라 다릅니다.
- GKE 클러스터: 멀티 호스트 TPU 테스트(
tpu-collectives및tpu-network-stress)에는 완전한 유휴 슬라이스가 필요하지만 단일 호스트 TPU 테스트는 개별 유휴 노드에서 실행할 수 있습니다.- 정적 슬라이싱 노드 풀(
--nodepools또는--nodes):lite또는standard도구 모음을 실행할 때 풀의 일부 노드가 사용 중이면 클러스터 상태 스캐너가 경고를 로깅하고 멀티 호스트 테스트를 생략하고 나머지 유휴 노드에서 단일 호스트 TPU 테스트를 실행합니다. - 동적 슬라이싱 노드 풀(
--nodepools또는--nodes):--nodepools로 풀을 타겟팅하려면 클러스터 상태 스캐너가 전체 풀Slice리소스를 프로비저닝할 수 있도록 전체 노드 풀이 유휴 상태여야 합니다.--nodes(GKE 버전1.36.0-gke.3712000이상)를 사용하여 특정 노드를 타겟팅하는 경우 클러스터 상태 스캐너는 각 유휴 노드에 대해 개별2x2x1하위 슬라이스를 프로비저닝하고 사용 중인 노드를 건너뛰고 유휴 노드에서 단일 호스트 TPU 테스트를 실행합니다.
- 정적 슬라이싱 노드 풀(
- 독립형 TPU 인스턴스: 다른 프로세스가
/dev/vfio에서 TPU 기기를 사용하는 경우 클러스터 상태 스캐너를 실행할 수 없습니다.
- GKE 클러스터: 멀티 호스트 TPU 테스트(
대상 용량이 유휴 상태인지 확인하려면 환경에 맞는 단계를 따르세요.
GKE 클러스터
대상 노드 풀에서 활성 워크로드 작업 또는 포드를 중지하거나 삭제하거나 실행 중인 워크로드가 완료될 때까지 기다립니다.
kubectl drain를 사용하여 노드 풀에서 워크로드를 제거하는 경우 클러스터 상태 스캐너가 노드에서 진단 포드를 예약할 수 있도록 스캔을 시작하기 전에 노드를 차단 해제합니다(클러스터 상태 스캐너는 차단된 노드를 건너뜀).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스캔이 실행되는 동안 노드 풀에 새 워크로드가 예약되지 않도록 합니다.
노드 풀에 워크로드 포드가 남아 있지 않은지 확인합니다.
kubectl get pods --all-namespaces -o wide \ --field-selector=status.phase=Running | grep NODE_POOL_NAMEkube-system네임스페이스의 DaemonSet에서 관리하는 포드와 같은 시스템 포드는 계속 실행될 수 있습니다.
Slurm 클러스터
대상 파티션에서 실행 중인 작업을 확인합니다.
squeue --partition=PARTITION_NAME파티션에서 작업이 실행 중인 경우 완료될 때까지 기다리거나
scancel JOB_ID로 취소합니다.대상 파티션의 노드가
idle상태인지 확인합니다.sinfo --partition=PARTITION_NAME
독립형 TPU 인스턴스
인스턴스에서 TPU 기기를 사용하는 다른 프로세스가 없는지 확인합니다.
sudo fuser -v /dev/vfio/*
나열된 프로세스가 있으면 워크로드가 완료될 때까지 기다리거나 프로세스를 중지한 후 스캔을 시작합니다.
스캔 시작
chs run 명령어에 전달하는 플래그는 클러스터 상태 스캐너를 실행하는 환경에 따라 다릅니다. 클러스터 상태 스캐너는 스케줄러와 가속기 유형을 자동으로 감지하므로 지정할 필요가 없습니다.
가속기 유형에 사용할 수 있는 진단 도구 모음 및 테스트를 나열하려면 다음 명령어를 실행합니다.
GPU:
chs list suites --gpu chs list tests --gpuTPU:
chs list suites --tpu chs list tests --tpu
GKE 노드 풀
로컬 머신 또는 Cloud Shell과 같이 클러스터에 대한 kubectl 액세스 권한이 있는 머신에서 클러스터 상태 스캐너를 실행합니다.
하나 이상의 노드 풀에서 스캔을 시작하려면 다음 명령어를 실행합니다.
chs run \
--nodepools=NODE_POOL_NAMES \
--suite=SUITE
다음을 바꿉니다.
NODE_POOL_NAMES: 스캔할 GPU 또는 TPU 노드 풀의 쉼표로 구분된 목록입니다. 예를 들면a4-pool-1,a4-pool-2또는tpu7x-pool-1,tpu7x-pool-2입니다. 모든 대상 노드 풀은 동일한 머신 유형을 사용해야 합니다.SUITE: 실행할 진단 도구 모음(lite또는standard)입니다. 각 도구 모음에 대한 자세한 내용은 진단 도구 모음을 참조하세요.
전체 모음 대신 특정 테스트를 실행하려면 --suite 플래그를 --tests 플래그로 바꾸고 쉼표로 구분된 테스트 이름 목록을 지정합니다.
chs run \
--nodepools=NODE_POOL_NAMES \
--tests=TEST_NAMES
전체 노드 풀 대신 특정 노드를 스캔하려면 --nodepools 플래그를 --nodes 플래그로 바꾸고 쉼표로 구분된 노드 이름 목록을 지정합니다.
--nodepools 플래그에 노드 풀을 여러 개 지정하면 클러스터 상태 스캐너는 가속기 유형에 따라 이를 처리합니다.
- GPU 노드 풀: 지정된 노드 풀의 모든 유휴 GPU 노드를 단일 대상 세트로 결합하고 모든 노드에서 다중 노드 테스트(
nccl-cluster및nccl-pairwise)를 함께 실행합니다. - TPU 노드 풀: 교차 슬라이스(멀티슬라이스) 테스트 없이 단일 실행 내에서 각 노드 풀(TPU 슬라이스)을 독립적으로 동시에 평가합니다.
Slurm 파티션
sinfo 및 sbatch 명령어를 사용할 수 있는 Slurm 컨트롤러 또는 로그인 노드에서 클러스터 상태 스캐너를 실행합니다. Slurm에는 Python 패키지 설치 옵션이 필요합니다. 설치 안내는 Python 패키지를 참조하세요.
스캔을 시작하기 전에 노드가 us-docker.pkg.dev에서 벤치마크 이미지를 가져올 수 있도록 클러스터에서 Enroot 사용자 인증 정보를 구성합니다.
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
하나 이상의 파티션에서 스캔을 시작합니다.
chs run \
--partitions=PARTITION_NAMES \
--suite=SUITE
다음을 바꿉니다.
PARTITION_NAMES: 스캔할 Slurm 파티션의 쉼표로 구분된 목록입니다.SUITE: 실행할 진단 도구 모음(lite또는standard)입니다. 각 도구 모음에 대한 자세한 내용은 진단 도구 모음을 참조하세요.
전체 모음 대신 특정 GPU 테스트를 실행하려면 --suite 플래그를 --tests 플래그로 바꾸고 쉼표로 구분된 테스트 이름 목록(예: nccl-pairwise,gemm 또는 nccl-domain)을 지정합니다.
chs run \
--partitions=PARTITION_NAMES \
--tests=TEST_NAMES
독립형 TPU 인스턴스
TPU 인스턴스에서 직접 클러스터 상태 스캐너를 실행합니다. TPU 인스턴스는 /dev/vfio에서 TPU 기기를 노출해야 합니다. 인스턴스에서 ls /dev/vfio를 실행하여 이를 확인할 수 있습니다.
root 사용자로 클러스터 상태 스캐너를 실행하지 않는 경우 TPU 테스트를 실행하기 전에 memlock 한도를 높입니다.
ulimit -l unlimited
TPU 인스턴스에서 스캔을 시작하려면 다음 명령어를 실행합니다.
chs run --suite=SUITE
SUITE를 실행할 진단 도구 모음(lite 또는 standard)으로 바꿉니다.
각 도구 모음에 대한 자세한 내용은 진단 도구 모음을 참조하세요.
전체 모음 대신 특정 TPU 테스트를 실행하려면 --suite 플래그를 --tests 플래그로 바꾸고 쉼표로 구분된 테스트 이름 목록을 지정합니다(예: tpu-host-device,tpu-hbm-stress).
chs run --tests=TEST_NAMES
실행 및 결과 보기
클러스터 상태 스캐너는 chs 명령어를 실행하는 클라이언트 머신에 로컬로 실행 기록 및 구성 설정을 저장합니다(~/.local/share/chs/ 또는 컨테이너 이미지를 사용할 때 chs-local-state Docker 볼륨). 따라서 chs history 및 chs results 명령어는 해당 환경에서 시작된 실행만 나열합니다.
이전 실행과 실행 ID를 나열하려면 다음 명령어를 실행합니다.
chs history
실행 결과와 대화형 HTML 보고서(bill_of_health.html) 및 JSON 보고서(bill_of_health.json)의 위치를 표시하려면 다음 명령어를 실행합니다.
chs results RUN_ID
RUN_ID를 생략하면 클러스터 상태 스캐너에서 실행을 선택하라는 메시지가 표시됩니다.
이 명령어는 로컬 경로 또는 버킷을 구성한 경우 Cloud Storage URI를 출력합니다. 이전 실행의 저장된 결과를 읽고 클러스터 또는 인스턴스에서 새 작업을 시작하지 않습니다.
스캔 취소하기
스캔을 취소하고, 작업을 중지하고, 클러스터 또는 인스턴스에서 만든 리소스를 삭제하려면 다음 명령어 중 하나를 실행합니다.
최근 실행을 취소합니다.
chs cancel특정 실행 취소:
chs cancel RUN_ID다른 사용자가 시작한 실행을 포함하여 클러스터 또는 인스턴스에서 실행되는 모든 클러스터 상태 스캐너 실행을 취소합니다.
chs cancel --all
결과 해석
스캔이 완료되면 클러스터 상태 스캐너는 다음 아티팩트를 로컬 출력 디렉터리에 저장하고 스토리지를 구성한 경우 Cloud Storage 버킷에 업로드합니다.
- 대화형 HTML 보고서(
bill_of_health.html): 각 테스트, 측정된 측정항목, 상태를 표시합니다. - JSON 보고서(
bill_of_health.json): 각 테스트의 매개변수 스윕 및 측정된 측정항목이 포함됩니다. - 작업공간 디렉터리: 진단 로그가 포함됩니다.
상태 보고서 보기
스캔 보고서의 정확한 로컬 경로 또는 Cloud Storage URI(gs://BUCKET/PREFIX/bills_of_health/RUN_ID.html 및 gs://BUCKET/PREFIX/bills_of_health/RUN_ID.json)를 찾으려면 다음 명령어를 실행합니다.
chs results RUN_ID
Cloud Storage 버킷을 구성한 경우 chs results에서 반환된 URI에서 직접 JSON 보고서를 볼 수 있습니다.
gcloud storage cat gs://BUCKET_NAME/PREFIX/bills_of_health/RUN_ID.json
보고서 내용
상태 보고서에는 클러스터 상태 스캐너가 테스트한 모든 노드와 각 노드의 벤치마크 결과가 나열됩니다. GPU 및 TPU 스캔은 동일한 보고서 형식을 사용합니다. 각 노드는 다음 상태 중 하나를 수신합니다.
| 상태 | 설명 |
|---|---|
HEALTHY |
모든 테스트가 머신 유형에 예상되는 성능을 충족했습니다. |
DEGRADED |
노드가 테스트를 완료했지만 하나 이상의 결과가 예상 성능보다 낮습니다. |
POTENTIALLY DEGRADED |
선별 테스트가 예상 성능에 미치지 못했으며, 결과를 확인하기 위한 해당 스트레스 테스트가 실행되지 않았습니다. |
INCOMPLETE |
하나 이상의 테스트가 실행되지 않았거나, 타임아웃되었거나, 취소되었거나, 노드에서 측정항목을 보고하지 않았습니다. |
bill_of_health.json 파일에는 다음과 같은 최상위 필드가 포함됩니다.
report_id: 스캔 실행의 고유 식별자입니다.chs_version: 보고서를 생성한 클러스터 상태 스캐너의 버전입니다.created_at: 보고서가 생성된 타임스탬프입니다.system_info: 클러스터 유형 및 머신 유형과 같은 테스트 중인 시스템에 대한 메타데이터입니다.test_results: 테스트 결과 객체 목록입니다. 각 항목에는 다음 필드가 포함됩니다.test_name: 진단 테스트의 이름입니다.result_status: 테스트 결과(예:RESULT_STATUS_SUCCESS또는RESULT_STATUS_FAILED)target_resources: 테스트가 실행된 노드(node_name및instance_id)입니다.metrics: 테스트의 측정된 측정항목 및 검증 기준입니다.
상태 보고서는 일관되고 구조화된 JSON 형식을 사용합니다. 보고서를 BigQuery 또는 다른 분석 도구에 로드하고 동일한 용량의 연속 스캔 보고서를 비교하여 점진적인 성능 드리프트를 감지할 수 있습니다.
비정상 노드 복구
상태 보고서에서 DEGRADED, POTENTIALLY DEGRADED 또는 INCOMPLETE 상태의 노드 또는 인스턴스를 식별하는 경우 다음 단계를 수행합니다.
일시적인 문제를 배제하려면 노드를 차단하거나 드레이닝하기 전에 GKE 노드 풀 또는 노드, Slurm 파티션 또는 독립형 TPU 인스턴스에서 스캔을 다시 실행합니다(클러스터 상태 스캐너는 차단된 GKE 노드와 드레이닝된 Slurm 노드를 건너뜀). 자세한 내용은 스캔 시작을 참조하세요.
문제가 지속되면 영향을 받는 노드 또는 인스턴스에서 새 워크로드가 예약되지 않도록 합니다.
GKE 클러스터: 비정상 노드를 차단합니다.
kubectl cordon NODE_NAMESlurm 클러스터: 비정상 노드를 드레이닝합니다.
sudo scontrol update NodeName=NODE_NAME State=DRAIN Reason="CHS unhealthy"독립형 TPU 인스턴스: 문제를 해결할 때까지 TPU 인스턴스에서 새 워크로드를 시작하지 마세요.
가속기 유형 및 환경에 따라 다음 옵션 중 하나를 사용하여 노드 또는 인스턴스를 복구하거나 교체합니다.
- GPU:
- GKE 클러스터: Compute Engine에서 복구할 수 있도록 장애가 있는 호스트를 신고합니다. 자세한 내용은 GKE를 통해 결함이 있는 호스트 신고를 참조하세요.
- Slurm 클러스터: Compute Engine에서 복구할 수 있도록 장애가 있는 호스트를 신고합니다. 자세한 내용은 결함이 있는 호스트 신고를 참조하세요.
- Google의 도움을 받으려면 Cloud Customer Care에 문의하세요.
- TPU(GKE 클러스터 및 독립형 TPU 인스턴스):
- 모든 용량 모드에서 TPU를 사용하는 경우 장애가 있는 호스트를 신고합니다. 자세한 내용은 모든 용량 모드에서 장애가 있는 호스트 신고 및 복구를 참조하세요.
- 다른 용량 모드는 TPU 인스턴스의 장애 복구를 참조하세요.
- Google의 도움을 받으려면 Cloud TPU 지원에 문의하세요.
지원팀에 문의할 때 진단 로그가 포함된 로컬 출력 디렉터리 또는 Cloud Storage 버킷의 작업공간 디렉터리를 첨부하고 실행 ID를 포함합니다.
- GPU:
노드 또는 인스턴스가 복구되거나 교체된 후 클러스터 상태 스캐너가 이를 건너뛰지 않도록 다시 예약 가능하게 만든 다음 새 스캔을 실행하여 용량이 정상인지 확인합니다.
GKE 클러스터: 노드를 차단 해제한 후 새 워크로드를 예약하기 전에 스캔을 다시 실행합니다.
kubectl uncordon NODE_NAMESlurm 클러스터: 노드를 재개하여
idle상태로 돌아가도록 한 다음 새 작업을 예약하기 전에 스캔을 다시 실행합니다.sudo scontrol update NodeName=NODE_NAME State=RESUME독립형 TPU 인스턴스: 인스턴스에서 스캔을 다시 실행한 후 스캔에서 인스턴스가 정상인지 확인되면 워크로드 실행을 재개합니다.
원격 분석
클러스터 상태 스캐너는 도구 개선을 위해 익명의 사용량 측정항목을 Google에 전송하며 개인 식별 정보(PII)를 수집하지 않습니다.
원격 분석은 기본적으로 사용 설정되어 있습니다. 선택 해제하려면 chs configure telemetry
disable를 실행하거나 CHS_TELEMETRY=0 환경 변수를 설정합니다.
다음 단계
클러스터 상태 스캐너의 일반적인 문제를 해결하려면 클러스터 상태 스캐너 문제 해결을 참조하세요.