From 3f715b11480d00062eb5926e8d26979561c3b63a Mon Sep 17 00:00:00 2001 From: Elisamara Aoki Goncalves Date: Tue, 26 Sep 2023 17:25:40 +0000 Subject: [PATCH] Editorial fixes in CI-PT configuration (r8,dsR8) Editorial improvements requested in r7 review https://review.opendev.org/c/starlingx/docs/+/861840 Change-Id: Ie5a2d8223e302703402a934a10051bd7dea6a914 Signed-off-by: Elisamara Aoki Goncalves --- ...ng-pci-passthrough-ethernet-interfaces.rst | 158 ++++++++++-------- .../pci-sr-iov-ethernet-interface-devices.rst | 118 ++++++------- 2 files changed, 146 insertions(+), 130 deletions(-) diff --git a/doc/source/node_management/openstack/configuring-pci-passthrough-ethernet-interfaces.rst b/doc/source/node_management/openstack/configuring-pci-passthrough-ethernet-interfaces.rst index f7bb8d4c0..de26041ce 100644 --- a/doc/source/node_management/openstack/configuring-pci-passthrough-ethernet-interfaces.rst +++ b/doc/source/node_management/openstack/configuring-pci-passthrough-ethernet-interfaces.rst @@ -19,14 +19,12 @@ instance at boot/create time. .. rubric:: |prereq| -.. note:: - - To use |PCI| passthrough or |SRIOV| devices, you must have Intel VT-x and +- To use |PCI| passthrough or |SRIOV| devices, you must have Intel VT-x and Intel VT-d features enabled in the BIOS. -The exercise assumes that the underlying data network **group0-data0** exists -already, and that |VLAN| ID 10 is a valid segmentation ID assigned to -**project1**. +- The exercise assumes that the underlying data network **group0-data0** + exists already, and that |VLAN| ID 10 is a valid segmentation ID assigned + to **project1**. .. rubric:: |proc| @@ -34,41 +32,45 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to #. Lock the compute node you want to configure. -#. Configure the Ethernet interface to be used as a PCI passthrough interface. +#. Configure the Ethernet interface to be used as a |PCI| passthrough + interface. You can do this using Horizon or the |CLI|. + + - Using Horizon: + + #. Select **Admin** \> **Platform** \> **Host Inventory** from the + left-hand pane. + + #. Select the **Hosts** tab. + + #. Click the name of the compute host. + + #. Select the **Interfaces** tab. + + #. Click the **Edit Interface** button associated with the interface + you want to configure. - #. Select **Admin** \> **Platform** \> **Host Inventory** from the left-hand pane. + The Edit Interface dialog appears. - #. Select the **Hosts** tab. - - #. Click the name of the compute host. - - #. Select the **Interfaces** tab. - - #. Click the **Edit Interface** button associated with the interface you - want to configure. + .. image:: /node_management/figures/ptj1538163621289.png - The Edit Interface dialog appears. + #. Select **pci-passthrough**, from the **Interface Class** drop-down, + and then select the data network to attach the interface. - .. image:: /node_management/figures/ptj1538163621289.png + #. (Optional) You may also need to change the |MTU|. + + - Using the CLI: + + Assign the ``pci-sriov`` class to the interface. + + .. code-block:: none + + ~(keystone_admin)$ system host-if-modify -c pci-passthrough compute-0 enp0s3 + ~(keystone_admin)$ system interface-datanetwork-assign compute-0 - - Select **pci-passthrough**, from the **Interface Class** drop-down, and - then select the data network to attach the interface. - - You may also need to change the |MTU|. - - The interface can also be configured from the |CLI| as illustrated below: - - .. code-block:: none - - ~(keystone_admin)$ system host-if-modify -c pci-passthrough compute-0 enp0s3 - ~(keystone_admin)$ system interface-datanetwork-assign compute-0 - - -#. Check if the Ethernet interface supports |SRIOV| +#. Check if the Ethernet interface supports |SRIOV|. #. Check the host port associated with the configured |PCI|-passthrough interface. @@ -77,36 +79,40 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to ~(keystone_admin)$ system host-if-list | grep pci-passthrough - #. Describe the target port to check the value of sriov_totalvfs on it. - If the value is None, the Ethernet interface does not support |SRIOV|. - Otherwise, it does. + #. Review the value of ``sriov_totalvfs`` on the target port. + + If the value is ``None``, the Ethernet interface does not support + |SRIOV|. Otherwise, it does. .. code-block:: none ~(keystone_admin)$ system host-port-show | grep sriov_totalvfs - #. For Ethernet interfaces without |SRIOV| support, there is a known limitation + + .. note:: + + For Ethernet interfaces without |SRIOV| support, there is a known limitation reported `here `__. This limitation is overcome with a specific step later on this procedure. - .. note:: + .. _create-the-net0-project-network: - It will be required to know if the Ethernet interface supports or not |SRIOV| later in this procedure. +#. Create the ``net0`` project network for Ethernet interfaces that support + |SRIOV|. + .. warning:: -#. For Ethernet interfaces that support |SRIOV|, create the **net0** project network - - .. note:: - - If the Ethernet interface **DOES NOT** support |SRIOV|, **skip** this step. + If the Ethernet interface does not support |SRIOV|, **skip** this step. Log in as the **admin** user to the |os-prod-hor-long|. - Select **Admin** \> **Network** \> **Networks**, select the Networks tab, and then click **Create Network**. Fill in the Create Network dialog box as illustrated below. You must ensure that: + Select **Admin** \> **Network** \> **Networks**, select the Networks tab, + and then click **Create Network**. Fill in the Create Network dialog box as + illustrated below. You must ensure that: - - **project1** has access to the project network, either assigning it as - the owner, as in the illustration (using **Project**), or by enabling - the shared flag. + - **project1** has access to the project network. Either by assigning it + as the owner, as in the illustration \(using **Project**\), or by + enabling the shared flag. - The segmentation ID is set to 10. @@ -114,9 +120,9 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to .. image:: /node_management/figures/bek1516655307871.png - Click the **Next** button to proceed to the Subnet tab. + Click the **Next** button to proceed to the **Subnet** tab. - Click the **Next** button to proceed to the Subnet Details tab. + Click the **Next** button to proceed to the **Subnet Details** tab. #. Configure the access switch. Refer to the OEM documentation to configure the access switch. @@ -124,9 +130,9 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to Log in as the **admin** user to the |prod-p| |prod-hor-long|. Configure the physical port on the access switch used to connect to - Ethernet interface **enp0s3** as an access port with default |VLAN| ID of 10. - Traffic across the connection is therefore untagged, and effectively - integrated into the targeted project network. + Ethernet interface ``enp0s3`` to be an access port with the default |VLAN| + ID of 10. Traffic across the connection is therefore untagged, and + effectively integrated into the targeted project network. You can also use a trunk port on the access switch so that it handles tagged packets as well. However, this opens the possibility for guest @@ -138,12 +144,12 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to #. Unlock the compute node. -#. For Ethernet interfaces that support |SRIOV|, - create a neutron port with a |VNIC| type, direct-physical. +#. Create a neutron port with a |VNIC| of type ``direct-physical`` for + Ethernet interfaces that support |SRIOV|. - .. note:: + .. warning:: - If the Ethernet interface **DOES NOT** support |SRIOV|, **skip** this step. + If the Ethernet interface does not support |SRIOV|, **skip** this step. First, you must set up the environment and determine the correct network |UUID| to use with the port. @@ -158,41 +164,45 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to You have now created a port to be used when launching the server in the next step. -#. For Ethernet interfaces that do not support |SRIOV|, the following Nova - configuration is required. +#. Complete the following Nova configuration, for Ethernet interfaces that do + not support |SRIOV|. - .. note:: + .. warning:: - If the Ethernet interface **DOES** support |SRIOV|, **skip** this step. + If the Ethernet interface supports |SRIOV|, **skip** this step. - - Get the Ethernet interface ``vendor_id`` and ``product_id``: + #. Get the Ethernet interface ``vendor_id`` and ``product_id``: - .. code-block:: none + .. code-block:: none - ~(keystone_admin)$ source /etc/platform/openrc - ~(keystone_admin)$ system host-port-show | grep -E '(pvendor |pdevice )' + ~(keystone_admin)$ source /etc/platform/openrc + ~(keystone_admin)$ system host-port-show | grep -E '(pvendor |pdevice )' - - Use the retrieved IDs to create a |PCI| alias with ``"device_type":"type-PCI"``, - as peer :ref:`Configure a PCI Alias in Nova `. + #. Use the retrieved IDs to create a |PCI| alias with + ``"device_type":"type-PCI"``, as peer :ref:`Configure a PCI Alias in + Nova `. - - Configure a flavor with the extra spec key ``pci_passthrough:alias`` pointing to - the previously created |PCI| alias, as peer - :ref:`Configure a Flavor to Use a Generic PCI Device ` + #. Configure a flavor with the extra spec key ``pci_passthrough:alias`` + pointing to the previously created |PCI| alias, as peer :ref:`Configure + a Flavor to Use a Generic PCI Device + ` #. Launch the virtual machine .. note:: - You will need to source to the same project selected in the Create - Network 'net0' step. + You will need to source to the same project selected in the :ref:`Create + Network net0 ` step. - - For Ethernet interfaces with |SRIOV| support: specify the port uuid created + - For Ethernet interfaces with |SRIOV| support: specify the port uuid + created. .. code-block:: none ~(keystone_admin)$ openstack server create --flavor --image --nic port-id= - - For Ethernet interfaces without |SRIOV| support: specify the created flavor to use the |PCI| device + - For Ethernet interfaces without |SRIOV| support: specify the created + flavor to use the |PCI| device. .. code-block:: none diff --git a/doc/source/node_management/openstack/pci-sr-iov-ethernet-interface-devices.rst b/doc/source/node_management/openstack/pci-sr-iov-ethernet-interface-devices.rst index 8ead5b46e..7d821b8a1 100644 --- a/doc/source/node_management/openstack/pci-sr-iov-ethernet-interface-devices.rst +++ b/doc/source/node_management/openstack/pci-sr-iov-ethernet-interface-devices.rst @@ -6,23 +6,24 @@ Configure PCI SR-IOV Ethernet Interface Devices =============================================== -A |SRIOV| ethernet interface is a physical |PCI| ethernet |NIC| that implements -hardware-based virtualization mechanisms to expose multiple virtual network -interfaces that can be used by one or more virtual machines simultaneously. +An |SRIOV| Ethernet interface is a physical |PCI| Ethernet |NIC| that +implements hardware-based virtualization mechanisms to expose multiple virtual +network interfaces that can be used by one or more virtual machines +simultaneously. -The |PCI|-SIG Single Root I/O Virtualization and Sharing (|SRIOV|) specification -defines a standardized mechanism to create individual virtual ethernet devices -from a single physical ethernet interface. For each exposed virtual ethernet -device, formally referred to as a Virtual Function (VF), the |SRIOV| interface -provides separate management memory space, work queues, interrupts resources, -and |DMA| streams, while utilizing common resources behind the host interface. -Each VF therefore has direct access to the hardware and can be considered to be -an independent ethernet interface. +The |PCI|-SIG Single Root I/O Virtualization and Sharing \(|SRIOV|\) +specification defines a standardized mechanism to create individual virtual +Ethernet devices from a single physical Ethernet interface. For each exposed +virtual Ethernet device, formally referred to as a |VF|, the +|SRIOV| interface provides separate management memory space, work queues, +interrupts resources, and |DMA| streams, while utilizing common resources +behind the host interface. Each |VF| therefore has direct access to the hardware +and can be considered to be an independent Ethernet interface. -When compared with a |PCI| Passthrough ethernet interface, a |SRIOV| ethernet +When compared with a |PCI| Passthrough Ethernet interface, a |SRIOV| Ethernet interface: -- Provides benefits similar to those of a |PCI| Passthrough ethernet interface, +- Provides benefits similar to those of a |PCI| Passthrough Ethernet interface, including lower latency packet processing. - Scales up more easily in a virtualized environment by providing multiple @@ -37,8 +38,8 @@ interface: - Provides a similar configuration workflow when used on |prod-os|. -The configuration of a |PCI| |SRIOV| ethernet interface is almost identical to -:ref:`Configure PCI Passthrough ethernet Interfaces +The configuration of a |PCI| |SRIOV| Ethernet interface is almost identical to +:ref:`Configure PCI Passthrough Ethernet Interfaces ` and will be detailed bellow. .. rubric:: |context| @@ -49,14 +50,12 @@ instance at boot/create time. .. rubric:: |prereq| -.. note:: - - To use |PCI| passthrough or |SRIOV| devices, you must have Intel VT-x and +- To use |PCI| passthrough or |SRIOV| devices, you must have Intel VT-x and Intel VT-d features enabled in the BIOS. -The exercise assumes that the underlying data network **group0-data0** exists -already, and that |VLAN| ID 10 is a valid segmentation ID assigned to -**project1**. +- The exercise assumes that the underlying data network **group0-data0** + exists already, and that |VLAN| ID 10 is a valid segmentation ID assigned + to **project1**. .. rubric:: |proc| @@ -64,45 +63,51 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to #. Lock the compute node you want to configure. -#. Configure the Ethernet interface to be used as a PCI passthrough interface. +#. Configure the Ethernet interface to be used as a |PCI| passthrough + interface. You can do this using Horizon or the CLI. + - Using Horizon: - #. Select **Admin** \> **Platform** \> **Host Inventory** from the left-hand pane. + #. Select **Admin** \> **Platform** \> **Host Inventory** from the + left-hand pane. - #. Select the **Hosts** tab. + #. Select the **Hosts** tab. - #. Click the name of the compute host. + #. Click the name of the compute host. - #. Select the **Interfaces** tab. + #. Select the **Interfaces** tab. - #. Click the **Edit Interface** button associated with the interface you - want to configure. + #. Click the **Edit Interface** button associated with the interface + you want to configure. + The Edit Interface dialog appears. - The Edit Interface dialog appears. + .. image:: /node_management/figures/ptj1538163621290.png - .. image:: /node_management/figures/ptj1538163621290.png + #. Select **pci-sriov**, from the **Interface Class** drop-down, and + then select the data network to attach the interface. - Select **pci-sriov**, from the **Interface Class** drop-down, and - then select the data network to attach the interface. + #. (Optional) You may also need to change the |MTU|. - You may also need to change the |MTU|. + - Using the CLI: - The interface can also be configured from the |CLI| as illustrated below: + Assign the ``pci-sriov`` class to the interface. - .. code-block:: none + .. code-block:: none - ~(keystone_admin)$ system host-if-modify -c pci-sriov compute-0 enp0s3 - ~(keystone_admin)$ system interface-datanetwork-assign compute-0 + ~(keystone_admin)$ system host-if-modify -c pci-sriov compute-0 enp0s3 + ~(keystone_admin)$ system interface-datanetwork-assign compute-0 -#. Create the **net0** project network +#. Create the ``net0`` project network. Log in as the **admin** user to the |os-prod-hor-long|. - Select **Admin** \> **Network** \> **Networks**, select the Networks tab, and then click **Create Network**. Fill in the Create Network dialog box as illustrated below. You must ensure that: + Select **Admin** \> **Network** \> **Networks**, select the **Networks** + tab, and then click **Create Network**. Fill in the **Create Network** + dialog box as illustrated below. You must ensure that: - **project1** has access to the project network, either assigning it as - the owner, as in the illustration (using **Project**), or by enabling + the owner, as in the illustration \(using **Project**\), or by enabling the shared flag. - The segmentation ID is set to 10. @@ -110,20 +115,20 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to .. image:: /node_management/figures/bek1516655307871.png - The segmentation ID of the project network\(s) used is more significant - here since this identifies the particular |VF| of the |SRIOV| interface + The segmentation ID of the project network\(s\) used is more significant + here since this identifies the particular |VF| of the |SRIOV| interface. - Click the **Next** button to proceed to the Subnet tab. + Click the **Next** button to proceed to the **Subnet** tab. - Click the **Next** button to proceed to the Subnet Details tab. + Click the **Next** button to proceed to the **Subnet Details** tab. -#. Configure the access switch. Refer to the OEM documentation to configure - the access switch. +#. Configure the access switch. Refer to your |OEM| documentation for more + details. Log in as the **admin** user to the |prod-p| |prod-hor-long|. Configure the physical port on the access switch used to connect to - Ethernet interface **enp0s3** as an access port with default |VLAN| ID of 10. + Ethernet interface ``enp0s3`` as an access port with default |VLAN| ID of 10. Traffic across the connection is therefore untagged, and effectively integrated into the targeted project network. @@ -137,10 +142,10 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to #. Unlock the compute node. -#. Create a neutron port with a |VNIC| type, direct-physical. +#. Create a neutron port with a |VNIC| of type ``direct-physical``. - First, you must set up the environment and determine the correct - network |UUID| to use with the port. + Set up the environment and determine the correct network |UUID| to use with + the port. .. code-block:: none @@ -152,18 +157,19 @@ already, and that |VLAN| ID 10 is a valid segmentation ID assigned to You have now created a port to be used when launching the server in the next step. -#. Launch the virtual machine +#. Launch the virtual machine specifying the |UUID| of the port previously + created. .. note:: - You will need to source to the same project selected in the Create - Network 'net0' step. + You will need to source to the same project selected in the + :ref:`Create Network net0 ` step. - - Specify the port uuid created + Specify the port uuid created. - .. code-block:: none + .. code-block:: none - ~(keystone_admin)$ openstack server create --flavor --image --nic port-id= + ~(keystone_admin)$ openstack server create --flavor --image --nic port-id= For more information, see the Neutron documentation at: `https://docs.openstack.org/neutron/train/admin/config-sriov.html