RBLN Container Toolkit¶

RBLN Container Toolkit은 Container Device Interface (CDI) 스펙을 사용하여 컨테이너 런타임이 Rebellions NPU 장치에 액세스할 수 있도록 합니다. 호스트의 RBLN 라이브러리와 도구를 자동으로 검색하고, CDI 스펙을 생성하며, 컨테이너 런타임을 구성하여 애플리케이션 변경 없이 컨테이너가 NPU 하드웨어를 사용할 수 있도록 합니다.

범위

Container Toolkit은 현재 CDI 스펙 생성 — RBLN 라이브러리와 도구(rbln-smi 등)를 컨테이너에 마운트하는 기능을 담당합니다. RSD 그룹을 사용한 NPU 장치 할당은 NPU 할당 가이드를 참조하세요. 향후 릴리스에서 이러한 기능들이 통합된 툴킷으로 제공될 예정입니다.

동작 방식¶

                          ┌──────────────────────────────────────────┐
  Host System             │           RBLN Container Toolkit         │
 ─────────────            │                                          │
                          │  1. Discover    RBLN libs & tools        │
  /usr/lib64/             │       ↓         on the host              │
    librbln-*.so ────────►│  2. Generate    CDI spec (rbln.yaml)     │
  /usr/bin/               │       ↓                                  │
    rbln-smi ────────────►│  3. Configure   container runtime        │
                          │       ↓         (containerd/crio/docker) │
                          │  4. Hook        update ldcache           │
                          │                 in containers            │
                          └─────────────────────┬────────────────────┘
                                                │
                                                ▼
                          ┌──────────────────────────────────────────┐
  Container               │  $ docker run --device rebellions.ai/    │
                          │      npu=all my-app                      │
                          │                                          │
                          │  ✓ RBLN libraries mounted                │
                          │  ✓ Tools available (rbln-smi)            │
                          │  ✓ ldcache updated automatically         │
                          └──────────────────────────────────────────┘

툴킷은 세 가지 바이너리를 제공합니다:

바이너리	역할
`rbln-ctk`	메인 CLI — CDI 스펙 생성, 런타임 구성, 시스템 검사
`rbln-ctk-daemon`	Kubernetes 데몬 — 헬스 엔드포인트 및 정상 종료(graceful shutdown)를 통한 자동 설정
`rbln-cdi-hook`	OCI 훅 — 컨테이너 내부에서 실행되어 ldcache 업데이트 및 심볼릭 링크 생성

툴킷은 런타임 프로파일이 서로 다른 두 가지 배포 형태로 제공되며, 각 형태는 서로 다른 배포 시나리오를 위해 설계되었습니다:

배포 형태	대상	디바이스 주입	새로 고침 경로
DEB / RPM 패키지	독립 실행형 Docker 호스트	`rbln-ctk` 가 CDI 를 통해 `/dev/rbln` 와 대응되는 `/dev/rsd` 그룹 노드를 주입합니다. NPU↔RSD 매핑은 `librbln-ml` 로 해석되며, 패키지가 이를 런타임 의존성으로 함께 설치합니다.	호스트의 `rbln-cdi-refresh.path` systemd 유닛(postinstall 에서 자동 활성화). Systemd 통합 참조
컨테이너 이미지	Kubernetes DaemonSet	`rbln-ctk-daemon` 은 디바이스 노드를 생성하지 않습니다. Pod 별 `/dev/rbln*` 할당은 디바이스 플러그인(또는 DRA)이 담당합니다. 이 모드에서는 NPU↔RSD 리졸버가 호출되지 않으므로 이미지에 `librbln-ml` 의존성이 포함되지 않습니다.	`rbln-ctk-daemon` 내부 루프. 자동 CDI 새로 고침 참조

사전 요구사항¶

OS	아키텍처	컨테이너 런타임
Ubuntu 22.04/24.04	x86_64	containerd, CRI-O, Docker
RHEL 9+	x86_64	containerd, CRI-O, Docker

