containerd 에 nvidia 런타임 등록

목표

containerd 에 nvidia 런타임을 등록하고, TOML 문법을 검증하고, CDI 스펙과 RuntimeClass 를 작성합니다. 실제 GPU 없이도 설정의 정확성은 전부 검증할 수 있습니다.

왜 중요한가

"드라이버는 깔았고 nvidia-smi 도 되는데 컨테이너에서는 GPU 가 안 보인다" 는 신고의 원인은 대개 런타임 등록 누락입니다. 그리고 인터넷에서 주워 온 스니펫을 붙였는데 아무 효과가 없다면 대부분 config version 불일치입니다 — 섹션 헤더가 containerd 메이저 버전에 따라 통째로 바뀝니다.

또 하나 중요한 판단이 있습니다. default_runtime_name 을 nvidia 로 바꾸지 않는 것입니다. 바꾸면 GPU 를 안 쓰는 파드까지 그 런타임을 거치게 되어, 런타임 문제가 클러스터 전체로 번집니다. RuntimeClass 로 필요한 워크로드만 지정하는 것이 안전합니다.

단계

1. /etc/containerd 디렉터리를 만들고 /opt/fixtures/gpu-airgap/containerd/config.toml.base 를 /etc/containerd/config.toml 로 복사하세요. 그리고 /root/toolkit 작업 디렉터리도 만드세요.
2. config.toml 에 nvidia 런타임 섹션을 추가하세요. 섹션 헤더는 [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia] 이고 runtime_type = "io.containerd.runc.v2" 가 들어가야 합니다.
3. 그 하위에 옵션 섹션을 추가하세요. [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options] 아래에 BinaryName = "/usr/bin/nvidia-container-runtime" 과 SystemdCgroup = true 가 있어야 합니다.
4. default_runtime_name 값을 확인해 /root/toolkit/default.txt 에 다음 두 줄로 적으세요.
DEFAULT=runc / WHY=runtimeclass
(기본 런타임은 runc 여야 합니다. 바꾸지 마세요.)
5. config.toml 을 TOML 파서로 읽어 version 값과 등록된 런타임 이름 목록을 /root/toolkit/parsed.txt 로 저장하세요. runc 와 nvidia 가 모두 보여야 합니다.
6. /etc/cdi/nvidia.yaml 이 존재하고 kind: nvidia.com/gpu 를 포함하는지 확인하세요. 없으면 만드세요. 그리고 최상위 키 목록을 /root/toolkit/cdi-keys.txt 로 저장하세요.
7. /root/toolkit/runtimeclass.yaml 을 작성하세요. apiVersion: node.k8s.io/v1, kind: RuntimeClass, metadata.name: nvidia, handler: nvidia 네 가지가 있어야 합니다.
8. /root/toolkit/report.txt 를 다음 5줄로 만드세요.
CONFIG_VERSION=2 / RUNTIME=nvidia / RUNTIME_TYPE=io.containerd.runc.v2 / SYSTEMD_CGROUP=true / HANDLER=nvidia

참고

• TOML 파싱은 python3 -c "import tomllib;d=tomllib.load(open('/etc/containerd/config.toml','rb'));print(d['version'])" 형태입니다.
• 실제 환경에서는 nvidia-ctk runtime configure --runtime=containerd --set-as-default=false 가 2~3번을 대신해 줍니다.
• RuntimeClass 의 handler 는 config.toml 의 runtimes.<이름> 과 정확히 일치해야 합니다. 안 맞으면 파드가 RunContainerError 로 뜹니다.
• 흔한 실수 1: 섹션 헤더의 따옴표를 빼먹는 경우. TOML 에서 점이 포함된 키는 따옴표로 감싸야 합니다.
• 흔한 실수 2: SystemdCgroup 을 문자열 "true" 로 쓰는 경우. TOML 불리언이므로 따옴표 없이 true 입니다.

단계 8개

1. 기본 설정 파일 배치
2. nvidia 런타임 섹션 추가
3. 런타임 옵션 지정
4. 기본 런타임 확인
5. TOML 문법 검증
6. CDI 스펙 배치
7. RuntimeClass 작성
8. 등록 검증 보고서