Merge "docs: Document virtio-net multiqueue"

Author: Zuul

doc/source/admin/networking.rst

@@ -199,3 +199,93 @@ As with the L2-type networks, this configuration will ensure instances using
 one or more L3-type networks must be scheduled on host cores from NUMA node 0.
 It is also possible to define more than one NUMA node, in which case the
 instance must be split across these nodes.
+
+
+virtio-net Multiqueue
+---------------------
+
+.. versionadded:: 12.0.0 (Liberty)
+
+.. versionchanged:: 24.0.0 (Xena)
+
+   Support for configuring multiqueue via the ``hw:vif_multiqueue_enabled``
+   flavor extra spec was introduced in the Xena (24.0.0) release.
+
+.. important::
+
+   The functionality described below is currently only supported by the
+   libvirt/KVM driver.
+
+Virtual NICs using the virtio-net driver support the multiqueue feature. By
+default, these vNICs will only use a single virtio-net TX/RX queue pair,
+meaning guests will not transmit or receive packets in parallel. As a result,
+the scale of the protocol stack in a guest may be restricted as the network
+performance will not scale as the number of vCPUs increases and per-queue data
+processing limits in the underlying vSwitch are encountered. The solution to
+this issue is to enable virtio-net multiqueue, which can allow the guest
+instances to increase the total network throughput by scaling the number of
+receive and transmit queue pairs with CPU count.
+
+Multiqueue virtio-net isn't always necessary, but it can provide a significant
+performance benefit when:
+
+- Traffic packets are relatively large.
+- The guest is active on many connections at the same time, with traffic
+  running between guests, guest to host, or guest to an external system.
+- The number of queues is equal to the number of vCPUs. This is because
+  multi-queue support optimizes RX interrupt affinity and TX queue selection in
+  order to make a specific queue private to a specific vCPU.
+
+However, while the virtio-net multiqueue feature will often provide a welcome
+performance benefit, it has some limitations and therefore should not be
+unconditionally enabled:
+
+- Enabling virtio-net multiqueue increases the total network throughput, but in
+  parallel it also increases the CPU consumption.
+- Enabling virtio-net multiqueue in the host QEMU config does not enable the
+  functionality in the guest OS. The guest OS administrator needs to manually
+  turn it on for each guest NIC that requires this feature, using
+  :command:`ethtool`.
+- In case the number of vNICs in a guest instance is proportional to the number
+  of vCPUs, enabling the multiqueue feature is less important.
+
+Having considered these points, multiqueue can be enabled or explicitly
+disabled using either the :nova:extra-spec:`hw:vif_multiqueue_enabled` flavor
+extra spec or equivalent ``hw_vif_multiqueue_enabled`` image metadata property.
+For example, to enable virtio-net multiqueue for a chosen flavor:
+
+.. code-block:: bash
+
+    $ openstack flavor set --property hw:vif_multiqueue_enabled=true $FLAVOR
+
+Alternatively, to explicitly disable multiqueue for a chosen image:
+
+.. code-block:: bash
+
+    $ openstack image set --property hw_vif_multiqueue_enabled=false $IMAGE
+
+.. note::
+
+    If both the flavor extra spec and image metadata property are provided,
+    their values must match or an error will be raised.
+
+Once the guest has started, you must enable multiqueue using
+:command:`ethtool`. For example:
+
+.. code-block:: bash
+
+    $ ethtool -L $devname combined $N
+
+where ``$devname`` is the name of the network device, and ``$N`` is the number
+of TX/RX queue pairs to configure corresponding to the number of instance
+vCPUs. Alternatively, you can configure this persistently using udev. For
+example, to configure four TX/RX queue pairs for network device ``eth0``:
+
+.. code-block:: bash
+
+    # cat /etc/udev/rules.d/50-ethtool.rules
+    ACTION=="add", SUBSYSTEM=="net", NAME=="eth0", RUN+="/sbin/ethtool -L eth0 combined 4"
+
+For more information on this feature, refer to the `original spec`__.
+
+.. __: https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/libvirt-virtiomq.html