Alauda Container Platform

Configuring USB host passthrough

TOC

Feature Overview

USB(Universal Serial Bus) pass-through feature enables you to access and manage USB devices from a virtual machine.

Use Cases

Some applications running in virtual machines (VMs) have encryption requirements and need to interact with dedicated USB devices. In such cases, it is necessary to passthrough the USB devices from the host machine to the VM.

Prerequisites

  • The platform version must be at least v3.18.

Steps

Expose USB devices

To assign a USB device to a VM, the USB device must be exposed via a ResourceName. This can be configured by editing the spec.permittedHostDevices.usbHostDevices section in the HyperConverged CR under the kubevirt namespace.

Below is an example configuration for a USB device with ResourceName kubevirt.io/storage, where the vendor is 0bda and the product is 8812:

spec:
  permittedHostDevices:
    usbHostDevices:
      - resourceName: kubevirt.io/storage
        selectors:
          - vendor: '0bda'
            product: '8812'
Tip

The vendor and product identifiers of a USB device can be obtained using the lsusb command. For example:

lsusb
Bus 001 Device 007: ID 0bda:8812 Realtek Semiconductor Corp. RTL8812AU 802.11a/b/g/n/ac 2T2R DB WLAN Adapter

This command lists all connected USB devices, where ID displays the vendor:product pair.

Assign USB devices to a Virtual Machine

Now, in the VM configuration, you can add spec.domain.devices.hostDevices.deviceName to reference the ResourceName provided in the previous step and assign it a local name. For example:

spec:
  domain:
    devices:
      hostDevices:
        - deviceName: kubevirt.io/storage
          name: usb-storage
Tip

Ensure the VM is stopped before editing the configuration.

Operation Result

After completing the configuration, execute the lsusb command within the virtual machine. If the output lists the host node's USB device, the passthrough was successful. For example:

lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 0bda:8812 Realtek Semiconductor Corp. RTL8812AU 802.11a/b/g/n/ac 2T2R DB WLAN Adapter
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Learn More

You may want to passthrough multiple USB devices to a virtual machine, such as a keyboard, mouse, or smart card device. We support assigning multiple USB devices under the same resourceName. Here's how to configure it:

Expose multiple USB devices

spec:
  permittedHostDevices:
    usbHostDevices:
      - resourceName: kubevirt.io/peripherals
        selectors:
          - vendor: '0bda'
            product: '8812'
          - vendor: '062a'
            product: '4102'
          - vendor: '072f'
            product: 'b100'
Tip

Note: All USB devices must be physically connected and detected on the host to ensure successful assignment to the virtual machine.

Assign USB devices to a Virtual Machine

spec:
  domain:
    devices:
      hostDevices:
        - deviceName: kubevirt.io/peripherals
          name: local-peripherals

View full docs as PDF