NVIDIA GPU 패스스루 활성화

NVIDIA GPU 패스스루 활성화 (Enable NVIDIA GPU passthrough)

로컬 Docker Sandboxes에서 물리 NVIDIA GPU 위에 워크로드를 실행하는 방법을 알아볼게요.

출처: 문서

본문

중요 (Important): GPU 패스스루는 실험적이에요. --gpu 플래그, 드라이버 번들, 이 페이지의 설정 단계는 바뀔 수 있어요.

로컬 Docker Sandboxes의 GPU 패스스루는 물리 NVIDIA GPU 위에서 워크로드를 실행해요.

Docker 샌드박스의 GPU 패스스루는 VFIO를 통해 동작해요. VFIO는 PCI 장치를 가상 머신에 직접 할당하는 Linux 기능이에요. GPU가 호스트의 드라이버 대신 VFIO에 바인딩되고, 샌드박스 워크로드가 그 하드웨어를 스스로 구동해요.

요구사항 (Requirements)

VFIO 기반 GPU 패스스루는 NVIDIA GPU가 있는 x86_64 Linux 호스트(Arm 아님)에서만 지원돼요. 그리고 아무도 쓰지 않는 GPU가 필요해요: GPU가 있는 헤드리스 호스트 또는 추가 GPU.

호스트는 또한 BIOS에서 IOMMU를 켜야 하고, iommufd와 vfio_pci 커널 모듈이 로드되어야 해요:

sudo modprobe -a iommufd vfio_pci

샌드박스가 GPU를 구동하려면 다음이 필요해요:

Docker Sandboxes 게스트 커널용으로 빌드된 nvidia와 nvidia-uvm 커널 모듈
NVIDIA 사용자 공간 드라이버 라이브러리와 펌웨어

Docker Sandboxes는 EROFS 이미지로 패키징된 이 의존성들을 /usr/libexec/nerdbox-nvidia-bundle.erofs에서 찾아요. 이 번들은 Docker Sandboxes에 포함되지 않아요. 만들려면 Build the bundle을 보세요.

기능 켜기 (Turn on the feature)

--gpu 플래그는 실험 기능과 GPU 기능 플래그를 켜기 전까지 숨겨져 있어요:

sbx settings set platform.allowExperimentalFeatures true
sbx settings set feature.sandbox-gpu true

번들 빌드하기 (Build the bundle)

번들을 만드는 데 필요한 모든 구성 요소가 담긴 zip 아카이브가 각 Docker Sandboxes 릴리스와 함께 nerdbox-nvidia-modules-x86_64.zip으로 게시돼요. 아카이브에는 커널 모듈(nvidia.ko와 nvidia-uvm.ko), 빌드된 드라이버 버전(VERSION), 빌드 스크립트가 들어 있어요.

빌드 스크립트는 일치하는 NVIDIA 드라이버를 내려받는 linux/amd64 컨테이너를 실행하고, 번들을 조립하며, /usr/libexec/nerdbox-nvidia-bundle.erofs로 설치해요. 그 경로에 쓰려면 root 권한이 필요하므로 다음 명령에 sudo가 들어가요.

사전 요구사항:

download.nvidia.com에 대한 네트워크 접근
Docker

아카이브를 내려받아 풀고, 풀린 디렉터리에서 스크립트를 실행해요:

curl -fSLO https://github.com/docker/sbx-releases/releases/latest/download/nerdbox-nvidia-modules-x86_64.zip
unzip nerdbox-nvidia-modules-x86_64.zip -d nvidia-modules
cd nvidia-modules
sudo ./prepare-nvidia-bundle.sh

스크립트가 출력 경로에 쓸 수 없으면 번들을 현재 디렉터리에 남기고, 마무리하는 install 명령을 출력해요.

두 환경 변수가 스크립트의 기본 동작을 덮어써요:

변수 (Variable)	기본값 (Default)	용도 (Purpose)
`OUTPUT`	`/usr/libexec/nerdbox-nvidia-bundle.erofs`	완성된 번들이 쓰이는 위치
`ACCEPT_NVIDIA_LICENSE`	없음	스크립트나 CI에서 비대화형으로 NVIDIA 라이선스를 수락하려면 `1`로 설정

예를 들어 다음 명령은 완성된 번들을 /mnt/some-place/nerdbox-nvidia-bundle.erofs로 씁니다:

OUTPUT=/mnt/some-place/nerdbox-nvidia-bundle.erofs ./prepare-nvidia-bundle.sh

번들 설치하기 (Install the bundle)

GPU 샌드박스를 실행하는 x86_64 Linux 호스트에서 스크립트를 실행했고 OUTPUT을 덮어쓰지 않았다면 번들이 이미 제자리에 있어요. 다른 곳에서 빌드했다면, 스크립트가 만든 nerdbox-nvidia-bundle.erofs 파일을 그 호스트의 /usr/libexec 디렉터리로 복사하세요.

GPU로 샌드박스 실행하기 (Run a sandbox with a GPU)

GPU 패스스루로 샌드박스를 실행하려면 --gpu 플래그를 전달해요:

sbx create --gpu claude .

sbx run 명령도 같은 플래그를 받아요:

sbx run --gpu claude

플래그는 샌드박스가 만들어질 때 적용돼요. 기존 샌드박스에 다시 붙을 때 전달하면 효과가 없어요.

중요 (Important): 각 Docker Sandboxes 릴리스는 특정 게스트 커널을 사용해요. 번들의 NVIDIA 커널 모듈은 그 커널과 일치해야 해요. Docker Sandboxes를 업그레이드한 뒤에는 새 릴리스의 nerdbox-nvidia-modules-x86_64.zip 아카이브를 내려받고 스크립트를 다시 실행해 번들을 재빌드하세요.

문제 해결 (Troubleshooting)

스크립트가 `... not found in the driver download`라고 보고할 때

추출된 드라이버에 예상 라이브러리나 펌웨어 파일이 없었어요. 다운로드가 완료됐는지 확인하세요. 드라이버 버전에서 라이브러리 이름이 다르다면 스크립트의 DRIVER_LIB_FAMILIES를 조정하세요.

Docker Sandboxes 업그레이드 후 GPU 워크로드가 실패할 때

게스트 커널이나 고정된 드라이버 버전이 바뀌었을 가능성이 커요. 새 릴리스의 아카이브를 내려받고, 스크립트를 다시 실행하고, 번들을 다시 설치하세요.

더 알아보기 (Learn more)

관련 문서와 심화 내용은 원문을 참고해 주세요.

NVIDIA GPU 패스스루 활성화