문제점

docker와 Nvidia toolkit만 설치하면 되는 줄 알았는데
계속 빌드 후에 이미지를 pull 받아서 실행하는 과정에서 device의 용량이 부족하다고 실패하였다.

그래서 공식 문서를 찾아가보니

https://developer.nvidia.com/docs/drive/drive-os/6.0.5/public/drive-os-installation/common/topics/installation/get-started/intro.html

이렇게 공식 문서를 찾아보니 약 최소 78GB의 용량이 필요하다고 떴다...

왜 이렇게 많이 들까? 정말 이렇게 많이 드는걸까?
모든 GPU 서버의 사람들이 전부 이렇게 작업을 하는것일까? 하고 고민했는데,

Nvidia Container Toolkit이 존재했다!

우선은 Nvidia-toolkit과 Nvidia-Container-Toolkit의 차이점을 알아보자.

Nvidia Toolkit

NVIDIA Toolkit은 보통 CUDA Toolkit을 의미하며, 이는 GPU 가속 애플리케이션을 개발, 최적화, 배포하기 위한 포괄적인 개발 환경이다. 즉, GPU 그래픽 카드를 사용하기 위한 tool이라고 생각하면 된다.

• CUDA 드라이버: GPU를 제어하고 애플리케이션과 통신하는 소프트웨어
• CUDA 런타임: GPU에서 코드를 실행하는 데 필요한 핵심 라이브러리
• 컴파일러 (NVCC): C/C++ 코드를 GPU에서 실행할 수 있는 바이너리로 변환
• 라이브러리: cuBLAS (선형대수), cuDNN (딥러닝), cuFFT (고속 푸리에 변환) 등 다양한 분야의 GPU 가속 라이브러리를 제공

요약하자면, GPU 기반 애플리케이션을 만들고 실행하기 위한 개발 환경이다!

Nvidia-Container-Toolkit

NVIDIA Container Toolkit이란?

Docker와 같은 컨테이너 런타임이 NVIDIA GPU를 컨테이너 내에서 사용할 수 있도록 자동으로 설정해 주는 도구이다.

Nvidia의 특징

1. GPU 접근성 부여

호스트 시스템의 NVIDIA GPU 장치와 드라이버, CUDA 라이브러리 등을 컨테이너에 자동으로 마운트(mount)하여 컨테이너가 GPU에 직접 접근할 수 있게 해준다.

2. 간소화된 설정

사용자가 일일이 디바이스 파일이나 라이브러리 경로를 컨테이너에 매핑하는 복잡한 작업을 할 필요가 없게 만들어 준다
docker 명령어에 --gpus all 옵션만 붙여준다면 컨테이너가 GPU를 인식할 수 있도록 해준다

3. 구성 요소

컨테이너 런타임 라이브러리, 유틸리티, 그리고 컨테이너에 GPU 지원을 주입하는 스크립트 등으로 구성된다.
과거에는 nvidia-docker가 존재했는데 이제는 이걸 쓰지 않고 대체된 최신 솔루션이라고 한다

🥸 요약하자면 🥸,
컨테이너 환경에서 GPU를 사용하기 위한 인프라 역할을 해준다.

차이 정리

구분	NVIDIA Container Toolkit	NVIDIA Toolkit (CUDA ㅆoolkit)
주요 역할	컨테이너가 호스트 GPU를 사용할 수 있도록 연결	GPU 기반 애플리케이션을 개발하고 실행
목적	컨테이너화된 환경에서 GPU 인프라 구축	GPU 가속 컴퓨팅 애플리케이션 개발
구성 요소	컨테이너 런타임, 유틸리티, 훅 스크립트 등	CUDA 런타임, 컴파일러, 라이브러리, 개발 도구 등
필요성	컨테이너 환경에서 GPU를 사용하려면 필수	GPU 프로그래밍을 하려면 필수
설치 관계	GPU 드라이버와 별개로 컨테이너 환경 설정을 위해 설치	GPU 드라이버와 함께 설치되거나, 개발을 위해 추가 설치

---

그렇다면 Docker에서 어떻게 실행?

서버에서 NVIDIA Toolkit (CUDA Toolkit)만 설치했을 때 GPU를 사용하지 못한 이유는, 컨테이너 환경(Docker)과 호스트 시스템의 GPU를 연결해 주는 중간 다리가 없었기 때문이다.

용량이고 뭐고, docker가 runtime이 gpu로 지정이 되려면, container 상에서 적용이 가능한 Nvidia Container Toolkit이 필요한데, 이에 대하여 존재하지 않아서 계속 에러가 나는 것이었다.