RBLN 드라이버 — 컨테이너 툴킷보다 먼저 호스트에 설치하세요. 툴킷의 DEB·RPM 패키지는 드라이버의 UMD 라이브러리(Debian/Ubuntu 에서는 librbln-ml3, RHEL 계열에서는 librbln-ml)를 하드 런타임 의존성으로 선언하므로, 드라이버 없이 툴킷을 설치하면 apt-get 또는 dnf 에서 의존성 미해결 오류로 실패합니다.

설치¶

Ubuntu / Debian¶

Rebellions 공식 GPG 키 추가 (이미 구성된 경우 건너뛰기):

$ sudo apt-get update
$ sudo apt-get install ca-certificates curl
$ sudo install -m 0755 -d /etc/apt/keyrings
$ sudo curl -fsSL https://nexus.rebellions.ai/repository/raw-public/rebellions.asc -o /etc/apt/keyrings/rebellions.asc
$ sudo chmod a+r /etc/apt/keyrings/rebellions.asc

APT 소스에 저장소 추가 (이미 구성된 경우 건너뛰기):

$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/rebellions.asc] https://nexus.rebellions.ai/repository/apt-public/ stable main" | \
  sudo tee /etc/apt/sources.list.d/rebellions-apt-public.list > /dev/null

APT 업데이트 및 설치:

$ sudo apt-get update
$ sudo apt-get install rbln-container-toolkit

RHEL¶

Rebellions yum 저장소 등록 (이미 구성된 경우 건너뛰기):

$ sudo tee /etc/yum.repos.d/rebellions.repo > /dev/null <<EOF
[rebellions-stable]
name=Rebellions Stable
baseurl=https://nexus.rebellions.ai/repository/yum-public/stable/x86_64/Packages/
enabled=1
gpgcheck=0
EOF

캐시 갱신 후 설치:

$ sudo dnf clean all
$ sudo dnf install -y rbln-container-toolkit

Unsigned RPM packages

현재 배포 중인 RPM 패키지에는 아직 서명이 적용되지 않아 설치를 위해 gpgcheck=0 으로 설정합니다. 서명된 패키지가 제공되면 항목을 gpgcheck=1 로 되돌리세요.

빠른 시작¶

컨테이너에서 NPU에 액세스하는 가장 빠른 방법:

# 1. CDI 스펙 생성 (호스트에서 RBLN 라이브러리 검색)
$ sudo rbln-ctk cdi generate

# 2. CDI 지원을 위한 컨테이너 런타임 구성
$ sudo rbln-ctk runtime configure

# 3. NPU 에 액세스할 수 있는 컨테이너 실행 (모든 NPU)
$ docker run --device rebellions.ai/npu=all -it ubuntu:22.04

툴킷이 런타임을 자동으로 감지하고 올바른 구성을 적용합니다. 호스트 NPU 중 일부만 컨테이너에 노출하려면 장치 선택을 참조하세요.

설정 확인¶

# 검색된 항목 확인
$ rbln-ctk cdi list

# 시스템 정보 보기
$ rbln-ctk info

# 컨테이너 내부에서 NPU 도구 사용
$ docker run --device rebellions.ai/npu=all -it ubuntu:22.04 rbln-smi

적용 전 미리보기¶

모든 명령은 --dry-run을 지원하여 실제로 수정하지 않고 변경될 내용을 확인할 수 있습니다:

$ rbln-ctk cdi generate --dry-run
$ rbln-ctk runtime configure --dry-run

장치 선택¶

CDI 사양은 두 가지 형태의 장치 핸들을 제공합니다. 워크로드 범위에 맞는 것을 선택하세요:

핸들	노출 범위
`rebellions.ai/npu=all`	호스트의 모든 NPU 및 모든 RSD 그룹 (권장)
`rebellions.ai/npu=N`	인덱스로 지정한 단일 NPU (`0`, `1`, ...). 해당 NPU가 속한 RSD 그룹은 자동으로 함께 첨부됩니다.

=N 핸들에 인덱스를 지정해 단일 NPU를 선택합니다:

$ docker run \
  --device rebellions.ai/npu=N \
  -it IMAGE_NAME:TAG

--device 를 반복해 여러 NPU를 부착합니다. 선택한 NPU들이 같은 RSD 그룹에 속하면, 컨테이너에서 텐서 병렬 워크로드를 실행할 수 있습니다:

