Podman 컨테이너 환경에서 NVIDIA 그래픽 라이브러리 사용

Podman을 이용한 컨테이너를 사용할 때 호스트에 다음과 같은 작업을 한 번 해야 정상적으로 컨테이너에서 nvidia 그래픽카드 사용이 가능하다. 호스트 시스템은 Ubuntu 24.04이다.

1단계: 필수 권한 설정 (호스트 환경)

Rootless(비-루트 권한) 환경에서 Podman이 호스트의 그래픽 장치에 접근하려면 사용자에게 직접 렌더링 권한이 있어야 한다.
1) 사용자 그룹에 렌더링/비디오 권한 추가

sudo usermod -aG render $USER
sudo usermod -aG video $USER

2) 권한 적용을 위해 시스템 재부팅

sudo reboot

재부팅 후 터미널에 groups 명령어를 입력해 render와 video가 출력되는지 확인한다.

──────

2단계: NVIDIA Container Toolkit 설치 및 설정

GPU 드라이버 라이브러리들을 컨테이너 내부로 자동으로 연결해주는 도구(CDI)를 설치해야 한다.

• CDI (Container Device Interface): Podman이나 Docker 등 컨테이너 런타임이 호스트의 하드웨어(GPU)를 컨테이너 내부에 주입(Injection)하기 위해 사용하는 표준 규격

• 설정 파일 위치: /etc/cdi/nvidia.yaml (시스템 공용) 및 ~/.config/cdi/nvidia.yaml (사용자 전용)

1) NVIDIA Container Toolkit 설치 (이미 설치되어 있다면 최신 상태로 업데이트)
저장소 키 및 리스트 추가

  curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
  curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

2) 패키지 업데이트 및 설치

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

3) 기존 CDI 파일 제거
과거에 잘못 생성된 설정이 하나라도 남아있으면 Podman이 전체 장치 인식을 거부한다.

sudo rm -f /etc/cdi/nvidia.yaml /var/run/cdi/nvidia.yaml  ~/.config/cdi/nvidia.yaml

Podman(Docker) CDI 연동 및 NVIDIA 드라이버 업데이트 트러블슈팅 가이드

호스트 시스템의 NVIDIA 드라이버가 apt update를 통해 업데이트 된 후 갑자기 컨테이너 실행 때 cannot stat ... No such file or directory 에러가 발생.

원인은 호스트 시스템의 NVIDIA 드라이버가 업데이트되면서 기존 설치 경로가 변경됨. 하지만 기존 생성되어 있던 nvidia.yaml에는 이전 드라이버 버전(libEGL_nvidia.so.580.159.03 등)의 경로가 정적으로 하드코딩되어 있어, 컨테이너 실행 시 오류 발생.

해결 방법

드라이버가 업데이트될 때마다 수동으로 CDI 설정 파일을 새로 발급받아야 한다.
NVIDIA Container Toolkit을 사용하여 호스트 시스템의 현재 드라이버 상태에 맞게 설정 파일을 새로 생성한다.

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

주의사항 (버전 호환성 문제)

최신 버전의 nvidia-ctk 도구로 파일을 재생성하면 CDI 스펙 v0.7.0 규격으로 만들어지며, 내부에 additionalGids라는 최신 필드가 추가된다. 만약 호스트에 설치된 podman(내부 런타임 crun)이 구형 버전이라면 이 필드를 파싱하지 못해 다음과 같은 에러 메시지가 나타난다.

Error: setting up CDI devices: unresolvable CDI devices nvidia.com/gpu=1

이 에러가 발생할 경우, 재생성된 nvidia.yaml 파일을 구형 Podman이 읽을 수 있도록 수정해줘야 한다.

참고 링크
https://github.com/NVIDIA/nvidia-container-toolkit/issues/1860

1) 파일 에디터로 열기 (예: nano, vim)

    sudo vi /etc/cdi/nvidia.yaml

2) 버전 변경
최상단의 cdiVersion: 0.7.0 (또는 이상)을 cdiVersion: "0.5.0"으로 수정한다.
(Podman 5.1.0 부터 cdiVersion: 0.7.0을 지원하기 시작)

