docs: Rework the PCI passthrough guides
Rewrite the document, making the following changes: - Remove use of bullet points in favour of more descriptive steps - Cross-reference various configuration options - Emphasise that ``[pci] alias`` must be set on both controller and compute node - Style nits, such as fixing the header style Change-Id: I2ac7df7d235f0af25f5a99bc8f6abddbae2cb3af Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
This commit is contained in:
Stephen Finucane
parent
38c774a8e0
commit
d5259abfe1
@ -22,83 +22,98 @@ assigned to only one guest and cannot be shared.
|
|||||||
|
|
||||||
**Limitations**
|
**Limitations**
|
||||||
|
|
||||||
* Attaching SR-IOV ports to existing servers is not currently supported, see
|
* Attaching SR-IOV ports to existing servers is not currently supported.
|
||||||
`bug 1708433 <https://bugs.launchpad.net/nova/+bug/1708433>`_ for details.
|
This is now rejected by the API but previously it fail later in the
|
||||||
|
process. See `bug 1708433 <https://bugs.launchpad.net/nova/+bug/1708433>`_
|
||||||
|
for details.
|
||||||
* Cold migration (resize) of servers with SR-IOV devices attached was not
|
* Cold migration (resize) of servers with SR-IOV devices attached was not
|
||||||
supported until the 14.0.0 Newton release, see
|
supported until the 14.0.0 Newton release, see
|
||||||
`bug 1512800 <https://bugs.launchpad.net/nova/+bug/1512880>`_ for details.
|
`bug 1512800 <https://bugs.launchpad.net/nova/+bug/1512880>`_ for details.
|
||||||
|
|
||||||
To enable PCI passthrough, follow the steps below:
|
To enable PCI passthrough, follow the steps below.
|
||||||
|
|
||||||
#. Configure nova-scheduler (Controller)
|
|
||||||
|
|
||||||
#. Configure nova-api (Controller)**
|
|
||||||
|
|
||||||
#. Configure a flavor (Controller)
|
|
||||||
|
|
||||||
#. Enable PCI passthrough (Compute)
|
|
||||||
|
|
||||||
#. Configure PCI devices in nova-compute (Compute)
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
The PCI device with address ``0000:41:00.0`` is used as an example. This
|
The PCI device with address ``0000:41:00.0``, the vendor ID of ``8086`` and
|
||||||
will differ between environments.
|
the product ID of ``154d`` is used as an example. This will differ between
|
||||||
|
environments.
|
||||||
|
|
||||||
Configure nova-scheduler (Controller)
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
#. Configure ``nova-scheduler`` as specified in :neutron-doc:`Configure
|
Configure ``nova-scheduler`` (Controller)
|
||||||
nova-scheduler
|
-----------------------------------------
|
||||||
<admin/config-sriov.html#configure-nova-scheduler-controller>`.
|
|
||||||
|
|
||||||
#. Restart the ``nova-scheduler`` service.
|
The :program:`nova-scheduler` service must be configured to enable the
|
||||||
|
``PciPassthroughFilter``. To do this, add this filter to the list of filters
|
||||||
|
specified in :oslo.config:option:`filter_scheduler.enabled_filters` and set
|
||||||
|
:oslo.config:option:`filter_scheduler.available_filters` to the default of
|
||||||
|
``nova.scheduler.filters.all_filters``. For example:
|
||||||
|
|
||||||
Configure nova-api (Controller)
|
.. code-block:: ini
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
#. Specify the PCI alias for the device.
|
[filter_scheduler]
|
||||||
|
enabled_filters = ...,PciPassthroughFilter
|
||||||
|
available_filters = nova.scheduler.filters.all_filters
|
||||||
|
|
||||||
Configure a PCI alias ``a1`` to request a PCI device with a ``vendor_id`` of
|
Once done, restart the :program:`nova-scheduler` service.
|
||||||
``0x8086`` and a ``product_id`` of ``0x154d``. The ``vendor_id`` and
|
|
||||||
``product_id`` correspond the PCI device with address ``0000:41:00.0``.
|
|
||||||
|
|
||||||
Edit ``/etc/nova/nova.conf``:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
.. _pci-passthrough-alias:
|
||||||
|
|
||||||
|
Configure ``nova-api`` (Controller)
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
|
PCI devices are requested through flavor extra specs, specifically via the
|
||||||
|
``pci_passthrough:alias`` flavor extra spec. However, the aliases themselves
|
||||||
|
must be configured. This done via the :oslo.config:option:`pci.alias`
|
||||||
|
configuration option. For example, to configure a PCI alias ``a1`` to request
|
||||||
|
a PCI device with a vendor ID of ``0x8086`` and a product ID of ``0x154d``:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
[pci]
|
[pci]
|
||||||
alias = { "vendor_id":"8086", "product_id":"154d", "device_type":"type-PF", "name":"a1" }
|
alias = { "vendor_id":"8086", "product_id":"154d", "device_type":"type-PF", "name":"a1" }
|
||||||
|
|
||||||
Refer to :oslo.config:option:`pci.alias` for syntax information.
|
Refer to :oslo.config:option:`pci.alias` for syntax information.
|
||||||
|
|
||||||
#. Restart the ``nova-api`` service.
|
Once configured, restart the :program:`nova-api` service.
|
||||||
|
|
||||||
Configure a flavor (Controller)
|
.. important::
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Configure a flavor to request two PCI devices, each with ``vendor_id`` of
|
This option must also be configured on compute nodes. This is discussed later
|
||||||
``0x8086`` and ``product_id`` of ``0x154d``:
|
in this document.
|
||||||
|
|
||||||
|
|
||||||
|
Configure a flavor (API)
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Once the alias has been configured, it can be used for an flavor extra spec.
|
||||||
|
For example, to request two of the PCI devices referenced by alias ``a1``, run:
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
# openstack flavor set m1.large --property "pci_passthrough:alias"="a1:2"
|
$ openstack flavor set m1.large --property "pci_passthrough:alias"="a1:2"
|
||||||
|
|
||||||
For more information about the syntax for ``pci_passthrough:alias``, refer to
|
For more information about the syntax for ``pci_passthrough:alias``, refer to
|
||||||
:ref:`Flavors <extra-spec-pci-passthrough>`.
|
:ref:`Flavors <extra-spec-pci-passthrough>`.
|
||||||
|
|
||||||
Enable PCI passthrough (Compute)
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Enable VT-d and IOMMU. For more information, refer to steps one and two in
|
Configure host (Compute)
|
||||||
:neutron-doc:`Create Virtual Functions
|
------------------------
|
||||||
<admin/config-sriov.html#create-virtual-functions-compute>`.
|
|
||||||
|
|
||||||
For Hyper-V compute nodes, the requirements are as follows:
|
To enable PCI passthrough on an x86, Linux-based compute node, the following
|
||||||
|
are required:
|
||||||
|
|
||||||
* Windows 10 or Windows / Hyper-V Server 2016 or newer.
|
* VT-d enabled in the BIOS
|
||||||
* VT-d and SR-IOV enabled on the host.
|
* IOMMU enabled on the host OS, by adding the ``intel_iommu=on`` or
|
||||||
* Assignable PCI devices.
|
``amd_iommu=on`` parameter to the kernel parameters
|
||||||
|
* Assignable PCIe devices
|
||||||
|
|
||||||
|
To enable PCI passthrough on a Hyper-V compute node, the following are
|
||||||
|
required:
|
||||||
|
|
||||||
|
* Windows 10 or Windows / Hyper-V Server 2016 or newer
|
||||||
|
* VT-d enabled on the host
|
||||||
|
* Assignable PCI devices
|
||||||
|
|
||||||
In order to check the requirements above and if there are any assignable PCI
|
In order to check the requirements above and if there are any assignable PCI
|
||||||
devices, run the following Powershell commands:
|
devices, run the following Powershell commands:
|
||||||
@ -115,56 +130,54 @@ passthrough`__.
|
|||||||
|
|
||||||
.. __: https://devblogs.microsoft.com/scripting/passing-through-devices-to-hyper-v-vms-by-using-discrete-device-assignment/
|
.. __: https://devblogs.microsoft.com/scripting/passing-through-devices-to-hyper-v-vms-by-using-discrete-device-assignment/
|
||||||
|
|
||||||
Configure PCI devices (Compute)
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
#. Configure ``nova-compute`` to allow the PCI device to pass through to
|
Configure ``nova-compute`` (Compute)
|
||||||
VMs. Edit ``/etc/nova/nova.conf``:
|
------------------------------------
|
||||||
|
|
||||||
.. code-block:: ini
|
Once PCI passthrough has been configured for the host, :program:`nova-compute`
|
||||||
|
must be configured to allow the PCI device to pass through to VMs. This is done
|
||||||
|
using the :oslo.config:option:`pci.passthrough_whitelist` option. For example,
|
||||||
|
to enable passthrough of a specific device using its address:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
[pci]
|
[pci]
|
||||||
passthrough_whitelist = { "address": "0000:41:00.0" }
|
passthrough_whitelist = { "address": "0000:41:00.0" }
|
||||||
|
|
||||||
Alternatively specify multiple PCI devices using whitelisting:
|
Refer to :oslo.config:option:`pci.passthrough_whitelist` for syntax information.
|
||||||
|
|
||||||
.. code-block:: ini
|
Alternatively, to enable passthrough of all devices with the same product and
|
||||||
|
vendor ID:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
[pci]
|
[pci]
|
||||||
passthrough_whitelist = { "vendor_id": "8086", "product_id": "10fb" }
|
passthrough_whitelist = { "vendor_id": "8086", "product_id": "154d" }
|
||||||
|
|
||||||
All PCI devices matching the ``vendor_id`` and ``product_id`` are added to
|
If using vendor and product IDs, all PCI devices matching the ``vendor_id`` and
|
||||||
the pool of PCI devices available for passthrough to VMs.
|
``product_id`` are added to the pool of PCI devices available for passthrough
|
||||||
|
to VMs.
|
||||||
|
|
||||||
Refer to :oslo.config:option:`pci.passthrough_whitelist` for syntax
|
In addition, it is necessary to configure the :oslo.config:option:`pci.alias`
|
||||||
information.
|
option on the compute node too. This is required to allow resizes of guests
|
||||||
|
with PCI devices. This should be identical to the alias configured
|
||||||
|
:ref:`previously <pci-passthrough-alias>`. For example:
|
||||||
|
|
||||||
#. Specify the PCI alias for the device.
|
.. code-block:: ini
|
||||||
|
|
||||||
From the Newton release, to resize guest with PCI device, configure the PCI
|
|
||||||
alias on the compute node as well.
|
|
||||||
|
|
||||||
Configure a PCI alias ``a1`` to request a PCI device with a ``vendor_id`` of
|
|
||||||
``0x8086`` and a ``product_id`` of ``0x154d``. The ``vendor_id`` and
|
|
||||||
``product_id`` correspond the PCI device with address ``0000:41:00.0``.
|
|
||||||
|
|
||||||
Edit ``/etc/nova/nova.conf``:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
|
||||||
|
|
||||||
[pci]
|
[pci]
|
||||||
alias = { "vendor_id":"8086", "product_id":"154d", "device_type":"type-PF", "name":"a1" }
|
alias = { "vendor_id":"8086", "product_id":"154d", "device_type":"type-PF", "name":"a1" }
|
||||||
|
|
||||||
Refer to :oslo.config:option:`pci.alias` for syntax information.
|
Refer to :oslo.config:option:`pci.alias` for syntax information.
|
||||||
|
|
||||||
|
Once configured, restart the :program:`nova-compute` service.
|
||||||
|
|
||||||
#. Restart the ``nova-compute`` service.
|
|
||||||
|
|
||||||
Create instances with PCI passthrough devices
|
Create instances with PCI passthrough devices
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
---------------------------------------------
|
||||||
|
|
||||||
The ``nova-scheduler`` selects a destination host that has PCI devices
|
The :program:`nova-scheduler` service selects a destination host that has PCI
|
||||||
available with the specified ``vendor_id`` and ``product_id`` that matches the
|
devices available that match the ``alias`` specified in the flavor.
|
||||||
``alias`` from the flavor.
|
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user