RBLN NPU Operator¶

RBLN NPU Operator는 Kubernetes 및 OpenShift 클러스터에서 RBLN NPU 제품군의 프로비저닝에 필요한 Rebellions 소프트웨어 구성 요소를 자동으로 배포하고 관리합니다. 단일 RBLNClusterPolicy 커스텀 리소스가 전체 워크플로를 주도하고 해당 정책이 생성되면, 오퍼레이터는 자동으로 다음 작업을 수행합니다.

Node Feature Discovery(NFD)를 활용한 하드웨어 탐지와 노드 라벨링
컨테이너/VM 패스스루 2가지 워크로드 유형에 맞춘 디바이스 노출
Driver Manager를 통한 드라이버 설치 및 라이프사이클 관리(RBLNDriver 커스텀 리소스 기반)
VFIO 바인딩, 장치 플러그인, 메트릭 수집기 등 NPU 주변 구성요소 배포 및 상태 관리
OpenShift와 Vanilla Kubernetes 모두에서 동작하도록 RBAC/SCC 자동 구성

핵심 구성 요소¶

다음 표는 오퍼레이터가 배포·관리하는 주요 구성 요소와 역할을 요약합니다.

구성 요소	설명
Device Plugin	`rebellions/k8s-device-plugin` 이미지를 사용해 `rebellions.ai/ATOM` 같은 리소스를 파드에 노출합니다. `resourceList`에 제품 카드별 리소스를 매핑합니다.
Sandbox Device Plugin	VM 패스스루용 리소스로 `rebellions.ai/ATOM_PT` 등을 제공합니다. VFIO 체크 컨테이너와 동작하며 KubeVirt 환경을 대상으로 합니다.
VFIO Manager	`rebellions/rbln-vfio-manager` 이미지와 `vfio-manage.sh` 스크립트를 ConfigMap으로 전달해 VFIO 바인딩/언바인딩을 담당합니다.
Driver Manager	`RBLNDriver` 커스텀 리소스를 기반으로 NPU 드라이버를 설치하고 유지합니다.
NPU Feature Discovery	`rebellions/rbln-npu-feature-discovery`가 노드의 `PCI-1eff` 벤더 라벨을 식별해 `rebellions.ai/npu.present` 등을 설정합니다.
Container Toolkit	CDI 스펙을 생성하고 컨테이너 런타임을 설정/재시작해 CDI 기반 장치 주입을 준비합니다.
Metrics Exporter	`rebellions/rbln-metrics-exporter`가 NPU 메트릭을 Prometheus 형식으로 노출합니다.
Operator Validator	드라이버/컨테이너 툴킷 준비 상태를 검증하고 hostPath ready 파일로 결과를 기록합니다.
Operator Manager	`cmd/main.go`에서 로드되는 컨트롤러가 단일 `RBLNClusterPolicy`만 허용하며, K8S Node와 구성요소의 DaemonSet 변화를 감시합니다.

NPU Operator 설치¶

RBLN NPU Operator Helm Chart는 Kubernetes 클러스터에서 RBLN NPU를 자동으로 탐지하고 필요한 디바이스 플러그인을 배포하며 관련 컴포넌트의 상태를 모니터링합니다. 빠르게 시작하려면 다음 단계를 따르세요.

사전 준비
- Kubernetes 1.19+ 클러스터와 kubectl, helm 명령어 사용 가능
- rbln-system처럼 오퍼레이터를 배치할 전용 네임스페이스 권장
- NPU가 장착된 워커 노드와 Node Feature Discovery(NFD) 설치(차트에서 nfd.enabled=true로 함께 설치 가능)

Helm 설치(필요 시)

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

Rebellions Helm 리포지토리 등록

helm repo add rebellions https://rebellions-sw.github.io/rbln-npu-operator
helm repo update

NPU Operator 설치

helm install --wait --generate-name \
     -n rbln-system --create-namespace \
     rebellions/rbln-npu-operator

설치 확인¶

Helm 설치가 성공적으로 끝나면 RBLNClusterPolicy 커스텀 리소스가 생성되고 정상 동작하는지 먼저 확인합니다.

kubectl get rblnclusterpolicies.rebellions.ai -n rbln-system
NAME                  AGE
rbln-cluster-policy   8m

드라이버 관리를 활성화했다면 RBLNDriver 커스텀 리소스가 생성됐는지 확인합니다.

kubectl get rblndrivers.rebellions.ai -n rbln-system
NAME          AGE
rbln-driver   99m

다음으로 rbln-system 네임스페이스에서 컨트롤러와 파드가 모두 실행 중인지 점검합니다.

kubectl get pods -n rbln-system
NAME                                             READY   STATUS    AGE
controller-manager-797798d7b8-rjzht              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

