| 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 |
| |
| |
| @@ -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 |
| |
| |
| @@ -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 |
| |