Revision as of 11:52, 2 September 2016

Honeycomb plugin development tutorial

Honeycomb plugin development guide for 16.09 Honeycomb release.

Plugin overview

Honeycomb provides a framework for plugins to participate in the data handling. The plugins use YANG modeling language to describe what:

• data they can handle (Create, Read, Update, Delete operations)
• notifications do they emit
• RPCs are not supported

A plugin usually consists of:

• YANG models - These models contain data and notification definitions that are implemented by the plugin. ODL's Yangtools project is used to generate Java APIs from those models (called Binding Aware APIs in ODL) and are later used in the translation code.
• Set of readers - Readers provide operational/state data from plugin or its underlying layer. This means that operational/state data is current state of the plugin or its underlying layer. Readers return these operational data by e.g. reading from underlying layer and transforming it into YANG modeled data.
• Set of writers - Writers handle configuration data for the plugin or its underlying layer This means that configuration data is the intent being sent to Honeycomb, that should be passed to plugins or their underlying layers. Writers handle these configuration data by transforming YANG modeled data into e.g. underlying layer calls.
• Set of initializers - Initializers are invoked right after Honeycomb starts. The gould here is to read current operational/state data of the plugin or its underlying layer and then transform the operational data into configuration data. This enables reconciliation in cases when Honeycomb looses it's persisted data, or is started fresh while the underlying layer already contains some configuration that is manifested as operational/state data
• Plugin configuration - Usually configuration in json format + it's Java equivalent.
• Set of notification producers - If there are any notifications, the producers transform the data into YANG model notifications and emit them.
• Module - Small class instantiating & exposing plugin's components

What's good to add:

• Unit tests
• Documentation
• Sample REST or NETCONF requests

Prerequisites

Make sure to check Honeycomb/Setting_Up_Your_Dev_Environment page to properly setup the environment.

Developing generic plugins

Since Honeycomb is a generic agent. Any plugin (translation code) can be injected into the framework, creating a custom agent providing RESTCONF/NETCONF northbound interfaces out-of-box.

Developing plugin code

Honeycomb provides a maven archetype to generate a plugin skeleton. To use that archetype, run maven:

 mvn -X archetype:generate -DarchetypeGroupId=io.fd.honeycomb.tools -DarchetypeArtifactId=honeycomb-plugin-archetype -DarchetypeVersion=1.16.9-SNAPSHOT

Fill in the parameters e.g.

 groupId: io.fd.honeycomb.tutorial
 artifactId: sample-plugin
 version: 1.16.9-SNAPSHOT
 package: io.fd.honeycomb.tutorial

And following structure should be created:

 sample-plugin/
 ├── pom.xml
 ├── sample-plugin-api
 │   ├── pom.xml
 │   └── src
 │       └── main
 │           ├── java
 │           └── yang
 │               └── sample-plugin.yang
 └── sample-plugin-impl
     ├── pom.xml
     ├── Readme.adoc
     └── src
         ├── main
         │   └── java
         │       └── io
         │           └── fd
         │               └── honeycomb
         │                   └── tutorial
         │                       ├── CrudService.java
         │                       ├── ElementCrudService.java
         │                       ├── init
         │                       │   └── ConfigDataInitializer.java
         │                       ├── ModuleConfiguration.java
         │                       ├── Module.java
         │                       ├── read
         │                       │   ├── ElementStateCustomizer.java
         │                       │   └── ModuleStateReaderFactory.java
         │                       └── write
         │                           ├── ElementCustomizer.java
         │                           └── ModuleWriterFactory.java
         └── test
             └── java
 

There are 2 modules:

• sample-plugin-api - Contains YANG models and generates Java APIs from the models.
• sample-plugin-impl - Contains: Readers, Writers, Initializers, Notification producers (not yet), Configuration and Wiring.

There is plenty of comments within the code, so its is advised to import the code into an IDE and take a look around.

The archetype generates a plugin that is fully working right from the start. Since it contains all the components necessary, works on a sample yang model and provides some sample values.

Building the code

To build the code, just execute maven:

 mvn clean install

And that's it. This is a working Honeycomb plugin.

Adding notifications

