1. Documentation
×

Configuring USB host passthrough

As a cluster administrator, you can expose USB devices in a cluster, making them available for virtual machine (VM) owners to assign to VMs. Enabling this passthrough of USB devices allows a guest to connect to actual USB hardware that is attached to an OKD node, as if the hardware and the VM are physically connected.

You can expose a USB device by first enabling host passthrough and then configuring the VM to use the USB device.

Enabling USB host passthrough

You can enable USB host passthrough at the cluster level.

You specify a resource name and USB device name for each device you want first to add and then assign to a virtual machine (VM). You can allocate more than one device, each of which is known as a selector in the HyperConverged (HCO) 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 OKD cluster as a user who has the cluster-admin role.

Procedure

  1. Identify the USB device vendor and product by running the following command:

    $ lsusb

  2. Open the HCO CR by running the following commmand:

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

  3. Add a USB device to the permittedHostDevices stanza, as shown in the following example:

    Example YAML snippet
    apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
   name: kubevirt-hyperconverged
   namespace: {CNVNamespace}
spec:
  configuration:
    permittedHostDevices: (1)
      usbHostDevices: (2)
        - resourceName: kubevirt.io/peripherals (3)
          selectors:
            - vendor: "045e"
              product: "07a5"
            - vendor: "062a"
              product: "4102"
            - vendor: "072f"
              product: "b100"
    1 Lists the host devices that have permission to be used in the cluster.
    2 Lists the available USB devices.
    3 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.

Configuring a virtual machine connection to a USB device

You can configure virtual machine (VM) access to a USB device. This configuration allows a guest to connect to actual USB hardware that is attached to an OKD node, as if the hardware and the VM are physically connected.

Procedure

  1. Locate the USB device by running the following command:

    $ oc /dev/serial/by-id/usb-VENDOR_device_name

  2. Open the virtual machine instance custom resource (CR) by running the following commmand:

    $ oc edit vmi vmi-usb

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

    Example configuration
    apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  labels:
    special: vmi-usb
  name: vmi-usb (1)
spec:
  domain:
    devices:
      hostDevices:
      - deviceName: kubevirt.io/peripherals
        name: local-peripherals
# ...
    1 The name of the USB device.