os-vif(1)

OS_VIF(1)

os_vif

OS_VIF(1)

NAME

os_vif - os_vif 3.1.1

os-vif is a library for plugging and unplugging virtual interfaces (VIFs) in OpenStack. It provides:

Versioned objects that represent various types of virtual interfaces and their components
Base VIF plugin class that supplies a plug() and unplug() interface
Plugins for two networking backends - Open vSwitch and Linux Bridge

os-vif is intended to define a common model for representing VIF types in OpenStack. With the exception of the two included plugins, all plugins for other networking backends are maintained in separate code repositories.

USAGE GUIDE

Usage

The interface to the os_vif library is very simple. To begin using the library, first call the os_vif.initialize() function. This will load all installed plugins and register the object model:

import os_vif
os_vif.initialize()

Once the os_vif library is initialized, there are only two other library functions: os_vif.plug() and os_vif.unplug(). Both methods accept an argument of (a subclass of) type os_vif.objects.vif.VIFBase and an argument of type os_vif.objects.instance_info.InstanceInfo:

import uuid
from nova import objects as nova_objects
from os_vif import exception as vif_exc
from os_vif.objects import fields
from os_vif.objects import instance_info
from os_vif.objects import network
from os_vif.objects import subnet as os_subnet
from os_vif.objects import vif as vif_obj
instance_uuid = 'd7a730ca-3c28-49c3-8f26-4662b909fe8a'
instance = nova_objects.Instance.get_by_uuid(instance_uuid)
instance_info = instance_info.InstanceInfo(


    uuid=instance.uuid,


    name=instance.name,


    project_id=instance.project_id)
subnet = os_subnet.Subnet(cidr='192.168.1.0/24')
subnets = os_subnet.SubnetList([subnet])
network = network.Network(label='tenantnet',


                          subnets=subnets,


                          multi_host=False,


                          should_provide_vlan=False,


                          should_provide_bridge=False)
vif_uuid = uuid.uuid4()
vif = vif_obj.VIFVHostUser(id=vif_uuid,


                           address=None,


                           network=network,


                           plugin='vhostuser',


                           path='/path/to/socket',


                           mode=fields.VIFVHostUserMode.SERVER)
# Now do the actual plug operations to connect the VIF to
# the backing network interface.
try:


    os_vif.plug(vif, instance_info)
except vif_exc.PlugException as err:


    # Handle the failure...
# If you are removing a virtual machine and its interfaces,
# you would use the unplug() operation:
try:


    os_vif.unplug(vif, instance_info)
except vif_exc.UnplugException as err:


    # Handle the failure...

VIF Types

In os-vif, a VIF type refers to a particular approach for configuring the backend of a guest virtual network interface. There is a small, finite set of ways that a VIF backend can be configured for any given hypervisor and a limited amount of metadata is associated with each approach.

VIF objects

Each distinct type of VIF configuration is represented by a versioned object, subclassing VIFBase.

class os_vif.objects.vif.VIFBase(context=None, **kwargs): Represents a virtual network interface.
The base VIF defines fields that are common to all types of VIF and provides an association to the network the VIF is plugged into. It should not be instantiated itself - use a subclass instead.

class os_vif.objects.vif.VIFGeneric(context=None, **kwargs)

A generic-style VIF.

Generic-style VIFs are unbound, floating TUN/TAP devices that should be setup by the plugin, not the hypervisor. The way the TAP device is connected to the host network stack is explicitly left undefined.

For libvirt drivers, this maps to type="ethernet" which just implies a bare TAP device with all setup delegated to the plugin.

class os_vif.objects.vif.VIFBridge(context=None, **kwargs)

A bridge-style VIF.

Bridge-style VIFs are bound to a Linux host bridge by the hypervisor. This provides Ethernet layer bridging, typically to the LAN. Other devices may be bound to the same L2 virtual bridge.

For libvirt drivers, this maps to type='bridge'.

class os_vif.objects.vif.VIFOpenVSwitch(context=None, **kwargs)

