os-vif/README.rst
Daniel P. Berrange 72d5dfbf48 Provide plugins an oslo_config group for their setup
The plugin implementations need to be isolated from the
entity that is using os-vif. Plugins should be allowed
to define their own custom config parameters, without
needing the user of os-vif to pass further options into
the os_vif.initialize() method.

This change introduces a CONFIG_OPTS attribute on the
Plugin class. This provides a list of oslo_config
options that are to be used by the plugin. os_vif will
register these options into a group 'os_vif_$PLUGIN'
eg 'os_vif_linux_bridge'.

This gives the plugin impls the ability to have config
options in the main project conf (ie /etc/nova/nova.conf)
without exposing them directly to all of nova's own
config options.

Change-Id: I9634b474cd0d3fda09aef5800020c9415c28e3d8
2016-02-16 11:06:58 +00:00

71 lines
2.3 KiB
ReStructuredText

======
os-vif
======
A library for plugging and unplugging virtual interfaces in OpenStack.
Features
--------
* A base VIF plugin class that supplies a plug() and unplug() interface
* Versioned objects that represent a virtual interface and its components
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 a single
argument of type `os_vif.objects.VIF`::
import uuid
from nova import objects as nova_objects
from os_vif import exception as vif_exc
from os_vif import objects as vif_objects
from os_vif import vnic_types
instance_uuid = 'd7a730ca-3c28-49c3-8f26-4662b909fe8a'
instance = nova_objects.Instance.get_by_uuid(instance_uuid)
instance_info = vif_objects.InstanceInfo(
uuid=instance.uuid,
name=instance.name,
project_id=instance.project_id)
subnet = vif_objects.Subnet(cidr='192.168.1.0/24')
subnets = vif_objects.SubnetList([subnet])
network = vif_objects.Network(label='tenantnet',
subnets=subnets,
multi_host=False,
should_provide_vlan=False,
should_provide_bridge=False)
vif_uuid = uuid.uuid4()
vif = vif_objects.VIFVHostUser(id=vif_uuid,
address=None,
network=network,
plugin='vhostuser',
path='/path/to/socket',
mode=vif_objects.fields.VIFVHostUserMode.SERVER)
# Now do the actual plug operations to connect the VIF to
# the backing network interface.
try:
os_vif.plug(vif)
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)
except vif_exc.UnplugException as err:
# Handle the failure...