From a7ad591f6a6b86b24b1ed030cc9b1ca5b3bf4346 Mon Sep 17 00:00:00 2001

Message-Id: <a7ad591f6a6b86b24b1ed030cc9b1ca5b3bf4346@dist-git>

From: Laine Stump <laine@redhat.com>

Date: Thu, 30 Jan 2020 14:12:44 -0500

Subject: [PATCH] docs: document <interface> subelement <teaming>

MIME-Version: 1.0

Content-Type: text/plain; charset=UTF-8

Content-Transfer-Encoding: 8bit

Signed-off-by: Laine Stump <laine@redhat.com>

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

(cherry picked from commit f0f34056ab26eaa9f903a51cd1fa155088fd640f)

Conflicts:

   docs/news.xml - feature is in release 6.1.0 upstream, but

      that release doesn't exist downstream.

https://bugzilla.redhat.com/1693587

Signed-off-by: Laine Stump <laine@redhat.com>

Message-Id: <20200130191244.24174-7-laine@redhat.com>

Reviewed-by: Jiri Denemark <jdenemar@redhat.com>

---

 docs/formatdomain.html.in | 101 ++++++++++++++++++++++++++++++++++++++

 docs/news.xml             |  28 +++++++++++

 2 files changed, 129 insertions(+)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in

index 4db9c292b7..98a811bd09 100644

--- a/docs/formatdomain.html.in

+++ b/docs/formatdomain.html.in

@@ -5873,6 +5873,107 @@

 </devices>

 ...

+    
Teaming a virtio/hostdev NIC pair

+

+    

+      Since 6.1.0 (QEMU and KVM only, requires

+        QEMU 4.2.0 or newer axnd a guest virtio-net driver supporting

+        the "failover" feature, such as the one included in Linux

+        kernel 4.18 and newer)

+      

+      The <teaming> 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).

+    

+

+

+...

+<devices>

+  <interface type='network'>

+    <source network='mybridge'/>

+    <mac address='00:11:22:33:44:55'/>

+    <model type='virtio'/>

+    <teaming type='persistent'/>

+    <alias name='ua-backup0'/>

+  </interface>

+  <interface type='network'>

+    <source network='hostdev-pool'/>

+    <mac address='00:11:22:33:44:55'/>

+    <model type='virtio'/>

+    <teaming type='transient' persistent='ua-backup0'/>

+  </interface>

+</devices>

+...

+

+    

+      The <teaming> element required

+      attribute type will be set to

+      either "persistent" to indicate a device that

+      should always be present in the domain,

+      or "transient" 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 <teaming> called "persistent"

+      - this attribute should be set to the alias name of the other

+      device in the pair (the one that has <teaming

+      type="persistent'/>).

+    

+    

+      In the particular case of QEMU,

+      libvirt's <teaming> element is used to setup

+      a virtio-net "failover" device pair. For this setup, the

+      persistent device must be an interface with <model

+      type="virtio"/>, and the transient device must

+      be <interface type='hostdev'/>

+      (or <interface type='network'/> 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).

+    

+    

+      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-").

+    

+    

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

+    

+    

+      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 <source> of the

+      hostdev NIC (<interface type='hostdev'>) 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.

+    

     
Multicast tunnel

diff --git a/docs/news.xml b/docs/news.xml

index 731f010297..408ffc8518 100644

--- a/docs/news.xml

+++ b/docs/news.xml

@@ -65,6 +65,34 @@

       </change>

     </section>

     <section title="New features">

+      <change>

+        <summary>

+          support for virtio+hostdev NIC <teaming>

+        </summary>

+        <description>

+          QEMU 4.2.0 and later, combined with a sufficiently recent

+          guest virtio-net driver (e.g. the driver included in Linux

+          kernel 4.18 and later), 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 <teaming> subelement

+          "type" and "persistent" attributes.

+        </description>

+      </change>

       <change>

         <summary>

           new PCI hostdev address type: unassigned

-- 

2.25.0