Skip to content

RBLN Container Toolkit

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 — so containers can use NPU hardware with zero application changes.

Scope

The Container Toolkit currently handles CDI spec generation — mounting RBLN libraries and tools (such as rbln-smi) into containers. 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
                          ┌──────────────────────────────────────────┐
  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         │
                          └──────────────────────────────────────────┘

The toolkit provides three binaries:

Binary Role
rbln-ctk Main CLI — generate CDI specs, configure runtimes, inspect 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

Installation

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

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

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

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

Quick Start

The fastest way to get NPU access in containers:

1
2
3
4
5
6
7
8
# 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

That's it. The toolkit auto-detects your runtime and applies the right configuration.

Verify Setup

1
2
3
4
5
6
7
8
# Check what was discovered
$ rbln-ctk cdi list

# View system info
$ 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:

1
2
$ 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.

1
$ 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 running container runtime and enables CDI support.

1
$ 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.

1
$ rbln-ctk cdi list

rbln-ctk info

Displays system information including detected runtime and configuration.

1
$ 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 runtime
  4. Serves health check endpoints
  5. Cleans up on SIGTERM (pod termination)

Container Image

The official container image is available on Docker Hub:

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

Deploy

1
$ 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 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

 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

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

1
2
3
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:

1
$ 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:

1
2
3
4
$ 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

1
2
3
4
5
6
7
8
# 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 can't find RBLN libraries

1
2
3
4
5
# 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:

1
$ sudo systemctl restart containerd  # or crio, docker

Permission errors

Most operations require root access:

1
2
$ 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