A bridge-style VIF specifically for use with OVS.

Open vSwitch VIFs are bound directly (or indirectly) to an Open vSwitch bridge by the hypervisor. Other devices may be bound to the same virtual bridge.

For libvirt drivers, this also maps to type='bridge'.

class os_vif.objects.vif.VIFDirect(context=None, **kwargs)

A direct-style VIF.

Despite the confusing name, direct-style VIFs utilize macvtap which is a device driver that inserts a software layer between a guest and an SR-IOV Virtual Function (VF). Contrast this with VIFHostDevice, which allows the guest to directly connect to the VF.

The connection to the device may operate in one of a number of different modes, VEPA (either 802.1Qbg or 802.1Qbh), passthrough (exclusive assignment of the host NIC) or bridge (ethernet layer bridging of traffic). The passthrough mode would be used when there is a network device which needs to have a MAC address or VLAN configuration. For passthrough of network devices without MAC/VLAN configuration, VIFHostDevice should be used instead.

For libvirt drivers, this maps to type='direct'

class os_vif.objects.vif.VIFVHostUser(context=None, **kwargs)

A vhostuser-style VIF.

vhostuser-style VIFs utilize a userspace vhost backend, which allows traffic to traverse between the guest and a host userspace application (commonly a virtual switch), bypassing the kernel network stack. Contrast this with VIFBridge, where all packets must be handled by the hypervisor.

For libvirt drivers, this maps to type='vhostuser'

class os_vif.objects.vif.VIFNestedDPDK(context=None, **kwargs)

A nested DPDK-style VIF.

Nested DPDK-style VIFs are used by Kuryr-Kubernetes to provide accelerated DPDK datapath for nested Kubernetes pods running inside the VM. The port is first attached to the virtual machine, bound to the userspace driver (e.g. uio_pci_generic, igb_uio or vfio-pci) and then consumed by Kubernetes pod via the kuryr-kubernetes CNI plugin.

This does not apply to libvirt drivers.

VIF port profile objects

Each VIF instance can optionally be associated with a port profile object. This provides a set of metadata attributes that serve to identify the guest virtual interface to the host. Different types of host connectivity will require different port profile object metadata. Each port profile type is associated with a versioned object, subclassing VIFPortProfileBase.

class os_vif.objects.vif.VIFPortProfileBase(context=None, **kwargs): Base class for all types of port profile.
The base profile defines fields that are common to all types of profile. It should not be instantiated itself - use a subclass instead.

class os_vif.objects.vif.VIFPortProfileOpenVSwitch(context=None, **kwargs): Port profile info for Open vSwitch networks.
This profile provides the metadata required to associate a VIF with an Open vSwitch interface.

class os_vif.objects.vif.VIFPortProfileFPOpenVSwitch(context=None, **kwargs): Port profile info for Open vSwitch networks using fast path.
This profile provides the metadata required to associate a fast path VIF with an Open vSwitch port.

class os_vif.objects.vif.VIFPortProfileOVSRepresentor(context=None, **kwargs)

Port profile info for OpenVSwitch networks using a representor.

This profile provides the metadata required to associate a VIF with a VF representor and Open vSwitch port. If representor_name is specified, it indicates a desire to rename the representor to the given name on plugging.

NOTE:

This port profile is provided for backwards compatibility only.

This interface has been superceded by the one provided by the DatapathOffloadRepresentor class, which is now a field element of the VIFPortProfileBase class. The datapath_offload field in port profiles should be used instead.

class os_vif.objects.vif.VIFPortProfileFPBridge(context=None, **kwargs): Port profile info for Linux Bridge networks using fast path.
This profile provides the metadata required to associate a fast path VIF with a Linux Bridge port.

class os_vif.objects.vif.VIFPortProfileFPTap(context=None, **kwargs): Port profile info for Calico networks using fast path.
This profile provides the metadata required to associate a fast path VIF with a Calico port.

