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

Author: Zuul

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>`.

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