RBLN NPU Operator로 샌드박스형 워크로드 구성¶

BREAKING CHANGE

Sandbox Device Plugin은 더 이상 sandboxDevicePlugin.resourceList를 사용하지 않습니다. 이제 리소스 이름을 NPU 제품별로 자동 도출하고 제품당 하나의 리소스를 노출하므로 리소스 이름이 변경됩니다. 예를 들어 rebellions.ai/ATOM_CA25_PT는 rebellions.ai/RBLN-CA25_PF로 바뀝니다. 업그레이드 시 KubeVirt permittedHostDevices의 resourceName 항목과 각 VM hostDevices의 deviceName을 새 이름에 맞게 수정하세요. 리소스 이름 규칙을 참고하세요.

개요¶

RBLN NPU Operator는 VFIO를 통해 NPU를 게스트 VM에 직접 제공하여 가상화된 AI 워크로드를 구동할 수 있습니다. 이 모드에서 오퍼레이터는 다음을 수행합니다.

VFIO 드라이버로 장치를 바인딩
vfio-manager DaemonSet이 ConfigMap에 포함된 vfio-manage.sh 스크립트를 실행하여 Rebellions PCI 장치를 기본 드라이버에서 분리하고 vfio-pci로 재바인딩해 안전한 패스스루를 제공합니다.
VFIO 기반 리소스 노출
sandbox-device-plugin DaemonSet은 VFIO로 관리되는 NPU를 검사해 NPU 제품마다 하나의 리소스(예: rebellions.ai/RBLN-CA22_PF, rebellions.ai/RBLN-CA25_PF)를 자동으로 노출합니다. Kubernetes 디바이스 플러그인으로 리소스를 요청하는 모든 워크로드(KubeVirt 포함)는 이 리소스를 사용할 수 있습니다.
클러스터 라벨 일관성 유지
Node Feature Discovery(NFD)가 feature.node.kubernetes.io/pci-1eff.present=true 라벨로 하드웨어를 보고하면, 오퍼레이터가 해당 노드에 rebellions.ai/npu.present=true 등을 붙여 VFIO 패스스루가 가능한 노드만 샌드박스 컴포넌트를 실행하도록 합니다.

