Configuring USB host passthrough

As a cluster administrator, you can expose USB devices in a cluster, which makes the devices available for virtual machine (VM) owners to assign to VMs. Enabling this passthrough of USB devices allows a 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

Ensure that the HostDevices feature gate is enabled:

$ oc get featuregate cluster -o yaml

Successful output

  featureGates:
# ...
    enabled:
    - name: HostDevices

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

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:

oc patch hyperconverged kubevirt-hyperconverged \
  -n openshift-cnv \
  --type=merge \
  -p '{
    "metadata": {
      "annotations": {
        "kubevirt.kubevirt.io/jsonpatch": "[{\"op\": \"add\", \"path\": \"/spec/permittedHostDevices/usbHostDevices/-\", \"value\": {\"resourceName\": \"kubevirt.io/peripherals\", \"selectors\": [{\"vendor\": \"045e\", \"product\": \"07a5\"}]}}]"
      }
    }
  }'

Verification

Ensure that the HCO CR contains the required USB devices:

$ oc get hyperconverged kubevirt-hyperconverged -n openshift-cnv

Example output

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"

Lists the host devices that have permission to be used in the cluster.
Lists the available USB devices.
Uses resourceName: deviceName for each device 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 hyperconverged 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 instance CR:
```
$ oc edit vmi <vmi_usb>
```
where:

<vmi_usb>

Specifies the name of the VirtualMachineInstance CR.

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

Example configuration

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  labels:
    special: vmi-usb
  name: vmi-usb
spec:
  domain:
    devices:
      hostDevices:
      - deviceName: kubevirt.io/peripherals
        name: local-peripherals 
# ...

The name of the USB device.

Apply the modifications to the VM configurations:
```
$ oc apply -f <filename>.yaml
```
where:

<filename>

Specifies the name of the VirtualMachineInstance manifest YAML file.