RBLN NPU Operator 설치

이 문서는 Helm 차트를 사용해 RBLN NPU Operator를 새로 설치하는 방법과 설치 검증, NPU 워크로드 빠른 시작, 모델별 스케줄링, 차트 사용자 옵션을 다룹니다.

오퍼레이터의 아키텍처 개요는 RBLN NPU Operator를 참고하세요. 업그레이드 및 제거는 NPU Operator 업그레이드와 NPU Operator 제거를 참고하세요.

사전 요구사항

• kubectl과 helm을 사용할 수 있는 Kubernetes 1.19 이상 클러스터
• Helm 3.8 이상(OCI 레지스트리 지원 필요)
• Node Feature Discovery가 클러스터에 설치되어 있어야 합니다. 오퍼레이터와 라이프사이클을 분리하려면 업스트림 Helm 차트를 사용해 별도의 node-feature-discovery 네임스페이스에 NFD를 설치하는 것을 권장합니다. 차트에 포함된 nfd.enabled=true 옵션은 빠른 테스트에는 편리하지만 NFD의 라이프사이클이 이 Helm 릴리스에 종속됩니다.
• 오퍼레이터 전용 네임스페이스(예: rbln-system)
• NPU가 장착된 워커 노드

Helm이 설치되어 있지 않거나 버전이 3.8 미만이면 먼저 설치합니다.

$ curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 \
  && chmod 700 get_helm.sh \
  && ./get_helm.sh

이미지 풀 시크릿 생성

드라이버 컨테이너 이미지와 rbln-daemon 컨테이너 이미지는 repo.rebellions.ai에 호스팅되며, 접근하려면 RBLN Portal 계정 인증이 필요합니다. 설치하기 전에 오퍼레이터 네임스페이스에 docker-registry 시크릿을 생성하세요.

$ kubectl create secret docker-registry drivercred \
  --docker-server=repo.rebellions.ai \
  --docker-username=<your-username> \
  --docker-password=<your-password> \
  --docker-email=<your-email> \
  -n rbln-system

이 시크릿 이름을 그대로 사용하면 차트 기본값인 driver.imagePullSecrets와 일치하므로 별도로 Helm 값을 재정의할 필요가 없습니다.

드라이버 설치

오퍼레이터 차트를 배포하기 전에 오퍼레이터가 컨테이너로 커널 드라이버를 설치할지, 각 호스트에 직접 설치된 드라이버를 감지하도록 할지 결정해야 합니다. 두 모드와 driver.enabled 차트 값으로 설정하는 방법은 NPU 드라이버 설치를 참고하세요.

OCI 레지스트리에서 NPU Operator 설치

v0.3.4부터 차트는 OCI 아티팩트로 Docker Hub의 oci://docker.io/rebellions/rbln-npu-operator-chart에 게시됩니다. 재현 가능한 설치를 위해 버전을 명시적으로 고정하세요. 사용 가능한 버전은 Docker Hub의 차트 페이지에서 확인할 수 있습니다.

$ export CHART_VERSION=0.4.0

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

개별 값은 --set으로 재정의할 수 있습니다.

$ export CHART_VERSION=0.4.0

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

또는 사용자 정의 values 파일을 전달할 수 있습니다.

$ export CHART_VERSION=0.4.0

$ helm install rbln-npu-operator \
     oci://docker.io/rebellions/rbln-npu-operator-chart \
     --version ${CHART_VERSION} \
     --namespace rbln-system --create-namespace \
     -f my-values.yaml

이전 차트 리포지토리

