docs: Use sphinx.ext.autodoc for VIF types
This lets us keep all our docs in code where we can see them. Change-Id: Ibac3e94aa3d5018afbc331982e245951dc0ccd4b
This commit is contained in:
Stephen Finucane
parent
dd47251f23
commit
8609f8a803
@ -85,15 +85,21 @@ Glossary
|
||||
|
||||
vhost
|
||||
|
||||
An alternative to :term:`virtio` that allows a userspace process to share
|
||||
*virtqueues* directly with the kernel, preventing the QEMU process from
|
||||
becoming a bottleneck.
|
||||
An alternative to :term:`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 :term:`vhost` that operates entirely in userspace. This
|
||||
allows processes operating in userspace, such as virtual switches, to
|
||||
avoid the kernel entirely and maximize performance.
|
||||
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 :term:`virtio-net` for networking, on this socket.
|
||||
|
||||
Refer to the `QEMU documentation`__ for more information.
|
||||
|
||||
|
||||
@ -11,11 +11,9 @@ Supported VIF Types
|
||||
|
||||
The Linux Bridge plugin provides support for the following VIF types:
|
||||
|
||||
``VIFBridge``
|
||||
:mod:`~os_vif.objects.VIFBridge`
|
||||
Configuration where a guest is connected to a Linux bridge via a TAP device.
|
||||
This is the only supported configuration for this plugin.
|
||||
|
||||
Refer to :ref:`vif-bridge` for more information.
|
||||
|
||||
For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note
|
||||
that only the above VIF types are supported by this plugin.
|
||||
|
||||
@ -12,11 +12,9 @@ Supported VIF Types
|
||||
|
||||
The no-op plugin provides support for the following VIF types:
|
||||
|
||||
``VIFVHostUser``
|
||||
:mod:`~os_vif.objects.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.
|
||||
|
||||
Refer to :ref:`vif-vhostuser` for more information.
|
||||
|
||||
For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note
|
||||
that only the above VIF types are supported by this plugin.
|
||||
|
||||
@ -11,28 +11,24 @@ Supported VIF Types
|
||||
|
||||
The Open vSwitch plugin provides support for the following VIF types:
|
||||
|
||||
``VIFOpenVSwitch``
|
||||
:mod:`~os_vif.objects.VIFOpenVSwitch`
|
||||
Configuration where a guest is directly connected an Open vSwitch bridge.
|
||||
|
||||
Refer to :ref:`vif-openvswitch` for more information.
|
||||
|
||||
``VIFBridge``
|
||||
:mod:`~os_vif.objects.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.
|
||||
|
||||
Refer to :ref:`vif-bridge` for more information.
|
||||
|
||||
``VIFVHostUser``
|
||||
:mod:`~os_vif.objects.VIFVHostUser`
|
||||
Configuration where a guest exposes a UNIX socket for its control plane. This
|
||||
configuration is used with the `DPDK datapath of Open vSwitch`__.
|
||||
|
||||
Refer to :ref:`vif-vhostuser` for more information.
|
||||
__ http://docs.openvswitch.org/en/latest/howto/dpdk/
|
||||
|
||||
``VIFHostDevice``
|
||||
:mod:`~os_vif.objects.VIFHostDevice`
|
||||
Configuration where an :term:`SR-IOV` PCI device :term:`VF` is passed through
|
||||
to a guest. The ``hw-tc-offload`` feature should be enabled on the SR-IOV
|
||||
:term:`PF` using ``ethtool``:
|
||||
:term:`PF` using :command:`ethtool`:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@ -48,11 +44,7 @@ The Open vSwitch plugin provides support for the following VIF types:
|
||||
2.8. These add support for :term:`tc`-based hardware offloads for SR-IOV
|
||||
VFs and offloading of OVS datapath rules using tc, respectively.
|
||||
|
||||
Refer to :ref:`vif-hostdevice` for more information.
|
||||
|
||||
.. versionadded:: 1.5.0
|
||||
|
||||
For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note
|
||||
that only the above VIF types are supported by this plugin.
|
||||
|
||||
__ http://docs.openvswitch.org/en/latest/howto/dpdk/
|
||||
|
||||
@ -2,90 +2,36 @@
|
||||
VIF Types
|
||||
=========
|
||||
|
||||
In os-vif, a VIF type refers to a particular approach for configuring the
|
||||
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.
|
||||
|
||||
|
||||
.. py:module:: os_vif.objects.vif
|
||||
|
||||
VIF objects
|
||||
===========
|
||||
|
||||
Each distinct type of VIF configuration is represented by a versioned object in
|
||||
os-vif, subclassed from `os_vif.objects.VIFBase`. The `VIFBase` class defines
|
||||
some fields that are common to all types of VIF, and provides an association to
|
||||
a versioned object describing the network the VIF is plugged into.
|
||||
Each distinct type of VIF configuration is represented by a versioned object,
|
||||
subclassing :class:`VIFBase`.
|
||||
|
||||
.. _vif-generic:
|
||||
.. autoclass:: VIFBase
|
||||
|
||||
VIFGeneric
|
||||
----------
|
||||
.. autoclass:: VIFGeneric
|
||||
|
||||
This class provides a totally generic type of configuration, where the guest is
|
||||
simply associated with an arbitrary TAP device (or equivalent). The way the
|
||||
TAP device is connected to the host network stack is explicitly left undefined
|
||||
and entirely up to the plugin to decide.
|
||||
.. autoclass:: VIFBridge
|
||||
|
||||
.. _vif-bridge:
|
||||
.. autoclass:: VIFOpenVSwitch
|
||||
|
||||
VIFBridge
|
||||
---------
|
||||
.. autoclass:: VIFDirect
|
||||
|
||||
This class provides a configuration where the guest is connected directly to an
|
||||
explicit host bridge device. This provides ethernet layer bridging, typically
|
||||
to the LAN.
|
||||
.. autoclass:: VIFVHostUser
|
||||
|
||||
.. _vif-openvswitch:
|
||||
.. autoclass:: VIFDirect
|
||||
|
||||
VIFOpenVSwitch
|
||||
--------------
|
||||
.. autoclass:: VIFNestedDPDK
|
||||
|
||||
This class provides a configuration where the guest is connected to an Open
|
||||
vSwitch port.
|
||||
|
||||
.. _vif-direct:
|
||||
|
||||
VIFDirect
|
||||
---------
|
||||
|
||||
This class provides a configuration where the guest is connected to a physical
|
||||
network device. The connection to the device may operate in one of a number of
|
||||
different modes, :term:`VEPA` (either :term:`802.1Qbg` or :term:`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, the
|
||||
`VIFHostDevice` should be used instead.
|
||||
|
||||
.. _vif-vhostuser:
|
||||
|
||||
VIFVHostUser
|
||||
------------
|
||||
|
||||
This class provides another totally generic type of configuration, where the
|
||||
guest is exposing a UNIX socket for its control plane, allowing an external
|
||||
userspace service to provide the backend data plane via a mapped memory region.
|
||||
The process must implement the :term:`virtio-net` vhost protocol on this socket
|
||||
in whatever means is most suitable.
|
||||
|
||||
.. _vif-hostdevice:
|
||||
|
||||
VIFHostDevice
|
||||
-------------
|
||||
|
||||
This class provides a way to pass a physical device to the guest. Either an
|
||||
entire physical device, or an SR-IOV PCI device virtual function, are
|
||||
permitted.
|
||||
|
||||
.. _vif-nesteddpdk:
|
||||
|
||||
VIFNestedDPDK
|
||||
-------------
|
||||
|
||||
This class provides a configuration, where kuryr-kuberentes is used to provide
|
||||
accelerated DPDK datapath for nested Kubernetes pods running inside the VM.
|
||||
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 kuryr-kubernetes CNI plugin.
|
||||
|
||||
VIF port profile objects
|
||||
========================
|
||||
|
||||
@ -22,7 +22,12 @@ from os_vif.objects import fields as osv_fields
|
||||
|
||||
@base.VersionedObjectRegistry.register
|
||||
class VIFBase(osv_base.VersionedObject, base.ComparableVersionedObject):
|
||||
"""Represents a virtual network interface."""
|
||||
"""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.
|
||||
"""
|
||||
|
||||
# Version 1.0: Initial release
|
||||
VERSION = '1.0'
|
||||
@ -60,7 +65,8 @@ class VIFGeneric(VIFBase):
|
||||
"""A generic-style VIF.
|
||||
|
||||
Generic-style VIFs are unbound, floating TUN/TAP devices that should be
|
||||
setup by the plugin, not the hypervisor.
|
||||
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.
|
||||
@ -79,8 +85,9 @@ class VIFGeneric(VIFBase):
|
||||
class VIFBridge(VIFBase):
|
||||
"""A bridge-style VIF.
|
||||
|
||||
Bridge-style VIFs are bound to a linux bridge by the hypervisor. Other
|
||||
devices may be bound to the same L2 virtual bridge.
|
||||
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'.
|
||||
"""
|
||||
@ -130,6 +137,15 @@ class VIFDirect(VIFBase):
|
||||
:class:`~os_vif.objects.vif.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, :term:`VEPA` (either :term:`802.1Qbg` or :term:`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, :class:`~os_vif.objects.vif.VIFHostDevice` should be used
|
||||
instead.
|
||||
|
||||
For libvirt drivers, this maps to type='direct'
|
||||
"""
|
||||
|
||||
@ -155,11 +171,11 @@ class VIFDirect(VIFBase):
|
||||
class VIFVHostUser(VIFBase):
|
||||
"""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 :class:`~os_vif.objects.vif.VIFBridge`, where all packets must be
|
||||
handled by the hypervisor.
|
||||
vhostuser-style VIFs utilize a :term:`userspace vhost <vhost-user>`
|
||||
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 :class:`~os_vif.objects.vif.VIFBridge`,
|
||||
where all packets must be handled by the hypervisor.
|
||||
|
||||
For libvirt drivers, this maps to type='vhostuser'
|
||||
"""
|
||||
@ -190,9 +206,10 @@ class VIFVHostUser(VIFBase):
|
||||
class VIFHostDevice(VIFBase):
|
||||
"""A hostdev-style VIF.
|
||||
|
||||
Hostdev-style VIFs provide a guest with direct access to an SR-IOV Virtual
|
||||
Function (VF). Contrast this with :class:`~ovs_vif.objects.vif.VIFDirect`,
|
||||
which includes a software layer between the VF and the guest.
|
||||
Hostdev-style VIFs provide a guest with direct access to an :term:`SR-IOV`
|
||||
:term:`Virtual Function` (VF) or an entire :term:`Physical Function` (PF).
|
||||
Contrast this with :class:`~ovs_vif.objects.vif.VIFDirect`, which includes
|
||||
a software layer between the interface and the guest.
|
||||
|
||||
For libvirt drivers, this maps to type='hostdev'
|
||||
"""
|
||||
@ -216,9 +233,15 @@ class VIFHostDevice(VIFBase):
|
||||
|
||||
@base.VersionedObjectRegistry.register
|
||||
class VIFNestedDPDK(VIFBase):
|
||||
"""TODO.
|
||||
"""A nested DPDK-style VIF.
|
||||
|
||||
For kuryr-kubernetes nested DPDK interfaces.
|
||||
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.
|
||||
"""
|
||||
|
||||
# Version 1.0: Initial release
|
||||
|
||||
Loading…
Reference in New Issue
Block a user