콘텐츠로 이동

RBLN 쿠버네티스 디바이스 플러그인

RBLN SDK는 쿠버네티스 클러스터에서 RBLN NPU를 사용할 수 있도록 쿠버네티스 디바이스 플러그인(Device Plugin)을 제공합니다.

1단계. NPU 노드 준비

먼저 RBLN NPU 및 RBLN 드라이버가 설치 된 쿠버네티스 노드(Kubernetes node)를 준비합니다. 보통은 사용 중인 클라우드 서버에 안정적으로 동작하는 최신 RBLN 드라이버가 이미 설치되어 있습니다. 커맨드라인에서 rbln-smi 명령어로 RBLN NPU를 조회할 수 있다면 RBLN 드라이버가 이미 설치되어있는 상태이므로 드라이버 설치를 생략할 수 있습니다. 드라이버 설치와 관련된 정보는 설치 가이드를 참고하시기 바랍니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
$ rbln-smi
Mon May 27 03:28:44 2024
+-------------------------------------------------------------------------------------------------+
|                        Device Infomation KMD ver: 0.12.37-6eed3e9-release                       |
+-----+-----------+-----------+---------------+------+---------+--------------------------+-------+
| NPU |    Name   | Device    |   PCI BUS ID  | Temp |  Power  |    Memory(used/total)    |  Util |
+-----+-----------+-----------+---------------+------+---------+--------------------------+-------+
| 0   | RBLN-CA02 | rbln0     |  0000:b6:00.0 |  25C |   6.2W  |      0.0B / 15.7GiB      |   0.0 |
+-----+-----------+-----------+---------------+------+---------+--------------------------+-------+
+-------------------------------------------------------------------------------------------------+
|                                        Context Infomation                                       |
+-----+---------------------+--------------+-----+----------+------+---------------------+--------+
| NPU | Process             |     PID      | CTX | Priority | PTID |            Memalloc | Status |
+-----+---------------------+--------------+-----+----------+------+---------------------+--------+
| N/A | N/A                 |     N/A      | N/A |   N/A    | N/A  |                 N/A |  N/A   |
+-----+---------------------+--------------+-----+----------+------+---------------------+--------+

CDI 설정 (필수)

디바이스 플러그인은 컨테이너 런타임에서 CDI가 활성화되어 있어야 동작합니다. containerd를 직접 설정하고 재시작하거나, Container Toolkit이 CDI 설정을 수행하도록 할 수 있습니다.

containerd v1.7.x (/etc/containerd/config.toml)

1
2
3
4
[plugins]
  [plugins."io.containerd.grpc.v1.cri"]
    enable_cdi = true
    cdi_spec_dirs = ["/etc/cdi", "/var/run/cdi"]

containerd v2.x.x (/etc/containerd/config.toml)

1
2
3
4
[plugins]
  [plugins."io.containerd.cri.v1.runtime"]
    enable_cdi = true
    cdi_spec_dirs = ["/etc/cdi", "/var/run/cdi"]

CDI가 활성화되면 디바이스 플러그인은 rebellions.ai/npu=all CDI 어노테이션을 추가합니다. 이를 통해 워크로드가 NPU 리소스(예: rebellions.ai/npu)를 요청할 때 필요한 라이브러리와 rbln-smi 같은 도구가 자동으로 마운트됩니다.

2단계. 디바이스 플러그인 설치

디바이스 플러그인은 NPU Operator를 사용하여 설치하는 것을 권장합니다. 다만, 단독 설치가 필요한 경우에는 다음 명령어를 사용하여 설치할 수 있습니다.

1
2
3
4
$ git clone https://github.com/RBLN-SW/k8s-device-plugin
$ cd k8s-device-plugin/deployments/helm/rbln-device-plugin

$ helm install rbln-device-plugin . -n kube-system

디바이스 플러그인 설치를 완료하면 kube-system 네임스페이스에서 rbln-device-plugin 데몬셋(DaemonSet)과 데몬셋으로부터 생성된 파드(Pod)를 확인할 수 있습니다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ kubectl get ds -n kube-system rbln-device-plugin
NAME                  DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR              AGE
rbln-device-plugin   4         4         4       4            4           kubernetes.io/arch=amd64   26s

$ kubectl get pod -n kube-system -l name=rbln-device-plugin -o wide
NAME                        READY   STATUS    RESTARTS   AGE
rbln-device-plugin-5tj4z   1/1     Running   0          41s
rbln-device-plugin-7zqgh   1/1     Running   0          41s
rbln-device-plugin-ddtts   1/1     Running   0          41s
rbln-device-plugin-zrw8s   1/1     Running   0          41s

추가로 kubectl describe 명령어를 통해 RBLN NPU 자원(여기서는 rebellions.ai/npu 자원)을 확인 할 수 있습니다:

1
2
3
4
5
6
7
8
9
$ kubectl describe node <your-node-name>
...
Capacity:
  ...
  rebellions.ai/npu:  1
Allocatable:
  ...
  rebellions.ai/npu:  1
...

3단계. NPU 파드 생성

파드스펙(Pod spec)에 spec.containers[].resources.limits을 추가하여 NPU 자원을 포함하는 파드를 생성할 수 있도록 합니다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
apiVersion: v1
kind: Pod
metadata:
  name: rbln-device-plugin-testpod
spec:
  containers:
  - name: ubuntu
    image: ubuntu:latest
    imagePullPolicy: IfNotPresent
    command: ["/bin/bash", "-c", "--"]
    args: ["while true; do sleep 300000; done;"]
    resources:
      requests:
        rebellions.ai/npu: 1
      limits:
        rebellions.ai/npu: 1

정의된 파드스펙을 기반으로 kubectl create 명령어를 사용하여 파드를 생성할 수 있습니다:

