[libvirt PATCH 11/12] docs: document virtio failover / QEMU auto-plug of hostdev during migration

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

 



The information in formatdomain.html seems too detailed, but it also
didn't seem right to put that information in a wiki page before the
patches are even pushed...

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

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 6e86d057a8..e3ea89fe25 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -5871,6 +5871,76 @@
 &lt;/devices&gt;
 ...</pre>
 
+    <h5><a id="elementsVirtioFailover">Using virtio "failover" to bond an emulated/hostdev NIC pair</a></h5>
+
+    <p>
+      <span class="since">Since 6.1.0 (QEMU and KVM only, requires
+      QEMU 4.2.0 or newer)</span> If the virtio-net driver in the
+      guest OS supports the virtio "failover" feature, it is possible
+      to setup a simple bond device comprised of one emulated virtio
+      NIC and one SRIOV VF "hostdev" NIC. In this configuration, the
+      higher-performing hostdev NIC will normally be preferred for all
+      network traffic, but when the VM is migrated, QEMU will
+      automatically unplug the VF from the VM, 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). The
+      interface <code>&lt;driver&gt;</code> subelement
+      attributes <code>failover</code> and <code>backupAlias</code>
+      are used to set this up - the virtio NIC will need to
+      have <code>failover='on'</code> set in
+      its <code>&lt;driver&gt;</code>, and the hostdev NIC will
+      use <code>backupAlias</code> to indicate the alias name of the
+      virtio NIC.
+    </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, it must start with "ua-".
+    </p>
+    <p>
+      NB2: Currently the only known implementation of failover in a
+      guest OS virtio-net driver requires that the MAC addresses of
+      the virtio and hostdev NIC must match. Since that may not always
+      be a requirement, libvirt doesn't enforce this limitation - it
+      is up to the person/management application that is creating the
+      configuration.
+    </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 following 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.
+    </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;driver failover='on'/&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;driver backupAlias='ua-backup0'/&gt;
+  &lt;/interface&gt;
+&lt;/devices&gt;
+...</pre>
 
     <h5><a id="elementsNICSMulticast">Multicast tunnel</a></h5>
 
diff --git a/docs/news.xml b/docs/news.xml
index 056c7ef026..051b6b3a54 100644
--- a/docs/news.xml
+++ b/docs/news.xml
@@ -44,6 +44,33 @@
 <libvirt>
   <release version="v6.1.0" date="unreleased">
     <section title="New features">
+      <change>
+        <summary>
+          support for virtio "failover" / QEMU auto-unplug of vfio devices
+        </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). 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;driver&gt; subelement "failover" and
+          "backupAlias" 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