class os_vif.objects.vif.VIFPortProfile8021Qbg(context=None, **kwargs): Port profile info for VEPA 802.1qbg networks.
This profile provides the metadata required to associate a VIF with a VEPA host device supporting the 802.1Qbg spec.

class os_vif.objects.vif.VIFPortProfile8021Qbh(context=None, **kwargs): Port profile info for VEPA 802.1qbh networks.
This profile provides the metadata required to associate a VIF with a VEPA host device supporting the 802.1Qbh spec.

class os_vif.objects.vif.VIFPortProfileK8sDPDK(context=None, **kwargs): Port profile info for Kuryr-Kubernetes DPDK ports.
This profile provides the metadata required to associate nested DPDK VIF with a Kubernetes pod.

Datapath Offload type object

Port profiles can be associated with a datapath_offload object. This provides a set of metadata attributes that serve to identify the datapath offload parameters of a VIF. Each different type of datapath offload is associated with a versioned object, subclassing DatapathOffloadBase.

class os_vif.objects.vif.DatapathOffloadBase(context=None, **kwargs): Base class for all types of datapath offload.

class os_vif.objects.vif.DatapathOffloadRepresentor(context=None, **kwargs): Offload type for VF Representors conforming to the switchdev model.
This datapath offloads provides the metadata required to associate a VIF with a VF representor conforming to the switchdev kernel model. If representor_name is specified, it indicates a desire to rename the representor to the given name on plugging.

VIF network objects

Each VIF instance is associated with a set of objects which describe the logical network that the guest will be plugged into. This information is again represented by a set of versioned objects

Host Information

To enable negotiation of features between a service host (typically a compute node) and the network provider host, os-vif exposes some objects that describe the host running the plugins.

Host Information Objects

The following objects encode the information about the service host.

HostInfo

This class provides information about the host as a whole. This currently means a list of plugins installed on the host. In the future this may include further information about the host OS state.

HostPluginInfo

This class provides information about the capabilities of a single os-vif plugin implementation that is installed on the host. This currently means a list of VIF objects that the plugin is capable of consuming. In the future this may include further information about resources on the host that the plugin can/will utilize. While many plugins will only ever support a single VIF object, it is permitted to support multiple different VIF objects. An example would be openvswitch which can use the same underlying host network functionality to configure a VM in several different ways.

HostVIFInfo

This class provides information on a single VIF object that is supported by a plugin. This will include the versioned object name and the minimum and maximum versions of the object that can be consumed.

It is the responsibility of the network provider to ensure that it only sends back a serialized VIF object that satisfies the minimum and maximum version constraints indicated by the plugin. Objects outside of this version range will be rejected with a fatal error.

Negotiating networking

When a service host wants to create a network port, it will first populate an instance of the HostInfo class, to describe all the plugins installed on the host. It will then serialize this class to JSON and send it to the network manager host. The network manager host will deserialize it back into a HostInfo object. This can then be passed down into the network driver which can use it to decide how to configure the network port.

If the os-vif version installed on the network host is older than that on the service host, it may not be able to deserialize the HostInfo class. In this case it should reply with an error to the service host. The error message should report the maximum version of the HostInfo class that is supported. the service host should then backlevel its HostInfo object to that version before serializing it and re-trying the port creation request.

The mechanism or transport for passing the plugin information between the network and service hosts is left undefined. It is upto the user of os-vif to decide upon the appropriate approach.

Linux Bridge

The Linux Bridge plugin, vif_plug_linux_bridge, is an os-vif VIF plugin for the Linux Bridge network backend. It is one of three plugins provided as part of os-vif itself, the others being ovs and noop.

Supported VIF Types

The Linux Bridge plugin provides support for the following VIF types:

VIFBridge: Configuration where a guest is connected to a Linux bridge via a TAP device. This is the only supported configuration for this plugin.

For information on the VIF type objects, refer to /user/vif-types. Note that only the above VIF types are supported by this plugin.

no-op

The no-op plugin, vif_plug_noop, is an os-vif VIF plugin for use with network backends that do not require plugging of network interfaces. It is one of three plugins provided as part of os-vif itself, the others being ovs and linux-bridge.

