RBLN Container Toolkit¶

Ubuntu / Debian¶

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

RHEL¶

1. Register the Rebellions yum repository (skip if already configured):

   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. Refresh the cache and install:

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

Verify Setup¶

1
2
3
4
5
6
7
8

# 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=all -it ubuntu:22.04 rbln-smi

Preview Before Applying¶

cdi generate and runtime configure — the two subcommands that write — support --dry-run to see what would change without modifying anything. runtime configure resolves its target before it previews anything, so a multi-runtime host needs -r here too:

1
2

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

Global Options¶

These apply to every rbln-ctk subcommand.

rbln-ctk cdi generate¶

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

1

$ sudo rbln-ctk cdi generate

rbln-ctk runtime configure¶

Enables CDI support in the container runtime config. The runtime is picked automatically only when exactly one runtime socket is present; otherwise -r is required.

1

$ sudo rbln-ctk runtime configure

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

rbln-ctk version¶

Prints the toolkit version and build information.

1

$ rbln-ctk version

rbln-ctk-daemon runtime¶

A one-shot command that applies or reverts the runtime configuration and CDI spec files a DaemonSet left behind. Each runtime subcommand (docker, containerd, crio) carries setup and cleanup.

setup runs three steps in order: it enables CDI in the runtime config (containerd's config.toml and Docker's daemon.json are first copied to a .backup file; CRI-O gets the 99-rbln.conf drop-in), writes rbln.yaml to the CDI spec directory along with rbln-rds.yaml on hosts that have RDS devices, and restarts the runtime — by default with SIGHUP for containerd and Docker and systemctl restart for CRI-O. Unlike the DaemonSet, it does not first check whether CDI is already enabled, so every run rewrites the config and restarts the runtime.

1
2

# Enable CDI in the runtime config, write the CDI specs, and restart the runtime
$ sudo rbln-ctk-daemon runtime containerd setup

cleanup runs three steps in order: it removes rbln.yaml and rbln-rds.yaml from the CDI spec directory, reverts the runtime config (containerd and Docker are restored from their .backup file, CRI-O's 99-rbln.conf drop-in is deleted), and restarts the runtime.

1
2

# Remove the CDI specs, revert the runtime config, and restart the runtime
$ sudo rbln-ctk-daemon runtime containerd cleanup

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¶

Environment Variables¶

RBLN_CTK_DAEMON_CONFIG_PATH must be an absolute path; the daemon refuses to start otherwise. It is treated as the final path inside the daemon filesystem and is not auto-prefixed with RBLN_CTK_DAEMON_HOST_ROOT. Callers passing host-relative paths, as on rke2 and k3s, must include the prefix themselves (for example, /var/lib/rancher/rke2/... → /host/var/lib/rancher/rke2/...).

Automatic CDI Refresh¶

rbln-ctk-daemon (the Kubernetes DaemonSet binary) drives the refresh loop. On DEB/RPM hosts, the systemd unit described in Systemd Integration handles the same job.

The daemon periodically fingerprints the host's RBLN UMD libraries (librbln-ccl, librbln-thunk) by their GNU build-id and regenerates /var/run/cdi/rbln.yaml whenever a fingerprint changes. Libraries with no readable build-id fall back to a size and mtime digest. Because the daemon tracks library changes automatically, operators can reinstall or upgrade the driver while keeping the DaemonSet in place. The container runtime mounts the current library into each new container at startup.

RBLN_CTK_DAEMON_REFRESH_INTERVAL (or the --refresh-interval flag) controls the refresh period. The default is 60s; setting 0 disables polling. The daemon writes the spec to a temporary file, then swaps it in with fsync followed by rename, so the container runtime always reads a complete spec.

The /ready endpoint response includes a cdi-refresh block that reports the last run time, the number of libraries discovered, and the most recent refresh error (if any).

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"

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¶

The DEB and RPM packages install two systemd units under /usr/lib/systemd/system/ and the postinstall script enables them automatically:

• rbln-cdi-refresh.path — watches librbln-ml.so under the standard library paths and the rbln-ctk binary
• rbln-cdi-refresh.service — oneshot unit that runs rbln-ctk cdi generate --output /var/run/cdi/rbln.yaml

A driver re-install or a toolkit upgrade triggers the path unit, which runs the service unit and rewrites the CDI spec on the host. Newly started containers bind to the current libraries without any operator action.

Verify the path watcher is active:

1

$ systemctl status rbln-cdi-refresh.path

To turn the refresher off (for example, on a host that drives CDI regeneration via a custom workflow):

1

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

This systemd path applies to DEB/RPM installs only. On Kubernetes, the equivalent loop runs in-process inside rbln-ctk-daemon — see Automatic CDI Refresh.

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:

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 cannot 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