os-vif: add initial documentation about object model
Start to fill out some content in the docs. This describes the different VIF objects at a high level, and also the host information objects and how they pass info to the network service Change-Id: I3455a756a64a1616c130cc96a8a834d6837aaa38
This commit is contained in:
Daniel P. Berrange
parent
a29ef804b9
commit
447c153b2b
76
doc/source/host_info.rst
Normal file
76
doc/source/host_info.rst
Normal file
@ -0,0 +1,76 @@
|
||||
================
|
||||
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.
|
||||
@ -6,6 +6,9 @@ Contents:
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
vif_types
|
||||
host_info
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
|
||||
109
doc/source/vif_types.rst
Normal file
109
doc/source/vif_types.rst
Normal file
@ -0,0 +1,109 @@
|
||||
===========
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
VIFBridge
|
||||
---------
|
||||
|
||||
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.
|
||||
|
||||
VIFOpenVSwitch
|
||||
--------------
|
||||
|
||||
This class provides a configuration where the guest is connected to
|
||||
an openvswitch port.
|
||||
|
||||
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, VEPA (either 802.1qbg
|
||||
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 conf. For passthrough of network devices
|
||||
without MAC/vlan configuration, the VIFHostDevice should be used
|
||||
instead.
|
||||
|
||||
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
|
||||
virtio-net vhost protocol on this socket in whatever means is most
|
||||
suitable.
|
||||
|
||||
VIFHostDevice
|
||||
-------------
|
||||
|
||||
This class provides a way to pass a physical device to the guest.
|
||||
Either an entire physical device, or a SR-IOV PCI device virtual
|
||||
function, are permitted.
|
||||
|
||||
|
||||
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 wtih a versioned
|
||||
object, subclassing VIFPortProfileBase
|
||||
|
||||
VIFPortProfileOpenVSwitch
|
||||
-------------------------
|
||||
|
||||
This profile provides the metadata required to associate a VIF
|
||||
with an openvswitch host port.
|
||||
|
||||
VIFPortProfile8021Qbg
|
||||
---------------------
|
||||
|
||||
This profile provides the metadata required to associate a VIF
|
||||
with a VEPA host device supporting the 801.1Qbg spec.
|
||||
|
||||
VIFPortProfile8021Qbh
|
||||
---------------------
|
||||
|
||||
This profile provides the metadata required to associate a VIF
|
||||
with a VEPA host device supporting the 801.1Qbg spec.
|
||||
|
||||
|
||||
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
|
||||
|
||||
TODO :-(
|
||||
Loading…
Reference in New Issue
Block a user