[libvirt PATCH v2 6/6] docs: document <interface> subelement <teaming>

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



and the QEMU backend implementation using virtio failover.

Signed-off-by: Laine Stump <laine@xxxxxxxxxx>
---
 docs/formatdomain.html.in | 100 ++++++++++++++++++++++++++++++++++++++
 docs/news.xml             |  28 +++++++++++
 2 files changed, 128 insertions(+)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 4db9c292b7..a1c2a1e392 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -5873,6 +5873,106 @@
 &lt;/devices&gt;
 ...</pre>
 
+    <h5><a id="elementsTeaming">Teaming a virtio/hostdev NIC pair</a></h5>
+
+    <p>
+      <span class="since">Since 6.1.0 (QEMU and KVM only, requires
+        QEMU 4.2.0 or newer and a guest virtio-net driver supporting
+        the "failover" feature)
+      </span>
+      The <code>&lt;teaming&gt;</code> element of two interfaces can
+      be used to connect them as a team/bond device in the guest
+      (assuming proper support in the hypervisor and the guest
+      network driver).
+    </p>
+
+<pre>
+...
+&lt;devices&gt;
+  &lt;interface type='network'&gt;
+    &lt;source network='mybridge'/&gt;
+    &lt;mac address='00:11:22:33:44:55'/&gt;
+    &lt;model type='virtio'/&gt;
+    &lt;teaming type='persistent'/&gt;
+    &lt;alias name='ua-backup0'/&gt;
+  &lt;/interface&gt;
+  &lt;interface type='network'&gt;
+    &lt;source network='hostdev-pool'/&gt;
+    &lt;mac address='00:11:22:33:44:55'/&gt;
+    &lt;model type='virtio'/&gt;
+    &lt;teaming type='transient' persistent='ua-backup0'/&gt;
+  &lt;/interface&gt;
+&lt;/devices&gt;
+...</pre>
+
+    <p>
+      The <code>&lt;teaming&gt;</code> element required
+      attribute <code>type</code> will be set to
+      either <code>"persistent"</code> to indicate a device that
+      should always be present in the domain,
+      or <code>"transient"</code> to indicate a device that may
+      periodically be removed, then later re-added to the domain. When
+      type="transient", there should be a second attribute
+      to <code>&lt;teaming&gt;</code> called <code>"persistent"</code>
+      - this attribute should be set to the alias name of the other
+      device in the pair (the one that has <code>&lt;teaming
+      type="persistent'/&gt;</code>).
+    </p>
+    <p>
+      In the particular case of QEMU,
+      libvirt's <code>&lt;teaming&gt;</code> element is used to setup
+      a virtio-net "failover" device pair. For this setup, the
+      persistent device must be an interface with <code>&lt;model
+      type="virtio"/&gt;</code>, and the transient device must
+      be <code>&lt;interface type='hostdev'/&gt;</code>
+      (or <code>&lt;interface type='network'/&gt;</code> where the
+      referenced network defines a pool of SRIOV VFs). The guest will
+      then have a simple network team/bond device made of the virtio
+      NIC + hostdev NIC pair. In this configuration, the
+      higher-performing hostdev NIC will normally be preferred for all
+      network traffic, but when the domain is migrated, QEMU will
+      automatically unplug the VF from the guest, and then hotplug a
+      similar device once migration is completed; while migration is
+      taking place, network traffic will use the virtio NIC. (Of
+      course the emulated virtio NIC and the hostdev NIC must be
+      connected to the same subnet for bonding to work properly).
+    </p>
+    <p>
+      NB1: Since you must know the alias name of the virtio NIC when
+      configuring the hostdev NIC, it will need to be manually set in
+      the virtio NIC's configuration (as with all other manually set
+      alias names, this means it must start with "ua-").
+    </p>
+    <p>
+      NB2: Currently the only implementation of the guest OS
+      virtio-net driver supporting virtio-net failover requires that
+      the MAC addresses of the virtio and hostdev NIC must
+      match. Since that may not always be a requirement in the future,
+      libvirt doesn't enforce this limitation - it is up to the
+      person/management application that is creating the configuration
+      to assure the MAC addresses of the two devices match.
+    </p>
+    <p>
+      NB3: Since the PCI addresses of the SRIOV VFs on the hosts that
+      are the source and destination of the migration will almost
+      certainly be different, either higher level management software
+      will need to modify the <code>&lt;source&gt;</code> of the
+      hostdev NIC (<code>&lt;interface type='hostdev'&gt;</code>) at
+      the start of migration, or (a simpler solution) the
+      configuration will need to use a libvirt "hostdev" virtual
+      network that maintains a pool of such devices, as is implied in
+      the example's use of the libvirt network named "hostdev-pool" -
+      as long as the hostdev network pools on both hosts have the same
+      name, libvirt itself will take care of allocating an appropriate
+      device on both ends of the migration. Similarly the XML for the
+      virtio interface must also either work correctly unmodified on
+      both the source and destination of the migration (e.g. by
+      connecting to the same bridge device on both hosts, or by using
+      the same virtual network), or the management software must
+      properly modify the interface XML during migration so that the
+      virtio device remains connected to the same network segment
+      before and after migration.
+    </p>
 
     <h5><a id="elementsNICSMulticast">Multicast tunnel</a></h5>
 
diff --git a/docs/news.xml b/docs/news.xml
index 056c7ef026..7dc9cc18cb 100644
--- a/docs/news.xml
+++ b/docs/news.xml
@@ -44,6 +44,34 @@
 <libvirt>
   <release version="v6.1.0" date="unreleased">
     <section title="New features">
+      <change>
+        <summary>
+          support for virtio+hostdev NIC &lt;teaming&gt;
+        </summary>
+        <description>
+          QEMU 4.2.0 and later, combined with a sufficiently recent
+          guest virtio-net driver, supports setting up a simple
+          network bond device comprised of one virtio emulated NIC and
+          one hostdev NIC (which must be an SRIOV VF). (in QEMU, this
+          is known as the "virtio failover" feature). The allure of
+          this setup is that the bond will always favor the hostdev
+          device, providing better performance, until the guest is
+          migrated - at that time QEMU will automatically unplug the
+          hostdev NIC and the bond will send all traffic via the
+          virtio NIC until migration is completed, then QEMU on the
+          destination side will hotplug a new hostdev NIC and the bond
+          will switch back to using the hostdev for network
+          traffic. The result is that guests desiring the extra
+          performance of a hostdev NIC are now migratable without
+          network downtime (performance is just degraded during
+          migration) and without requiring a complicated bonding
+          configuration in the guest OS network config and complicated
+          unplug/replug logic in the management application on the
+          host - it can instead all be accomplished in libvirt with
+          the interface &lt;teaming&gt; subelement "type" and
+          "persistent" attributes.
+        </description>
+      </change>
     </section>
     <section title="Improvements">
     </section>
-- 
2.24.1





[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux