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=runtime 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 업데이트 및 심볼릭 링크 생성

사전 요구사항¶

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

호스트에 RBLN 드라이버 설치

설치¶

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

빠른 시작¶

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

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

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

# 3. NPU 액세스가 가능한 컨테이너 실행
$ docker run --device rebellions.ai/npu=runtime -it ubuntu:22.04

이것으로 끝입니다. 툴킷이 런타임을 자동으로 감지하고 올바른 구성을 적용합니다.

설정 확인¶

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

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

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

적용 전 미리보기¶

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

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

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_DEBUG`	디버그 로깅 활성화	`false`
`RBLN_CTK_DAEMON_FORCE`	시작 전 기존 인스턴스 종료	`false`

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가 라이브러리 해석을 기본적으로 처리합니다
setuid 바이너리를 지원합니다 (LD_LIBRARY_PATH를 무시함)

Systemd 통합¶

드라이버 파일이 변경될 때 CDI 사양을 자동으로 새로 고치려면:

$ sudo cp deployments/systemd/rbln-cdi-refresh.service /etc/systemd/system/
$ sudo cp deployments/systemd/rbln-cdi-refresh.path /etc/systemd/system/
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now rbln-cdi-refresh.path

구성 파일¶

툴킷은 /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를 할당하는 방법 알아보기