Supported VIF Types

The no-op plugin provides support for the following VIF types:

VIFVHostUser: Configuration where a guest exposes a UNIX socket for its control plane. This configuration is used with a userspace dataplane such as VPP or Snabb switch.

For information on the VIF type objects, refer to /user/vif-types. Note that only the above VIF types are supported by this plugin.

Open vSwitch

The Open vSwitch plugin, vif_plug_ovs, is an os-vif VIF plugin for the Open vSwitch network backend. It is one of three plugins provided as part of os-vif itself, the others being linux-bridge and noop.

Supported VIF Types

The Open vSwitch plugin provides support for the following VIF types:

VIFOpenVSwitch: Configuration where a guest is directly connected an Open vSwitch bridge.
VIFBridge: Configuration where a guest is connected to a Linux bridge via a TAP device, and that bridge is connected to the Open vSwitch bridge. This allows for the use of iptables rules for filtering traffic.
VIFVHostUser: Configuration where a guest exposes a UNIX socket for its control plane. This configuration is used with the DPDK datapath of Open vSwitch.
VIFHostDevice: Configuration where an SR-IOV PCI device VF is passed through to a guest. The hw-tc-offload feature should be enabled on the SR-IOV PF using ethtool:

ethtool -K <PF> hw-tc-offload

This will create a VF representor per VF. The VF representor plays the same role as TAP devices in Para-Virtual (PV) setup. In this case the plug() method connects the VF representor to the OpenVSwitch bridge.

IMPORTANT:

Support for this feature requires Linux Kernel >= 4.8 and Open vSwitch 2.8. These add support for tc-based hardware offloads for SR-IOV VFs and offloading of OVS datapath rules using tc, respectively.

New in version 1.5.0.

For information on the VIF type objects, refer to /user/vif-types. Note that only the above VIF types are supported by this plugin.

FOR CONTRIBUTORS

•: If you are a new contributor to os-vif please refer: contributor/contributing

So You Want to Contribute...

For general information on contributing to OpenStack, please check out the contributor guide to get started. It covers all the basics that are common to all OpenStack projects: the accounts you need, the basics of interacting with our Gerrit review system, how we communicate as a community, etc.

Below will cover the more project specific information you need to get started with os-vif.

Communication

Please refer how-to-get-involved.

Contacting the Core Team

The overall structure of the os-vif team is documented on the wiki.

New Feature Planning

You can file an RFE bug if it has no interaction with other projects like nova or neutron.

If changes are part of the nova or neutron feature then it can be tracked as part of the nova or neutron feature. In that case, you should use the same topic to track the os-vif changes.

Task Tracking

We track our tasks in Launchpad.

If you're looking for some smaller, easier work item to pick up and get started on, search for the 'low-hanging-fruit' tag.

Reporting a Bug

You found an issue and want to make sure we are aware of it? You can do so on Launchpad. More info about Launchpad usage can be found on OpenStack docs page.

Getting Your Patch Merged

All changes proposed to the os-vif requires two Code-Review +2 votes from os-vif core reviewers before one of the core reviewers can approve patch by giving Workflow +1 vote. One exception is for trivial changes for example typo fixes etc which can be approved by a single core.

REFERENCE

Glossary

Calico

A virtual networking solution that uses IP routing (layer 3) to provide connectivity in the form of a flat IP network instead of bridging and tunneling.

Refer to the Calico documentation for more information.

Fast Path

When used, 6Wind's proprietary fast path technology behaves as a transparent acceleration layer for traditional switches (Open vSwitch, Linux Bridge) and for alternative networking mechanisms (Calico, Midonet).

Linux Bridge

The native networking "backend" found in Linux.

Refer to the Linux Foundation wiki for more information.

Open vSwitch

A software implementation of a virtual multilayer network switch

Refer to the OVS documentation for more information.

VEB

