Registering the nvidia Runtime With containerd

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

목표

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

왜 중요한가

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

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

단계

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

기본 설정 파일 배치

/etc/containerd 디렉터리를 만들고 /opt/fixtures/gpu-airgap/containerd/config.toml.base 를 /etc/containerd/config.toml 로 복사하세요. 그리고 /root/toolkit 작업 디렉터리도 만드세요.

픽스처에 축약된 기본 설정이 있습니다. 실제 환경에서는 containerd config default 로 만듭니다.

nvidia 런타임 섹션 추가

config.toml 에 nvidia 런타임 섹션을 추가하세요. 섹션 헤더는 [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia] 이고 runtime_type = "io.containerd.runc.v2" 가 들어가야 합니다.

config version 2 의 CRI 플러그인 경로 아래 runtimes.<이름> 형태입니다. runtime_type 값이 핵심입니다.

런타임 옵션 지정

그 하위에 옵션 섹션을 추가하세요. [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options] 아래에 BinaryName = "/usr/bin/nvidia-container-runtime" 과 SystemdCgroup = true 가 있어야 합니다.

options 는 런타임 섹션의 하위 테이블입니다. 바이너리 경로와 cgroup 드라이버 두 키가 필요합니다.

기본 런타임 확인

default_runtime_name 값을 확인해 /root/toolkit/default.txt 에 다음 두 줄로 적으세요. DEFAULT=runc / WHY=runtimeclass (기본 런타임은 runc 여야 합니다. 바꾸지 마세요.)

default_runtime_name 은 runc 여야 합니다. 왜 그런지도 함께 기록하세요.

TOML 문법 검증

config.toml 을 TOML 파서로 읽어 version 값과 등록된 런타임 이름 목록을 /root/toolkit/parsed.txt 로 저장하세요. runc 와 nvidia 가 모두 보여야 합니다.

python3.11 이상에는 표준 라이브러리에 TOML 파서가 있습니다. 파싱에 성공하면 문법은 정상입니다.

CDI 스펙 배치

/etc/cdi/nvidia.yaml 이 존재하고 kind: nvidia.com/gpu 를 포함하는지 확인하세요. 없으면 만드세요. 그리고 최상위 키 목록을 /root/toolkit/cdi-keys.txt 로 저장하세요.

앞 코스에서 만든 것과 같은 구조입니다. 여기서는 배치 경로와 최소 키만 확인합니다.

RuntimeClass 작성

/root/toolkit/runtimeclass.yaml 을 작성하세요. apiVersion: node.k8s.io/v1, kind: RuntimeClass, metadata.name: nvidia, handler: nvidia 네 가지가 있어야 합니다.

apiVersion 과 kind, metadata.name, handler 네 가지가 필요합니다. handler 는 config.toml 의 런타임 이름과 같아야 합니다.

등록 검증 보고서

/root/toolkit/report.txt 를 다음 5줄로 만드세요. CONFIG_VERSION=2 / RUNTIME=nvidia / RUNTIME_TYPE=io.containerd.runc.v2 / SYSTEMD_CGROUP=true / HANDLER=nvidia

값은 작성한 파일을 파싱해 얻어야 합니다. 경로는 절대 경로로 적으세요.