$ docker run \
  --device rebellions.ai/npu=0 \
  --device rebellions.ai/npu=1 \
  -it IMAGE_NAME:TAG

Kubernetes 런타임(containerd / CRI-O)에서는 =all 핸들만 공개되며, 이 핸들은 라이브러리 마운트와 rbln-smi 도구 바인드만 포함하고 디바이스 노드는 첨부하지 않습니다. Pod 별 /dev/rbln* 할당은 디바이스 플러그인 또는 DRA 드라이버가 담당합니다. NPU 별 핸들은 독립 실행형 Docker 호스트에서 사용합니다.

Regenerate the CDI spec after RSD topology changes

rbln-ctk cdi generate 는 실행 시점에 호스트에 존재하는 /dev/rsd* 노드를 바탕으로 =N 핸들을 CDI 사양에 기록합니다. 자동 새로 고침 경로 (Systemd 통합, 자동 CDI 새로 고침) 는 드라이버 또는 툴킷 라이브러리 변경 시에만 동작합니다. rbln-smi group -c, -a, -d 로 RSD 그룹을 재구성한 뒤에는 sudo rbln-ctk cdi generate 를 다시 실행하거나 다음 드라이버 새로 고침을 기다려야 컨테이너 런타임이 새 =N 핸들을 정상적으로 해석합니다. =all 핸들은 RSD 그룹 변경과 무관하게 동작합니다.

npu=runtime 호환성

v0.1.x 의 rebellions.ai/npu=runtime 은 =all 의 alias 로 유지되며 내용이 동일합니다. v0.2 로 업그레이드해도 기존 매니페스트와 디바이스 플러그인 빌드를 재작성할 필요가 없습니다. 새 매니페스트에는 =all 또는 장치 단위 셀렉터 사용을 권장하며, 이 alias 는 향후 릴리스에서 제거될 수 있습니다.

CLI 레퍼런스¶

rbln-ctk cdi generate¶

RBLN 라이브러리와 도구를 검색한 다음 CDI 스펙을 작성합니다.

$ sudo rbln-ctk cdi generate

플래그	설명	기본값
`-o, --output`	출력 경로	`/var/run/cdi/rbln.yaml`
`-f, --format`	출력 형식 (`yaml` 또는 `json`)	`yaml`
`--driver-root`	드라이버 파일의 루트 경로 (CoreOS: `/host`)	`/`
`--container-library-path`	컨테이너 내 격리된 라이브러리 경로	(호스트와 동일)
`--dry-run`	작성하지 않고 미리보기	`false`

rbln-ctk runtime configure¶

실행 중인 컨테이너 런타임을 자동으로 감지하고 CDI 지원을 활성화합니다.

$ sudo rbln-ctk runtime configure

플래그	설명	기본값
`-r, --runtime`	특정 런타임 강제 지정 (`containerd`, `crio`, `docker`)	(자동 감지)
`--config-path`	사용자 정의 런타임 구성 경로	(런타임 기본값)
`--dry-run`	변경 사항 미리보기	`false`

rbln-ctk cdi list¶

검색된 RBLN 라이브러리와 도구를 나열합니다.

$ rbln-ctk cdi list

rbln-ctk info¶

감지된 런타임 및 구성을 포함한 시스템 정보를 표시합니다.

1	`$ rbln-ctk info`

Kubernetes 배포¶

Kubernetes 클러스터의 경우 툴킷을 DaemonSet으로 배포합니다. 데몬(rbln-ctk-daemon)은 전체 라이프사이클을 처리합니다:

시작 시 CDI 스펙 생성
컨테이너 런타임 구성
런타임 재시작
헬스 체크 엔드포인트 제공
SIGTERM 시 정리 (Pod 종료)

컨테이너 이미지¶

공식 컨테이너 이미지는 Docker Hub에서 제공됩니다:

$ docker pull rebellions/rbln-container-toolkit:latest

배포¶

$ kubectl apply -f deployments/kubernetes/daemonset.yaml

헬스 엔드포인트¶