Virtual Ethernet Bridge A virtual Ethernet switch that implmented in a virtualized server environment. It is anything that mimics a traditional external layer 2 (L2) switch or bridge for connecting VMs. Generally implemented as a vSwitch, though hardware-based VEBs using SR-IOV are possible.

Refer to this Virtual networking technologies brief for more information.

vSwitch

Virtual Switch A software-based virtual switch that connects virtual NICs to other virtual NICs and the broader physical network.

Refer to this presentation for more information.

VEPA

Virtual Ethernet Port Aggregator An approach to virtual networking where VM traffic is handled on the physical network rather than by a virtual switch. Unlike VNTag, frames are not tagged and the switch will use a single port to handle all VIFs for a host.

The basis of the 802.1Qbg spec.

Refer to this presentation for more information.

VN-Tag

VNTag An approach to virtual networking where an interface virtualizer (IV) is used in place of a VEB to connect multiple VIFs to a single, external, IV-capable hardware bridge. Each VIF is tagged with a unique ID (vif_id) which is used to route traffic through IVs, and VIFs are then treated like any other interface.

The basis of the 802.1Qbh and 802.1Qbr specs.

Refer to this Cisco presentation for more information.

vhost

An alternative to virtio that allows userspace guest processes to share virtqueues directly with the kernel (or, more specifically, a kernel module) preventing the QEMU process from becoming a bottleneck.

vhost-user

A variation of vhost that operates entirely in userspace. This allows userspace guest processes to share virtqueues with other processes operating in userspace, such as virtual switches, avoiding the kernel entirely and maximize performance.

When used, a guest exposes a UNIX socket for its control plane, allowing the external userspace service to provide the backend data plane via a mapped memory region. This process must implement the corresponding virtio vhost protocol, such as virtio-net for networking, on this socket.

Refer to the QEMU documentation for more information.

virtio

A class of virtual device emulated by QEMU. Virtio devices have virtqueues which can be used to share data from host to guest.

Refer to the libvirt Wiki for more information.

virtio-net

A network driver implementation based on virtio. Guests share virtqueues with the QEMU process, which in turn receives this traffic and forwards it to the host.

Refer to the KVM documentation for more information.

VIF

A virtual network interface.

IEEE 802.1Q

802.1Q A networking standard that supports virtual LANs (VLANs) on an Ethernet network.

Refer to the IEEE spec for more information.

IEEE 802.1Qbg

802.1Qbg An amendment to the 802.1Q spec known as "Edge Virtual Bridging", 802.1Qbg is an approach to networking where VM traffic is handled on the physical network rather than by a virtual switch. Originally based on VEPA.

Refer to the IEEE spec for more information.

IEEE 802.1Qbh

802.1Qbh A withdrawn amendment to the 802.1Q spec known as "Bridge Port Extensions", replaced by 802.1Qbr spec.

Refer to the IEEE spec for more information.

IEEE 802.1Qbr

802.1Qbr An amendment to the 802.1Q spec known as "Bridge Port Extensions",

Refer to the IEEE spec for more information.

tc

A framework for interacting with traffic control settings (QoS, essentially) in the Linux kernel.

Refer to the tc(8) man page for more information.

SR-IOV

Single Root I/O Virtualization An extension to the PCI Express (PCIe) specification that allows a device, typically a network adapter, to split access to its resources among various PCIe hardware functions, physical or virtual.

Refer to this article by Scott Lowe or the original PCI-SIG spec (paywall) for more information.

PF

Physical Function In SR-IOV, a PCIe function that has full configuration resources. An SR-IOV device can have up to 8 PFs, though this varies between devices. A PF would typically correspond to a single interface on a NIC.

Refer to this article by Scott Lowe for more information.

VF

Virtual Function In SR-IOV, a PCIe function that lacks configuration resources. An SR-IOV device can have up to 256 VFs, though this varies between devices. A VF must be of the same type as the parent device's PF.

Refer to this article by Scott Lowe for more information.

AUTHOR

unknown

COPYRIGHT

2023, OpenStack Foundation

December 29, 2023

3.1.1