해당 컨트롤러들이 동기화된 후에는 각 hostDevices 절에 참조된 rebellions.ai/* 리소스 이름을 통해 NPU가 KubeVirt VirtualMachine 객체에 노출됩니다.

아래의 Helm 설정은 클러스터 전체에 샌드박스 모드를 활성화합니다. 대부분의 노드는 컨테이너 워크로드를 처리하면서 일부 노드만 VFIO 기반 VM을 호스팅하는 하이브리드 배포를 원한다면, 차트에서는 workloadType: container를 유지한 채 vfioManager.enabled와 sandboxDevicePlugin.enabled를 모두 켜고, VM을 호스팅할 노드에만 rebellions.ai/npu.workload.config=vm-passthrough 라벨을 부여하세요. 자세한 절차와 운영 시 주의사항은 노드별 워크로드 라벨링을 참고하세요.

디바이스 라이프사이클¶

샌드박스 모드는 노드의 워크로드 라벨에 따라 RBLN PCI 디바이스를 vfio-pci 드라이버에 바인딩하거나 해제합니다. 바인딩과 해제가 모두 처리되므로 동일한 노드를 컨테이너 모드와 VM 패스스루 모드 사이에서 별도 작업 없이 전환할 수 있습니다.

라벨 선택: 노드에 rebellions.ai/npu.workload.config=vm-passthrough 라벨을 부여합니다.
진입 시 바인딩: VFIO Manager DaemonSet이 노드에 스케줄링되면 init container가 호스트의 RBLN 커널 드라이버를 언로드하고, 메인 컨테이너가 각 NPU PCI 디바이스를 vfio-pci에 바인딩합니다. 이어서 sandbox device plugin의 init container가 모든 디바이스의 바인딩 상태를 검증한 후에야 sandbox device plugin이 VFIO 리소스를 노출하기 시작합니다.
하이브리드 클러스터: spec.workloadType: container로 설정되어 있다면 우선 vfioManager.enabled: true와 sandboxDevicePlugin.enabled: true를 함께 활성화해야 합니다. 그런 다음 원하는 노드에만 rebellions.ai/npu.workload.config=vm-passthrough 라벨을 부여합니다. 나머지 노드의 컨테이너 워크로드는 RBLN 드라이버를 그대로 사용합니다. 라벨 우선순위는 노드별 워크로드 라벨링을 참고하세요.

사전 요구 사항¶

Kubernetes 1.19+ 클러스터
RBLN NPU(RBLN-CA22/CA25)가 장착된 워커 노드
BIOS에서 IOMMU 활성화(intel_iommu=on 또는 amd_iommu=on) 및 VFIO 커널 모듈(vfio, vfio_pci, vfio_iommu_type1) 로드
VM 스케줄이 가능한 상태의 KubeVirt Operator
Node Feature Discovery(NFD) — Helm 차트에서 함께 배포 가능

샌드박스형 워크로드를 위한 Helm 배포¶

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 repo add rebellions https://RBLN-SW.github.io/rbln-npu-operator
$ helm repo update

샌드박스 워크로드 프로필을 구성
차트에는 sample-values-SandboxWorkload.yaml 예제가 포함되어 있습니다. 이 예제는 VFIO Manager와 Sandbox Device Plugin을 활성화합니다.
1 2 3 4 5 6 7 8 9 10 11 12
name: rbln nfd: enabled: true operator: replicas: 1 sandboxDevicePlugin: enabled: true vfioManager: enabled: true
플러그인이 각 NPU를 탐지해 리소스 이름을 자동으로 도출하므로 별도의 리소스 목록을 지정하지 않아도 됩니다. 자세한 규칙은 리소스 이름 규칙을 참고하세요.

기본 values.yaml을 복사해 수동으로 조정할 수도 있습니다. - sandboxDevicePlugin.enabled=true을 설정 - vfioManager.enabled=true을 설정 - NFD가 없으면 nfd.enabled=true로 설정

샌드박스 프로파일로 설치

$ helm install rbln-npu-operator \
     rebellions/rbln-npu-operator \
     -n rbln-system --create-namespace \
     -f sample-values-SandboxWorkload.yaml

리소스 이름 규칙¶

Sandbox Device Plugin은 NPU 제품마다 하나의 Kubernetes 리소스를 노출합니다. 각 노드에서 vfio-pci에 바인딩된 NPU를 검사한 뒤, 플러그인에 포함된 PCI ID 데이터베이스의 Rebellions 벤더 ID 1eff 항목으로 제품 이름을 확인합니다. 리소스 이름은 자동으로 도출되므로 별도로 관리할 resourceList가 없습니다.

데이터베이스의 제품 이름을 리소스 접미사로 사용합니다. 제품 이름은 대문자로 변환되고, 공백은 _로 바뀌며, 영문자, 숫자, _, - 이외의 문자는 제거됩니다. 예를 들어 1250 RBLN-CA25 (PF) 항목은 rebellions.ai/RBLN-CA25_PF로 노출됩니다.

pci.ids 항목 (벤더 `1eff`)	노출되는 리소스
`1220 RBLN-CA22 (PF)`	`rebellions.ai/RBLN-CA22_PF`
`1250 RBLN-CA25 (PF)`	`rebellions.ai/RBLN-CA25_PF`
`2030 RBLN-CR03 (PF)`	`rebellions.ai/RBLN-CR03_PF`

Note

플러그인이 자체 PCI ID 데이터베이스를 포함하므로 리소스 이름 지정을 위해 호스트를 별도로 설정할 필요가 없습니다. 내장 데이터베이스에 없는 최신 제품은 해당 제품을 포함한 플러그인 빌드로 업데이트하기 전까지 디바이스 ID 기반 이름인 rebellions.ai/RBLN-<device-id>(예: rebellions.ai/RBLN-1250)로 노출됩니다.

KubeVirt에서 VFIO 리소스 사용¶

Note

VM에 장치를 연결하기 전에 KubeVirt의 HostDevices 기능 게이트를 활성화하고 각 Rebellions PCI 리소스를 permittedHostDevices.pciHostDevices에 등록하세요. 이때 각 항목에 externalResourceProvider: true를 지정하여 KubeVirt가 같은 resourceName을 직접 노출하지 않고 sandbox device plugin에 할당을 위임하도록 하세요:

apiVersion: kubevirt.io/v1
kind: KubeVirt
metadata:
  name: kubevirt
  namespace: kubevirt
spec:
  configuration:
    developerConfiguration:
      featureGates:
      - HostDevices
    permittedHostDevices:
      pciHostDevices:
      - pciVendorSelector: 1eff:1220
        resourceName: rebellions.ai/RBLN-CA22_PF
        externalResourceProvider: true
      - pciVendorSelector: 1eff:1250
        resourceName: rebellions.ai/RBLN-CA25_PF
        externalResourceProvider: true

sandbox-device-plugin이 노출한 리소스를 참조하는 VirtualMachine 매니페스트를 생성합니다.

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: vm-npu-workload
spec:
  runStrategy: Always
  template:
    metadata:
      labels:
        app: vm-npu
    spec:
      domain:
        devices:
          hostDevices:
          - name: rbln0
            deviceName: rebellions.ai/RBLN-CA25_PF
            tag: "pci"
        resources:
          requests:
            rebellions.ai/RBLN-CA25_PF: 1
          limits:
            rebellions.ai/RBLN-CA25_PF: 1

팁¶

요청한 각 단위는 VFIO에 바인딩된 NPU 기능 한 개에 해당합니다.
여러 장치를 요구하려면 requests와 limits 값을 늘리고 hostDevices 항목을 rbln1, rbln2처럼 추가하세요.
플러그인이 NPU 제품마다 별도의 리소스를 노출하므로 하나의 Kubernetes 클러스터에 여러 종류의 RBLN 장치가 공존해도 각 워크로드는 필요한 제품을 정확히 요청할 수 있습니다(예: rebellions.ai/RBLN-CA22_PF와 rebellions.ai/RBLN-CA25_PF).