NVIDIA Toolkit은 GPU 기반 애플리케이션 개발에 필요한 드라이버, 라이브러리, 컴파일러 등을 제공하지만, 이는 운영 체제에 직접 설치되는 것이다.

반면, Docker 컨테이너는 격리된 환경에서 실행되므로, 컨테이너가 호스트 시스템의 하드웨어 자원(이 경우, GPU)을 자동으로 인식하고 접근할 수 없다.

그렇다면, Docker에서 Nvidia container에 대하여 어떻게 설정하는지부터 확인하자!

Nvidia Container Toolkit 설치하기

• Nvidia Driver 존재 유무 확인

우선은 명령어로 GPU 드라이버가 존재하는지부터 확인하자!

nvidia-smi

처음 뜬 것이 아무것도 없고 available apt get nvidia-server... 등으로 시작한다면 새로 설치하면 된다

설치 후에 확인하면

nvidia-smi

다시 실행시에 다음처럼 보이면 성공이다!
(cuda 버전 확인 가능)

• Nvidia-Container-toolkit 설치하기
  이제 그 다음으로 nvidia-container-toolkit을 제대로 확인해보자

sudo apt-get update
sudo apt-get install -y nvidia-driver-550
sudo reboot

위에서 nvidia-server가 아닌 nvidia-driver를 설치해줘야한다.
알아서 버전에 맞게 설치해주면 된다.

• GPG 키 및 레포지토리 추가하기

# 키 저장 위치 생성
sudo mkdir -p /etc/apt/keyrings

# GPG 키 추가
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /etc/apt/keyrings/nvidia-container-toolkit.gpg

# 리포지토리 추가 (Ubuntu 24.04 = noble)
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)  # ubuntu24.04 → ubuntu24.04
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed "s#deb https://#deb [signed-by=/etc/apt/keyrings/nvidia-container-toolkit.gpg] https://#g" \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

나의 경우 ubuntu24.04 버전으로 진행했다.
각자의 환경에 맞춰서 설치해주면 된다!

• 패키지 설치

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

• docker 적용

# Docker 런타임에 nvidia를 기본으로 추가
sudo nvidia-ctk runtime configure --runtime=docker

# Docker 재시작
sudo systemctl restart docker

이제 Docker 설정까지 완료하면, GPU 환경에서 NVIDIA Container Toolkit을 통해 드라이버가 설정되는 것이다.

• docker에서 실행하기

docker run --gpus ....

이제 gpu 환경에서 실행을 하고 싶은 컨테이너가 있다면, 위와 같이 --gpus 옵션을 추가해주기만 하고, 평소 컨테이너 실행 명령어와 동일하게 작성해주면 된다!

---

그렇다면 궁금한 점은 여전히 존재한다.
Nvidia-toolkit을 설치해서 실행하려고 하면,
더이상 device 용량 부족으로 뜨던 문제를 어떻게 Container Toolkit은 바로 해결해준걸까?

NVIDIA Container Toolkit이 문제를 해결한 이유가 뭘까?

Docker 설정 변경: Container Toolkit을 설치하면,

nvidia-ctk runtime configure --runtime=docker

위와 같은 명령을 통해 Docker 데몬의 설정 파일(daemon.json)을 자동으로 설정에 대하여 수정하게 된다.

이 과정을 통해 Docker는 GPU 사용을 위한 새로운 "런타임"인 nvidia 런타임을 인식할 수 있게 된다.

docker는 우선적으로 미니 컴퓨터와 같은 개념이고, HOST에는 접근이 본래 불가능하기 때문에,
Nvidia-toolkit 자체는 HOST에 설치된 GPU이므로 docker에서는 함부로 접근이 불가능한 것이다.

• 자동 GPU 마운트
  그렇다면 위의 설정을 통하여 Docker에 --gpus 옵션을 사용하여 컨테이너를 실행하면,
  NVIDIA Container Toolkit이 작동하여 호스트에 설치된 GPU 장치(/dev/nvidia0, /dev/nvidia1 등)와 관련 라이브러리(/usr/lib/x86_64-linux-gnu/libcuda.so 등)를 컨테이너 내부에 자동으로 마운트하는 것이다!

즉, 사실상 내가 마주한 "device용량 부족" 오류는
실제 물리적인 용량 부족이 아니라,
컨테이너가 GPU 장치를 찾지 못하거나 접근할 수 없어 발생한 문제이다.

이제는 NVIDIA Container Toolkit이 이 연결 과정을 성공적으로 처리했기 때문에, 컨테이너가 정상적으로 GPU를 인식하고 사용할 수 있게 된 것이다.