From 447c153b2b045ce8c62ea4d803e8829aa3d1e268 Mon Sep 17 00:00:00 2001 From: "Daniel P. Berrange" Date: Wed, 2 Mar 2016 11:44:54 +0000 Subject: [PATCH] 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 --- doc/source/host_info.rst | 76 +++++++++++++++++++++++++++ doc/source/index.rst | 3 ++ doc/source/vif_types.rst | 109 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 188 insertions(+) create mode 100644 doc/source/host_info.rst create mode 100644 doc/source/vif_types.rst diff --git a/doc/source/host_info.rst b/doc/source/host_info.rst new file mode 100644 index 00000000..74e37a3b --- /dev/null +++ b/doc/source/host_info.rst @@ -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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 30237722..be6bc740 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,6 +6,9 @@ Contents: .. toctree:: :maxdepth: 2 + vif_types + host_info + Indices and tables ================== diff --git a/doc/source/vif_types.rst b/doc/source/vif_types.rst new file mode 100644 index 00000000..180d8cb7 --- /dev/null +++ b/doc/source/vif_types.rst @@ -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 :-(