--- /dev/null
+Neutron Northbound
+==================
+
+How to add new API support
+--------------------------
+
+OpenStack Neutron is a moving target. It is continuously adding new
+features as new rest APIs. Here is a basic step to add new API support:
+
+In the Neutron Northbound project:
+
+- Add new YANG model for it under ``neutron/model/src/main/yang`` and
+ ``update neutron.yang``
+
+- Add northbound API for it, and neutron-spi
+
+ - Implement ``Neutron<New API>Request.java`` and
+ ``Neutron<New API>Norhtbound.java`` under
+ ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/``
+
+ - Implement ``INeutron<New API>CRUD.java`` and new data structure if
+ any under
+ ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/``
+
+ - update
+ ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/NeutronCRUDInterfaces.java``
+ to wire new CRUD interface
+
+ - Add unit tests, ``Neutron<New structure>JAXBTest.java`` under
+ ``neutron/neutron-spi/src/test/java/org/opendaylight/neutron/spi/``
+
+- update
+ ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/NeutronNorthboundRSApplication.java``
+ to wire new northbound api to ``RSApplication``
+
+- Add transcriber, ``Neutron<New API>Interface.java`` under
+ ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/``
+
+- update
+ ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/NeutronTranscriberProvider.java``
+ to wire a new transcriber
+
+ - Add integration tests ``Neutron<New API>Tests.java`` under
+ ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/``
+
+ - update
+ ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/ITNeutronE2E.java``
+ to run a newly added tests.
+
+In OpenStack networking-odl
+
+- Add new driver (or plugin) for new API with tests.
+
+In a southbound Neutron Provider
+
+- implement actual backend to realize those new API by listening
+ related YANG models.
+
+How to write transcriber
+------------------------
+
+For each Neutron data object, there is an ``Neutron*Interface`` defined
+within the transcriber artifact that will write that object to the
+MD-SAL configuration datastore.
+
+All ``Neutron*Interface`` extend ``AbstractNeutronInterface``, in which
+two methods are defined:
+
+- one takes the Neutron object as input, and will create a data object
+ from it.
+
+- one takes an uuid as input, and will create a data object containing
+ the uuid.
+
+::
+
+ protected abstract T toMd(S neutronObject);
+ protected abstract T toMd(String uuid);
+
+In addition the ``AbstractNeutronInterface`` class provides several
+other helper methods (``addMd``, ``updateMd``, ``removeMd``), which
+handle the actual writing to the configuration datastore.
+
+The semantics of the ``toMD()`` methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each of the Neutron YANG models defines structures containing data.
+Further each YANG-modeled structure has it own builder. A particular
+``toMD()`` method instantiates an instance of the correct builder, fills
+in the properties of the builder from the corresponding values of the
+Neutron object and then creates the YANG-modeled structures via the
+``build()`` method.
+
+As an example, one of the ``toMD`` code for Neutron Networks is
+presented below:
+
+::
+
+ protected Network toMd(NeutronNetwork network) {
+ NetworkBuilder networkBuilder = new NetworkBuilder();
+ networkBuilder.setAdminStateUp(network.getAdminStateUp());
+ if (network.getNetworkName() != null) {
+ networkBuilder.setName(network.getNetworkName());
+ }
+ if (network.getShared() != null) {
+ networkBuilder.setShared(network.getShared());
+ }
+ if (network.getStatus() != null) {
+ networkBuilder.setStatus(network.getStatus());
+ }
+ if (network.getSubnets() != null) {
+ List<Uuid> subnets = new ArrayList<Uuid>();
+ for( String subnet : network.getSubnets()) {
+ subnets.add(toUuid(subnet));
+ }
+ networkBuilder.setSubnets(subnets);
+ }
+ if (network.getTenantID() != null) {
+ networkBuilder.setTenantId(toUuid(network.getTenantID()));
+ }
+ if (network.getNetworkUUID() != null) {
+ networkBuilder.setUuid(toUuid(network.getNetworkUUID()));
+ } else {
+ logger.warn("Attempting to write neutron network without UUID");
+ }
+ return networkBuilder.build();
+ }
+
--- /dev/null
+Neutron Service Developer Guide
+===============================
+
+Overview
+--------
+
+This Karaf feature (``odl-neutron-service``) provides integration
+support for OpenStack Neutron via the OpenDaylight ML2 mechanism driver.
+The Neutron Service is only one of the components necessary for
+OpenStack integration. It defines YANG models for OpenStack Neutron data
+models and northbound API via REST API and YANG model RESTCONF.
+
+Those developers who want to add new provider for new OpenStack Neutron
+extensions/services (Neutron constantly adds new extensions/services and
+OpenDaylight will keep up with those new things) need to communicate
+with this Neutron Service or add models to Neutron Service. If you want
+to add new extensions/services themselves to the Neutron Service, new
+YANG data models need to be added, but that is out of scope of this
+document because this guide is for a developer who will be *using* the
+feature to build something separate, but *not* somebody who will be
+developing code for this feature itself.
+
+Neutron Service Architecture
+----------------------------
+
+.. figure:: ./images/neutron/odl-neutron-service-developer-architecture.png
+ :alt: Neutron Service Architecture
+
+ Neutron Service Architecture
+
+The Neutron Service defines YANG models for OpenStack Neutron
+integration. When OpenStack admins/users request changes
+(creation/update/deletion) of Neutron resources, e.g., Neutron network,
+Neutron subnet, Neutron port, the corresponding YANG model within
+OpenDaylight will be modified. The OpenDaylight OpenStack will subscribe
+the changes on those models and will be notified those modification
+through MD-SAL when changes are made. Then the provider will do the
+necessary tasks to realize OpenStack integration. How to realize it (or
+even not realize it) is up to each provider. The Neutron Service itself
+does not take care of it.
+
+How to Write a SB Neutron Consumer
+----------------------------------
+
+In Boron, there is only one options for SB Neutron Consumers:
+
+- Listening for changes via the Neutron YANG model
+
+Until Beryllium there was another way with the legacy I\*Aware
+interface. From Boron, the interface was eliminated. So all the SB
+Neutron Consumers have to use Neutron YANG model.
+
+Neutron YANG models
+-------------------
+
+Neutron service defines YANG models for Neutron. The details can be
+found at
+
+- https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=tree;f=model/src/main/yang;hb=refs/heads/stable/boron
+
+Basically those models are based on OpenStack Neutron API definitions.
+For exact definitions, OpenStack Neutron source code needs to be
+referred as the above documentation doesn’t always cover the necessary
+details. There is nothing special to utilize those Neutron YANG models.
+The basic procedure will be:
+
+1. subscribe for changes made to the the model
+
+2. respond on the data change notification for each models
+
+.. note::
+
+ Currently there is no way to refuse the request configuration at
+ this point. That is left to future work.
+
+.. code:: java
+
+ public class NeutronNetworkChangeListener implements DataChangeListener, AutoCloseable {
+ private ListenerRegistration<DataChangeListener> registration;
+ private DataBroker db;
+
+ public NeutronNetworkChangeListener(DataBroker db){
+ this.db = db;
+ // create identity path to register on service startup
+ InstanceIdentifier<Network> path = InstanceIdentifier
+ .create(Neutron.class)
+ .child(Networks.class)
+ .child(Network.class);
+ LOG.debug("Register listener for Neutron Network model data changes");
+ // register for Data Change Notification
+ registration =
+ this.db.registerDataChangeListener(LogicalDatastoreType.CONFIGURATION, path, this, DataChangeScope.ONE);
+
+ }
+
+ @Override
+ public void onDataChanged(
+ AsyncDataChangeEvent<InstanceIdentifier<?>, DataObject> changes) {
+ LOG.trace("Data changes : {}",changes);
+
+ // handle data change notification
+ Object[] subscribers = NeutronIAwareUtil.getInstances(INeutronNetworkAware.class, this);
+ createNetwork(changes, subscribers);
+ updateNetwork(changes, subscribers);
+ deleteNetwork(changes, subscribers);
+ }
+ }
+
+Neutron configuration
+---------------------
+
+From Boron, new models of configuration for OpenDaylight to tell
+OpenStack neutron/networking-odl its configuration/capability.
+
+hostconfig
+~~~~~~~~~~
+
+This is for OpenDaylight to tell per-node configuration to Neutron.
+Especially this is used by pseudo agent port binding heavily.
+
+The model definition can be found at
+
+- https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-hostconfig.yang;hb=refs/heads/stable/boron
+
+How to populate this for pseudo agent port binding is documented at
+
+- http://git.openstack.org/cgit/openstack/networking-odl/tree/doc/source/devref/hostconfig.rst
+
+Neutron extension config
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Boron this is experimental. The model definition can be found at
+
+- https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-extensions.yang;hb=refs/heads/stable/boron
+
+Each Neutron Service provider has its own feature set. Some support the
+full features of OpenStack, but others support only a subset. With same
+supported Neutron API, some functionality may or may not be supported.
+So there is a need for a way that OpenDaylight can tell networking-odl
+its capability. Thus networking-odl can initialize Neutron properly
+based on reported capability.
+
+Neutorn Logger
+--------------
+
+There is another small Karaf feature, ``odl-neutron-logger``, which logs
+changes of Neutron YANG models. which can be used for debug/audit.
+
+It would also help to understand how to listen the change.
+
+- 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
+
+API Reference Documentation
+---------------------------
+
+The OpenStack Neutron API references
+
+- http://developer.openstack.org/api-ref-networking-v2.html
+
+- http://developer.openstack.org/api-ref-networking-v2-ext.html
+
== Neutron Northbound
-=== How to add new API support
-OpenStack Neutron is a moving target. It is continuously adding new features
-as new rest APIs. Here is a basic step to add new API support:
-
-In the Neutron Northbound project:
-
-* Add new YANG model for it under `neutron/model/src/main/yang` and
- `update neutron.yang`
-* Add northbound API for it, and neutron-spi
-** Implement `Neutron<New API>Request.java` and `Neutron<New API>Norhtbound.java`
- under
- `neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/`
-** Implement `INeutron<New API>CRUD.java` and new data structure if any under
- `neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/`
-** update
- `neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/NeutronCRUDInterfaces.java`
- to wire new CRUD interface
-** Add unit tests, `Neutron<New structure>JAXBTest.java` under
- `neutron/neutron-spi/src/test/java/org/opendaylight/neutron/spi/`
-* update
- `neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/NeutronNorthboundRSApplication.java`
- to wire new northbound api to `RSApplication`
-* Add transcriber, `Neutron<New API>Interface.java` under
- `transcriber/src/main/java/org/opendaylight/neutron/transcriber/`
-* update
- `transcriber/src/main/java/org/opendaylight/neutron/transcriber/NeutronTranscriberProvider.java`
- to wire a new transcriber
-** Add integration tests `Neutron<New API>Tests.java`
- under `integration/test/src/test/java/org/opendaylight/neutron/e2etest/`
-** update `integration/test/src/test/java/org/opendaylight/neutron/e2etest/ITNeutronE2E.java`
- to run a newly added tests.
-
-In OpenStack networking-odl
-
-* Add new driver (or plugin) for new API with tests.
-
-In a southbound Neutron Provider
-
-* implement actual backend to realize those new API by listening related YANG
- models.
-
-
-=== How to write transcriber
-
-For each Neutron data object, there is an `Neutron*Interface` defined within
-the transcriber artifact that will write that object to the MD-SAL
-configuration datastore.
-
-All `Neutron*Interface` extend `AbstractNeutronInterface`, in which two methods
-are defined:
-
-* one takes the Neutron object as input, and will create a data object from it.
-* one takes an uuid as input, and will create a data object containing the uuid.
-
-----
-protected abstract T toMd(S neutronObject);
-protected abstract T toMd(String uuid);
-----
-
-In addition the `AbstractNeutronInterface` class provides several other
-helper methods (`addMd`, `updateMd`, `removeMd`), which handle the actual
-writing to the configuration datastore.
-
-==== The semantics of the `toMD()` methods
-Each of the Neutron YANG models defines structures containing data.
-Further each YANG-modeled structure has it own builder.
-A particular `toMD()` method instantiates an instance of the correct
-builder, fills in the properties of the builder from the corresponding
-values of the Neutron object and then creates the YANG-modeled structures
-via the `build()` method.
-
-As an example, one of the `toMD` code for Neutron Networks is
-presented below:
-
-----
-protected Network toMd(NeutronNetwork network) {
- NetworkBuilder networkBuilder = new NetworkBuilder();
- networkBuilder.setAdminStateUp(network.getAdminStateUp());
- if (network.getNetworkName() != null) {
- networkBuilder.setName(network.getNetworkName());
- }
- if (network.getShared() != null) {
- networkBuilder.setShared(network.getShared());
- }
- if (network.getStatus() != null) {
- networkBuilder.setStatus(network.getStatus());
- }
- if (network.getSubnets() != null) {
- List<Uuid> subnets = new ArrayList<Uuid>();
- for( String subnet : network.getSubnets()) {
- subnets.add(toUuid(subnet));
- }
- networkBuilder.setSubnets(subnets);
- }
- if (network.getTenantID() != null) {
- networkBuilder.setTenantId(toUuid(network.getTenantID()));
- }
- if (network.getNetworkUUID() != null) {
- networkBuilder.setUuid(toUuid(network.getNetworkUUID()));
- } else {
- logger.warn("Attempting to write neutron network without UUID");
- }
- return networkBuilder.build();
-}
-----
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/neutron-northbound.html
== Neutron Service Developer Guide
-=== Overview
-This Karaf feature (`odl-neutron-service`) provides integration support for OpenStack Neutron
-via the OpenDaylight ML2 mechanism driver. The Neutron Service is only one of the
-components necessary for OpenStack integration.
-It defines YANG models for OpenStack Neutron data models and northbound
-API via REST API and YANG model RESTCONF.
-
-Those developers who want to add new provider for new OpenStack Neutron
-extensions/services (Neutron constantly adds new extensions/services and OpenDaylight
-will keep up with those new things) need to communicate with this Neutron
-Service or add models to Neutron Service.
-If you want to add new extensions/services themselves to the Neutron Service,
-new YANG data models need to be added, but that is out of scope of this document
-because this guide is for a developer who will be _using_ the feature
-to build something separate, but _not_ somebody who will be developing
-code for this feature itself.
-
-=== Neutron Service Architecture
-image::neutron/odl-neutron-service-developer-architecture.png[height="450px", width="550px", title="Neutron Service Architecture"]
-// image original: https://docs.google.com/drawings/d/15xtroJahSFt93K10Zp8AVln_WZgowmhv7MC_2VdZQzg/edit?usp=sharing
-
-The Neutron Service defines YANG models for OpenStack Neutron integration.
-When OpenStack admins/users request changes (creation/update/deletion)
-of Neutron resources, e.g., Neutron network, Neutron subnet, Neutron port, the corresponding YANG model within OpenDaylight will be modified.
-The OpenDaylight OpenStack will subscribe the changes on those models and
-will be notified those modification through MD-SAL when changes are made.
-Then the provider will do the necessary tasks to realize OpenStack integration.
-How to realize it (or even not realize it) is up to each provider.
-The Neutron Service itself does not take care of it.
-
-=== How to Write a SB Neutron Consumer
-In Boron, there is only one options for SB Neutron Consumers:
-
-* Listening for changes via the Neutron YANG model
-
-Until Beryllium there was another way with the legacy I*Aware interface.
-From Boron, the interface was eliminated. So all the SB Neutron Consumers
-have to use Neutron YANG model.
-
-
-=== Neutron YANG models
-Neutron service defines YANG models for Neutron. The details can be found
-at
-
-* https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=tree;f=model/src/main/yang;hb=refs/heads/stable/boron
-
-Basically those models are based on OpenStack Neutron API definitions.
-For exact definitions, OpenStack Neutron source code needs to be referred
-as the above documentation doesn't always cover the necessary details.
-There is nothing special to utilize those Neutron YANG models.
-The basic procedure will be:
-
-. subscribe for changes made to the the model
-. respond on the data change notification for each models
-
-[NOTE]
-Currently there is no way to refuse the request configuration at this
-point. That is left to future work.
-
-[source,java]
-----
-public class NeutronNetworkChangeListener implements DataChangeListener, AutoCloseable {
- private ListenerRegistration<DataChangeListener> registration;
- private DataBroker db;
-
- public NeutronNetworkChangeListener(DataBroker db){
- this.db = db;
- // create identity path to register on service startup
- InstanceIdentifier<Network> path = InstanceIdentifier
- .create(Neutron.class)
- .child(Networks.class)
- .child(Network.class);
- LOG.debug("Register listener for Neutron Network model data changes");
- // register for Data Change Notification
- registration =
- this.db.registerDataChangeListener(LogicalDatastoreType.CONFIGURATION, path, this, DataChangeScope.ONE);
-
- }
-
- @Override
- public void onDataChanged(
- AsyncDataChangeEvent<InstanceIdentifier<?>, DataObject> changes) {
- LOG.trace("Data changes : {}",changes);
-
- // handle data change notification
- Object[] subscribers = NeutronIAwareUtil.getInstances(INeutronNetworkAware.class, this);
- createNetwork(changes, subscribers);
- updateNetwork(changes, subscribers);
- deleteNetwork(changes, subscribers);
- }
-}
-----
-
-=== Neutron configuration
-From Boron, new models of configuration for OpenDaylight to tell
-OpenStack neutron/networking-odl its configuration/capability.
-
-==== hostconfig
-This is for OpenDaylight to tell per-node configuration to Neutron.
-Especially this is used by pseudo agent port binding heavily.
-
-The model definition can be found at
-
-* https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-hostconfig.yang;hb=refs/heads/stable/boron
-
-How to populate this for pseudo agent port binding is documented at
-
-* http://git.openstack.org/cgit/openstack/networking-odl/tree/doc/source/devref/hostconfig.rst
-
-==== Neutron extension config
-In Boron this is experimental.
-The model definition can be found at
-
-* https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-extensions.yang;hb=refs/heads/stable/boron
-
-Each Neutron Service provider has its own feature set. Some support
-the full features of OpenStack, but others support only a subset.
-With same supported Neutron API, some functionality may or may not be
-supported. So there is a need for a way that OpenDaylight can tell networking-odl its
-capability. Thus networking-odl can initialize Neutron properly based
-on reported capability.
-
-
-=== Neutorn Logger
-There is another small Karaf feature, `odl-neutron-logger`, which logs changes of Neutron
-YANG models. which can be used for debug/audit.
-
-It would also help to understand how to listen the change.
-
-* 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
-
-
-=== API Reference Documentation
-The OpenStack Neutron API references
-
-* http://developer.openstack.org/api-ref-networking-v2.html
-* http://developer.openstack.org/api-ref-networking-v2-ext.html
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/neutron-service-developer-guide.html
Code Review / docs.git / commitdiff