엔드포인트	프로브 유형	200 반환 조건
`/live`	Liveness	데몬 프로세스가 실행 중일 때
`/ready`	Readiness	설정이 완료되었을 때
`/startup`	Startup	초기화가 완료되었을 때

환경 변수¶

변수	설명	기본값
`RBLN_CTK_DAEMON_RUNTIME`	컨테이너 런타임	(자동 감지)
`RBLN_CTK_DAEMON_HOST_ROOT`	호스트 루트 마운트 경로	`/` (호스트), `/host` (컨테이너)
`RBLN_CTK_DAEMON_DRIVER_ROOT`	CDI 스펙을 위한 드라이버 루트 경로	`/`
`RBLN_CTK_DAEMON_CDI_SPEC_DIR`	CDI 스펙 디렉토리	`/var/run/cdi`
`RBLN_CTK_DAEMON_CONTAINER_LIBRARY_PATH`	격리를 위한 컨테이너 라이브러리 경로	(비어 있음)
`RBLN_CTK_DAEMON_SOCKET`	런타임 소켓 경로	(자동 감지)
`RBLN_CTK_DAEMON_HEALTH_PORT`	헬스 체크 포트	`8080`
`RBLN_CTK_DAEMON_SHUTDOWN_TIMEOUT`	정상 종료(graceful shutdown) 타임아웃	`30s`
`RBLN_CTK_DAEMON_PID_FILE`	PID 파일 경로	`/run/rbln/toolkit.pid`
`RBLN_CTK_DAEMON_NO_CLEANUP_ON_EXIT`	종료 시 정리 건너뛰기	`false`
`RBLN_CTK_DAEMON_REFRESH_INTERVAL`	`rbln-ctk-daemon` 내부 CDI 사양 새로 고침 주기 (`0` 으로 설정 시 비활성화). DaemonSet 전용이며, DEB/RPM CLI 경로에서는 systemd 유닛이 동일 역할을 수행합니다. 자동 CDI 새로 고침 참조	`60s`
`RBLN_CTK_DAEMON_DEBUG`	디버그 로깅 활성화	`false`
`RBLN_CTK_DAEMON_FORCE`	시작 전 기존 인스턴스 종료	`false`

자동 CDI 새로 고침¶

rbln-ctk-daemon(Kubernetes DaemonSet 바이너리)이 이 새로 고침 루프를 수행합니다. DEB/RPM 설치 환경에서는 Systemd 통합에 설명한 systemd 유닛이 동일한 역할을 합니다.

데몬은 호스트 RBLN UMD 라이브러리에 내장된 rbln version: 마커를 주기적으로 확인하여, 마커 변경을 감지하면 /var/run/cdi/rbln.yaml 을 다시 생성합니다. 데몬이 라이브러리 변경을 자동으로 반영하므로 운영자는 DaemonSet 을 그대로 둔 채 드라이버 재설치나 업그레이드를 적용할 수 있습니다. 컨테이너 런타임은 새로 시작하는 컨테이너에 현재 라이브러리를 즉시 마운트합니다.

새로 고침 주기는 RBLN_CTK_DAEMON_REFRESH_INTERVAL 환경 변수 또는 --refresh-interval 플래그로 제어합니다. 기본값은 60s 이며 0 으로 설정하면 새로 고침이 비활성화됩니다. 데몬은 임시 파일에 사양을 작성한 뒤 fsync + rename 순서로 교체하므로 컨테이너 런타임은 항상 완전한 사양을 읽습니다.

데몬은 /ready 엔드포인트의 cdi-refresh 블록으로 마지막 실행 시각, 검색된 라이브러리 수, 직전 새로 고침 오류를 보고합니다.

Kubernetes Pod 예제¶

apiVersion: v1
kind: Pod
metadata:
  name: rbln-workload
spec:
  containers:
  - name: app
    image: ubuntu:22.04
    resources:
      limits:
        rebellions.ai/npu: "1"

CoreOS / OpenShift¶

호스트 파일시스템이 /host에 마운트된 Red Hat CoreOS 환경의 경우:

env:
  - name: RBLN_CTK_DAEMON_HOST_ROOT
    value: "/host"

고급 설정¶

라이브러리 격리¶

