9c7d73195e
The ``pci_passthrough_whitelist`` and ``pci_alias`` options in the ``[DEFAULT]`` section were deprecated and replaced by ``passthrough_whitelist`` and ``alias`` in the ``[pci]`` section, respectively, in ocata via [1]. However, the PCI passthrough documentation [2] was missed. [1] https://review.openstack.org/#/c/356604/ [2] https://docs.openstack.org/nova/pike/admin/pci-passthrough.html Change-Id: I77ec8e9b4f90caa5a1e803d248fbc7d4e8db4005 Closes-Bug: #1713502
149 lines
5.0 KiB
ReStructuredText
149 lines
5.0 KiB
ReStructuredText
========================================
|
|
Attaching physical PCI devices to guests
|
|
========================================
|
|
|
|
The PCI passthrough feature in OpenStack allows full access and direct control
|
|
of a physical PCI device in guests. This mechanism is generic for any kind of
|
|
PCI device, and runs with a Network Interface Card (NIC), Graphics Processing
|
|
Unit (GPU), or any other devices that can be attached to a PCI bus. Correct
|
|
driver installation is the only requirement for the guest to properly use the
|
|
devices.
|
|
|
|
Some PCI devices provide Single Root I/O Virtualization and Sharing (SR-IOV)
|
|
capabilities. When SR-IOV is used, a physical device is virtualized and appears
|
|
as multiple PCI devices. Virtual PCI devices are assigned to the same or
|
|
different guests. In the case of PCI passthrough, the full physical device is
|
|
assigned to only one guest and cannot be shared.
|
|
|
|
.. note::
|
|
|
|
For information on attaching virtual SR-IOV devices to guests, refer to the
|
|
`Networking Guide`_.
|
|
|
|
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::
|
|
|
|
The PCI device with address ``0000:41:00.0`` is used as an example. This
|
|
will differ between environments.
|
|
|
|
Configure nova-scheduler (Controller)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
#. Configure ``nova-scheduler`` as specified in `Configure nova-scheduler`_.
|
|
|
|
#. Restart the ``nova-scheduler`` service.
|
|
|
|
Configure nova-api (Controller)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
#. Specify the PCI alias for the device.
|
|
|
|
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]
|
|
alias = { "vendor_id":"8086", "product_id":"154d", "device_type":"type-PF", "name":"a1" }
|
|
|
|
For more information about the syntax of ``alias``, refer to `nova.conf
|
|
configuration options`_.
|
|
|
|
#. Restart the ``nova-api`` service.
|
|
|
|
Configure a flavor (Controller)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Configure a flavor to request two PCI devices, each with ``vendor_id`` of
|
|
``0x8086`` and ``product_id`` of ``0x154d``:
|
|
|
|
.. code-block:: console
|
|
|
|
# openstack flavor set m1.large --property "pci_passthrough:alias"="a1:2"
|
|
|
|
For more information about the syntax for ``pci_passthrough:alias``, refer to
|
|
`flavor`_.
|
|
|
|
Enable PCI passthrough (Compute)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Enable VT-d and IOMMU. For more information, refer to steps one and two in
|
|
`Create Virtual Functions`_.
|
|
|
|
Configure PCI devices (Compute)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
#. Configure ``nova-compute`` to allow the PCI device to pass through to
|
|
VMs. Edit ``/etc/nova/nova.conf``:
|
|
|
|
.. code-block:: ini
|
|
|
|
[pci]
|
|
passthrough_whitelist = { "address": "0000:41:00.0" }
|
|
|
|
Alternatively specify multiple PCI devices using whitelisting:
|
|
|
|
.. code-block:: ini
|
|
|
|
[pci]
|
|
passthrough_whitelist = { "vendor_id": "8086", "product_id": "10fb" }
|
|
|
|
All PCI devices matching the ``vendor_id`` and ``product_id`` are added to
|
|
the pool of PCI devices available for passthrough to VMs.
|
|
|
|
For more information about the syntax of ``passthrough_whitelist``,
|
|
refer to `nova.conf configuration options`_.
|
|
|
|
#. Specify the PCI alias for the device.
|
|
|
|
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]
|
|
alias = { "vendor_id":"8086", "product_id":"154d", "device_type":"type-PF", "name":"a1" }
|
|
|
|
For more information about the syntax of ``alias``, refer to `nova.conf
|
|
configuration options`_.
|
|
|
|
#. Restart the ``nova-compute`` service.
|
|
|
|
Create instances with PCI passthrough devices
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The ``nova-scheduler`` selects a destination host that has PCI devices
|
|
available with the specified ``vendor_id`` and ``product_id`` that matches the
|
|
``alias`` from the flavor.
|
|
|
|
.. code-block:: console
|
|
|
|
# openstack server create --flavor m1.large --image cirros-0.3.5-x86_64-uec --wait test-pci
|
|
|
|
.. Links
|
|
.. _`Create Virtual Functions`: https://docs.openstack.org/ocata/networking-guide/config-sriov.html#create-virtual-functions-compute
|
|
.. _`Configure nova-scheduler`: https://docs.openstack.org/ocata/networking-guide/config-sriov.html#configure-nova-scheduler-controller
|
|
.. _`nova.conf configuration options`: https://docs.openstack.org/ocata/config-reference/compute/config-options.html
|
|
.. _`flavor`: https://docs.openstack.org/admin-guide/compute-flavors.html
|
|
.. _`Networking Guide`: https://docs.openstack.org/ocata/networking-guide/config-sriov.html
|