docs/developer-guides/neutron-northbound.rst

   1 .. _neutron-northbound-developer-guide:
   2
   3 Neutron Northbound
   4 ==================
   5
   6 How to add new API support
   7 --------------------------
   8
   9 OpenStack Neutron is a moving target. It is continuously adding new
  10 features as new rest APIs. Here is a basic step to add new API support:
  11
  12 In the Neutron Northbound project:
  13
  14 -  Add new YANG model for it under ``neutron/model/src/main/yang`` and
  15    ``update neutron.yang``
  16
  17 -  Add northbound API for it, and ``neutron-spi``
  18
  19    -  Implement ``Neutron<New API>Request.java`` and
  20       ``Neutron<New API>Norhtbound.java`` under
  21       ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/``
  22
  23    -  Implement ``INeutron<New API>CRUD.java`` and new data structure if
  24       any under
  25       ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/``
  26
  27    -  update
  28       ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/NeutronCRUDInterfaces.java``
  29       to wire new CRUD interface
  30
  31    -  Add unit tests, ``Neutron<New structure>JAXBTest.java`` under
  32       ``neutron/neutron-spi/src/test/java/org/opendaylight/neutron/spi/``
  33
  34 -  update
  35    ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/NeutronNorthboundRSApplication.java``
  36    to wire new northbound API to ``RSApplication``
  37
  38 -  Add transcriber, ``Neutron<New API>Interface.java`` under
  39    ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/``
  40
  41 -  update
  42    ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/NeutronTranscriberProvider.java``
  43    to wire a new transcriber
  44
  45    -  Add integration tests ``Neutron<New API>Tests.java`` under
  46       ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/``
  47
  48    -  update
  49       ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/ITNeutronE2E.java``
  50       to run a newly added tests.
  51
  52 In OpenStack ``networking-odl``
  53
  54 -  Add new driver (or plugin) for new API with tests.
  55
  56 In a southbound Neutron Provider
  57
  58 -  implement actual back-end to realize those new API by listening
  59    related YANG models.
  60
  61 How to write transcriber
  62 ------------------------
  63
  64 For each Neutron data object, there is an ``Neutron*Interface`` defined
  65 within the transcriber artifact that will write that object to the
  66 MD-SAL configuration datastore.
  67
  68 All ``Neutron*Interface`` extend ``AbstractNeutronInterface``, in which
  69 two methods are defined:
  70
  71 -  one takes the Neutron object as input, and will create a data object
  72    from it.
  73
  74 -  one takes an uuid as input, and will create a data object containing
  75    the uuid.
  76
  77 ::
  78
  79     protected abstract T toMd(S neutronObject);
  80     protected abstract T toMd(String uuid);
  81
  82 In addition the ``AbstractNeutronInterface`` class provides several
  83 other helper methods (``addMd``, ``updateMd``, ``removeMd``), which
  84 handle the actual writing to the configuration datastore.
  85
  86 The semantics of the ``toMD()`` methods
  87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  88
  89 Each of the Neutron YANG models defines structures containing data.
  90 Further each YANG-modeled structure has it own builder. A particular
  91 ``toMD()`` method instantiates an instance of the correct builder, fills
  92 in the properties of the builder from the corresponding values of the
  93 Neutron object and then creates the YANG-modeled structures via the
  94 ``build()`` method.
  95
  96 As an example, one of the ``toMD`` code for Neutron Networks is
  97 presented below:
  98
  99 ::
 100
 101     protected Network toMd(NeutronNetwork network) {
 102         NetworkBuilder networkBuilder = new NetworkBuilder();
 103         networkBuilder.setAdminStateUp(network.getAdminStateUp());
 104         if (network.getNetworkName() != null) {
 105             networkBuilder.setName(network.getNetworkName());
 106         }
 107         if (network.getShared() != null) {
 108             networkBuilder.setShared(network.getShared());
 109         }
 110         if (network.getStatus() != null) {
 111             networkBuilder.setStatus(network.getStatus());
 112         }
 113         if (network.getSubnets() != null) {
 114             List<Uuid> subnets = new ArrayList<Uuid>();
 115             for( String subnet : network.getSubnets()) {
 116                 subnets.add(toUuid(subnet));
 117             }
 118             networkBuilder.setSubnets(subnets);
 119         }
 120         if (network.getTenantID() != null) {
 121             networkBuilder.setTenantId(toUuid(network.getTenantID()));
 122         }
 123         if (network.getNetworkUUID() != null) {
 124             networkBuilder.setUuid(toUuid(network.getNetworkUUID()));
 125         } else {
 126             logger.warn("Attempting to write neutron network without UUID");
 127         }
 128         return networkBuilder.build();
 129     }
 130