1
$ kubectl create -f https://raw.githubusercontent.com/rebellions-sw/rbln-k8s-device-plugin/master/deployments/rbln/pod-tc.yaml

kubectl describe 명령어를 통해 1개의 rebellions.ai/npu 자원이 할당 된 파드를 확인할 수 있습니다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
$ kubectl describe pod rbln-device-plugin-testpod
Name:             rbln-device-plugin-testpod
Namespace:        default
...
Containers:
  ubuntu:
    ...
    Limits:
      rebellions.ai/npu:  1
    Requests:
      rebellions.ai/npu:  1
    ...

디바이스 플러그인은 호스트 머신의 rbln-smi 유틸리티를 파드 컨테이너로 자동으로 마운트하기 때문에, 생성된 컨테이너에서 아래와 같이 rbln-smi 유틸리티를 사용할 수 있습니다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
$ kubectl exec -it rbln-device-plugin-testpod -- bash
root@rbln-device-plugin-testpod:/# rbln-smi
Mon May 27 08:44:05 2024
+-------------------------------------------------------------------------------------------------+
|                        Device Infomation KMD ver: 0.12.37-6eed3e9-release                       |
+-----+-----------+-----------+---------------+------+---------+--------------------------+-------+
| NPU |    Name   | Device    |   PCI BUS ID  | Temp |  Power  |    Memory(used/total)    |  Util |
+-----+-----------+-----------+---------------+------+---------+--------------------------+-------+
| 0   | RBLN-CA02 | rbln0     |  0000:b6:00.0 |  25C |   6.2W  |      0.0B / 15.7GiB      |   0.0 |
+-----+-----------+-----------+---------------+------+---------+--------------------------+-------+
+-------------------------------------------------------------------------------------------------+
|                                        Context Infomation                                       |
+-----+---------------------+--------------+-----+----------+------+---------------------+--------+
| NPU | Process             |     PID      | CTX | Priority | PTID |            Memalloc | Status |
+-----+---------------------+--------------+-----+----------+------+---------------------+--------+
| N/A | N/A                 |     N/A      | N/A |   N/A    | N/A  |                 N/A |  N/A   |
+-----+---------------------+--------------+-----+----------+------+---------------------+--------+

디바이스 상태 기반 격리

디바이스 플러그인은 디바이스 검색 주기마다 커널 드라이버를 통해 각 NPU의 상태를 확인하여 kubelet에 Healthy/Unhealthy 상태를 보고합니다. 워크로드가 실행될 수 없는 디바이스는 스케줄링 대상에서 자동으로 제외되고, 드라이버가 다시 READY 상태를 보고하면 자동으로 스케줄링 가능한 상태로 복귀합니다.

NPU 할당 트레이스

디바이스 플러그인은 NPU 할당 경로를 OpenTelemetry 트레이스로 계측합니다. 할당 요청마다 어떤 디바이스와 Rebellions Scalable Design(RSD) 그룹이 컨테이너에 전달되었는지 스팬(span)에 기록되므로, OpenTelemetry Protocol(OTLP) 백엔드에서 노드별 NPU 할당 이력을 트레이스할 수 있습니다.

트레이스는 기본적으로 비활성화되어 있으며, 다음 Helm 값으로 OTLP gRPC 엔드포인트를 지정하여 활성화할 수 있습니다.

1
2
devicePlugin:
  otlpEndpoint: <OTLP_ENDPOINT>

트레이스는 부가적인 관찰가능성 기능이므로, 엔드포인트 형식이 잘못되었거나 OTLP 익스포터 초기화에 실패하더라도 플러그인은 트레이스 없이 계속 동작하며, 노드의 NPU 스케줄링에는 영향을 주지 않습니다.

할당 요청 단위의 Allocate 스팬과 컨테이너 단위의 allocateContainer 스팬이 생성되며, 다음 속성을 포함합니다. 할당이 실패하면 오류 내용이 스팬에 기록됩니다.

속성 설명
rbln.resource_name 할당이 요청된 리소스 이름(예: rebellions.ai/npu)
rbln.device.ids 컨테이너에 할당된 NPU 디바이스 ID 목록
rbln.device.count 할당된 디바이스 수
rbln.device.bus_ids 할당된 디바이스의 PCI 버스 ID 목록
rbln.rsd.host_path 할당에 사용된 RSD 그룹의 호스트 경로

모든 스팬에는 리소스 속성으로 service.name=rbln-device-plugin과 service.version이 포함됩니다. 또한 NODE_NAME 환경 변수가 설정된 경우(Helm DaemonSet은 spec.nodeName을 항상 주입) k8s.node.name 속성이 추가되어 노드별로 구분할 수 있습니다.

로깅

플러그인은 구조화된 로그를 stdout에 출력합니다. 다음 환경 변수로 로그 레벨과 출력 형식을 설정합니다.

변수 설명 기본값
RBLN_DEVICE_PLUGIN_LOG_LEVEL 로그 상세도: error, warning(또는 warn), info, debug. info
RBLN_DEVICE_PLUGIN_LOG_FORMAT 출력 형식: json 또는 text. json

잘못된 값을 지정해도 중단되지 않고 기본값으로 되돌아가면서 경고를 남깁니다. 비정상 디바이스 관련 레코드는 warn으로 기록됩니다.

노드 상태가 바뀌지 않으면 플러그인은 info 로그를 기록하지 않습니다. 스캔 루프가 정상적으로 동작하는지 확인하려면 레벨을 debug로 설정하고 스캔마다 출력되는 Reconciled device inventory 레코드를 찾아보세요.

RBLN NPU Operator로 배포한 경우 차트의 devicePlugin.logging 값으로 설정하세요. 컴포넌트 로깅을 참고하세요.