Skip to content

Commit 78e9ebc

Browse files
sjhala-ccssjhala-ccs
authored
Merge pull request #97142 from jherrman/USB-passthrough-fixes_CNV-52697
CNV#52697: Fixes to USB config docs
2 parents d7f73f2 + b5d94cc commit 78e9ebc

File tree

3 files changed

+124
-21
lines changed

3 files changed

+124
-21
lines changed

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

Lines changed: 46 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,47 +4,83 @@
44

55
:_mod-docs-content-type: PROCEDURE
66
[id="virt-configuring-vm-use-usb-device_{context}"]
7-
= Configuring a virtual machine connection to a USB device
7+
= Connecting a USB device to a virtual machine
88

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 the VM are physically connected.
9+
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 {product-title} node, as if the hardware and the VM are physically connected.
1010

1111
.Prerequisites
1212

1313
* You have installed the {oc-first}.
14+
* You have attached the required USB device as a resource at the cluster level.
1415
1516
.Procedure
1617

17-
. Locate the USB device by running the following command:
18+
. In the `HyperConverged` custom resource (CR), find the assigned resource name of the USB device:
1819
+
1920
[source,terminal]
2021
----
21-
$ oc /dev/serial/by-id/usb-VENDOR_device_name
22+
$ oc get hyperconverged kubevirt-hyperconverged -n openshift-cnv
23+
----
24+
+
25+
*Example output*
26+
+
27+
[source, yaml]
28+
----
29+
# ...
30+
spec:
31+
permittedHostDevices:
32+
usbHostDevices:
33+
- resourceName: kubevirt.io/peripherals
34+
selectors:
35+
- vendor: "045e"
36+
product: "07a5"
37+
- vendor: "062a"
38+
product: "4102"
39+
- vendor: "072f"
40+
product: "b100"
2241
----
2342

24-
. Open the virtual machine instance custom resource (CR) by running the following command:
43+
. Open the VM instance CR:
2544
+
2645
[source,terminal]
2746
----
28-
$ oc edit vmi vmi-usb
47+
$ oc edit vmi <vmi_usb>
2948
----
49+
+
50+
where:
51+
52+
<vmi_usb>:: Specifies the name of the `VirtualMachineInstance` CR.
53+
3054

31-
. Edit the CR by adding a USB device, as shown in the following example:
55+
. Edit the CR by adding the USB device, as shown in the following example:
56+
+
57+
*Example configuration*
3258
+
33-
.Example configuration
3459
[source, yaml]
3560
----
3661
apiVersion: kubevirt.io/v1
3762
kind: VirtualMachineInstance
3863
metadata:
3964
labels:
4065
special: vmi-usb
41-
name: vmi-usb <1>
66+
name: vmi-usb
4267
spec:
4368
domain:
4469
devices:
4570
hostDevices:
4671
- deviceName: kubevirt.io/peripherals
47-
name: local-peripherals
72+
name: local-peripherals <1>
4873
# ...
4974
----
5075
<1> The name of the USB device.
76+
77+
. Apply the modifications to the VM configurations:
78+
+
79+
[source,terminal]
80+
----
81+
$ oc apply -f <filename>.yaml
82+
----
83+
+
84+
where:
85+
86+
<filename>:: Specifies the name of the `VirtualMachineInstance` manifest YAML file.

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

Lines changed: 76 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@
66
[id="virt-enabling-usb-host-passthrough_{context}"]
77
= Enabling USB host passthrough
88

9-
You can enable USB host passthrough at the cluster level.
9+
To attach a USB device to a virtual machine (VM), you must first enable USB host passthrough at the cluster level.
1010

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.
11+
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.
1212

1313
.Prerequisites
1414

@@ -17,24 +17,92 @@ You specify a resource name and USB device name for each device you want first t
1717
1818
.Procedure
1919

