Initial Modular L2 Mechanism Driver implementation.

Define the Mechanism Driver interface for create/update/delete
operations on networks and ports. For each of these event, the
Mechanism Driver provides one method that is called within the
database transaction of the ml2 plugin method, and one that is called
after the transaction is completed.

Support for mechanism drivers is still a work-in-progress, and the
interface is subject to change in future versions before the release
of Havana. However this initial version should be sufficient to enable
others to start defining their own mechanism drivers.

Change-Id: Ife30215589792ee27df9897d3b2bc04392638266
Implements: blueprint ml2-mechanism-drivers
Fixes: bug #1199977
Fixes: bug #1199978
DocImpact

etc/neutron/plugins/ml2/ml2_conf.ini

@@ -13,6 +13,12 @@
 # tenant_network_types = local
 # Example: tenant_network_types = vlan,gre
 
+# (ListOpt) Ordered list of networking mechanism driver entrypoints
+# to be loaded from the neutron.ml2.mechanism_drivers namespace.
+# mechanism_drivers =
+# Example: mechanism_drivers = arista
+# Example: mechanism_drivers = cisco,logger
+
 [ml2_type_flat]
 # (ListOpt) List of physical_network names with which flat networks
 # can be created. Use * to allow flat networks with arbitrary

neutron/plugins/ml2/README

@@ -31,13 +31,13 @@ openvswitch and linuxbridge plugins' L2 agents, and should also work
 with the hyperv L2 agent. A modular agent may be developed as a
 follow-on effort.
 
-Support for mechanism drivers is currently skeletal. The
-MechanismDriver interface is currently a stub, with details to be
-defined in future versions. MechanismDrivers will be called both
-inside and following DB transactions for network and port
-create/update/delete operations. They will also be called to establish
-a port binding, determining the VIF type and network segment to be
-used.
+Support for mechanism drivers is currently a work-in-progress in
+pre-release Havana versions, and the interface is subject to change
+before the release of Havana. MechanismDrivers are currently called
+both inside and following DB transactions for network and port
+create/update/delete operations. In a future version, they will also
+called to establish a port binding, determining the VIF type and
+network segment to be used.
 
 The database schema and driver APIs support multi-segment networks,
 but the client API for multi-segment networks is not yet implemented.

neutron/plugins/ml2/common/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2013 OpenStack Foundation
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.

neutron/plugins/ml2/common/exceptions.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2013 OpenStack Foundation
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Exceptions used by ML2."""
+
+from neutron.common import exceptions
+
+
+class MechanismDriverError(exceptions.NeutronException):
+    """Mechanism driver call failed."""
+    message = _("%(method)s failed.")

neutron/plugins/ml2/config.py

@@ -29,9 +29,9 @@
                        "networks.")),
     cfg.ListOpt('mechanism_drivers',
                 default=[],
-                help=_("List of networking mechanism driver entrypoints to "
-                       "be loaded from the neutron.ml2.mechanism_drivers "
-                       "namespace.")),
+                help=_("An ordered list of networking mechanism driver "
+                       "entrypoints to be loaded from the "
+                       "neutron.ml2.mechanism_drivers namespace.")),
 ]
 
 

neutron/plugins/ml2/driver_api.py

@@ -13,7 +13,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-from abc import ABCMeta, abstractmethod
+from abc import ABCMeta, abstractmethod, abstractproperty
 
 # The following keys are used in the segment dictionaries passed via
 # the driver API. These are defined separately from similar keys in
@@ -128,15 +128,103 @@ def release_segment(self, session, segment):
         pass
 
 
+class NetworkContext(object):
+    """Context passed to MechanismDrivers for changes to network resources.
+
+    A NetworkContext instance wraps a network resource. It provides
+    helper methods for accessing other relevant information. Results
+    from expensive operations are cached so that other
+    MechanismDrivers can freely access the same information.
+    """
+
+    __metaclass__ = ABCMeta
+
+    @abstractproperty
+    def current(self):
+        """Return the current state of the network.
+
+        Return the current state of the network, as defined by
+        NeutronPluginBaseV2.create_network and all extensions in the
+        ml2 plugin.
+        """
+        pass
+
+    @abstractproperty
+    def original(self):
+        """Return the original state of the network.
+
+        Return the original state of the network, prior to a call to
+        update_network. Method is only valid within calls to
+        update_network_precommit and update_network_postcommit.
+        """
+        pass
+
+    @abstractproperty
+    def network_segments(self):
+        """Return the segments associated with this network resource."""
+        pass
+
+
+class PortContext(object):
+    """Context passed to MechanismDrivers for changes to port resources.
+
+    A PortContext instance wraps a port resource. It provides helper
+    methods for accessing other relevant information. Results from
+    expensive operations are cached so that other MechanismDrivers can
+    freely access the same information.
+    """
+
+    __metaclass__ = ABCMeta
+
+    @abstractproperty
+    def current(self):
+        """Return the current state of the port.
+
+        Return the current state of the port, as defined by
+        NeutronPluginBaseV2.create_port and all extensions in the ml2
+        plugin.
+        """
+        pass
+
+    @abstractproperty
+    def original(self):
+        """Return the original state of the port
+
+        Return the original state of the port, prior to a call to
+        update_port. Method is only valid within calls to
+        update_port_precommit and update_port_postcommit.
+        """
+        pass
+
+    @abstractproperty
+    def network(self):
+        """Return the NetworkContext associated with this port."""
+        pass
+
+
 class MechanismDriver(object):
     """Define stable abstract interface for ML2 mechanism drivers.
 
