starlingx/docs
Code Issues Proposed changes

Merge "Editorial fixes in CI-PT configuration (r8,dsR8)"

Browse Source
This commit is contained in:
Zuul 2023-11-24 14:53:13 +00:00 committed by Gerrit Code Review
commit b7d082451d
2 changed files with 146 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
doc/source/node_management/openstack/configuring-pci-passthrough-ethernet-interfaces.rst
View File

@ -19,14 +19,12 @@ instance at boot/create time.
.. rubric:: |prereq| .. 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. Intel VT-d features enabled in the BIOS.
The exercise assumes that the underlying data network **group0-data0** exists - The exercise assumes that the underlying data network **group0-data0**
already, and that |VLAN| ID 10 is a valid segmentation ID assigned to exists already, and that |VLAN| ID 10 is a valid segmentation ID assigned
**project1**. to **project1**.
.. rubric:: |proc| .. 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. #. 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. .. image:: /node_management/figures/ptj1538163621289.png
#. Click the name of the compute host.
#. Select the **Interfaces** tab.
#. Click the **Edit Interface** button associated with the interface you
want to configure.
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 <enp0s3_interface_uuid> <group0_data0_data_network_uuid>
#. Check if the Ethernet interface supports |SRIOV|.
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 <enp0s3_interface_uuid> <group0_data0_data_network_uuid>
#. Check if the Ethernet interface supports |SRIOV|
#. Check the host port associated with the configured |PCI|-passthrough interface. #. 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 <host-name> | grep pci-passthrough ~(keystone_admin)$ system host-if-list <host-name> | grep pci-passthrough
#. Describe the target port to check the value of sriov_totalvfs on it. #. 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. If the value is ``None``, the Ethernet interface does not support
|SRIOV|. Otherwise, it does.
.. code-block:: none .. code-block:: none
~(keystone_admin)$ system host-port-show <host-name> <port-name> | grep sriov_totalvfs ~(keystone_admin)$ system host-port-show <host-name> <port-name> | 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 <https://bugs.launchpad.net/starlingx/+bug/1836682>`__. reported `here <https://bugs.launchpad.net/starlingx/+bug/1836682>`__.
This limitation is overcome with a specific step later on this procedure. 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 If the Ethernet interface does not support |SRIOV|, **skip** this step.
.. note::
If the Ethernet interface **DOES NOT** support |SRIOV|, **skip** this step.
Log in as the **admin** user to the |os-prod-hor-long|. 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 - **project1** has access to the project network. Either by assigning it
the owner, as in the illustration (using **Project**), or by enabling as the owner, as in the illustration \(using **Project**\), or by
the shared flag. enabling the shared flag.
- The segmentation ID is set to 10. - 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 .. 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 #. Configure the access switch. Refer to the OEM documentation to configure
the access switch. 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|. 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 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`` to be an access port with the default |VLAN|
Traffic across the connection is therefore untagged, and effectively ID of 10. Traffic across the connection is therefore untagged, and
integrated into the targeted project network. effectively integrated into the targeted project network.
You can also use a trunk port on the access switch so that it handles 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 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. #. Unlock the compute node.
#. For Ethernet interfaces that support |SRIOV|, #. Create a neutron port with a |VNIC| of type ``direct-physical`` for
create a neutron port with a |VNIC| type, direct-physical. 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 First, you must set up the environment and determine the correct
network |UUID| to use with the port. 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 You have now created a port to be used when launching the server in the
next step. next step.
#. For Ethernet interfaces that do not support |SRIOV|, the following Nova #. Complete the following Nova configuration, for Ethernet interfaces that do
configuration is required. 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)$ source /etc/platform/openrc
~(keystone_admin)$ system host-port-show <host-name> <port-name> | grep -E '(pvendor |pdevice )' ~(keystone_admin)$ system host-port-show <host-name> <port-name> | grep -E '(pvendor |pdevice )'
- Use the retrieved IDs to create a |PCI| alias with ``"device_type":"type-PCI"``, #. Use the retrieved IDs to create a |PCI| alias with
as peer :ref:`Configure a PCI Alias in Nova <configuring-a-pci-alias-in-nova>`. ``"device_type":"type-PCI"``, as peer :ref:`Configure a PCI Alias in
Nova <configuring-a-pci-alias-in-nova>`.
- Configure a flavor with the extra spec key ``pci_passthrough:alias`` pointing to #. Configure a flavor with the extra spec key ``pci_passthrough:alias``
the previously created |PCI| alias, as peer pointing to the previously created |PCI| alias, as peer :ref:`Configure
:ref:`Configure a Flavor to Use a Generic PCI Device <configuring-a-flavor-to-use-a-generic-pci-device>` a Flavor to Use a Generic PCI Device
<configuring-a-flavor-to-use-a-generic-pci-device>`
#. Launch the virtual machine #. Launch the virtual machine
.. note:: .. note::
You will need to source to the same project selected in the Create You will need to source to the same project selected in the :ref:`Create
Network 'net0' step. Network net0 <create-the-net0-project-network>` 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 .. code-block:: none
~(keystone_admin)$ openstack server create --flavor <flavor_name> --image <image_name> --nic port-id=<port_uuid> <name> ~(keystone_admin)$ openstack server create --flavor <flavor_name> --image <image_name> --nic port-id=<port_uuid> <name>
- 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 .. code-block:: none

