Skip to content

VM Passthrough with the Sandbox Device Plugin

Complete the sandboxed workload setup, then use the Sandbox Device Plugin to attach an NPU through a product-specific Kubernetes resource.

The plugin advertises a product-specific resource for each NPU model bound to vfio-pci. Register these resources in KubeVirt's permittedHostDevices, then reference them in the VM's hostDevices configuration. For allocation through ResourceClaim, see DRA Driver (VM Passthrough).

Operator Configuration

For a VM-only cluster, use the Sandbox Device Plugin tab in KubeVirt VM passthrough. For a mixed container and VM cluster, use the same tab in the Helm settings for mixed container and VM workloads.

Installation Verification

Check the pod status and the NPU resources available to VMs.

Pod Status

Check the VFIO Manager and Sandbox Device Plugin pods:

1
kubectl get pods -n <NAMESPACE>

The VFIO Manager and Sandbox Device Plugin pods should be running.

NPU Resources

Check the NPU resources advertised by a VM node:

1
kubectl get node <NODE_NAME> -o jsonpath='{.status.allocatable}'

On a Rebel100™ node, the allocatable map should include rebellions.ai/RBLN-CR13_PF. Other product names are listed in Resource Naming.

Resource Naming

The Sandbox Device Plugin derives Kubernetes resource names from its bundled PCI ID database under the Rebellions vendor ID 1eff. There is no resourceList to maintain.

The plugin converts the PCI database label (for example, RBLN-CR13 (PF)) into the resource suffix. It converts letters to uppercase and replaces whitespace, /, and . with _. It removes all remaining characters except letters, digits, _, and -. The following table lists physical-function (PF) resources:

Product Card model (SKU) PCI device ID (PF) Advertised resource
Rebel100™ RBLN-CR13 2130 rebellions.ai/RBLN-CR13_PF
ATOM™+ RBLN-CA22 1220 rebellions.ai/RBLN-CA22_PF
ATOM™-Max RBLN-CA25 1250 rebellions.ai/RBLN-CA25_PF

Note

The plugin includes its own PCI ID database, so you do not need to configure resource names on the host. If a product is missing from the bundled database, the plugin advertises it under the device-ID name rebellions.ai/RBLN-<device-id> (for example, rebellions.ai/RBLN-1250). It uses this name until you update the plugin to a version whose database includes the product.

KubeVirt VFIO Resource Configuration

Register the NPU resource names in permittedHostDevices.pciHostDevices. Set externalResourceProvider: true so that KubeVirt delegates allocation to the Sandbox Device Plugin.

Merge the entries for your cards into the existing KubeVirt resource from KubeVirt Configuration, preserving its feature gates and other permitted devices. If you use both product families, add the entries from both tabs.

Register the Rebel100™ resources.

1
2
3
4
5
6
7
spec:
  configuration:
    permittedHostDevices:
      pciHostDevices:
      - pciVendorSelector: "1eff:2130"
        resourceName: rebellions.ai/RBLN-CR13_PF
        externalResourceProvider: true

Register the ATOM™ resources.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
spec:
  configuration:
    permittedHostDevices:
      pciHostDevices:
      - pciVendorSelector: "1eff:1220"
        resourceName: rebellions.ai/RBLN-CA22_PF
        externalResourceProvider: true
      - pciVendorSelector: "1eff:1250"
        resourceName: rebellions.ai/RBLN-CA25_PF
        externalResourceProvider: true

Each pciVendorSelector identifies a vendor/device pair, and resourceName matches the resource advertised for that product.

For an example that creates a VM with the registered resource and verifies the device in the guest, see Attach an NPU to a KubeVirt VM.