Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add usbdevice documentation #638

Merged
merged 1 commit into from
Sep 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 55 additions & 1 deletion docs/advanced/addons/pcidevices.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,4 +94,58 @@ We have also introduced a new filter to help you filter PCI devices by the under
![](/img/v1.2/pcidevices/SriovNetworkDevicesFilter.png)

The newly created PCI device can be passed through to virtual machines like any other PCI device.
![](/img/v1.2/pcidevices/SriovNetworkDevicesFilterResult.png)
![](/img/v1.2/pcidevices/SriovNetworkDevicesFilterResult.png)

## USB Devices

_Available as of v1.4.0_

A `USBDevice` resource in Harvester represents a USB device on the node. USB devices can be "passed through" by the hypervisor to allow direct access from VMs. This is accomplished through the `pcidevices-controller` add-on. To use USB passthrough, you can either create a `USBDeviceClaim` resource or enable the feature on the Harvester UI.

USB passthrough is slightly different from PCI passthrough. For example, you can fully control a USB controller with four USB ports by creating a `PCIDeviceClaim`. However, you can also create a `USBDeviceClaim` to control only one USB port. The other three USB ports remain available to the node.

### Enable Passthrough on a USB Device

1. On the Harvester UI, go to **Advanced** > **USB Devices**.

![](/img/v1.4/usbdevices/index.png)

1. Locate the device in the list.

![](/img/v1.4/usbdevices/search.png)

1. Select the target device, and then select **⋮** > **Enable Passthrough**.

![](/img/v1.4/usbdevices/select.png)

1. Read the confirmation message, and then click **Enable**. Allow some time for the device state to change to **Enabled**.

![](/img/v1.4/usbdevices/enable-done.png)

### Attach a USB Device to a Virtual Machine

1. Verify that passthrough is enabled on the target device.

1. Go to **Virtual Machines**, and then create a virtual machine or edit the configuration of an existing virtual machine.

1. On the virtual machine configuration screen, go to the **USB Devices** tab and then select a device from the **Available USB Devices** list.

![](/img/v1.4/usbdevices/attach-vm.png)

1. Click **Create** or **Save**.

### View USB Devices Attached to a Virtual Machine

1. Start and then access the virtual machine.

1. Run `lsusb`. This utility displays information about USB buses and attached devices.

![](/img/v1.4/usbdevices/usb-in-vm.png)

### Limitations

- Virtual machines with attached USB devices cannot be live-migrated because the devices are bound to a specific node.

- Hot-plugging and replugging of USB devices is not supported. For more information, see [KubeVirt Issue #11979](https://github.com/kubevirt/kubevirt/issues/11979).

- If the device path changes when you reattach the device or reboot the node, you must create a new USBDeviceClaim to enable the device.
Binary file added static/img/v1.4/usbdevices/attach-vm.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/v1.4/usbdevices/enable-done.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/v1.4/usbdevices/index.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/v1.4/usbdevices/search.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/v1.4/usbdevices/select.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/v1.4/usbdevices/usb-in-vm.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.