From ea167d265066dee66641d05f8cf326f0bf757ec7 Mon Sep 17 00:00:00 2001 From: Nahshon Unna Tsameret Date: Wed, 9 Sep 2026 08:25:50 +0300 Subject: [PATCH] OpenShift Virtualization: add hyperconverged v1 API OpenShift virtualization v4.22.0 introduced the new v1 API version for the `HyperConverged` kind. This API version is not backward compatible with the older `v1beta1` API version. The `v1beta1` API version will be deprecated, and later removed from OpenShift Virtualization. This PR adding the v1 API tab, whenever the v1beta1 format is already used in the documents. Note: In OpenShift Virtualization v4.22.x, because of the unchangeable way Kubernetes prioritizes API versions, using a non-versioned name of the HyperConverged custom resource, i.e. `hyperconverged` or `hco`, will make Kubernetes to use the v1 API version. It is recomanded to use the fully versioned named for v1beta1, i.e. `hyperconvergeds.v1beta1.hco.kubevirt.io`. Signed-off-by: Nahshon Unna Tsameret --- openshift/openshift-virtualization.rst | 140 +++++++++++++++++++------ 1 file changed, 110 insertions(+), 30 deletions(-) diff --git a/openshift/openshift-virtualization.rst b/openshift/openshift-virtualization.rst index 7f716cc65..bce3babe7 100644 --- a/openshift/openshift-virtualization.rst +++ b/openshift/openshift-virtualization.rst @@ -103,18 +103,48 @@ Prerequisites * `Install the OpenShift Virtualization Operator `__. * `Install the virtctl client `__. -* Starting with OpenShift Virtualization 4.12.3 and 4.13.0, set the ``disableMDevConfiguration`` feature gate: +* You must disable OpenShift Virtualization mediated device management to prevent conflicts with the GPU Operator: - .. code-block:: console + .. tab-set:: - $ kubectl patch hyperconverged -n openshift-cnv kubevirt-hyperconverged --type='json' -p='[{"op": "add", "path": "/spec/featureGates/disableMDevConfiguration", "value": true}]' + .. tab-item:: OpenShift Virtualization v4.23.0 or newer + :selected: - *Example Output* + Set the ``spec.virtualization.mediatedDevicesConfiguration.enabled`` field to ``false``: - .. code-block:: output + .. code-block:: console - hyperconverged.hco.kubevirt.io/kubevirt-hyperconverged patched + $ oc patch hyperconverged -n openshift-cnv kubevirt-hyperconverged --type='merge' \ + -p='{"spec":{"virtualization":{"mediatedDevicesConfiguration":{"enabled": false}}}}' + *Example Output* + + .. code-block:: output + + hyperconverged.hco.kubevirt.io/kubevirt-hyperconverged patched + + .. tab-item:: Earlier versions of OpenShift Virtualization + + Set the ``disableMDevConfiguration`` feature gate: + + .. code-block:: console + + $ oc patch hyperconverged -n openshift-cnv kubevirt-hyperconverged --type='json' \ + -p='[{"op": "add", "path": "/spec/featureGates/disableMDevConfiguration", "value": true}]' + + *Example Output* + + .. code-block:: output + + hyperconverged.hco.kubevirt.io/kubevirt-hyperconverged patched + + .. note:: + + in OpenShit Virtualization v4.22.x, use the full versioned name for the hyperconverged custom resource: + + .. code-block:: console + + $ oc patch hyperconvergeds.v1beta1.hco.kubevirt.io -n openshift-cnv kubevirt-hyperconverged --type='json' -p='[{"op": "add", "path": "/spec/featureGates/disableMDevConfiguration", "value": true}]' * If planning to use NVIDIA vGPU, SR-IOV must be enabled in the BIOS if your GPUs are based on the NVIDIA Ampere architecture or later. Refer to the `NVIDIA vGPU Documentation `_ to ensure you have met all the prerequisites for using NVIDIA vGPU. @@ -511,18 +541,43 @@ The following example permits the A10 GPU device, the device names for the GPUs #. Modify the ``HyperConverged`` custom resource like the following partial examples. - .. code-block:: yaml - - ... - spec: - featureGates: - disableMDevConfiguration: true - permittedHostDevices: # Defines VM devices to import. - pciHostDevices: # Include for GPU passthrough - - externalResourceProvider: true - pciDeviceSelector: 10DE:2236 - resourceName: nvidia.com/GA102GL_A10 - ... + .. tab-set:: + + .. tab-item:: OpenShift Virtualization v4.23.0 or newer + :selected: + + .. code-block:: yaml + + apiVersion: hco.kubevirt.io/v1 + kind: HyperConverged + ... + spec: + virtualization: + mediatedDevicesConfiguration: + enabled: false + permittedHostDevices: # Defines VM devices to import. + pciHostDevices: # Include for GPU passthrough + - externalResourceProvider: true + pciDeviceSelector: 10DE:2236 + resourceName: nvidia.com/GA102GL_A10 + ... + + .. tab-item:: Earlier versions of OpenShift Virtualization + + .. code-block:: yaml + + apiVersion: hco.kubevirt.io/v1beta1 + kind: HyperConverged + ... + spec: + featureGates: + disableMDevConfiguration: true + permittedHostDevices: # Defines VM devices to import. + pciHostDevices: # Include for GPU passthrough + - externalResourceProvider: true + pciDeviceSelector: 10DE:2236 + resourceName: nvidia.com/GA102GL_A10 + ... Replace the values in the YAML as follows. @@ -574,18 +629,43 @@ The following example permits the A10-12Q vGPU device, the device names for the #. Modify the ``HyperConverged`` custom resource like the following partial examples. - .. code-block:: yaml - - ... - spec: - featureGates: - disableMDevConfiguration: true - permittedHostDevices: # Defines VM devices to import. - mediatedDevices: # Include for vGPU - - externalResourceProvider: true - mdevNameSelector: NVIDIA A10-12Q - resourceName: nvidia.com/NVIDIA_A10-12Q - ... + .. tab-set:: + + .. tab-item:: OpenShift Virtualization v4.23.0 or newer + :selected: + + .. code-block:: yaml + + apiVersion: hco.kubevirt.io/v1 + kind: HyperConverged + ... + spec: + virtualization: + mediatedDevicesConfiguration: + enabled: false + permittedHostDevices: # Defines VM devices to import. + mediatedDevices: # Include for vGPU + - externalResourceProvider: true + mdevNameSelector: NVIDIA A10-12Q + resourceName: nvidia.com/NVIDIA_A10-12Q + ... + + .. tab-item:: Earlier versions of OpenShift Virtualization + + .. code-block:: yaml + + apiVersion: hco.kubevirt.io/v1beta1 + kind: HyperConverged + ... + spec: + featureGates: + disableMDevConfiguration: true + permittedHostDevices: # Defines VM devices to import. + mediatedDevices: # Include for vGPU + - externalResourceProvider: true + mdevNameSelector: NVIDIA A10-12Q + resourceName: nvidia.com/NVIDIA_A10-12Q + ... Replace the values in the YAML as follows.