2. 여러 대를 cluster로 등록하기

설치의 목표는 컨테이너 하나를 띄우는 것이 아니라 같은 조건의 worker 여러 대를 만드는 것이다

이 장에서 처음 나오는 말4개

NVIDIA Container Toolkit

컨테이너가 host의 NVIDIA GPU와 driver library를 쓰게 연결하는 runtime 구성 요소다.

registration token

새 worker가 올바른 GPUStack cluster에 가입할 때 쓰는 비밀값이다.

advertise address

다른 구성 요소가 worker에 접근할 때 사용할 주소. 관리망 주소와 분산망 주소를 의도적으로 구분해야 한다.

image digest

tag가 가리키는 내용이 바뀌어도 동일한 image를 재현하도록 content hash로 고정한 식별자다.

권장 배치

Quickstart는 Server를 GPU worker와 같은 장비에 둘 수도 있다고 설명한다. PoC에는 편하지만 Spark의 unified memory와 CPU를 모델에 최대한 남기려면 운영 Server는 별도 VM이 낫다. 관리 노드에는 GPU가 필요 없다.

worker 표준을 먼저 만든다

worker 모두 다음이 같아야 한다.

• DGX OS·firmware·GPU driver·CUDA 호환 범위
• Docker와 NVIDIA Container Toolkit
• NTP 동기화와 hostname 규칙
• model cache 경로와 disk 여유
• 내부 DNS·사내 CA·egress proxy 설정
• GPUStack worker image와 backend image digest

Spark는 ARM64와 GB10 조합이다. upstream의 일반 x86 image를 그대로 당겨 쓰지 말고 multi-arch 여부를 확인한다. vLLM은 NVIDIA의 DGX Spark recipe가 지정한 NGC image와 모델별 실행 값을 출발점으로 삼는다.

설치 순서

1. 소규모 PoC 범위를 먼저 정한다

   운영망 주소, DNS 이름, model cache 위치, Server VM, 시험할 LLM·embedding·FastAPI image를 적는다. 전체 worker에 바로 설치하면 host 차이를 원인으로 의심해야 할 범위만 커진다.

2. Server를 CPU VM에 시작한다

   공식 quickstart의 최소 형태는 다음이다. 운영에서는 검증한 버전 또는 digest로 바꾸고 TLS·backup을 붙인다.

   sudo docker run -d --name gpustack \
     --restart unless-stopped \
     -p 80:80 \
     --volume gpustack-data:/var/lib/gpustack \
     gpustack/gpustack

3. Docker cluster를 만들고 worker 명령을 발급한다

   UI의 Clusters에서 Docker provider를 선택한다. 생성된 명령에는 Server URL과 registration token이 들어간다. token을 일반 문서나 shell history에 장기 보관하지 않는다.

4. Spark를 worker로 가입시킨다

   worker container는 host network, Docker socket과 NVIDIA runtime을 사용한다. 공식 UI가 발급한 명령을 기준으로 하되 worker-name과 접근 주소를 자산 명명 규칙에 맞춘다.

5. label을 설치 직후 붙인다

   hardware=dgx-spark
   arch=arm64
   workload=general
   cell=single
   environment=prod

   pair는 5장에서 cell=pair-a, fabric=cx7-a처럼 추가한다. 이름만 보고 topology를 추론하지 않는다.

6. 가장 작은 모델로 end-to-end를 확인한다

   Catalog 모델 하나를 배포해 download → container start → health → API → log → delete 전 과정을 본다. 그 다음 worker 재부팅과 instance 강제 종료를 시험한다.

네트워크를 두 길로 본다

일반 독립 replica에는 관리 10GbE가 요청·제어·model download 경로다. 2대 pair에서 NCCL/Ray가 통신할 때만 ConnectX-7 고속망이 중요하다. worker 간 분산 inference를 쓸 경우 GPUStack의 worker port와 Ray port range도 해당 망과 방화벽에서 열어야 한다.

함정

GPUStack worker는 Docker socket과 privileged 권한을 사용한다. Server·worker 관리 포트를 사용자망에 그대로 노출하지 않는다. LiteLLM만 북쪽에 열고 GPUStack 관리면은 관리자망과 TLS 뒤에 둔다.

참고 자료

• GPUStack Quickstart — Server와 Docker worker 등록 명령.
• GPUStack 설치 요구사항 — ARM64, NTP, database와 port 범위.
• DGX Spark vLLM — Spark용 NGC image와 QSFP multi-node 전제.
• DGX Spark Container Runtime — 기본 NVIDIA container runtime 확인.

3. vLLM과 임베딩가장 표준적인 두 workload를 한 노드 replica 중심으로 배포하고 LiteLLM에 연결한다.