-    Note that this is currently a stub class, but it is expected to be
-    functional for the H-2 milestone. It currently serves mainly to
-    help solidify the architectural distinction between TypeDrivers
-    and MechanismDrivers.
+    A mechanism driver is called on the creation, update, and deletion
+    of networks and ports. For every event, there are two methods that
+    get called - one within the database transaction (method suffix of
+    _precommit), one right afterwards (method suffix of _postcommit).
+
+    Exceptions raised by methods called inside the transaction can
+    rollback, but should not make any blocking calls (for example,
+    REST requests to an outside controller). Methods called after
+    transaction commits can make blocking external calls, though these
+    will block the entire process. Exceptions raised in calls after
+    the transaction commits may cause the associated resource to be
+    deleted.
+
+    Because rollback outside of the transaction is not done in the
+    update network/port case, all data validation must be done within
+    methods that are part of the database transaction.
     """
 
+    # TODO(apech): add calls for subnets
+
     __metaclass__ = ABCMeta
 
     @abstractmethod
@@ -149,10 +237,177 @@ def initialize(self):
         """
         pass
 
-    # TODO(rkukura): Add methods called inside and after transaction
-    # for create_network, update_network, delete_network, create_port,
-    # update_port, delete_port, and maybe for port binding
-    # changes. Exceptions raised by methods called inside transactions
-    # can rollback, but shouldn't block. Methods called after
-    # transaction commits can block, and exceptions may cause deletion
-    # of resource.
+    def create_network_precommit(self, context):
+        """Allocate resources for a new network.
+
+        :param context: NetworkContext instance describing the new
+        network.
+
+        Create a new network, allocating resources as necessary in the
+        database. Called inside transaction context on session. Call
+        cannot block.  Raising an exception will result in a rollback
+        of the current transaction.
+        """
+        pass
+
+    def create_network_postcommit(self, context):
+        """Create a network.
+
+        :param context: NetworkContext instance describing the new
+        network.
+
+        Called after the transaction commits. Call can block, though
+        will block the entire process so care should be taken to not
+        drastically affect performance. Raising an exception will
+        cause the deletion of the resource.
+        """
+        pass
+
+    def update_network_precommit(self, context):
+        """Update resources of a network.
+
+        :param context: NetworkContext instance describing the new
+        state of the network, as well as the original state prior
+        to the update_network call.
+
+        Update values of a network, updating the associated resources
+        in the database. Called inside transaction context on session.
+        Raising an exception will result in rollback of the
+        transaction.
+
+        update_network_precommit is called for all changes to the
+        network state. It is up to the mechanism driver to ignore
+        state or state changes that it does not know or care about.
+        """
+        pass
+
+    def update_network_postcommit(self, context):
+        """Update a network.
+
+        :param context: NetworkContext instance describing the new
+        state of the network, as well as the original state prior
+        to the update_network call.
+
+        Called after the transaction commits. Call can block, though
+        will block the entire process so care should be taken to not
+        drastically affect performance. Raising an exception will
+        cause the deletion of the resource.
+
+        update_network_postcommit is called for all changes to the
+        network state.  It is up to the mechanism driver to ignore
+        state or state changes that it does not know or care about.
+        """
+        pass
+
+    def delete_network_precommit(self, context):
+        """Delete resources for a network.
+
+        :param context: NetworkContext instance describing the current
+        state of the network, prior to the call to delete it.
+
+        Delete network resources previously allocated by this
+        mechanism driver for a network. Called inside transaction
+        context on session. Runtime errors are not expected, but
+        raising an exception will result in rollback of the
+        transaction.
+        """
+        pass
+
+    def delete_network_postcommit(self, context):
+        """Delete a network.
+
+        :param context: NetworkContext instance describing the current
+        state of the network, prior to the call to delete it.
+
+        Called after the transaction commits. Call can block, though
+        will block the entire process so care should be taken to not
+        drastically affect performance. Runtime errors are not
+        expected, and will not prevent the resource from being
+        deleted.
+        """
+        pass
+
+    def create_port_precommit(self, context):
+        """Allocate resources for a new port.
+
+        :param context: PortContext instance describing the port.
+
+        Create a new port, allocating resources as necessary in the
+        database. Called inside transaction context on session. Call
+        cannot block.  Raising an exception will result in a rollback
+        of the current transaction.
+        """
+        pass
+
+    def create_port_postcommit(self, context):
+        """Create a port.
+
+        :param context: PortContext instance describing the port.
+
+        Called after the transaction completes. Call can block, though
+        will block the entire process so care should be taken to not
+        drastically affect performance.  Raising an exception will
+        result in the deletion of the resource.
+        """
+        pass
+
+    def update_port_precommit(self, context):
+        """Update resources of a port.
+
+        :param context: PortContext instance describing the new
+        state of the port, as well as the original state prior
+        to the update_port call.
+
+        Called inside transaction context on session to complete a
+        port update as defined by this mechanism driver. Raising an
+        exception will result in rollback of the transaction.
+
+        update_port_precommit is called for all changes to the port
+        state. It is up to the mechanism driver to ignore state or
+        state changes that it does not know or care about.
+        """
+        pass
+
+    def update_port_postcommit(self, context):
+        """Update a port.
+
+        :param context: PortContext instance describing the new
+        state of the port, as well as the original state prior
+        to the update_port call.
+
+        Called after the transaction completes. Call can block, though
+        will block the entire process so care should be taken to not
+        drastically affect performance.  Raising an exception will
+        result in the deletion of the resource.
+
+        update_port_postcommit is called for all changes to the port
+        state. It is up to the mechanism driver to ignore state or
+        state changes that it does not know or care about.
+        """
+        pass
+
+    def delete_port_precommit(self, context):
+        """Delete resources of a port.
+
+        :param context: PortContext instance describing the current
+        state of the port, prior to the call to delete it.
+
+        Called inside transaction context on session. Runtime errors
+        are not expected, but raising an exception will result in
+        rollback of the transaction.
+        """
+        pass
+
+    def delete_port_postcommit(self, context):
+        """Delete a port.
+
+        :param context: PortContext instance describing the current
+        state of the port, prior to the call to delete it.
+
+        Called after the transaction completes. Call can block, though
+        will block the entire process so care should be taken to not
+        drastically affect performance.  Runtime errors are not
+        expected, and will not prevent the resource from being
+        deleted.
+        """
+        pass