Browse Source

Merge "docs: Remove duplicated PCI passthrough extra spec info"

changes/79/781079/2
Zuul 4 months ago
committed by Gerrit Code Review
parent
commit
f4f0f8eea1
  1. 126
      doc/source/admin/pci-passthrough.rst
  2. 73
      doc/source/user/flavors.rst

126
doc/source/admin/pci-passthrough.rst

@ -16,11 +16,12 @@ different guests. In the case of PCI passthrough, the full physical device is
assigned to only one guest and cannot be shared.
PCI devices are requested through flavor extra specs, specifically via the
``pci_passthrough:alias=<alias>`` flavor extra spec. This guide demonstrates
how to enable PCI passthrough for a type of PCI device with a vendor ID of
``8086`` and a product ID of ``154d`` - an Intel X520 Network Adapter - by
mapping them to the alias ``a1``. You should adjust the instructions for other
devices with potentially different capabilities.
:nova:extra-spec:`pci_passthrough:alias` flavor extra spec.
This guide demonstrates how to enable PCI passthrough for a type of PCI device
with a vendor ID of ``8086`` and a product ID of ``154d`` - an Intel X520
Network Adapter - by mapping them to the alias ``a1``.
You should adjust the instructions for other devices with potentially different
capabilities.
.. note::
@ -50,9 +51,12 @@ devices with potentially different capabilities.
Nova will ignore PCI devices reported by the hypervisor if the address is
outside of these ranges.
Configure host (Compute)
Enabling PCI passthrough
------------------------
Configure compute host
~~~~~~~~~~~~~~~~~~~~~~
To enable PCI passthrough on an x86, Linux-based compute node, the following
are required:
@ -83,9 +87,8 @@ passthrough`__.
.. __: https://devblogs.microsoft.com/scripting/passing-through-devices-to-hyper-v-vms-by-using-discrete-device-assignment/
Configure ``nova-compute`` (Compute)
------------------------------------
Configure ``nova-compute``
~~~~~~~~~~~~~~~~~~~~~~~~~~
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
@ -115,9 +118,10 @@ In addition, it is necessary to configure the :oslo.config:option:`pci.alias`
option, which is a JSON-style configuration option that allows you to map a
given device type, identified by the standard PCI ``vendor_id`` and (optional)
``product_id`` fields, to an arbitrary name or *alias*. This alias can then be
used to request a PCI device using the ``pci_passthrough:alias=<alias>`` flavor
extra spec, as discussed previously. For our sample device with a vendor ID of
``0x8086`` and a product ID of ``0x154d``, this would be:
used to request a PCI device using the :nova:extra-spec:`pci_passthrough:alias`
flavor extra spec, as discussed previously.
For our sample device with a vendor ID of ``0x8086`` and a product ID of
``0x154d``, this would be:
.. code-block:: ini
@ -152,9 +156,8 @@ Refer to :oslo.config:option:`pci.alias` for syntax information.
Once configured, restart the :program:`nova-compute` service.
Configure ``nova-scheduler`` (Controller)
-----------------------------------------
Configure ``nova-scheduler``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :program:`nova-scheduler` service must be configured to enable the
``PciPassthroughFilter``. To do this, add this filter to the list of filters
@ -170,11 +173,8 @@ specified in :oslo.config:option:`filter_scheduler.enabled_filters` and set
Once done, restart the :program:`nova-scheduler` service.
.. _pci-passthrough-alias:
Configure ``nova-api`` (Controller)
-----------------------------------
Configure ``nova-api``
~~~~~~~~~~~~~~~~~~~~~~
It is necessary to also configure the :oslo.config:option:`pci.alias` config
option on the controller. This configuration should match the configuration
@ -186,13 +186,14 @@ found on the compute nodes. For example:
alias = { "vendor_id":"8086", "product_id":"154d", "device_type":"type-PF", "name":"a1", "numa_policy":"preferred" }
Refer to :oslo.config:option:`pci.alias` for syntax information.
Refer to :ref:`Affinity <pci_numa_affinity_policy>` for ``numa_policy`` information.
Refer to :ref:`Affinity <pci-numa-affinity-policy>` for ``numa_policy``
information.
Once configured, restart the :program:`nova-api` service.
Configure a flavor (API)
------------------------
Configuring a flavor or image
-----------------------------
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:
@ -202,15 +203,76 @@ For example, to request two of the PCI devices referenced by alias ``a1``, run:
$ openstack flavor set m1.large --property "pci_passthrough:alias"="a1:2"
For more information about the syntax for ``pci_passthrough:alias``, refer to
:ref:`Flavors <extra-spec-pci-passthrough>`.
Create instances with PCI passthrough devices
---------------------------------------------
The :program:`nova-scheduler` service selects a destination host that has PCI
devices available that match the ``alias`` specified in the flavor.
:doc:`the documentation </configuration/extra-specs>`.
.. _pci-numa-affinity-policy:
PCI-NUMA affinity policies
--------------------------
By default, the libvirt driver enforces strict NUMA affinity for PCI devices,
be they PCI passthrough devices or neutron SR-IOV interfaces. This means that
by default a PCI device must be allocated from the same host NUMA node as at
least one of the instance's CPUs. This isn't always necessary, however, and you
can configure this policy using the
:nova:extra-spec:`hw:pci_numa_affinity_policy` flavor extra spec or equivalent
image metadata property. There are three possible values allowed:
**required**
This policy means that nova will boot instances with PCI devices **only**
if at least one of the NUMA nodes of the instance is associated with these
PCI devices. It means that if NUMA node info for some PCI devices could not
be determined, those PCI devices wouldn't be consumable by the instance.
This provides maximum performance.
**socket**
This policy means that the PCI device must be affined to the same host
socket as at least one of the guest NUMA nodes. For example, consider a
system with two sockets, each with two NUMA nodes, numbered node 0 and node
1 on socket 0, and node 2 and node 3 on socket 1. There is a PCI device
affined to node 0. An PCI instance with two guest NUMA nodes and the
``socket`` policy can be affined to either:
* node 0 and node 1
* node 0 and node 2
* node 0 and node 3
* node 1 and node 2
* node 1 and node 3
The instance cannot be affined to node 2 and node 3, as neither of those
are on the same socket as the PCI device. If the other nodes are consumed
by other instances and only nodes 2 and 3 are available, the instance
will not boot.
**preferred**
This policy means that ``nova-scheduler`` will choose a compute host
with minimal consideration for the NUMA affinity of PCI devices.
``nova-compute`` will attempt a best effort selection of PCI devices
based on NUMA affinity, however, if this is not possible then
``nova-compute`` will fall back to scheduling on a NUMA node that is not
associated with the PCI device.
**legacy**
This is the default policy and it describes the current nova behavior.
Usually we have information about association of PCI devices with NUMA
nodes. However, some PCI devices do not provide such information. The
``legacy`` value will mean that nova will boot instances with PCI device
if either:
* The PCI device is associated with at least one NUMA nodes on which the
instance will be booted
* There is no information about PCI-NUMA affinity available
For example, to configure a flavor to use the ``preferred`` PCI NUMA affinity
policy for any neutron SR-IOV interfaces attached by the user:
.. code-block:: console
# openstack server create --flavor m1.large --image cirros-0.3.5-x86_64-uec --wait test-pci
$ openstack flavor set $FLAVOR \
--property hw:pci_numa_affinity_policy=preferred
You can also configure this for PCI passthrough devices by specifying the
policy in the alias configuration via :oslo.config:option:`pci.alias`. For more
information, refer to :oslo.config:option:`the documentation <pci.alias>`.

73
doc/source/user/flavors.rst

@ -184,61 +184,6 @@ Performance Monitoring Unit (vPMU)
required, such workloads should set ``hw:pmu=False``. For most workloads
the default of unset or enabling the vPMU ``hw:pmu=True`` will be correct.
.. _pci_numa_affinity_policy:
PCI NUMA Affinity Policy
For the libvirt driver, you can specify the NUMA affinity policy for
PCI passthrough devices and neutron SR-IOV interfaces via the
``hw:pci_numa_affinity_policy`` flavor extra spec or
``hw_pci_numa_affinity_policy`` image property. The allowed values are
``required``, ``socket``, ``preferred`` or ``legacy`` (default).
**required**
This value will mean that nova will boot instances with PCI devices
**only** if at least one of the NUMA nodes of the instance is associated
with these PCI devices. It means that if NUMA node info for some PCI
devices could not be determined, those PCI devices wouldn't be consumable
by the instance. This provides maximum performance.
**socket**
This means that the PCI device must be affined to the same host socket as
at least one of the guest NUMA nodes. For example, consider a system with
two sockets, each with two NUMA nodes, numbered node 0 and node 1 on
socket 0, and node 2 and node 3 on socket 1. There is a PCI device
affined to node 0. An PCI instance with two guest NUMA nodes and the
``socket`` policy can be affined to either:
* node 0 and node 1
* node 0 and node 2
* node 0 and node 3
* node 1 and node 2
* node 1 and node 3
The instance cannot be affined to node 2 and node 3, as neither of those
are on the same socket as the PCI device. If the other nodes are consumed
by other instances and only nodes 2 and 3 are available, the instance
will not boot.
**preferred**
This value will mean that ``nova-scheduler`` will choose a compute host
with minimal consideration for the NUMA affinity of PCI devices.
``nova-compute`` will attempt a best effort selection of PCI devices
based on NUMA affinity, however, if this is not possible then
``nova-compute`` will fall back to scheduling on a NUMA node that is not
associated with the PCI device.
**legacy**
This is the default value and it describes the current nova behavior.
Usually we have information about association of PCI devices with NUMA
nodes. However, some PCI devices do not provide such information. The
``legacy`` value will mean that nova will boot instances with PCI device
if either:
* The PCI device is associated with at least one NUMA nodes on which the
instance will be booted
* There is no information about PCI-NUMA affinity available
.. _extra-specs-memory-encryption:
Hardware encryption of guest memory
@ -251,24 +196,6 @@ Hardware encryption of guest memory
$ openstack flavor set FLAVOR-NAME \
--property hw:mem_encryption=True
.. _extra-spec-pci-passthrough:
PCI passthrough
You can assign PCI devices to a guest by specifying them in the flavor.
.. code:: console
$ openstack flavor set FLAVOR-NAME \
--property pci_passthrough:alias=ALIAS:COUNT
Where:
- ALIAS: (string) The alias which correspond to a particular PCI device class
as configured in the nova configuration file (see
:oslo.config:option:`pci.alias`).
- COUNT: (integer) The amount of PCI devices of type ALIAS to be assigned to
a guest.
.. _extra-specs-hiding-hypervisor-signature:
Hiding hypervisor signature

Loading…
Cancel
Save