RBLN Container Toolkit¶

Ubuntu / Debian¶

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

   1 2 3 4 5

   $ 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

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

   1 2 3

   $ 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

3. APT 업데이트 및 설치:

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

RHEL¶

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

   1 2 3 4 5 6 7

   $ 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

2. 캐시 갱신 후 설치:

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

설정 확인¶

1
2
3
4
5
6
7
8

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

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

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

적용 전 미리보기¶

쓰기를 수행하는 두 서브커맨드 cdi generate 와 runtime configure 는 --dry-run 을 지원하여 실제로 수정하지 않고 변경될 내용을 확인할 수 있습니다. runtime configure 는 미리보기 전에 대상 런타임을 먼저 확정하므로, 런타임이 여러 개인 호스트에서는 여기서도 -r 이 필요합니다:

1
2

$ rbln-ctk cdi generate --dry-run
$ sudo rbln-ctk runtime configure -r docker --dry-run

전역 옵션¶

모든 rbln-ctk 하위 명령에 공통으로 적용됩니다.

rbln-ctk cdi generate¶

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

1

$ sudo rbln-ctk cdi generate

rbln-ctk runtime configure¶

컨테이너 런타임 구성에서 CDI 지원을 활성화합니다. 런타임 소켓이 하나만 있을 때는 런타임을 자동으로 선택하며, 그 외에는 -r 지정이 필요합니다.

1

$ sudo rbln-ctk runtime configure

rbln-ctk cdi list¶

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

1

$ rbln-ctk cdi list

rbln-ctk info¶

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

1

$ rbln-ctk info

rbln-ctk version¶

툴킷 버전과 빌드 정보를 출력합니다.

1

$ rbln-ctk version

rbln-ctk-daemon runtime¶

DaemonSet 이 남긴 런타임 구성과 CDI 스펙 파일을 수동으로 적용하거나 되돌리는 일회성 명령입니다. 런타임별 하위 명령(docker, containerd, crio) 아래에 setup 과 cleanup 이 있습니다.

setup 은 세 단계를 순서대로 수행합니다. 런타임 구성에서 CDI 를 활성화하고(containerd 의 config.toml 과 Docker 의 daemon.json 은 먼저 .backup 파일로 복사, CRI-O 는 99-rbln.conf 드롭인 생성), CDI 스펙 디렉터리에 rbln.yaml 을 기록한 뒤(RDS 장치가 있는 호스트에서는 rbln-rds.yaml 도 함께), 런타임을 재시작합니다. 재시작은 기본적으로 containerd 와 Docker 에 SIGHUP 을 보내고, CRI-O 는 systemctl restart 로 수행합니다. DaemonSet 과 달리 CDI 가 이미 활성화되어 있는지 먼저 확인하지 않으므로, 실행할 때마다 구성을 다시 쓰고 런타임을 재시작합니다.

1
2

# 런타임 구성에 CDI 활성화, CDI 스펙 생성, 런타임 재시작
$ sudo rbln-ctk-daemon runtime containerd setup

cleanup 은 세 단계를 순서대로 수행합니다. CDI 스펙 디렉터리에서 rbln.yaml 과 rbln-rds.yaml 을 제거하고, 런타임 구성을 되돌린 뒤(containerd 와 Docker 는 .backup 파일에서 복원, CRI-O 는 99-rbln.conf 드롭인 삭제), 런타임을 재시작합니다.

1
2

# CDI 스펙 제거, 런타임 구성 원복, 런타임 재시작
$ sudo rbln-ctk-daemon runtime containerd cleanup

컨테이너 이미지¶

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

1

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

배포¶

1

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

헬스 엔드포인트¶

환경 변수¶

RBLN_CTK_DAEMON_CONFIG_PATH 는 절대 경로여야 하며, 그렇지 않으면 데몬이 시작을 거부합니다. 데몬 파일시스템 기준의 최종 경로로 해석되며 RBLN_CTK_DAEMON_HOST_ROOT 가 자동으로 붙지 않습니다. rke2·k3s 처럼 호스트 기준 경로를 넘길 때는 호출자가 접두사를 직접 포함해야 합니다(예: /var/lib/rancher/rke2/... → /host/var/lib/rancher/rke2/...).

자동 CDI 새로 고침¶

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

데몬은 호스트 RBLN UMD 라이브러리(librbln-ccl, librbln-thunk)의 GNU build-id 를 주기적으로 확인하여, 지문 변경을 감지하면 /var/run/cdi/rbln.yaml 을 다시 생성합니다. build-id 를 읽을 수 없는 라이브러리는 크기와 수정 시각으로 대체 지문을 계산합니다. 데몬이 라이브러리 변경을 자동으로 반영하므로 운영자는 DaemonSet 을 그대로 둔 채 드라이버 재설치나 업그레이드를 적용할 수 있습니다. 컨테이너 런타임은 새로 시작하는 컨테이너에 현재 라이브러리를 즉시 마운트합니다.

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

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

Kubernetes Pod 예제¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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 환경의 경우:

1
2
3

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

라이브러리 격리¶

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

1

$ 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 워처가 활성 상태인지 확인:

1

$ systemctl status rbln-cdi-refresh.path

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

1

$ 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 스펙이 생성되지 않음¶

1
2
3
4
5
6
7
8

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

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

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

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

1
2
3
4
5

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

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

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

구성 후 런타임이 CDI 장치를 인식하지 못하는 경우 수동으로 재시작합니다:

1

$ sudo systemctl restart containerd  # 또는 crio, docker

권한 오류¶

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

1
2

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