컨트롤러 컴포넌트: controller-manager-* 파드가 RBLNClusterPolicy를 상시 조율합니다.
드라이버 관리: RBLNDriver 커스텀 리소스로 NPU 드라이버 버전을 선언하면 Driver Manager가 클러스터 전반에 설치합니다.
검증 컴포넌트: rbln-operator-validator-*가 드라이버/컨테이너 툴킷 준비 상태를 확인하고 hostPath ready 파일에 기록합니다.
오퍼랜드: rbln-device-plugin, rbln-npu-feature-discovery, rbln-container-toolkit, rbln-metrics-exporter가 디바이스 노출·CDI 활성화·라벨링·모니터링 관리를 담당합니다.

어떤 파드라도 Pending/CrashLoopBackOff 상태라면 kubectl logs <pod> -n rbln-system으로 로그를 확인하고 Helm values 설정과 선행 조건을 다시 점검하세요.

드라이버 관리¶

오퍼레이터는 RBLNDriver CRD를 정의해 NPU 드라이버 설치를 관리합니다. 원하는 드라이버 버전을 RBLNDriver 커스텀 리소스로 선언하면 Driver Manager가 해당 버전을 클러스터 전반에 설치하고 유지합니다.

RBLNDriver 샘플¶

apiVersion: rebellions.ai/v1alpha1
kind: RBLNDriver
metadata:
  labels:
    app.kubernetes.io/name: rbln-driver
  name: rblndriver-sample
spec:
  registry: docker.io
  image: rebellions/rbln-driver
  version: "3.0.0"
  imagePullPolicy: IfNotPresent
  labels:
    app.kubernetes.io/component: driver
  resources:
    requests:
      cpu: 250m
      memory: 64Mi
    limits:
      cpu: 500m
      memory: 128Mi
  manager:
    registry: docker.io
    image: rebellions/rbln-k8s-driver-manager
    version: "latest"
    imagePullPolicy: IfNotPresent

Driver Manager가 설치하는 구성 요소¶

RBLNDriver 리소스를 적용하면 Driver Manager가 아래 구성 요소를 설치합니다.

Kernel 드라이버
UMD 라이브러리
rbln-smi 같은 유틸리티

드라이버 이미지 선택 기준¶

Driver Manager는 각 노드의 Node Feature Discovery 라벨 조합을 기준으로 드라이버 컨테이너 이미지를 선택합니다.

feature.node.kubernetes.io/system-os_release.ID
feature.node.kubernetes.io/system-os_release.VERSION_ID
feature.node.kubernetes.io/kernel-version.full

예를 들어 Ubuntu 22.04와 커널 6.8.0-90-generic 조합이면 다음과 같은 이미지로 해석될 수 있습니다: docker.io/rebellions/rbln-driver:3.0.0-rc3-6.8.0-90-generic-ubuntu22.04.

Operator Validator¶

rbln-validator는 RBLN NPU 스택의 드라이버/컨테이너 툴킷 준비 상태를 검증하는 컴포넌트입니다. 오퍼레이터가 배포하는 Validator DaemonSet 안에서 동작하며, 검증 결과를 hostPath ready 파일로 기록해 다른 컴포넌트가 의존할 수 있게 합니다.

Container Toolkit¶

NPU Operator는 RBLNClusterPolicy의 containerToolkit 설정을 기반으로 Container Toolkit DaemonSet을 배포합니다. 이 DaemonSet의 역할은 CDI 스펙 생성과 컨테이너 런타임 설정/재시작이며, 이후 Device Plugin 및 워크로드가 CDI 기반 장치 주입을 사용할 수 있도록 준비합니다.

NPU 상태 확인¶

Kubernetes가 각 노드에서 인식한 NPU 용량을 조회해 디바이스 플러그인이 기대한 리소스를 노출했는지 확인합니다.

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

샌드박스 워크로드 전용으로 rebellions.ai/ATOM_PT 같은 대체 리소스 이름을 사용한다면, 위 명령에서 해당 문자열로 바꿔서 동일하게 용량 컬럼을 확인하면 됩니다.

NPU 지원 Pod 생성¶

매니페스트 저장 (예: npu-demo-pod.yaml) — 아래와 같이 rebellions.ai/ATOM 리소스 4개를 요청합니다.

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/ATOM: 4

Pod 생성.
1
kubectl apply -f npu-demo-pod.yaml
Pod 상태 및 리소스 할당 확인.
1
kubectl get pod npu-pod
kubectl describe pod npu-pod 명령으로 요청한 NPU 리소스가 바인딩되어 NPU 지원 노드에 스케줄되었는지 확인합니다.

차트 커스터마이징 옵션¶

아래 표들은 Helm 값(values.yaml)에서 자주 조정되는 항목과 사용 시나리오를 범주별로 정리한 것입니다.

글로벌 및 의존성¶

주요 키	기본값 / 설명	커스터마이징 시나리오
`name`	`rbln` – 모든 자식 리소스 접두사	다중 오퍼레이터 인스턴스를 같은 클러스터에 둘 때 충돌 방지
`nfd.enabled`	`false` – NFD 동시 설치 여부	NFD가 없는 클러스터에서 빠르게 설치하려면 `true`
`npuFeatureDiscovery.enabled` / `image.*`	`true`, `rebellions/rbln-npu-feature-discovery:latest`	수동 라벨링 체계가 있으면 비활성화

