NPU 드라이버 설치¶

RBLN NPU Operator는 각 노드에 NPU 커널 드라이버를 설치하는 두 가지 방법을 지원합니다. 오퍼레이터 차트를 배포하기 전에 둘 중 하나를 선택하세요.

차트 기본값은 driver.enabled=false이므로, 컨테이너 드라이버 모드를 명시적으로 활성화하지 않으면 호스트 드라이버 모드가 사용됩니다.

컨테이너 드라이버 모드(driver.enabled=true): 오퍼레이터가 RBLNDriver CR의 스펙에 따라 DaemonSet을 배포하고, 커널 드라이버를 설치·관리합니다. 드라이버의 설치, 업그레이드, 롤백 등 라이프사이클을 오퍼레이터가 Kubernetes 방식으로 일관되게 제어해야 할 때 사용합니다.
호스트 드라이버 모드(driver.enabled=false): 오퍼레이터를 배포하기 전에 각 노드의 호스트 OS에 커널 드라이버를 직접 설치합니다(runfile 인스톨러, 배포판 패키지, dkms 등). 이후 오퍼레이터는 호스트에 설치된 드라이버를 자동으로 감지하고, 컨테이너 드라이버를 통한 설치, 업그레이드, 롤백은 수행하지 않습니다.

이 페이지에서는 두 설치 방식과 노드별 활성 모드를 확인하는 방법을 다룹니다. 오퍼레이터 차트 설치에 대해서는 NPU Operator 설치를 참고하세요.

컨테이너 드라이버 모드¶

helm install 또는 helm upgrade를 실행할 때 driver.enabled=true를 설정합니다. 오퍼레이터가 RBLNDriver CR을 생성하고 드라이버 DaemonSet을 배포한 뒤 각 노드의 커널 드라이버를 일관된 상태로 유지합니다.

driver:
  enabled: true

드라이버 이미지 선택, 업그레이드 롤아웃 정책, 수동 업그레이드, 노드별 업그레이드 제외 등 전체 라이프사이클은 NPU 드라이버 업그레이드 워크플로우를 참고하세요.

제품군별 드라이버 이미지¶

커널 드라이버 빌드는 NPU 제품군 하나만 지원하므로, 드라이버 이미지는 제품군별로 게시됩니다. 한 클러스터에서 여러 NPU 제품을 운영할 수 있도록 오퍼레이터는 제품군별로 드라이버를 결정하고, 노드의 rebellions.ai/npu.family 레이블을 사용해 노드 풀마다 이미지 경로를 조합합니다.

1	`<registry>/<org>/<family>/<name>:<version>-<kernel>-<os>`

driver.image.registry와 driver.image.repository에는 제품군을 넣지 마세요. 오퍼레이터가 제품군 세그먼트를 직접 삽입하므로, ATOM 노드에서는 rebellions/rbln-driver가 rebellions/atom/rbln-driver가 됩니다.

이에 따라 다음 두 가지 사항을 고려하세요.

클러스터에서 실행하는 드라이버 버전은 그 버전을 사용하는 모든 제품군의 경로에 게시되어 있어야 합니다. 하나의 RBLNDriver가 여러 제품군을 담당한다면 모든 제품군에 같은 버전이 있어야 하며, 버전이 다르다면 여러 드라이버 버전 운영을 참고하세요.
제품군 레이블은 오퍼레이터가 직접 관리하는 rbln-npu-family라는 NodeFeatureRule이 부여하며, 값은 atom과 같은 소문자 제품군 이름입니다. 노드에 레이블을 수동으로 붙일 필요는 없지만, 규칙이 적용되려면 Node Feature Discovery가 동작하고 있어야 합니다.

오퍼레이터는 풀을 롤아웃하기 전에 조합된 이미지를 확인하고, 이미지가 없으면 정확한 경로와 함께 DriverImageNotFound로 보고합니다. 롤아웃 전 레지스트리 확인을 참고하세요.

호스트 드라이버 모드¶

먼저 모든 NPU 노드에 커널 드라이버를 설치한 뒤(RBLN 드라이버 설치 가이드 참고), rbln-smi가 호스트의 PATH에 있는지 확인합니다. 그런 다음 driver.enabled=false로 오퍼레이터를 설치합니다.

호스트 드라이버 탐지에 rbln-smi가 필요합니다

오퍼레이터 validator는 chroot 환경에서 rbln-smi --version을 실행해 호스트 드라이버를 탐지합니다. 호스트의 PATH에 rbln-smi가 없으면 validator는 해당 노드에 호스트 드라이버가 없다고 판단합니다. 설치 전에 다음 명령으로 실행 파일 위치를 확인하세요.

$ which rbln-smi && rbln-smi --version

driver:
  enabled: false

또는 명령줄에서 직접 설정할 수도 있습니다.

