docs/developer-guide/neutron-service-developer-guide.rst

   1 Neutron Service Developer Guide
   2 ===============================
   3
   4 Overview
   5 --------
   6
   7 This Karaf feature (``odl-neutron-service``) provides integration
   8 support for OpenStack Neutron via the OpenDaylight ML2 mechanism driver.
   9 The Neutron Service is only one of the components necessary for
  10 OpenStack integration. It defines YANG models for OpenStack Neutron data
  11 models and northbound API via REST API and YANG model RESTCONF.
  12
  13 Those developers who want to add new provider for new OpenStack Neutron
  14 extensions/services (Neutron constantly adds new extensions/services and
  15 OpenDaylight will keep up with those new things) need to communicate
  16 with this Neutron Service or add models to Neutron Service. If you want
  17 to add new extensions/services themselves to the Neutron Service, new
  18 YANG data models need to be added, but that is out of scope of this
  19 document because this guide is for a developer who will be *using* the
  20 feature to build something separate, but *not* somebody who will be
  21 developing code for this feature itself.
  22
  23 Neutron Service Architecture
  24 ----------------------------
  25
  26 .. figure:: ./images/neutron/odl-neutron-service-developer-architecture.png
  27    :alt: Neutron Service Architecture
  28
  29    Neutron Service Architecture
  30
  31 The Neutron Service defines YANG models for OpenStack Neutron
  32 integration. When OpenStack admins/users request changes
  33 (creation/update/deletion) of Neutron resources, e.g., Neutron network,
  34 Neutron subnet, Neutron port, the corresponding YANG model within
  35 OpenDaylight will be modified. The OpenDaylight OpenStack will subscribe
  36 the changes on those models and will be notified those modification
  37 through MD-SAL when changes are made. Then the provider will do the
  38 necessary tasks to realize OpenStack integration. How to realize it (or
  39 even not realize it) is up to each provider. The Neutron Service itself
  40 does not take care of it.
  41
  42 How to Write a SB Neutron Consumer
  43 ----------------------------------
  44
  45 In Boron, there is only one options for SB Neutron Consumers:
  46
  47 -  Listening for changes via the Neutron YANG model
  48
  49 Until Beryllium there was another way with the legacy I\*Aware
  50 interface. From Boron, the interface was eliminated. So all the SB
  51 Neutron Consumers have to use Neutron YANG model.
  52
  53 Neutron YANG models
  54 -------------------
  55
  56 Neutron service defines YANG models for Neutron. The details can be
  57 found at
  58
  59 -  https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=tree;f=model/src/main/yang;hb=refs/heads/stable/boron
  60
  61 Basically those models are based on OpenStack Neutron API definitions.
  62 For exact definitions, OpenStack Neutron source code needs to be
  63 referred as the above documentation doesn’t always cover the necessary
  64 details. There is nothing special to utilize those Neutron YANG models.
  65 The basic procedure will be:
  66
  67 1. subscribe for changes made to the the model
  68
  69 2. respond on the data change notification for each models
  70
  71 .. note::
  72
  73     Currently there is no way to refuse the request configuration at
  74     this point. That is left to future work.
  75
  76 .. code:: java
  77
  78     public class NeutronNetworkChangeListener implements DataChangeListener, AutoCloseable {
  79         private ListenerRegistration<DataChangeListener> registration;
  80         private DataBroker db;
  81
  82         public NeutronNetworkChangeListener(DataBroker db){
  83             this.db = db;
  84             // create identity path to register on service startup
  85             InstanceIdentifier<Network> path = InstanceIdentifier
  86                     .create(Neutron.class)
  87                     .child(Networks.class)
  88                     .child(Network.class);
  89             LOG.debug("Register listener for Neutron Network model data changes");
  90             // register for Data Change Notification
  91             registration =
  92                     this.db.registerDataChangeListener(LogicalDatastoreType.CONFIGURATION, path, this, DataChangeScope.ONE);
  93
  94         }
  95
  96         @Override
  97         public void onDataChanged(
  98                 AsyncDataChangeEvent<InstanceIdentifier<?>, DataObject> changes) {
  99             LOG.trace("Data changes : {}",changes);
 100
 101             // handle data change notification
 102             Object[] subscribers = NeutronIAwareUtil.getInstances(INeutronNetworkAware.class, this);
 103             createNetwork(changes, subscribers);
 104             updateNetwork(changes, subscribers);
 105             deleteNetwork(changes, subscribers);
 106         }
 107     }
 108
 109 Neutron configuration
 110 ---------------------
 111
 112 From Boron, new models of configuration for OpenDaylight to tell
 113 OpenStack neutron/networking-odl its configuration/capability.
 114
 115 hostconfig
 116 ~~~~~~~~~~
 117
 118 This is for OpenDaylight to tell per-node configuration to Neutron.
 119 Especially this is used by pseudo agent port binding heavily.
 120
 121 The model definition can be found at
 122
 123 -  https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-hostconfig.yang;hb=refs/heads/stable/boron
 124
 125 How to populate this for pseudo agent port binding is documented at
 126
 127 -  http://git.openstack.org/cgit/openstack/networking-odl/tree/doc/source/devref/hostconfig.rst
 128
 129 Neutron extension config
 130 ~~~~~~~~~~~~~~~~~~~~~~~~
 131
 132 In Boron this is experimental. The model definition can be found at
 133
 134 -  https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-extensions.yang;hb=refs/heads/stable/boron
 135
 136 Each Neutron Service provider has its own feature set. Some support the
 137 full features of OpenStack, but others support only a subset. With same
 138 supported Neutron API, some functionality may or may not be supported.
 139 So there is a need for a way that OpenDaylight can tell networking-odl
 140 its capability. Thus networking-odl can initialize Neutron properly
 141 based on reported capability.
 142
 143 Neutorn Logger
 144 --------------
 145
 146 There is another small Karaf feature, ``odl-neutron-logger``, which logs
 147 changes of Neutron YANG models. which can be used for debug/audit.
 148
 149 It would also help to understand how to listen the change.
 150
 151 -  https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=neutron-logger/src/main/java/org/opendaylight/neutron/logger/NeutronLogger.java;hb=refs/heads/stable/boron
 152
 153 API Reference Documentation
 154 ---------------------------
 155
 156 The OpenStack Neutron API references
 157
 158 -  http://developer.openstack.org/api-ref-networking-v2.html
 159
 160 -  http://developer.openstack.org/api-ref-networking-v2-ext.html
 161