오퍼레이터 배포¶

주요 키	기본값 / 설명	커스터마이징 시나리오
`operator.image.*`	`rebellions/rbln-npu-operator:latest`	사설 레지스트리 사용, 특정 버전 고정
`operator.replicas`	`1`	고가용성이 필요하면 2 이상
`operator.resources`	CPU/메모리 요청·제한	클러스터 용량에 맞춰 리소스 튜닝
`operator.service.*`	`ClusterIP`, 8443/8443	Ingress/서비스 메시 통합 시 포트·타입 변경
`operator.securityContext.runAsNonRoot`	`true`	보안 요구사항에 따라 권한 조정
`operator.affinity` / `tolerations`	기본 비어 있음	컨트롤 플레인 전용 또는 특정 워커 고정 스케줄링

컨테이너 워크로드 스택¶

주요 키	기본값 / 설명	커스터마이징 시나리오
`devicePlugin.enabled`	`true`	컨테이너 기반 워크로드면 유지, VM 전용이면 `false`
`devicePlugin.image.*`	`rebellions/k8s-device-plugin:latest`	사설 레지스트리 사용, 특정 버전 고정
`devicePlugin.resourceList[]`	`rebellions.ai/ATOM`	카드별 리소스 이름/프리픽스 추가
`metricsExporter.enabled` / `image.*`	`true`, `rebellions/rbln-metrics-exporter:latest`	별도 모니터링 스택이 있으면 비활성화

드라이버 설정¶

주요 키	기본값 / 설명	커스터마이징 시나리오
`driver.enabled`	`true`	드라이버를 노드에 사전 설치했거나 외부에서 관리하면 `false`
`driver.image.*`	`harbor.k8s.rebellions.in/playground/rbln-driver:3.0.0-rc3`, `IfNotPresent`	사설 레지스트리 사용, 특정 드라이버 버전 고정
`driver.imagePullSecrets`	`[]`	사설 레지스트리 사용 시 필요
`driver.nodeSelector` / `nodeAffinity` / `tolerations`	기본 비어 있음	특정 노드/아키텍처에만 드라이버 파드를 배치
`driver.labels` / `annotations`	`{}`	정책/감사/모니터링 연동을 위한 메타데이터 추가
`driver.priorityClassName`	`""`	스케줄링 우선순위 상향(예: `system-node-critical`)
`driver.resources`	`{}`	CPU/메모리 요청·제한 설정
`driver.args` / `driver.env`	`[]`	커스텀 인자/환경변수 전달(예: 로그 레벨)
`driver.manager.*`	`rebellions/rbln-k8s-driver-manager:latest`, `IfNotPresent`	Driver Manager 이미지/버전 교체

Validator 설정¶

주요 키	기본값 / 설명	커스터마이징 시나리오
`validator.registry` / `image` / `tag`	`harbor.k8s.rebellions.in`, `rebellions/rbln-npu-operator-validator`, `driver-test`	Validator 이미지 위치/버전 교체
`validator.pullPolicy`	`IfNotPresent`	캐시된 이미지를 우선 사용
`validator.imagePullSecrets`	`[]`	사설 레지스트리 사용 시 필요
`validator.resources`	`{}`	CPU/메모리 요청·제한 설정
`validator.args` / `validator.env`	`[]`	커스텀 인자/환경변수 전달

Container Toolkit 설정¶

주요 키	기본값 / 설명	커스터마이징 시나리오
`containerToolkit.enabled`	`true`	CDI 스펙/런타임 설정을 외부에서 관리하면 비활성화
`containerToolkit.image.*`	`harbor.k8s.rebellions.in/rebellions/rbln-container-toolkit:latest`, `Always`	Container Toolkit 이미지 위치/버전 교체
`containerToolkit.imagePullSecrets`	`[]`	사설 레지스트리 사용 시 필요
`containerToolkit.resources`	`{}`	CPU/메모리 요청·제한 설정
`containerToolkit.args` / `containerToolkit.env`	`[]`	커스텀 인자/환경변수 전달

VM 패스스루 스택¶

주요 키	기본값 / 설명	커스터마이징 시나리오
`sandboxDevicePlugin.enabled`	`false` (기본 비활성)	KubeVirt 등 VM 환경에서 `true`
`sandboxDevicePlugin.resourceList[]`	`rebellions.ai/ATOM_PT`	카드 모델별 VFIO 리소스 이름 조정
`sandboxDevicePlugin.vfioChecker.image.*`	`rebellions/rbln-vfio-manager:latest`	검증 컨테이너 이미지를 교체
`vfioManager.enabled`	`false`	VM passthrough 구성 시 `true`
`vfioManager.image.*`	`rebellions/rbln-vfio-manager:latest`	사설 레지스트리 사용, 특정 버전 고정