이전 버전(≤0.3.3)은 GitHub Pages 차트 리포지토리(https://rbln-sw.github.io/rbln-npu-operator)에서 계속 받을 수 있지만, 새 릴리스는 OCI에만 게시됩니다.

설치 검증

Helm 설치가 성공적으로 완료되면 RBLNClusterPolicy가 존재하고 오퍼레이터에 의해 반영되었는지 확인합니다. 두 CRD 모두 클러스터 범위 리소스이므로 -n 플래그가 필요하지 않습니다.

$ kubectl get rblnclusterpolicies.rebellions.ai
NAME                  STATUS   AGE
rbln-cluster-policy   ready    8m

드라이버 관리가 활성화되어 있다면 RBLNDriver 커스텀 리소스가 생성되었는지 확인합니다.

$ kubectl get rblndrivers.rebellions.ai
NAME          STATUS   AGE
rbln-driver   ready    99m

STATUS 열은 .status.state(ready 또는 notReady)를 반영하며, 오퍼레이터가 이 값을 갱신합니다.

다음으로 컨트롤러와 컴포넌트 Pod가 오퍼레이터 네임스페이스에서 실행 중인지 확인합니다.

$ kubectl get pods -n rbln-system
NAME                                             READY   STATUS    AGE
controller-manager-797798d7b8-rjzht              1/1     Running   8m
rbln-daemon-45k2k                                1/1     Running   8m
rbln-device-plugin-4qgxc                         1/1     Running   8m
rbln-metrics-exporter-jghbg                      1/1     Running   8m
rbln-npu-feature-discovery-zg47r                 1/1     Running   8m
rbln-container-toolkit-ttz2c                     1/1     Running   8m
rbln-driver-ubuntu22.04-6.8.0-90-generic-6gtrc   1/1     Running   8m
rbln-operator-validator-qhf4t                    1/1     Running   8m

모든 Pod가 Running이면 오퍼레이터가 정상 상태입니다. Pod 이름은 rbln-<component>-* 패턴을 따릅니다. 각 컴포넌트의 역할은 핵심 컴포넌트를 참고하세요. 드라이버 Pod의 접미사(<os>-<kernel>)는 NFD 라벨로 구성됩니다. 규칙은 드라이버 이미지 선택을 참고하세요.

특정 Pod가 멈춰 있거나 CrashLoopBackOff 상태라면 kubectl logs <pod> -n rbln-system으로 로그를 확인하고, 누락된 사전 요구사항이 없는지 Helm 값을 점검하세요.

오퍼레이터가 드라이버 컨테이너로 드라이버를 설치하는 경우(차트의 driver.enabled=true)에는 커널 모듈이 로드되었는지, 요청한 드라이버 버전과 일치하는지 확인할 수 있습니다. 동작 중인 드라이버 확인을 참고하세요.

NPU 상태 확인

각 노드에 대해 Kubernetes가 보고하는 NPU 용량을 확인하면 Device Plugin이 예상한 리소스를 노출했는지 확인할 수 있습니다. devicePlugin.useGenericResourceName: true(Device Plugin v0.4.0부터 차트 기본값)이면 오퍼레이터는 일반 리소스 이름인 rebellions.ai/npu를 노출합니다.

$ kubectl get nodes -o custom-columns=NAME:.metadata.name,NPUs:.status.capacity.'rebellions\.ai/npu'
NAME                            NPUs
rbln-npu-worker-01              16

클러스터에 여러 NPU 모델이 있고 워크로드를 특정 모델에 스케줄링해야 한다면, 일반 rebellions.ai/npu 리소스를 NPU Feature Discovery가 부여하는 제품별 노드 라벨과 함께 사용하세요. 아래 특정 NPU 제품 지정하기를 참고하세요.

NPU를 사용하는 Pod 생성

1. 매니페스트를 작성합니다(예: npu-demo-pod.yaml). 이 예시는 4개의 rebellions.ai/npu 디바이스를 요청합니다.

   apiVersion: v1
   kind: Pod
   metadata:
     name: npu-pod
   spec:
     containers:
       - name: ubuntu
         image: ubuntu:latest
         imagePullPolicy: IfNotPresent
         command: ["/bin/bash", "-c", "--"]
         args: ["while true; do sleep 300000; done;"]
         resources:
           limits:
             rebellions.ai/npu: 4
   

2. Pod를 생성합니다.

   $ kubectl apply -f npu-demo-pod.yaml
   

3. Pod 상태와 리소스 할당을 확인합니다.

   $ kubectl get pod npu-pod
   

   kubectl describe pod npu-pod로 요청한 NPU 리소스가 바인딩되었는지, Pod가 NPU 장착 노드에 스케줄링되었는지 확인합니다.

특정 NPU 제품 지정하기

여러 NPU 제품(예: RBLN-CA25와 RBLN-CR03 카드)이 혼재된 클러스터에서는 일반 rebellions.ai/npu 리소스를 요청한 Pod가 NPU가 장착된 어느 노드에든 스케줄링될 수 있습니다. NPU Feature Discovery가 부여하는 제품별 노드 라벨인 rebellions.ai/npu.product를 nodeSelector 또는 nodeAffinity와 함께 사용해 워크로드를 특정 모델에 고정하세요.

nodeSelector: 단일 제품

apiVersion: v1
kind: Pod
metadata:
  name: npu-pod-ca25
spec:
  nodeSelector:
    rebellions.ai/npu.product: RBLN-CA25
  containers:
    - name: workload
      image: ubuntu:latest
      resources:
        limits:
          rebellions.ai/npu: 1

nodeAffinity: 여러 제품

apiVersion: v1
kind: Pod
metadata:
  name: npu-pod-atom-family
spec:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: rebellions.ai/npu.family
                operator: In
                values: [ATOM]
  containers:
    - name: workload
      image: ubuntu:latest
      resources:
        limits:
          rebellions.ai/npu: 1

이전 카드별 리소스 이름

카드별 리소스 이름(rebellions.ai/ATOM, rebellions.ai/REBEL)은 더 이상 권장되지 않습니다. 위 예시처럼 일반 rebellions.ai/npu 리소스와 NFD 라벨을 함께 사용하는 방식을 권장합니다. 전체 라벨 레퍼런스는 RBLN NPU Feature Discovery를 참고하세요.

설정 레퍼런스

아래 표는 values.yaml의 주요 설정 항목을 정리한 것입니다. 각 절은 핵심 컴포넌트 개요의 항목과 대응됩니다.

이 값들은 helm install 또는 helm upgrade를 실행할 때 --set <key>=<value>(또는 -f my-values.yaml)로 전달할 수 있습니다.

아래 표에 없는 키를 포함해 차트의 전체 values 목록과 템플릿 주석을 보려면 다음을 실행하세요.

$ export CHART_VERSION=0.4.0

$ helm show values oci://docker.io/rebellions/rbln-npu-operator-chart --version ${CHART_VERSION}

image.* 블록은 표준 Helm 차트 규칙에 따라 4개의 하위 키를 사용합니다.

image:
  registry: <registry>
  repository: <repository>
  tag: <chart default>     # 실제 값은 차트가 고정합니다. 위 `helm show values`를 참고하세요
  pullPolicy: <pullPolicy>

아래 기본값 열에서는 이 정보를 <registry>/<repository>:<tag> 형태와 둘째 줄의 pullPolicy:로 압축해 표시합니다.

차트 전반

키	설명	기본값
nameOverride	모든 하위 리소스 이름에 적용되는 접두어. 여러 오퍼레이터 인스턴스를 동시에 운영해 충돌이 발생하면 이 값을 변경합니다.	rbln-npu-operator
workloadType	클러스터의 워크로드 모드. KubeVirt 배포에는 vm-passthrough로 설정합니다. 이 모드에서는 CRD가 vfioManager.enabled와 sandboxDevicePlugin.enabled도 true인지 검증합니다.	container
nfd.enabled	차트가 Node Feature Discovery를 하위 차트로 함께 배포할지 여부. NFD의 라이프사이클을 오퍼레이터와 분리하려면 false로 두고 업스트림 Helm 차트로 별도 설치하세요. 빠른 테스트에만 true로 설정합니다.	false
podDefaults.labels	오퍼레이터가 관리하는 모든 DaemonSet Pod에 적용되는 라벨(제거된 daemonsets 블록을 대체).	{}
podDefaults.annotations	오퍼레이터가 관리하는 모든 DaemonSet Pod에 적용되는 어노테이션.	{}
podDefaults.tolerations	오퍼레이터가 관리하는 모든 DaemonSet Pod에 적용되는 톨러레이션.	[]
podDefaults.priorityClassName	오퍼레이터가 관리하는 모든 DaemonSet Pod에 적용되는 PriorityClass.	""

Operator

키	설명	기본값
operator.image.*	controller-manager Pod의 이미지. 특정 오퍼레이터 버전으로 고정하려면 tag를 덮어씁니다.	docker.io/rebellions/rbln-npu-operator:<chart default> pullPolicy: IfNotPresent
operator.replicas	오퍼레이터 Pod 개수. 고가용성을 위해 2 이상으로 늘리세요.	1
operator.resources.requests	오퍼레이터 Pod에 보장되는 최소 리소스.	cpu: 50m, memory: 128Mi
operator.resources.limits	오퍼레이터 Pod의 최대 리소스.	cpu: 500m, memory: 256Mi
operator.service.type	오퍼레이터의 webhook/metrics 엔드포인트 Service 타입. ingress 또는 service mesh와 통합할 때 변경합니다.	ClusterIP
operator.service.port	Service 포트.	8443
operator.service.targetPort	Service가 전달하는 컨테이너 포트.	8443
operator.securityContext.runAsNonRoot	Pod 수준 securityContext. 클러스터 보안 정책에 맞춰 조정합니다.	true
operator.affinity	오퍼레이터 Pod의 affinity(예: control-plane 노드 고정).	{}
operator.tolerations	오퍼레이터 Pod의 톨러레이션(예: taint가 설정된 노드에 스케줄링 허용).	[]

Driver Manager

키	설명	기본값
driver.enabled	오퍼레이터가 NPU 드라이버를 설치·관리할지 여부. 호스트에 드라이버가 미리 설치되어 있다면 false로 둡니다.	false
driver.image.*	드라이버 컨테이너 이미지. 사설 미러나 특정 드라이버 릴리스로 고정하려면 값을 재정의합니다.	repo.rebellions.ai/rebellions/rbln-driver:<chart default> pullPolicy: IfNotPresent
driver.imagePullSecrets	드라이버 이미지의 이미지 풀 시크릿. 앞에서 만든 drivercred 이름을 사용하지 않는다면 실제 시크릿 이름에 맞게 변경하세요.	[drivercred]
driver.nodeSelector	드라이버 Pod를 특정 노드로 제한합니다.	{}
driver.tolerations	드라이버 Pod의 톨러레이션.	[]
driver.annotations	드라이버 Pod의 어노테이션.	{}
driver.priorityClassName	Pod PriorityClass. 비워두면 CRD가 system-node-critical로 기본 설정합니다.	""
driver.resources	드라이버 Pod의 CPU/메모리 requests/limits. CRD 필드는 필수이며, 비워두면 차트가 기본값을 채웁니다.	{}
driver.env	드라이버 컨테이너에 전달되는 환경 변수(예: 로그 레벨).	[]
driver.manager.image.*	노드 단위 reconciliation을 수행하는 driver-manager initContainer 이미지.	docker.io/rebellions/rbln-k8s-driver-manager:<chart default> pullPolicy: IfNotPresent

driver.upgradePolicy.* 키(autoUpgrade, drain, reboot 등)는 NPU 드라이버 업그레이드 워크플로우에서 다룹니다.

Device Plugin

키	설명	기본값
devicePlugin.enabled	표준 컨테이너 Device Plugin 배포 여부. DRA 전용(draKubeletPlugin)이나 VM 전용 워크로드만 사용한다면 비활성화합니다.	true
devicePlugin.image.*	Device Plugin 이미지.	docker.io/rebellions/k8s-device-plugin:<chart default> pullPolicy: IfNotPresent
devicePlugin.useGenericResourceName	일반 rebellions.ai/npu 리소스를 노출할지 여부. true로 유지하세요. false로 설정하면 권장하지 않는 카드별 명명 모드로 동작합니다.	true

DRA Driver

키	설명	기본값
draKubeletPlugin.enabled	Kubernetes 1.34 이상에서 Dynamic Resource Allocation을 사용할 때 활성화합니다. devicePlugin.enabled와 동시에 사용할 수 없습니다.	false
draKubeletPlugin.image.*	DRA kubelet 플러그인 이미지.	docker.io/rebellions/k8s-dra-driver-npu:<chart default> pullPolicy: IfNotPresent
draKubeletPlugin.driverName	드라이버 이름. DeviceClass.spec.config.driver에서 참조하는 값과 일치해야 합니다.	npu.rebellions.ai
draKubeletPlugin.kubeletRegistrarDirectoryPath	플러그인이 kubelet에 등록되는 호스트 경로.	/var/lib/kubelet/plugins_registry
draKubeletPlugin.kubeletPluginsDirectoryPath	플러그인 소켓이 위치하는 호스트 경로.	/var/lib/kubelet/plugins
draKubeletPlugin.healthcheckPort	플러그인 헬스체크 엔드포인트의 TCP 포트.	51515

전체 DRA 사용법은 NPU DRA Driver를 참고하세요.

Sandbox Device Plugin

키	설명	기본값
sandboxDevicePlugin.enabled	VFIO 기반 Sandbox Device Plugin 배포 여부. KubeVirt 등 VM 환경에서 활성화합니다.	false
sandboxDevicePlugin.image.*	Sandbox Device Plugin 이미지.	docker.io/rebellions/k8s-device-plugin:<chart default> pullPolicy: IfNotPresent
sandboxDevicePlugin.resourceList[]	카드별 VFIO 리소스 매핑. 새 SKU가 추가되면 항목을 추가합니다.	RBLN-CA12 → ATOM_PT RBLN-CA25 → ATOM_MAX_PT RBLN-CR03 → REBEL_PT

VFIO Manager

키	설명	기본값
vfioManager.enabled	VFIO bind/unbind 헬퍼 배포 여부. VM 패스스루를 사용하려면 Sandbox Device Plugin과 함께 활성화합니다.	false
vfioManager.image.*	VFIO Manager 이미지.	docker.io/rebellions/rbln-vfio-manager:<chart default> pullPolicy: IfNotPresent

Container Toolkit

키	설명	기본값
containerToolkit.enabled	Container Toolkit DaemonSet 배포 여부. CDI 사양과 런타임 설정을 외부에서 관리한다면 비활성화합니다.	true
containerToolkit.image.*	Container Toolkit 이미지.	docker.io/rebellions/rbln-container-toolkit:<chart default> pullPolicy: IfNotPresent
containerToolkit.imagePullSecrets	이미지 풀 시크릿. 사설 레지스트리에서 이미지를 받을 때 필요합니다.	[]
containerToolkit.resources	툴킷 Pod의 CPU/메모리 requests/limits.	{}
containerToolkit.env	툴킷에 전달되는 환경 변수(RBLN_CTK_DAEMON_SOCKET, RBLN_CTK_DAEMON_CONFIG_PATH 등).	[]

NPU Feature Discovery

키	설명	기본값
npuFeatureDiscovery.enabled	오퍼레이터가 NPU Feature Discovery를 배포할지 여부. NPU 노드 라벨을 다른 방식으로 관리한다면 비활성화합니다.	true
npuFeatureDiscovery.image.*	NPU Feature Discovery 이미지.	docker.io/rebellions/rbln-npu-feature-discovery:<chart default> pullPolicy: IfNotPresent

Metrics Exporter

키	설명	기본값
metricsExporter.enabled	Prometheus 메트릭 익스포터 배포 여부. 다른 텔레메트리 파이프라인이 NPU를 이미 수집한다면 비활성화합니다.	true
metricsExporter.image.*	메트릭 익스포터 이미지.	docker.io/rebellions/rbln-metrics-exporter:<chart default> pullPolicy: IfNotPresent

Operator Validator

키	설명	기본값
validator.image.*	Validator DaemonSet 이미지.	docker.io/rebellions/rbln-npu-operator-validator:<chart default> pullPolicy: IfNotPresent
validator.imagePullSecrets	이미지 풀 시크릿. 사설 레지스트리에서 이미지를 받을 때 필요합니다.	[]
validator.resources	Validator Pod의 CPU/메모리 requests/limits.	{}
validator.env	최상위 Validator 프로세스의 환경 변수.	[]
validator.toolkit.env	Container Toolkit 준비 상태 하위 검사용 환경 변수.	[]
validator.driver.env	드라이버 준비 상태 하위 검사용 환경 변수.	[]

RBLN Daemon

키	설명	기본값
rblnDaemon.enabled	노드별 rbln-daemon 호스트 서비스 배포 여부. 워크로드에 클러스터 내부 RBLN Daemon이 필요할 때 활성화합니다.	false
rblnDaemon.image.*	RBLN Daemon 이미지.	repo.rebellions.ai/rebellions/rbln-daemon:<chart default> pullPolicy: IfNotPresent
rblnDaemon.imagePullSecrets	이미지 풀 시크릿. 드라이버 이미지와 동일한 drivercred 시크릿을 사용합니다.	[drivercred]
rblnDaemon.hostPort	데몬이 수신하는 TCP 포트. 각 노드에서 hostPort로 노출됩니다.	50051
rblnDaemon.resources	데몬 Pod의 CPU/메모리 requests/limits.	{}
rblnDaemon.env	데몬 컨테이너에 전달되는 환경 변수.	[]

관련 문서

• RBLN NPU Operator
• NPU Operator 업그레이드
• NPU Operator 제거
• NPU 드라이버 업그레이드 워크플로우
• 노드별 워크로드 라벨링