Skip to content

Commit f87f538

Browse files
skopacz1skopacz1
authored
Merge pull request #77072 from aspauldi/CNV-29336
CNV#29336: Document USB host passthrough (GA)
2 parents 42c9cb3 + 3d4e5e0 commit f87f538

File tree

4 files changed

+123
-0
lines changed

4 files changed

+123
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4431,6 +4431,8 @@ Topics:
44314431
File: virt-configuring-pci-passthrough
44324432
- Name: Configuring virtual GPUs
44334433
File: virt-configuring-virtual-gpus
4434+
- Name: Configuring USB host passthrough
4435+
File: virt-configuring-usb-host-passthrough
44344436
- Name: Enabling descheduler evictions on virtual machines
44354437
File: virt-enabling-descheduler-evictions
44364438
- Name: About high availability for virtual machines

‎modules/virt-configuring-vm-use-usb-device.adoc

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt//virtual_machines/advanced_vm_management/virt-configuring-usb-host-passthrough.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="virt-configuring-vm-use-usb-device_{context}"]
7+
= Configuring a virtual machine connection to a USB device
8+
9+
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 {product-title} node, as if the hardware and VM are physically connected.
10+
11+
.Procedure
12+
13+
. Locate the USB device by running the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ oc /dev/serial/by-id/usb-VENDOR_device_name
18+
----
19+
20+
. Open the virtual machine instance custom resource (CR) by running the following commmand:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc edit vmi vmi-usb
25+
----
26+
27+
. Edit the CR by adding a USB device, as shown in the following example:
28+
+
29+
.Example configuration
30+
[source, yaml]
31+
----
32+
apiVersion: kubevirt.io/v1
33+
kind: VirtualMachineInstance
34+
metadata:
35+
labels:
36+
special: vmi-usb
37+
name: vmi-usb <1>
38+
spec:
39+
domain:
40+
devices:
41+
hostDevices:
42+
- deviceName: kubevirt.io/peripherals
43+
name: local-peripherals
44+
# ...
45+
----
46+
<1> The name of the USB device.
47+

‎modules/virt-enabling-usb-host-passthrough.adoc

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/advanced_vm_management/virt-configuring-usb-host-passthrough.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="virt-enabling-usb-host-passthrough_{context}"]
7+
= Enabling USB host passthrough
8+
9+
You can enable USB host passthrough at the cluster level.
10+
11+
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.
12+
13+
.Prerequisites
14+
15+
* You have access to an {product-title} cluster as a user who has the `cluster-admin` role.
16+
17+
.Procedure
18+
19+
. Identify the USB device vendor and product by running the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ lsusb
24+
----
25+
26+
. Open the HCO CR by running the following commmand:
27+
+
28+
[source,terminal]
29+
----
30+
$ oc edit hyperconverged kubevirt-hyperconverged -n openshift-cnv
31+
----
32+
33+
. Add a USB device to the `permittedHostDevices` stanza, as shown in the following example:
34+
35+
+
36+
.Example YAML snippet
37+
[source,yaml]
38+
----
39+
apiVersion: hco.kubevirt.io/v1beta1
40+
kind: HyperConverged
41+
metadata:
42+
name: kubevirt-hyperconverged
43+
namespace: {CNVNamespace}
44+
spec:
45+
configuration:
46+
permittedHostDevices: <1>
47+
usbHostDevices: <2>
48+
- resourceName: kubevirt.io/peripherals <3>
49+
selectors:
50+
- vendor: "045e"
51+
product: "07a5"
52+
- vendor: "062a"
53+
product: "4102"
54+
- vendor: "072f"
55+
product: "b100"
56+
57+
----
58+
<1> Lists the host devices that have permission to be used in the cluster.
59+
<2> Lists the available USB devices.
60+
<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`.

‎virt/virtual_machines/advanced_vm_management/virt-configuring-usb-host-passthrough.adoc

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="virt-configuring-USB-host-passthrough"]
3+
= Configuring USB host passthrough
4+
include::_attributes/common-attributes.adoc[]
5+
:context: virt-configuring-USB-host-passthrough
6+
7+
toc::[]
8+
9+
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 {product-title} node, as if the hardware and the VM are physically connected.
10+
11+
You can expose a USB device by first enabling host passthrough and then configuring the VM to use the USB device.
12+
13+
include::modules/virt-enabling-usb-host-passthrough.adoc[leveloffset=+1]
14+
include::modules/virt-configuring-vm-use-usb-device.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)