20-
. Identify the USB device vendor and product by running the following command:
20+
. Ensure that the `HostDevices` feature gate is enabled:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc get featuregate cluster -o yaml
25+
----
26+
+
27+
*Successful output*
28+
+
29+
[source,yaml]
30+
----
31+
featureGates:
32+
# ...
33+
enabled:
34+
- name: HostDevices
35+
----
36+
37+
. Identify the USB device vendor and product:
2138
+
2239
[source,terminal]
2340
----
2441
$ lsusb
2542
----
43+
+
44+
*Example output*
45+
+
46+
[source,terminal]
47+
----
48+
Bus 003 Device 007: ID 1b1c:0a60 example_manufacturer example_product_name
49+
----
50+
51+
** If you cannot use the `lsusb` command, inspect the USB device configurations in the host's `/sys/bus/usb/devices/` directory:
52+
+
53+
[source,terminal]
54+
----
55+
for dev in *; do
56+
if [[ -f "$dev/idVendor" && -f "$dev/idProduct" ]]; then
57+
echo "Device: $dev"
58+
echo -n " Manufacturer : "; cat "$dev/manufacturer"
59+
echo -n " Product: "; cat "$dev/product"
60+
echo -n " Vendor ID : "; cat "$dev/idVendor"
61+
echo -n " Product ID: "; cat "$dev/idProduct"
62+
echo
63+
fi
64+
done
65+
----
66+
+
67+
*Example output*
68+
+
69+
[source,terminal]
70+
----
71+
Device: 3-7
72+
Manufacturer : example_manufacturer
73+
Product: example_product_name
74+
Vendor ID : 1b1c
75+
Product ID: 0a60
76+
----
77+
2678
27-
. Open the HCO CR by running the following command:
79+
. 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`:
2880
+
2981
[source,terminal]
3082
----
31-
$ oc edit hyperconverged kubevirt-hyperconverged -n openshift-cnv
83+
oc patch hyperconverged kubevirt-hyperconverged \
84+
-n openshift-cnv \
85+
--type=merge \
86+
-p '{
87+
"metadata": {
88+
"annotations": {
89+
"kubevirt.kubevirt.io/jsonpatch": "[{\"op\": \"add\", \"path\": \"/spec/permittedHostDevices/usbHostDevices/-\", \"value\": {\"resourceName\": \"kubevirt.io/peripherals\", \"selectors\": [{\"vendor\": \"045e\", \"product\": \"07a5\"}]}}]"
90+
}
91+
}
92+
}'
3293
----
3394
34-
. Add a USB device to the `permittedHostDevices` stanza, as shown in the following example:
95+
.Verification
3596
97+
* Ensure that the HCO CR contains the required USB devices:
98+
+
99+
[source,terminal]
100+
----
101+
$ oc get hyperconverged kubevirt-hyperconverged -n openshift-cnv
102+
----
103+
+
104+
*Example output*
36105
+
37-
.Example YAML snippet
38106
[source,yaml,subs="attributes+"]
39107
----
40108
apiVersion: hco.kubevirt.io/v1beta1
@@ -43,7 +111,6 @@ metadata:
43111
name: kubevirt-hyperconverged
44112
namespace: {CNVNamespace}
45113
spec:
46-
configuration:
47114
permittedHostDevices: <1>
48115
usbHostDevices: <2>
49116
- resourceName: kubevirt.io/peripherals <3>
@@ -58,4 +125,4 @@ spec:
58125
----
59126
<1> Lists the host devices that have permission to be used in the cluster.
60127
<2> Lists the available USB devices.
61-
<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`.
128+
<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/managing_vms/advanced_vm_management/virt-configuring-usb-host-passthrough.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

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.
9+
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 {product-title} node, as if the hardware and the VM are physically connected.
1010

11-
You can expose a USB device by first enabling host passthrough and then configuring the VM to use the USB device.
11+
To expose a USB device, first enable host passthrough and then configure the VM to use the USB device.
1212

1313
include::modules/virt-enabling-usb-host-passthrough.adoc[leveloffset=+1]
1414
include::modules/virt-configuring-vm-use-usb-device.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)