No notification producer is generated by the archetype, but it is pretty straightforward to add one.

First, the notification has to be defined in YANG (sample-plugin-api/src/main/yang/sample-plugin.yang) e.g.

 notification sample-notification {
     leaf content {
         type string;
     }
 }

Now rebuild the plugin to generate new APIs for our notification.

Next part is implementing the Notification producer. First thing to do is to add a dependency on notification-api, since it's not included by default. Update sample-plugin-impl's pom file with:

 <dependency>
   <groupId>io.fd.honeycomb</groupId>
   <artifactId>notification-api</artifactId>
   <version>${honeycomb.infra.version}</version>
 </dependency>

Now, the producer code can be added:

package io.fd.honeycomb.tutorial.notif;
 
import io.fd.honeycomb.notification.ManagedNotificationProducer;
import io.fd.honeycomb.notification.NotificationCollector;
import java.util.Collection;
import java.util.Collections;
import javax.annotation.Nonnull;
import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.sample.plugin.rev160918.SampleNotification;
import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.sample.plugin.rev160918.SampleNotificationBuilder;
import org.opendaylight.yangtools.yang.binding.Notification;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
/**
 * Notification producer for sample plugin
 */
public class SampleNotificationProducer implements ManagedNotificationProducer {
 
    private static final Logger LOG = LoggerFactory.getLogger(SampleNotificationProducer.class);
 
    private Thread thread;
 
    @Override
    public void start(@Nonnull final NotificationCollector collector) {
        LOG.info("Starting notification stream for interfaces");
 
        // Simulating notification producer
        thread = new Thread(() -> {
            while(true) {
                if (Thread.currentThread().isInterrupted()) {
                    return;
                }
 
                try {
                    Thread.sleep(2000);
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    break;
                }
 
                final SampleNotification notification = new SampleNotificationBuilder()
                        .setContent("Hello world " + System.currentTimeMillis())
                        .build();
                LOG.info("Emitting notification: {}", notification);
                collector.onNotification(notification);
            }
        }, "NotificationProducer");
        thread.setDaemon(true);
        thread.start();
    }
 
    @Override
    public void stop() {
        if(thread != null) {
            thread.interrupt();
        }
    }
 
    @Nonnull
    @Override
    public Collection<Class<? extends Notification>> getNotificationTypes() {
        // Producing only this single type of notification
        return Collections.singleton(SampleNotification.class);
    }
 
    @Override
    public void close() throws Exception {
        stop();
    }
}

This is placed sample-plugin/sample-plugin-impl/src/main/java/io/fd/honeycomb/tutorial/notif/SampleNotificationProducer.java.

Note: This is a sample producer, that creates a thread to periodically emit a sample notification

Now it needs to be exposed from the plugin. The configure method in Module class needs to be updated with:

  Multibinder.newSetBinder(binder(), ManagedNotificationProducer.class).addBinding().to(SampleNotificationProducer.class);

Plugin needs to be rebuilt, but that's it for notification producers.

Creating custom distribution

The plugin is now ready to have a Honeycomb distribution for it. This section will provides information on how to create a custom Honeycomb distribution.

A new maven module needs to be created. So in sample-plugin folder:

 mkdir sample-distribution
 cd sample-distribution
 mkdir -p src/main/java/io/fd/honeycomb/tutorial

Then create the pom:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 
  <parent>
    <groupId>io.fd.honeycomb.common</groupId>
    <artifactId>minimal-distribution-parent</artifactId>
    <version>1.16.9-SNAPSHOT</version>
  </parent>
 
  <modelVersion>4.0.0</modelVersion>
  <groupId>io.fd.honeycomb.tutorial</groupId>
  <artifactId>sample-distribution</artifactId>
  <version>1.16.9-SNAPSHOT</version>
 
  <properties>
    <exec.parameters>-Xms128m -Xmx128m</exec.parameters>
    <main.class>io.fd.honeycomb.tutorial.Main</main.class>
    <interfaces.mapping.version>1.16.9-SNAPSHOT</interfaces.mapping.version>
    <honeycomb.min.distro.version>1.16.9-SNAPSHOT</honeycomb.min.distro.version>
  </properties>
 
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
      </plugin>
      <plugin>
        <groupId>org.codehaus.gmaven</groupId>
        <artifactId>groovy-maven-plugin</artifactId>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
      </plugin>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
 
  <dependencies>
    <!-- Dependency on sample plugin -->
    <dependency>
      <groupId>io.fd.honeycomb.tutorial</groupId>
      <artifactId>sample-plugin-impl</artifactId>
      <version>${interfaces.mapping.version}</version>
    </dependency>
    <!-- Dependency on distribution base -->
    <dependency>
      <groupId>io.fd.honeycomb</groupId>
      <artifactId>minimal-distribution</artifactId>
      <version>${honeycomb.min.distro.version}</version>
    </dependency>
 
  </dependencies>
