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

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