manuals/developer-guide/src/main/asciidoc/neutron/odl-neutron-service-dev.adoc

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