</project>

Now, Main class has to be added in folder src/main/java/io/fd/honeycomb/tutorial:

package io.fd.honeycomb.tutorial;
 
import com.google.common.collect.Lists;
import com.google.inject.Module;
import java.util.List;
 
public class Main {
 
    public static void main(String[] args) {
        final List<Module> sampleModules = Lists.newArrayList(io.fd.honeycomb.infra.distro.Main.BASE_MODULES);
 
        sampleModules.add(new io.fd.honeycomb.tutorial.Module());
 
        io.fd.honeycomb.infra.distro.Main.init(sampleModules);
    }
}

Last thing to do is to update sample-plugin/pom.xml with:

    <module>sample-distribution</module>

Another rebuild and the distribution should be created in sample-distribution/target.

Adding existing plugins to the mix

In previous section, a custom Honeycomb distribution was created. This section will show how to add existing plugins to the new distribution.

So in order to add another existing sample (sample interface plugin from Honeycomb) into the distribution, update the sample-plugin/sample-distribution/pom.xml with:

    <dependency>
      <groupId>io.fd.honeycomb.samples.interfaces</groupId>
      <artifactId>interfaces-mapping</artifactId>
      <version>${interfaces.mapping.version}</version>
    </dependency>

Now in main, add this line:

    sampleModules.add(new SampleInterfaceModule());

That's it, just rebuild.

Verifying distribution

The distribution with this sample plugin and sample interface plugin is now available and can be tested.

Distribution can now be found in sample-plugin/sample-distribution/target as:

• zip archive
• tar.gz archive
• folder

The distribution can be started by:

 sudo ./sample-distribution/target/sample-distribution-1.16.9-SNAPSHOT-hc/sample-distribution-1.16.9-SNAPSHOT/honeycomb

Note: honeycomb-start script is the background alternative

Honeycomb will display following message in the log:

 2016-09-02 13:20:30.424 CEST [main] INFO  io.fd.honeycomb.infra.distro.Main - Honeycomb started successfully!

and that means Honeycomb was started successfully.

Testing over RESTCONF

Reading sample-plugin operational data:

 curl -u admin:admin  http://localhost:8181/restconf/operational/sample-plugin:sample-plugin-state

Writing sample-plugin operational data:

 Not possible from YANG spec. Operational data is only for read.

Writing sample-plugin config data:

 curl -H 'Content-Type: application/json' -H 'Accept: application/json' -u admin:admin -X PUT -d '{"sample-plugin":{"element":[{"id":10,"description":"This is a example of loaded data"}]}}' http://localhost:8181/restconf/config/sample-plugin:sample-plugin

Reading sample-plugin config data:

 curl -u admin:admin  http://localhost:8181/restconf/config/sample-plugin:sample-plugin

Testing over NETCONF

Netconf testing guide including Notifications, can be found in Honeycomb/Running_Honeycomb

Full working example

Full working example on github: https://github.com/marosmars/honeycomb-samples

Developing plugins for VPP

Honeycomb's primary use case is to provide an agent for VPP. There already are some plugins that provide the translation code for VPP, but there are still APIs that are not covered. In this section, a sample Honeycomb plugin will be created communicating with VPP.

Developing plugin code

Bootstrapping Honeycomb plugin

Creating custom agent distribution

Adding existing plugins to the mix

Verifying agent

Full working example