181 lines
8.0 KiB
Diff
181 lines
8.0 KiB
Diff
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>
|
|
...</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 axnd a guest virtio-net driver supporting
|
|
+ the "failover" feature, such as the one included in Linux
|
|
+ kernel 4.18 and newer)
|
|
+ </span>
|
|
+ The <code><teaming></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>
|
|
+...
|
|
+<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>
|
|
+...</pre>
|
|
+
|
|
+ <p>
|
|
+ The <code><teaming></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><teaming></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><teaming
|
|
+ type="persistent'/></code>).
|
|
+ </p>
|
|
+ <p>
|
|
+ In the particular case of QEMU,
|
|
+ libvirt's <code><teaming></code> element is used to setup
|
|
+ a virtio-net "failover" device pair. For this setup, the
|
|
+ persistent device must be an interface with <code><model
|
|
+ type="virtio"/></code>, and the transient device must
|
|
+ be <code><interface type='hostdev'/></code>
|
|
+ (or <code><interface type='network'/></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><source></code> of the
|
|
+ hostdev NIC (<code><interface type='hostdev'></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 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
|
|
|