RBLN Container Toolkit

The RBLN Container Toolkit enables container runtimes to access Rebellions NPU devices using the Container Device Interface (CDI) specification. It automatically discovers host RBLN libraries and tools, generates CDI specs, and configures your container runtime, enabling containers to use NPU hardware with zero application changes.

Scope

The Container Toolkit is currently responsible only for CDI spec generation and runtime configuration. It exposes RBLN libraries and tools (such as rbln-smi) to containers via CDI. For NPU device allocation using RSD groups, see the NPU Allocation guide. These features will be integrated into a unified toolkit in a future release.

How It Works

                          ┌──────────────────────────────────────────┐
  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. Run Hook    to update ldcache        │
                          │                 inside containers        │
                          └─────────────────────┬────────────────────┘
                                                │
                                                ▼
                          ┌──────────────────────────────────────────┐
  Container               │  $ docker run --device rebellions.ai/    │
                          │      npu=runtime my-app                  │
                          │                                          │
                          │  ✓ RBLN libraries mounted                │
                          │  ✓ Tools available (rbln-smi)            │
                          │  ✓ ldcache updated automatically         │
                          └──────────────────────────────────────────┘

The toolkit provides three binaries:

Binary	Role
rbln-ctk	Main CLI — generates CDI specs, configures runtimes, inspects the system
rbln-ctk-daemon	Kubernetes daemon — automated setup with health endpoints and graceful shutdown
rbln-cdi-hook	OCI hook — runs inside containers to update ldcache and create symlinks

Prerequisites

OS	Architecture	Container Runtime
Ubuntu 22.04/24.04	x86_64	containerd, CRI-O, Docker
RHEL 9+	x86_64	containerd, CRI-O, Docker

• RBLN driver installed on the host system

Installation

1. Add the Rebellions official GPG key (skip if already configured):

   $ 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. Add the repository to APT sources (skip if already configured):

   $ 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. Update APT and install:

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

Quick Start

The quickest way to enable NPU access in containers:

# 1. Generate CDI specification (discovers RBLN libraries on host)
$ sudo rbln-ctk cdi generate

# 2. Configure your container runtime for CDI support
$ sudo rbln-ctk runtime configure

# 3. Run a container with NPU access
$ docker run --device rebellions.ai/npu=runtime -it ubuntu:22.04

The toolkit auto-detects your runtime and applies the appropriate configuration.

Verify Setup

# Check what was discovered on the host
$ rbln-ctk cdi list

# View detected runtime and configuration
$ rbln-ctk info

# Use NPU tools inside a container
$ docker run --device rebellions.ai/npu=runtime -it ubuntu:22.04 rbln-smi

Preview Before Applying

Every command supports --dry-run to see what would change without modifying anything:

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

CLI Reference

rbln-ctk cdi generate

Discovers RBLN libraries and tools, then writes a CDI spec.

$ sudo rbln-ctk cdi generate

Flag	Description	Default
-o, --output	Output path	/var/run/cdi/rbln.yaml
-f, --format	Output format (yaml or json)	yaml
--driver-root	Root path for driver files (CoreOS: /host)	/
--container-library-path	Isolated library path in container	(same as host)
--dry-run	Preview without writing	false

rbln-ctk runtime configure

Auto-detects the active container runtime and enables CDI support.

$ sudo rbln-ctk runtime configure

Flag	Description	Default
-r, --runtime	Force specific runtime (containerd, crio, docker)	(auto-detect)
--config-path	Custom runtime config path	(runtime default)
--dry-run	Preview changes	false

rbln-ctk cdi list

Lists discovered RBLN libraries and tools.

$ rbln-ctk cdi list

rbln-ctk info

Displays system information including detected runtime and configuration.

$ rbln-ctk info

Kubernetes Deployment

For Kubernetes clusters, deploy the toolkit as a DaemonSet. The daemon (rbln-ctk-daemon) handles the entire lifecycle:

1. Generates CDI spec on startup
2. Configures the container runtime
3. Restarts the container runtime
4. Serves health check endpoints
5. Cleans up on SIGTERM (pod termination)

Container Image

The official container image is available on Docker Hub:

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

Deploy

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

Health Endpoints

Endpoint	Probe Type	Returns 200 When
/live	Liveness	Daemon process is running
/ready	Readiness	Setup is complete
/startup	Startup	Initialization finished

Environment Variables

Variable	Description	Default
RBLN_CTK_DAEMON_RUNTIME	Container runtime	(auto-detect)
RBLN_CTK_DAEMON_HOST_ROOT	Host root mount path	/ (host), /host (container)
RBLN_CTK_DAEMON_DRIVER_ROOT	Driver root path for CDI spec	/
RBLN_CTK_DAEMON_CDI_SPEC_DIR	CDI spec directory	/var/run/cdi
RBLN_CTK_DAEMON_CONTAINER_LIBRARY_PATH	Container library path for library isolation	(empty)
RBLN_CTK_DAEMON_SOCKET	Runtime socket path	(auto-detect)
RBLN_CTK_DAEMON_HEALTH_PORT	Health check port	8080
RBLN_CTK_DAEMON_SHUTDOWN_TIMEOUT	Graceful shutdown timeout	30s
RBLN_CTK_DAEMON_PID_FILE	PID file path	/run/rbln/toolkit.pid
RBLN_CTK_DAEMON_NO_CLEANUP_ON_EXIT	Skip cleanup on exit	false
RBLN_CTK_DAEMON_DEBUG	Enable debug logging	false
RBLN_CTK_DAEMON_FORCE	Terminate existing instance before starting	false

Kubernetes Pod Example

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

CoreOS / OpenShift

For Red Hat CoreOS environments where the host filesystem is mounted at /host:

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

Advanced Configuration

Library Isolation

By default, RBLN libraries are bind-mounted at their host paths inside the container. If this causes conflicts (e.g., different glibc versions), use library isolation:

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

This mode:

• Mounts libraries to an isolated path (/rbln/lib64) instead of host paths
• Uses the CDI hook to run ldconfig inside the container at startup
• Avoids LD_LIBRARY_PATH — the ldcache handles library resolution natively
• Supports setuid binaries (which ignore LD_LIBRARY_PATH)

Systemd Integration

For automatic CDI spec refresh when driver files change:

$ 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

Configuration File

The toolkit reads configuration from /etc/rbln/container-toolkit.yaml.

All CLI flags can also be set via environment variables with the prefix RBLN_CTK_ (e.g., --driver-root becomes RBLN_CTK_DRIVER_ROOT).

Key configuration sections:

Section	Controls
cdi	Output path, format, vendor/class names
libraries	Discovery patterns, plugin paths, container isolation path
tools	Which CLI tools to include (e.g., rbln-smi)
search-paths	Where to look for libraries and binaries
glibc-exclude	System libraries to exclude from CDI spec
hooks	CDI hook binary and ldconfig paths

Troubleshooting

CDI spec not generated

# Verify RBLN driver is installed
$ ls /usr/lib64/librbln-*.so*

# Run with debug output
$ rbln-ctk cdi generate --debug

# Check what was discovered
$ rbln-ctk cdi list

Container cannnot find RBLN libraries

# Verify hook is installed
$ ls -la /usr/local/bin/rbln-cdi-hook

# Regenerate CDI spec
$ sudo rbln-ctk cdi generate

Runtime not picking up changes

If the runtime is not recognizing CDI devices after configuration, try restarting it manually:

$ sudo systemctl restart containerd  # or crio, docker

Permission errors

Most operations require root access:

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

Next Steps

• NPU Allocation — Learn how to allocate specific NPUs to containers using RSD groups