기본적으로 RBLN 라이브러리는 컨테이너 내부의 호스트 경로에 바인드 마운트됩니다. 이로 인해 충돌이 발생하는 경우(예: 다른 glibc 버전), 라이브러리 격리를 사용하세요:

$ sudo rbln-ctk cdi generate --container-library-path /rbln/lib64

이 모드는:

호스트 경로 대신 격리된 경로(/rbln/lib64)에 라이브러리를 마운트합니다
CDI 훅을 사용하여 시작 시 컨테이너 내부에서 ldconfig 를 실행합니다
LD_LIBRARY_PATH 를 사용하지 않습니다 — ldcache 가 라이브러리 검색을 기본적으로 처리합니다
LD_LIBRARY_PATH 를 무시하는 setuid 바이너리도 지원합니다

Systemd 통합¶

DEB·RPM 패키지는 두 개의 systemd 유닛을 /usr/lib/systemd/system/ 아래에 설치하며, postinstall 스크립트가 자동으로 활성화합니다:

rbln-cdi-refresh.path — 표준 라이브러리 경로의 librbln-ml.so 와 rbln-ctk 바이너리 변경을 감시합니다
rbln-cdi-refresh.service — rbln-ctk cdi generate --output /var/run/cdi/rbln.yaml 을 실행하는 oneshot 유닛입니다

드라이버 재설치 또는 툴킷 업그레이드가 path 유닛을 트리거하고, 이로 인해 service 유닛이 실행되어 호스트의 CDI 사양을 다시 작성합니다. 운영자의 추가 조치 없이 새로 시작되는 컨테이너는 현재 라이브러리에 바인딩됩니다.

path 워처가 활성 상태인지 확인:

$ systemctl status rbln-cdi-refresh.path

자체 워크플로로 CDI 재생성을 관리하는 등 새로 고침이 필요 없는 경우 비활성화할 수 있습니다:

$ sudo systemctl disable --now rbln-cdi-refresh.path

이 systemd 경로는 DEB/RPM 설치에만 해당합니다. Kubernetes 에서는 동일한 역할이 rbln-ctk-daemon 내부에서 수행됩니다 — 자동 CDI 새로 고침 참조.

구성 파일¶

툴킷은 /etc/rbln/container-toolkit.yaml에서 구성을 읽습니다.

모든 CLI 플래그는 RBLN_CTK_ 접두사를 사용하는 환경 변수를 통해서도 설정할 수 있습니다(예: --driver-root는 RBLN_CTK_DRIVER_ROOT가 됨).

주요 구성 섹션:

섹션	제어 항목
`cdi`	출력 경로, 형식, 벤더/클래스 이름
`libraries`	검색 패턴, 플러그인 경로, 컨테이너 격리 경로
`tools`	포함할 CLI 도구 (예: `rbln-smi`)
`search-paths`	라이브러리 및 바이너리를 찾을 위치
`glibc-exclude`	CDI 스펙에서 제외할 시스템 라이브러리
`hooks`	CDI 훅 바이너리 및 ldconfig 경로

문제 해결¶

CDI 스펙이 생성되지 않음¶

# RBLN 드라이버가 설치되었는지 확인
$ ls /usr/lib64/librbln-*.so*

# 디버그 출력과 함께 실행
$ rbln-ctk cdi generate --debug

# 검색된 항목 확인
$ rbln-ctk cdi list

컨테이너가 RBLN 라이브러리를 찾을 수 없음¶

# 훅이 설치되었는지 확인
$ ls -la /usr/local/bin/rbln-cdi-hook

# CDI 스펙 재생성
$ sudo rbln-ctk cdi generate

런타임이 변경 사항을 인식하지 못함¶

구성 후 런타임이 CDI 장치를 인식하지 못하는 경우 수동으로 재시작해 보세요:

$ sudo systemctl restart containerd  # 또는 crio, docker

권한 오류¶

대부분의 작업에는 루트 액세스가 필요합니다:

$ sudo rbln-ctk cdi generate
$ sudo rbln-ctk runtime configure

다음 단계¶

NPU 할당 — RSD 그룹을 사용하여 컨테이너에 특정 NPU를 할당하는 방법 알아보기