118
doc/source/node_management/openstack/pci-sr-iov-ethernet-interface-devices.rst
View File

@ -6,23 +6,24 @@
Configure PCI SR-IOV Ethernet Interface Devices Configure PCI SR-IOV Ethernet Interface Devices
=============================================== ===============================================
A |SRIOV| ethernet interface is a physical |PCI| ethernet |NIC| that implements An |SRIOV| Ethernet interface is a physical |PCI| Ethernet |NIC| that
hardware-based virtualization mechanisms to expose multiple virtual network implements hardware-based virtualization mechanisms to expose multiple virtual
interfaces that can be used by one or more virtual machines simultaneously. 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 The |PCI|-SIG Single Root I/O Virtualization and Sharing \(|SRIOV|\)
defines a standardized mechanism to create individual virtual ethernet devices specification defines a standardized mechanism to create individual virtual
from a single physical ethernet interface. For each exposed virtual ethernet Ethernet devices from a single physical Ethernet interface. For each exposed
device, formally referred to as a Virtual Function (VF), the |SRIOV| interface virtual Ethernet device, formally referred to as a |VF|, the
provides separate management memory space, work queues, interrupts resources, |SRIOV| interface provides separate management memory space, work queues,
and |DMA| streams, while utilizing common resources behind the host interface. interrupts resources, and |DMA| streams, while utilizing common resources
Each VF therefore has direct access to the hardware and can be considered to be behind the host interface. Each |VF| therefore has direct access to the hardware
an independent ethernet interface. 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: 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. including lower latency packet processing.
- Scales up more easily in a virtualized environment by providing multiple - 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|. - Provides a similar configuration workflow when used on |prod-os|.
The configuration of a |PCI| |SRIOV| ethernet interface is almost identical to The configuration of a |PCI| |SRIOV| Ethernet interface is almost identical to
:ref:`Configure PCI Passthrough ethernet Interfaces :ref:`Configure PCI Passthrough Ethernet Interfaces
<configure-pci-passthrough-ethernet-interfaces>` and will be detailed bellow. <configure-pci-passthrough-ethernet-interfaces>` and will be detailed bellow.
.. rubric:: |context| .. rubric:: |context|
@ -49,14 +50,12 @@ instance at boot/create time.
.. rubric:: |prereq| .. 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. Intel VT-d features enabled in the BIOS.
The exercise assumes that the underlying data network **group0-data0** exists - The exercise assumes that the underlying data network **group0-data0**
already, and that |VLAN| ID 10 is a valid segmentation ID assigned to exists already, and that |VLAN| ID 10 is a valid segmentation ID assigned
**project1**. to **project1**.
.. rubric:: |proc| .. 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. #. 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 #. Click the **Edit Interface** button associated with the interface
want to configure. 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 #. (Optional) You may also need to change the |MTU|.
then select the data network to attach the interface.
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 host-if-modify -c pci-sriov compute-0 enp0s3
~(keystone_admin)$ system interface-datanetwork-assign compute-0 <enp0s3_interface_uuid> <group0_data0_data_network_uuid> ~(keystone_admin)$ system interface-datanetwork-assign compute-0 <enp0s3_interface_uuid> <group0_data0_data_network_uuid>
#. Create the **net0** project network #. Create the ``net0`` project network.
Log in as the **admin** user to the |os-prod-hor-long|. 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 - **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 shared flag.
- The segmentation ID is set to 10. - 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 .. image:: /node_management/figures/bek1516655307871.png
The segmentation ID of the project network\(s) used is more significant The segmentation ID of the project network\(s\) used is more significant
here since this identifies the particular |VF| of the |SRIOV| interface 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 #. Configure the access switch. Refer to your |OEM| documentation for more
the access switch. details.
Log in as the **admin** user to the |prod-p| |prod-hor-long|. 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 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 Traffic across the connection is therefore untagged, and effectively
integrated into the targeted project network. 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. #. 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 Set up the environment and determine the correct network |UUID| to use with
network |UUID| to use with the port. the port.
.. code-block:: none .. 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 You have now created a port to be used when launching the server in the
next step. next step.
#. Launch the virtual machine #. Launch the virtual machine specifying the |UUID| of the port previously
created.
.. note:: .. note::
You will need to source to the same project selected in the Create You will need to source to the same project selected in the
Network 'net0' step. :ref:`Create Network net0 <create-the-net0-project-network>` step.
- Specify the port uuid created Specify the port uuid created.
.. code-block:: none .. code-block:: none
~(keystone_admin)$ openstack server create --flavor <flavor_name> --image <image_name> --nic port-id=<port_uuid> <name> ~(keystone_admin)$ openstack server create --flavor <flavor_name> --image <image_name> --nic port-id=<port_uuid> <name>
For more information, see the Neutron documentation at: For more information, see the Neutron documentation at:
`https://docs.openstack.org/neutron/train/admin/config-sriov.html `https://docs.openstack.org/neutron/train/admin/config-sriov.html