3) 미지원 필드 삭제
파일 내부에 있는 additionalGids: 블록과 그 하위 항목(예: - 44, - 110 등)들을 모두 찾아 삭제한다.
주의: additionalGids 외의 장치 이름(- name: "1")이나 다른 설정이 함께 지워지지 않도록 주의해야 한다.

4) 저장 후 완료
수정한 파일을 덮어쓴 뒤 Podman 컨테이너를 재시작하면 정상적으로 GPU가 할당된다.

3단계: 컨테이너에서 3D 가속 쓰기 - VirtualGL

여기까지 하면 컨테이너가 GPU 장치와 드라이버 라이브러리에 접근할 수 있다. 하지만 이것만으로 RViz나 Gazebo 같은 OpenGL 애플리케이션이 GPU로 렌더링되지는 않는다. 이 애플리케이션들은 X 서버를 통해 렌더링하려 하는데, 컨테이너 안에는 X 서버가 없기 때문이다. 이때 필요한 것이 VirtualGL이다.

VirtualGL 설치

GitHub 릴리스에서 .deb를 받아 설치하는 방법이 일반적이지만, 이미지 빌드에서는 apt 저장소를 등록하는 쪽이 관리하기 편하다.

RUN wget -qO - https://packagecloud.io/dcommander/virtualgl/gpgkey \
      | gpg --dearmor -o /etc/apt/trusted.gpg.d/VirtualGL.gpg && \
    echo "deb https://packagecloud.io/dcommander/virtualgl/any/ any main" \
      > /etc/apt/sources.list.d/VirtualGL.list && \
    apt-get update && \
    apt-get install -y --no-install-recommends virtualgl && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

VirtualGL은 기본적으로 렌더링을 담당할 X 디스플레이(보통 :0)를 필요로 한다. 하지만 EGL 백엔드를 쓰면 X 서버를 거치지 않고 GPU 장치에 직접 렌더링하기 때문에 헤드리스 컨테이너 환경에서 쓰기 좋다.

ENV VGL_DISPLAY=egl
ENV PATH="/opt/VirtualGL/bin:${PATH}"

이미지에 환경 변수로 넣어 두면 실행할 때마다 -d egl 옵션을 붙이지 않아도 된다.

그리고, podman 실행 때 아래 옵션을 추가한다. --device nvidia.com/gpu=1은 내 환경에서 맞춘 것이고 --device nvidia.com/gpu=all로 설정해도 된다.

--device nvidia.com/gpu=1
-e NVIDIA_DRIVER_CAPABILITIES=graphics,display,utility
-e VGL_DISPLAY=egl

NVIDIA_DRIVER_CAPABILITIES의 기본값은 compute,utility라서 CUDA는 되지만 OpenGL은 되지 않는다. graphics와 display를 명시해야 컨테이너 안으로 OpenGL/EGL 관련 라이브러리가 함께 연결된다. CDI 설정이 다 맞는데도 RViz만 안 뜬다면 이 항목을 먼저 확인하는 것이 좋다.

GPU 인덱스는 nvidia-smi 출력 순서와 같고, /etc/cdi/nvidia.yaml의 - name: "1" 항목에 대응한다. 앞의 트러블슈팅에서 나온 unresolvable CDI devices nvidia.com/gpu=1 에러가 이 지정이 해소되지 않을 때 발생하는 것이다.

옵션이 빠졌거나 Container Device Interface(CDI) 설정이 잘못되어 있으면 EGL 초기화 실패로 나타난다. 아래 명령으로 GPU 이름이 나오는지 확인한다.

vglrun glxinfo | grep "OpenGL renderer" 

이 설정을 실제로 적용한 Containerfile은 아래 링크에 있다.
https://github.com/hwjeon0123/robot-arm-study/blob/main/environment/Containerfile

호스트 쪽 원격 접속 환경은 Sunshine을 사용한 headless Linux의 원격 데스크탑 설정에 정리했다.