ADR 0002: RKE2 GPU 클러스터에 NVIDIA GPU Operator 사용¶

1. 상태¶

Accepted

2. 결정 요약¶

RKE2 기반 GPU workload cluster에서 GPU enablement는 NVIDIA GPU Operator를 기본 방식으로 사용한다.

RKE2 설치는 Kubernetes bootstrap까지만 책임진다. GPU driver, container runtime integration, device plugin, GPU feature discovery, telemetry, validator는 RKE2 bootstrap 이후 별도 platform add-on으로 구성한다.

초기 구현은 RKE2 HelmChart resource로 NVIDIA GPU Operator를 설치한다. 장기적으로는 Argo CD가 관리하는 platform application으로 전환한다.

3. 배경¶

RKE2 cluster의 node가 Ready라고 해서 Kubernetes가 GPU를 사용할 수 있는 것은 아니다. Kubernetes scheduler가 GPU workload를 배치하려면 node의 Capacity와 Allocatable에 nvidia.com/gpu resource가 나타나야 한다.

GPU/A, GPU/C가 n/a로 보이는 상태는 RKE2 node join은 성공했지만 GPU 계층이 아직 Kubernetes에 연결되지 않았다는 뜻이다. 이 상태에서 RKE2를 재설치하는 것은 문제의 계층을 잘못 보는 것이다. 확인해야 할 대상은 host NVIDIA driver, libnvidia-ml, container runtime integration, NVIDIA device plugin이다.

GPU를 Kubernetes에 노출하는 데 필요한 계층은 다음과 같다.

NVIDIA GPU hardware
  |
  v
host NVIDIA kernel driver / libnvidia-ml
  |
  v
RKE2 containerd와 GPU injection 경로
  |
  v
NVIDIA device plugin
  |
  v
Kubernetes node allocatable resource: nvidia.com/gpu

병원 현장에서는 이 계층을 개별 스크립트와 수동 절차로 흩어 관리하면 운영 리스크가 커진다. driver 상태, runtime 설정, device plugin 상태, GPU metric 수집, validator 결과를 하나의 운영 단위로 볼 수 있어야 장애 대응과 감사 추적이 가능하다.

4. 선택 기준¶

이 결정에서 중요하게 본 기준은 다음과 같다.

RKE2가 관리하는 containerd와 충돌하지 않는 GPU runtime 구성
nvidia.com/gpu resource를 Kubernetes 표준 방식으로 노출
driver, toolkit, device plugin, feature discovery, monitoring을 하나의 lifecycle로 관리
병원 현장에서 설치 후 검증과 rollback 지점을 명확히 분리
Argo CD로 platform add-on을 관리할 수 있는 선언적 구조
향후 CDI/NRI, MIG, time-slicing, DCGM exporter 같은 GPU 운영 기능으로 확장 가능

5. 결정¶

GPU enablement는 NVIDIA GPU Operator를 기본 방식으로 사용한다.

GPU Operator는 NVIDIA driver, NVIDIA Container Toolkit, NVIDIA Device Plugin, GPU Feature Discovery, DCGM Exporter, validator 같은 구성요소를 하나의 Kubernetes add-on으로 관리한다. 이 방식은 각 구성요소를 Ansible task나 수동 명령으로 흩어 설치하는 것보다 cluster 상태를 설명하기 쉽고, upgrade와 검증 흐름을 한 곳에 모으기 좋다.

RKE2 공식 문서도 NVIDIA Operator를 RKE2 add-on으로 안내한다. 다만 host OS 요구사항은 여전히 중요하다. GPU를 pod에 올바르게 노출하려면 NVIDIA kernel driver와 libnvidia-ml이 host OS에서 정상 동작해야 한다. Operator가 driver 설치를 지원하지 않는 OS 조합이라면 host image나 별도 driver package 경로를 먼저 정해야 한다.

5-1. RKE2 bootstrap과 분리¶

GPU Operator는 make rke2/server/install이나 make rke2/agent/install 안에 숨겨서 실행하지 않는다.

RKE2 install playbook의 책임은 다음으로 제한한다.

RKE2 server/agent 설치
/etc/rancher/rke2/config.yaml 작성
RKE2 service start
node readiness 확인
kubeconfig export와 merge

GPU Operator의 책임은 별도 단계로 둔다.

NVIDIA driver와 library 상태 확인
RKE2 containerd에 맞는 GPU injection 경로 구성
NVIDIA device plugin 배포
GPU node label과 feature discovery 구성
nvidia.com/gpu resource 노출
GPU workload validation

이렇게 분리하면 RKE2 join 실패와 GPU driver/runtime 실패를 서로 다른 문제로 다룰 수 있다.

5-2. RKE2 containerd 기준¶

RKE2의 Kubernetes runtime은 RKE2가 관리하는 containerd다. DGX Spark host에 Docker나 NVIDIA Container Runtime이 이미 설치되어 있더라도, Kubernetes workload는 Docker daemon 경로가 아니라 RKE2 containerd 경로에서 실행된다.

따라서 GPU runtime 설정도 RKE2 containerd 기준으로 검증한다.

최신 NVIDIA GPU Operator는 CDI와 NRI Plugin 경로를 제공한다. 이 방식은 GPU injection을 container runtime 표준 인터페이스에 가깝게 다루고, containerd 설정 파일을 직접 수정하는 부담을 줄인다. 특히 RKE2처럼 containerd 구성이 distribution 내부에 있는 환경에서는 runtime 설정을 덜 건드리는 방향이 운영상 유리하다.

5-3. 초기 manifest¶

