Configuring USB host passthrough¶

You can enable passthrough of USB devices to allow a virtual machine (VM) to connect to USB hardware that is attached to an OpenShift Container Platform node, as if the hardware and the VM are physically connected.

To expose a USB device, first enable host passthrough and then configure the VM to use the USB device.

Enabling USB host passthrough¶

To attach a USB device to a virtual machine (VM), you must first enable USB host passthrough at the cluster level.

To do this, specify a resource name and USB device name for each device you want first to add and then assign to a VM. You can allocate more than one device, each of which is known as a selector in the HyperConverged custom resource (CR), to a single resource name. If you have multiple identical USB devices on the cluster, you can choose to allocate a VM to a specific device.

Prerequisites

You have access to an OpenShift Container Platform cluster as a user who has the cluster-admin role.
You have installed the OpenShift CLI (oc).

Procedure

Identify the USB device vendor and product:

$ lsusb

Example output

Bus 003 Device 007: ID 1b1c:0a60 example_manufacturer example_product_name

If you cannot use the lsusb command, inspect the USB device configurations in the host’s /sys/bus/usb/devices/ directory:

for dev in *; do
    if [[ -f "$dev/idVendor" && -f "$dev/idProduct" ]]; then
        echo "Device: $dev"
        echo -n "  Manufacturer : "; cat "$dev/manufacturer"
        echo -n "  Product: "; cat "$dev/product"
        echo -n "  Vendor ID : "; cat "$dev/idVendor"
        echo -n "  Product ID: "; cat "$dev/idProduct"
        echo
    fi
done

Example output

Device: 3-7
  Manufacturer : example_manufacturer
  Product: example_product_name
  Vendor ID : 1b1c
  Product ID: 0a60

Open the HyperConverged CR in your default editor by running the following command:

$ oc edit hyperconvergeds.v1beta1.hco.kubevirt.io kubevirt-hyperconverged -n openshift-cnv

Add the required USB device to the permittedHostDevices stanza of the HyperConvered CR. The following example adds a device with vendor ID 045e and product ID 07a5:
```
apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
  namespace: openshift-cnv
spec:
  permittedHostDevices:
    usbHostDevices:
    - resourceName: kubevirt.io/peripherals
      selectors:
      - vendor: "045e"
        product: "07a5"
      - vendor: "062a"
        product: "4102"
      - vendor: "072f"
        product: "b100"
```
- spec.permittedHostDevices defines the host devices that have permission to be used in the cluster.
- spec.permittedHostDevices.usbHostDevices defines a list of available USB devices.
- spec.permittedHostDevices.usbHostDevices.resourceName defines the USB device that you want to add and assign to the VM. In this example, the resource is bound to three devices, each of which is identified by vendor and product and is known as a selector.

Connecting a USB device to a virtual machine¶

You can configure virtual machine (VM) access to a USB device. This configuration enables the VM to connect to USB hardware that is attached to an OpenShift Container Platform node, as if the hardware and the VM are physically connected.

Prerequisites

You have installed the OpenShift CLI (oc).
You have attached the required USB device as a resource at the cluster level.

Procedure

In the HyperConverged custom resource (CR), find the assigned resource name of the USB device:

$ oc get hyperconvergeds.v1beta1.hco.kubevirt.io kubevirt-hyperconverged -n openshift-cnv

Example output:

# ...
  spec:
    permittedHostDevices:
      usbHostDevices:
        - resourceName: kubevirt.io/peripherals
          selectors:
            - vendor: "045e"
              product: "07a5"
            - vendor: "062a"
              product: "4102"
            - vendor: "072f"
              product: "b100"

Open the VM CR:
```
$ oc edit vm <vm_name>
```
where:

<vm_name>

Specifies the name of the VirtualMachine CR.

Edit the CR by adding the USB device, as shown in the following example:

Example configuration:

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: example-vm
spec:
  template:
    spec:
      architecture: amd64
      domain:
        devices:
          hostDevices:
          - deviceName: kubevirt.io/peripherals
            name: local-peripherals
# ...

spec.template.spec.domain.devices.hostDevices.deviceName specifies the resource name from the HyperConverged CR.
spec.template.spec.domain.devices.hostDevices.name defines the name of the USB device.

Save and apply your changes:
```
$ oc apply -f <filename>.yaml
```
where:

<filename>

Specifies the name of the VirtualMachine manifest YAML file.