CDI 스펙 작성하기

목표

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

왜 중요한가

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

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

단계

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

단계 8개

1. CDI 디렉터리 준비
2. 최소 스펙 작성
3. YAML 문법 검증
4. 두 번째 장치 추가
5. 라이브러리 마운트 추가
6. 훅 추가
7. 실행 커맨드 작성
8. 스펙 검증 보고서