초기 manifest는 RKE2 HelmChart resource로 표현한다.

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: gpu-operator
  namespace: kube-system
spec:
  repo: https://helm.ngc.nvidia.com/nvidia
  chart: gpu-operator
  version: v26.3.2
  targetNamespace: gpu-operator
  createNamespace: true
  valuesContent: |-
    driver:
      enabled: true
    cdi:
      nriPluginEnabled: true

초기값은 driver.enabled=true로 둔다. 즉 host에 호환 가능한 NVIDIA driver가 없으면 GPU Operator가 driver 설치를 시도한다. 병원 표준 OS image에서 NVIDIA driver를 별도로 관리하게 되면 driver.enabled=false로 전환한다.

cdi.nriPluginEnabled=true는 RKE2 containerd 설정을 직접 수정하는 부담을 줄이기 위한 선택이다. NRI Plugin을 사용하면 nvidia runtime class나 containerd config patch에 덜 의존할 수 있다.

5-4. 적용 시점¶

GPU Operator는 RKE2 설치 직후 자동으로 적용하지 않는다. 아래 순서로 명시적으로 적용한다.

1. host static IP 적용
2. inventory 렌더링
3. RKE2 server / agent 설치
4. kubeconfig merge
5. GPU Operator 적용
6. nvidia.com/gpu resource 검증
7. Argo CD workload 배포

GPU Operator는 container runtime이나 driver 계층을 건드릴 수 있다. RKE2 문서도 NVIDIA Operator가 containerd에 hangup을 보내 RKE2가 재시작될 수 있음을 경고한다. 병원 현장에서는 업무 시간, workload drain, rollback 계획을 고려해 적용한다.

5-5. 검증 기준¶

GPU Operator 적용 후 아래가 확인되어야 한다.

gpu-operator namespace의 operator pod가 정상 동작한다.
GPU node에 nvidia.com/* label이 붙는다.
node Capacity와 Allocatable에 nvidia.com/gpu가 나타난다.
CUDA sample pod가 resources.limits.nvidia.com/gpu: 1로 scheduling되고 정상 실행된다.

이 검증이 끝나야 RKE2 GPU cluster가 GPU workload를 받을 준비가 됐다고 본다.

6. 대안¶

6-1. NVIDIA device plugin만 직접 설치¶

NVIDIA device plugin만 설치하면 nvidia.com/gpu resource를 노출할 수 있다.

하지만 driver, container toolkit, feature discovery, monitoring, validator를 별도로 관리해야 한다. 병원 현장 운영에서는 구성요소가 흩어지면 장애 대응과 upgrade 경로가 불명확해진다.

결정: 지금 단계에서는 사용하지 않는다.

6-2. host image에 모든 NVIDIA stack 사전 설치¶

DGX 계열 장비나 병원 표준 image에 NVIDIA driver와 toolkit을 미리 넣을 수 있다.

이 방식은 현장 설치 시간을 줄이고 driver version을 통제하기 쉽다. 하지만 Kubernetes device plugin, feature discovery, DCGM exporter, validator는 여전히 cluster add-on으로 관리해야 한다. 또한 host image가 바뀔 때 Kubernetes 쪽 검증 흐름이 분리되어 있지 않으면 문제가 숨어들 수 있다.

결정: host driver 사전 설치는 향후 선택지로 남긴다. 그 경우에도 Kubernetes add-on은 GPU Operator로 관리하고 driver.enabled=false로 전환한다.

6-3. Ansible로 driver와 toolkit 직접 설치¶

Ansible로 NVIDIA driver, container toolkit, device plugin을 직접 설치할 수 있다.

하지만 kernel module, OS package, container runtime, Kubernetes DaemonSet lifecycle이 한 playbook에 섞인다. RKE2 install playbook의 책임이 커지고, 실패 시 RKE2 문제인지 GPU 문제인지 분리하기 어려워진다.

결정: 사용하지 않는다.

7. 결과¶

긍정적 영향:

GPU driver/runtime/device plugin/monitoring을 하나의 platform add-on으로 관리할 수 있다.
nvidia.com/gpu resource 노출 여부를 Kubernetes 상태로 검증할 수 있다.
RKE2 install과 GPU enablement의 책임이 분리된다.
Argo CD platform application으로 전환하기 쉽다.
CDI/NRI 경로를 통해 RKE2 containerd 설정 변경 부담을 줄일 수 있다.

부정적 영향:

GPU Operator는 privileged workload와 host-level 변경을 포함할 수 있다.
driver 설치를 Operator에 맡기면 OS/kernel compatibility를 별도로 확인해야 한다.
Operator 적용 중 RKE2/containerd 재시작이 발생할 수 있다.
air-gapped 병원 환경에서는 NVIDIA chart와 image mirror 전략이 필요하다.

중립적 영향:

RKE2를 선택해도 GPU driver 검증은 별도로 필요하다.
host driver를 사전 설치하는 운영 모델로 바뀌면 driver.enabled=false로 전환해야 한다.
MIG, time-slicing, DCGM metric 연동은 초기 범위가 아니라 단계적 enablement 대상이다.

8. 후속 작업¶

sites/tirosh-home/rke2/gpu-operator.helmchart.yaml을 추가한다.
make rke2/gpu/operator/apply target을 추가한다.
GPU Operator 적용 후 nvidia.com/gpu resource와 CUDA sample workload를 검증한다.
GPU Operator를 장기적으로 Argo CD platform application으로 전환한다.
병원 현장 air-gapped 배포를 위한 NVIDIA chart/image mirror 전략을 별도 이슈로 분리한다.