CDIスペックを書く

한국어 원문으로 표시합니다.

목표

CDI(Container Device Interface) 스펙을 직접 작성하고, 문법과 배치를 검증하고, podman run --device 인자 형식을 정확히 씁니다.

왜 중요한가

CDI 는 "이 장치를 컨테이너에 넣으려면 어떤 디바이스 노드·라이브러리·환경변수가 필요한가" 를 기술하는 벤더 중립 표준입니다. 예전의 런타임 훅 방식보다 투명하고 이식성이 높아, podman·containerd·CRI-O 가 모두 지원합니다. 실무에서는 nvidia-ctk cdi generate 가 자동으로 만들어 주지만, 드라이버 업데이트 후 GPU 가 안 잡히는 사고의 원인이 대부분 스펙 재생성 누락이기 때문에 그 내용을 읽을 줄 알아야 합니다.

이 환경에는 실제 GPU 가 없습니다. 그래서 스펙의 문법·구조·배치와 --device 인자 형식을 채점합니다 — 현장에서 실수가 나는 지점이 정확히 거기입니다.

단계

/etc/cdi 디렉터리를 만드세요. 그리고 /root/cdi 작업 디렉터리도 만드세요.
/etc/cdi/nvidia.yaml 을 만드세요. 최상위에 cdiVersion: "0.6.0" 과 kind: nvidia.com/gpu 가 있어야 하고, devices 배열에 name: "0" 인 항목이 하나 있어야 합니다. 그 항목의 containerEdits.deviceNodes 에는 /dev/nvidia0, /dev/nvidiactl, /dev/nvidia-uvm 세 경로가 들어가야 합니다.
그 파일을 YAML 로 파싱해 최상위 키 목록을 /root/cdi/parsed.txt 로 저장하세요. cdiVersion, kind, devices 세 키가 모두 보여야 합니다.
devices 배열에 name: "all" 인 두 번째 항목을 추가하세요. 그 항목의 deviceNodes 에도 최소 두 개의 경로가 있어야 합니다.
name: "0" 항목의 containerEdits 에 mounts 를 추가하세요. hostPath 와 containerPath 가 모두 /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.550.90.07 이고, options 에는 ro, nosuid, nodev, bind 네 값이 들어가야 합니다.
name: "0" 항목의 containerEdits 에 hooks 를 추가하세요. hookName 은 createContainer, path 는 /usr/bin/nvidia-ctk, args 는 ["nvidia-ctk", "hook", "update-ldcache"] 입니다.
/root/cdi/run.sh 를 작성하세요. podman run 으로 nvidia.com/gpu=all 장치를 요청하는 명령이 들어 있어야 합니다. --device 인자 값의 형식이 정확해야 합니다.
/root/cdi/report.txt 를 다음 5줄로 만드세요. 값은 작성한 스펙을 파싱해 얻어야 합니다. CDI_VERSION=0.6.0 / KIND=nvidia.com/gpu / DEVICES=<devices 배열 길이> / NODES_DEV0=<name 이 "0" 인 장치의 deviceNodes 개수> / SPEC_PATH=/etc/cdi/nvidia.yaml

참고

YAML 파싱은 python3 -c "import yaml,sys;d=yaml.safe_load(open('/etc/cdi/nvidia.yaml'));print(list(d))" 형태로 합니다.
--device 값 형식은 <kind>=<장치이름> 입니다.
실제 환경에서는 nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml 가 이 파일을 만들어 줍니다.
흔한 실수 1: kind 를 nvidia/gpu 처럼 쓰는 경우. 벤더 부분은 도메인 형식(nvidia.com)이어야 합니다.
흔한 실수 2: 장치 이름 "0" 을 따옴표 없이 써서 YAML 이 숫자로 파싱하는 경우. 문자열이어야 합니다.

CDI 디렉터리 준비

/etc/cdi 디렉터리를 만드세요. 그리고 /root/cdi 작업 디렉터리도 만드세요.

표준 경로는 두 곳입니다. 영구 스펙이 놓이는 쪽을 쓰세요.

최소 스펙 작성

/etc/cdi/nvidia.yaml 을 만드세요. 최상위에 cdiVersion: "0.6.0" 과 kind: nvidia.com/gpu 가 있어야 하고, devices 배열에 name: "0" 인 항목이 하나 있어야 합니다. 그 항목의 containerEdits.deviceNodes 에는 /dev/nvidia0, /dev/nvidiactl, /dev/nvidia-uvm 세 경로가 들어가야 합니다.

최상위에 두 개의 키와 devices 배열이 필요합니다. kind 는 도메인 형식의 벤더와 클래스를 슬래시로 잇습니다.

YAML 문법 검증

그 파일을 YAML 로 파싱해 최상위 키 목록을 /root/cdi/parsed.txt 로 저장하세요. cdiVersion, kind, devices 세 키가 모두 보여야 합니다.

python3 의 yaml 모듈로 읽어 보면 문법 오류가 즉시 드러납니다. 파싱 결과를 요약해 저장하세요.

두 번째 장치 추가

devices 배열에 name: "all" 인 두 번째 항목을 추가하세요. 그 항목의 deviceNodes 에도 최소 두 개의 경로가 있어야 합니다.

all 은 관례적으로 모든 장치를 뜻하는 이름입니다. devices 배열에 항목을 하나 더 넣으세요.

라이브러리 마운트 추가

name: "0" 항목의 containerEdits 에 mounts 를 추가하세요. hostPath 와 containerPath 가 모두 /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.550.90.07 이고, options 에는 ro, nosuid, nodev, bind 네 값이 들어가야 합니다.

mounts 항목은 hostPath, containerPath, options 세 키를 갖습니다. options 는 문자열 배열입니다.

훅 추가

name: "0" 항목의 containerEdits 에 hooks 를 추가하세요. hookName 은 createContainer, path 는 /usr/bin/nvidia-ctk, args 는 ["nvidia-ctk", "hook", "update-ldcache"] 입니다.

hooks 항목에는 hookName, path, args 가 들어갑니다. 컨테이너 생성 시점 훅 이름을 쓰세요.

실행 커맨드 작성

/root/cdi/run.sh 를 작성하세요. podman run 으로 nvidia.com/gpu=all 장치를 요청하는 명령이 들어 있어야 합니다. --device 인자 값의 형식이 정확해야 합니다.

--device 의 값은 kind 와 장치 이름을 등호로 이은 형식입니다. 스크립트로 남기세요.

스펙 검증 보고서

/root/cdi/report.txt 를 다음 5줄로 만드세요. 값은 작성한 스펙을 파싱해 얻어야 합니다. CDI_VERSION=0.6.0 / KIND=nvidia.com/gpu / DEVICES=<devices 배열 길이> / NODES_DEV0=<name 이 "0" 인 장치의 deviceNodes 개수> / SPEC_PATH=/etc/cdi/nvidia.yaml

값은 실제 작성한 스펙을 파싱해 얻어야 합니다. 개수는 배열 길이입니다.