$ export CHART_VERSION=0.5.0

$ helm install rbln-npu-operator \
     oci://docker.io/rebellions/rbln-npu-operator-chart \
     --version ${CHART_VERSION} \
     --namespace rbln-system --create-namespace \
     --set driver.enabled=false

driver.enabled=false이면 차트는 RBLNDriver CR을 생성하지 않고 드라이버 DaemonSet도 배포하지 않습니다. 다른 모든 컴포넌트들은 정상적으로 배포됩니다. 이들은 커널 모듈만 로드되어 있으면 동작하며, 커널 모듈의 설치 방식과 무관하게 동작하기 때문입니다.

운영 시 책임¶

커널 업데이트: 호스트 커널이 업그레이드된 경우, 드라이버를 반드시 재설치해야 합니다.
드라이버 업그레이드: 드라이버 업그레이드는 apt, yum, DKMS 등 기존 호스트 관리 도구를 사용해 진행합니다. 업그레이드 이후에는 노드를 재부팅하여 새 커널 모듈이 적용되도록 해야 합니다.

혼합 클러스터¶

컨테이너 드라이버 모드 노드와 호스트 드라이버 모드 노드는 하나의 RBLNClusterPolicy에서 함께 운영될 수 있습니다. driver.enabled=true로 설정되어 있어도, 오퍼레이터는 각 노드의 상태를 개별적으로 감지해 해당 노드에 맞는 방식으로 동작합니다.

노드에서 드라이버 DaemonSet이 시작됩니다.
Driver Manager initContainer가 chroot /host rbln-smi --version을 실행해 호스트에 설치된 드라이버를 확인합니다.
확인에 성공하면 Driver Manager는 노드에 rebellions.ai/npu.deploy.driver=pre-installed와 rebellions.ai/npu.deploy.rbln-smd=pre-installed 레이블을 추가하고 드라이버 컨테이너를 통해 커널 모듈을 설치하지 않고 종료합니다. 호스트 드라이버는 그대로 유지됩니다.
이후에도 같은 감지 로직이 반복 적용되며, 전체 동작은 멱등성을 보장합니다.
그 외 오퍼레이터가 관리하는 모든 컴포넌트들은 호스트에 설치된 커널 모듈을 사용해 정상적으로 배포·동작합니다.

이 자동 감지 기능을 통해 다음과 같은 두 가지 일반적인 시나리오를 지원합니다.

드라이버 설치 방식이 노드별로 혼재된 경우에도 정상적으로 동작합니다. 일부 노드는 호스트에 드라이버가 직접 설치되어 있고, 다른 노드는 컨테이너 드라이버를 사용할 수 있지만, 오퍼레이터가 각 노드에 맞는 설치 방식을 자동으로 선택하므로 별도의 노드별 설정은 필요 없습니다.
설치 후 노드를 호스트 드라이버 모드로 전환하는 경우에도 간단히 처리할 수 있습니다. 호스트에 커널 드라이버를 설치한 뒤 드라이버 파드를 재시작하면 드라이버 파드가 호스트 드라이버를 감지하여 컨테이너 기반 설치를 자동으로 중단합니다.

모든 노드가 호스트에 직접 설치된 드라이버를 사용하는 클러스터라면 driver.enabled=false를 사용하는 편이 좋습니다.

노드를 컨테이너 드라이버 모드로 다시 전환

호스트 드라이버가 감지된 노드에는 pre-installed 레이블이 그대로 남으며 오퍼레이터가 이를 자동으로 되돌리지 않습니다. 컨테이너 드라이버가 관리를 맡게 하려면 먼저 호스트 드라이버를 제거한 뒤 두 레이블을 모두 삭제하세요.

$ kubectl label node <node-name> rebellions.ai/npu.deploy.driver- rebellions.ai/npu.deploy.rbln-smd-

레이블을 삭제하면 오퍼레이터가 rebellions.ai/npu.deploy.driver=true를 다시 적용하고 드라이버 DaemonSet이 해당 노드에 스케줄링되어 컨테이너 드라이버가 커널 모듈을 설치·관리합니다.

노드별 활성 모드 확인¶

설치 후 각 노드가 어떤 모드를 사용하는지 확인합니다.

$ kubectl get nodes -L rebellions.ai/npu.deploy.driver -L rebellions.ai/npu.deploy.rbln-smd

값이 true인 경우 오퍼레이터가 관리하는 컨테이너 드라이버가 노드에서 활성화된 상태입니다.
값이 pre-installed인 경우 호스트에 드라이버가 이미 존재하는 것으로 감지되어, 컨테이너 드라이버를 통한 설치는 건너뜁니다. 이때 rebellions.ai/npu.deploy.rbln-smd 값도 pre-installed로 표시되며, 해당 노드에서 RSMD가 제외됨을 확인할 수 있습니다.