manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-config-subsystem.adoc

   1 === Description of OpenFlow Plugin Modules
   2
   3 The OpenFlow plugin project contains a variety of OpenDaylight modules,
   4 which are loaded using the configuration subsystem. This section
   5 describes the YANG files used to model each module.
   6
   7 *General model (interfaces)* - openflow-plugin-cfg.yang.
   8
   9 * the provided module is defined (`identity openflow-provider`)
  10 * and target implementation is assigned (`...OpenflowPluginProvider`)
  11
  12 [source,yang]
  13 ----
  14 module openflow-provider {
  15    yang-version 1;
  16    namespace "urn:opendaylight:params:xml:ns:yang:openflow:common:config[urn:opendaylight:params:xml:ns:yang:openflow:common:config]";
  17    prefix "ofplugin-cfg";
  18
  19    import config {prefix config; revision-date 2013-04-05; }
  20    description
  21        "openflow-plugin-custom-config";
  22    revision "2014-03-26" {
  23        description
  24            "Initial revision";
  25    }
  26    identity openflow-provider{
  27        base config:service-type;
  28        config:java-class "org.opendaylight.openflowplugin.openflow.md.core.sal.OpenflowPluginProvider";
  29    }
  30 }
  31 ----
  32
  33 *Implementation model* - openflow-plugin-cfg-impl.yang
  34
  35 * the implementation of module is defined
  36 (`identity openflow-provider-impl`)
  37 ** class name of generated implementation is defined
  38 (ConfigurableOpenFlowProvider)
  39 * via augmentation the configuration of module is defined:
  40 ** this module requires instance of binding-aware-broker
  41 (`container binding-aware-broker`)
  42 ** and list of openflow-switch-connection-provider (those are provided
  43 by openflowjava, one plugin instance will orchestrate multiple
  44 openflowjava modules)
  45
  46 [source,yang]
  47 ----
  48 module openflow-provider-impl {
  49    yang-version 1;
  50    namespace "urn:opendaylight:params:xml:ns:yang:openflow:common:config:impl[urn:opendaylight:params:xml:ns:yang:openflow:common:config:impl]";
  51    prefix "ofplugin-cfg-impl";
  52
  53    import config {prefix config; revision-date 2013-04-05;}
  54    import openflow-provider {prefix openflow-provider;}
  55    import openflow-switch-connection-provider {prefix openflow-switch-connection-provider;revision-date 2014-03-28;}
  56    import opendaylight-md-sal-binding { prefix md-sal-binding; revision-date 2013-10-28;}
  57
  58
  59    description
  60        "openflow-plugin-custom-config-impl";
  61
  62    revision "2014-03-26" {
  63        description
  64            "Initial revision";
  65    }
  66
  67    identity openflow-provider-impl {
  68        base config:module-type;
  69        config:provided-service openflow-provider:openflow-provider;
  70        config:java-name-prefix ConfigurableOpenFlowProvider;
  71    }
  72
  73    augment "/config:modules/config:module/config:configuration" {
  74        case openflow-provider-impl {
  75            when "/config:modules/config:module/config:type = 'openflow-provider-impl'";
  76
  77            container binding-aware-broker {
  78                uses config:service-ref {
  79                    refine type {
  80                        mandatory true;
  81                        config:required-identity md-sal-binding:binding-broker-osgi-registry;
  82                    }
  83                }
  84            }
  85            list openflow-switch-connection-provider {
  86                uses config:service-ref {
  87                    refine type {
  88                        mandatory true;
  89                        config:required-identity openflow-switch-connection-provider:openflow-switch-connection-provider;
  90                    }
  91                }
  92            }
  93        }
  94    }
  95 }
  96 ----
  97
  98 ==== Generating config and sal classes out of yangs
  99
 100 In order to involve suitable code generators, this is needed in pom:
 101
 102 [source,xml]
 103 ----
 104 <build> ...
 105   <plugins>
 106     <plugin>
 107       <groupId>org.opendaylight.yangtools</groupId>
 108       <artifactId>yang-maven-plugin</artifactId>
 109       <executions>
 110         <execution>
 111           <goals>
 112             <goal>generate-sources</goal>
 113           </goals>
 114           <configuration>
 115             <codeGenerators>
 116               <generator>
 117                 <codeGeneratorClass>
 118                   org.opendaylight.controller.config.yangjmxgenerator.plugin.JMXGenerator
 119                 </codeGeneratorClass>
 120                 <outputBaseDir>${project.build.directory}/generated-sources/config</outputBaseDir>
 121                 <additionalConfiguration>
 122                   <namespaceToPackage1>
 123                     urn:opendaylight:params:xml:ns:yang:controller==org.opendaylight.controller.config.yang
 124                   </namespaceToPackage1>
 125                 </additionalConfiguration>
 126               </generator>
 127               <generator>
 128                 <codeGeneratorClass>
 129                   org.opendaylight.yangtools.maven.sal.api.gen.plugin.CodeGeneratorImpl
 130                 </codeGeneratorClass>
 131                 <outputBaseDir>${project.build.directory}/generated-sources/sal</outputBaseDir>
 132               </generator>
 133               <generator>
 134                 <codeGeneratorClass>org.opendaylight.yangtools.yang.unified.doc.generator.maven.DocumentationGeneratorImpl</codeGeneratorClass>
 135                 <outputBaseDir>${project.build.directory}/site/models</outputBaseDir>
 136               </generator>
 137             </codeGenerators>
 138             <inspectDependencies>true</inspectDependencies>
 139           </configuration>
 140         </execution>
 141       </executions>
 142       <dependencies>
 143         <dependency>
 144           <groupId>org.opendaylight.controller</groupId>
 145           <artifactId>yang-jmx-generator-plugin</artifactId>
 146           <version>0.2.5-SNAPSHOT</version>
 147         </dependency>
 148         <dependency>
 149           <groupId>org.opendaylight.yangtools</groupId>
 150           <artifactId>maven-sal-api-gen-plugin</artifactId>
 151           <version>${yangtools.version}</version>
 152           <type>jar</type>
 153         </dependency>
 154       </dependencies>
 155     </plugin>
 156     ...
 157 ----
 158
 159 * JMX generator (target/generated-sources/config)
 160 * sal CodeGeneratorImpl (target/generated-sources/sal)
 161 * documentation generator (target/site/models):
 162 https://jenkins.opendaylight.org/openflowplugin/job/openflowplugin-merge/ws/openflowplugin/target/site/models/openflow-provider.html[openflow-provider.html],
 163 https://jenkins.opendaylight.org/openflowplugin/job/openflowplugin-merge/ws/openflowplugin/target/site/models/openflow-provider-impl.html[openflow-provider-impl.html]
 164
 165 ==== Altering generated files
 166
 167 Those files were generated under src/main/java in package as referred in
 168 yangs (if exist, generator will not overwrite them):
 169
 170 * ConfigurableOpenFlowProviderModuleFactory
 171 +
 172 ::
 173   here the *instantiateModule* methods are extended in order to capture
 174   and inject osgi BundleContext into module, so it can be injected into
 175   final implementation - *OpenflowPluginProvider*
 176   +
 177   `module.setBundleContext(bundleContext);`
 178 * ConfigurableOpenFlowProviderModule
 179 +
 180 ::
 181   here the *createInstance* method is extended in order to inject osgi
 182   BundleContext into module implementation
 183   +
 184   `pluginProvider.setContext(bundleContext);`
 185
 186 [[configuration-xml-file]]
 187 ==== Configuration xml file
 188
 189 Configuration file contains
 190
 191 * required capabilities
 192 ** modules definitions from openflowjava
 193 ** modules definitions from openflowplugin
 194 * modules definition
 195 ** openflow:switch:connection:provider:impl (listening on port 6633,
 196 name=openflow-switch-connection-provider-legacy-impl)
 197 ** openflow:switch:connection:provider:impl (listening on port 6653,
 198 name=openflow-switch-connection-provider-default-impl)
 199 ** openflow:common:config:impl (having 2 services (wrapping those 2
 200 previous modules) and binding-broker-osgi-registry injected)
 201 * provided services
 202 ** openflow-switch-connection-provider-default
 203 ** openflow-switch-connection-provider-legacy
 204 ** openflow-provider
 205
 206 [source,xml]
 207 ----
 208 <snapshot>
 209  <required-capabilities>
 210    <capability>urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider:impl?module=openflow-switch-connection-provider-impl&revision=2014-03-28</capability>
 211    <capability>urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider?module=openflow-switch-connection-provider&revision=2014-03-28</capability>
 212    <capability>urn:opendaylight:params:xml:ns:yang:openflow:common:config:impl?module=openflow-provider-impl&revision=2014-03-26</capability>
 213    <capability>urn:opendaylight:params:xml:ns:yang:openflow:common:config?module=openflow-provider&revision=2014-03-26</capability>
 214  </required-capabilities>
 215
 216  <configuration>
 217
 218
 219      <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 220        <module>
 221          <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider:impl">prefix:openflow-switch-connection-provider-impl</type>
 222          <name>openflow-switch-connection-provider-default-impl</name>
 223          <port>6633</port>
 224          <switch-idle-timeout>15000</switch-idle-timeout>
 225        </module>
 226        <module>
 227          <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider:impl">prefix:openflow-switch-connection-provider-impl</type>
 228          <name>openflow-switch-connection-provider-legacy-impl</name>
 229          <port>6653</port>
 230          <switch-idle-timeout>15000</switch-idle-timeout>
 231        </module>
 232
 233
 234        <module>
 235          <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:common:config:impl">prefix:openflow-provider-impl</type>
 236          <name>openflow-provider-impl</name>
 237
 238          <openflow-switch-connection-provider>
 239            <type xmlns:ofSwitch="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider">ofSwitch:openflow-switch-connection-provider</type>
 240            <name>openflow-switch-connection-provider-default</name>
 241          </openflow-switch-connection-provider>
 242          <openflow-switch-connection-provider>
 243            <type xmlns:ofSwitch="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider">ofSwitch:openflow-switch-connection-provider</type>
 244            <name>openflow-switch-connection-provider-legacy</name>
 245          </openflow-switch-connection-provider>
 246
 247
 248          <binding-aware-broker>
 249            <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-broker-osgi-registry</type>
 250            <name>binding-osgi-broker</name>
 251          </binding-aware-broker>
 252        </module>
 253      </modules>
 254
 255      <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 256        <service>
 257          <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider">prefix:openflow-switch-connection-provider</type>
 258          <instance>
 259            <name>openflow-switch-connection-provider-default</name>
 260            <provider>/modules/module[type='openflow-switch-connection-provider-impl'][name='openflow-switch-connection-provider-default-impl']</provider>
 261          </instance>
 262          <instance>
 263            <name>openflow-switch-connection-provider-legacy</name>
 264            <provider>/modules/module[type='openflow-switch-connection-provider-impl'][name='openflow-switch-connection-provider-legacy-impl']</provider>
 265          </instance>
 266        </service>
 267
 268        <service>
 269          <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:common:config">prefix:openflow-provider</type>
 270          <instance>
 271            <name>openflow-provider</name>
 272            <provider>/modules/module[type='openflow-provider-impl'][name='openflow-provider-impl']</provider>
 273          </instance>
 274        </service>
 275      </services>
 276
 277
 278  </configuration>
 279 </snapshot>
 280 ----
 281
 282 ==== API changes
 283
 284 In order to provide multiple instances of modules from openflowjava
 285 there is an API change. Previously OFPlugin got access to
 286 SwitchConnectionProvider exposed by OFJava and injected collection of
 287 configurations so that for each configuration new instance of tcp
 288 listening server was created. Now those configurations are provided by
 289 configSubsystem and configured modules (wrapping the original
 290 SwitchConnectionProvider) are injected into OFPlugin (wrapping
 291 SwitchConnectionHandler).
 292
 293 ==== Providing config file (IT, local distribution/base, integration/distributions/base)
 294
 295 ===== openflowplugin-it
 296
 297 Here the whole configuration is contained in one file (controller.xml).
 298 Required entries needed in order to startup and wire OEPlugin + OFJava
 299 are simply added there.
 300
 301 ===== OFPlugin/distribution/base
 302
 303 Here new config file has been added
 304 (src/main/resources/configuration/initial/42-openflow-protocol-impl.xml)
 305 and is being copied to config/initial subfolder of build.
 306
 307 ===== integration/distributions/build
 308
 309 In order to push the actual config into config/initial subfolder of
 310 distributions/base in integration project there was a new artifact in
 311 OFPlugin created - *openflowplugin-controller-config*, containing only
 312 the config xml file under src/main/resources. Another change was
 313 committed into integration project. During build this config xml is
 314 being extracted and copied to the final folder in order to be accessible
 315 during controller run.