mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-01-21 20:15:17 +00:00
docs: document <interface> subelement <teaming>
Signed-off-by: Laine Stump <laine@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
Laine Stump
parent
8a226ddb36
commit
f0f34056ab
@ -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>
|
||||
|
||||
|
||||
@ -54,6 +54,34 @@
|
||||
QEMU 4.2.
|
||||
</description>
|
||||
</change>
|
||||
<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>
|
||||
</section>
|
||||
<section title="Improvements">
|
||||
</section>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user