What if I told you, that there is an out-of-the-box pre-packaged microservice-ready application you can easily use for managing network elements in your SDN use case? And that it is open-sourced and you can try it for free? Yep, you heard it right.

The application consists of lighty.io modules packed together within various technologies – ready to be used right away.

Do you have a more complex deployment, and are using Helm to deploy into Kubernetes? Or you just need to use Docker images? Or you want to handle everything by yourself and the only thing you need is a runnable application? We got you covered.

lighty.io RESTCONF-NETCONF Application

The most common use case we see at our customers is for an SDN controller to handle NETCONF devices via REST endpoints. This is due to ease of integration to e.g. OSS and BSS systems, or ITSM systems, as these already have REST API interfaces and adapters.

This is where our first lighty.io application comes in – the lighty.io RNC application, where RNC stands for RESTCONF-NETCONF-controller.

Use Cases: Facilitate & Translate Network Device Communication

Imagine a scenario, where the ONAP Controller Design Studio (CDS) component needs to communicate with both RESTCONF & NETCONF devices.

lighty.io RESTCONF-NETCONF Controller enables and facilitates communication to both RESTCONF/NETCONF devices while translating communication both ways!

Its usability and features can save you time and resources in a variety of telco related scenarios:

• Data-Centers
• OSS/BSS Integration (w/ NETCONF speaking devices & appliances)
• Service Provider Networks (Access, Edge, etc.)
• Central Office

Components

As the name suggests, it includes the RESTCONF northbound plugin and NETCONF southbound plugin at the bottom of the lighty.io controller.

At the heart of the application is the lighty.io controller. It provides core OpenDaylight services like MD-SAL, datastores, YANG Tools, handles global schema context, and more.

NETCONF southbound plugin serves as an adapter for NETCONF devices. It allows lighty.io to connect and communicate with them, execute RPCs, and read/write configuration.

RESTCONF northbound plugin is responsible for RESTCONF endpoints. These are used for communication between a user (or another application, like the aforementioned OSS/BSS systems, workflow managers, or ServiceNow for example) and the lighty.io application. RESTCONF gives us access to the so-called mount points serving as a proxy to devices.

These three mentioned components make up the core of the lighty.io RNC Application. Together, they form a base of the application. But of course, there is no such thing as one solution to rule them all.

Oftentimes, there is a need for side-car functionalities to the RNC, that is best built bespoke, that fulfill some custom business logic. Or enhance the RESTCONF API endpoints with side-load data.

We provide the means to customize and configure the lighty.io RNC application via configuration files to better fit your needs.

And if there is something we didn’t cover, do not hesitate to contact us or create a Pull Request or issue in our GitHub repository. We provide commercial custom development, developer, and operational support to enhance your efforts.

Configuration

You can find some common options in the JSON configuration file, like:

• what address and port is RESTCONF listening to
• what is the base URL of the RC endpoints to RESTCONF endpoints
• what is the name of the network topology where NETCONF is listening
• which YANG models should be available in the lighty.io app itself
• and more

But wait! There is more!

There are some special configurations too with a bit bigger impact

One of them is an option to enable HTTPS for RESTCONF endpoints. When useHttps is set to true, HTTPS will be enabled. It is possible to specify a custom key-store too and we recommend doing so. But just for some tests default keystore should be more than enough.

The option enableAAA is used to enable the lighty-aaa module. This module is responsible for authorization, authentication, and accounting which for example enables to use Basic Authentication for RESTCONF northbound interface.

Generally, it’s a good practice to consider SDN controllers like this one as a stateless service. Especially in a complex and dynamic deployment with a bigger amount of services.

But if you want to initialize configurational datastore with some data right after startup, it’s possible with the “initialConfigData“ part of the configuration. For example, you insert connection information about a NETCONF device, so the lighty.io application will connect to it right after it starts.

Examples and a bit more explanation of these configuration options can be found in a lighty.io RESTCONF-NETCONF application README.md file.

Deployment

As mentioned in the beginning, we provide three main types of deployment: Helm chart for deployment in Kubernetes, Docker image, and a “zip” distribution containing all necessary jar files to run the application.

A step-by-step guide on how to build these artifacts from code can be found in a lighty.io RNC README.md file. It also contains steps on how to start and configure it.

Helm chart and Docker image can be also downloaded from public repositories.

Docker image can be downloaded from our GitHub Packages or via command:

docker pull ghcr.io/pantheontech/lighty-rnc:latest

Helm chart can be downloaded from our GitHub helm-charts repository and you can add it into your Helm environment via these commands:

helm repo add pantheon-helm-repo https://pantheontech.github.io/helm-charts/ 
helm repo update

Give lighty.io RNC a try

In case you need an SDN controller for NETCONF devices providing RESTCONF endpoints, give lighty.io RNC a try. The guides linked above should be pretty straightforward.

And if you need any help, got some cool ideas, or want to use our solutions, you can contact us here!

by Samuel Kontriš | Leave us your feedback on this post!

You can contact us here.

Explore our PANTHEON.tech GitHub.

Watch our YouTube Channel.

Binding Query (BQ) is an MD-SAL module, currently located at OpenDaylight version master (7.0.5), 6.0.x, and 5.0.x. Its primary function is to filter data from the Binding Awareness model.

To use BQ, it is required to create QueryExpression and QueryExecutor. QueryExecutor contains BindingCodecTree and data represented by the Binding Awareness model. A filter will be applied to this data and all operations from QueryExpression.

QueryExpression is created from the QueryFactory class. Creating a QueryFactory is started with the querySubtree method. Here, it is entered as an instance identifier, and it has to be at the root of data from QueryExecutor.

The next step will be to create a path to the data, which we want to filter – and then apply the required filter. When QueryExpression is ready, it will be applied with the method executeQuery in QueryExecutor. One QueryExpression can be used on multiple QueryExecutors with the same data schema.

Prerequisites for Binding Query

Now, we will demonstrate how to actually use Binding Query. We will create a YANG model for this purpose:

module queryTest {
    yang-version 1.1;
    namespace urn:yang.query;
    prefix qt;
 
    revision 2021-01-20 {
        description
          "Initial revision";
    }
 
    grouping container-root {
        container container-root {
            leaf root-leaf {
                type string;
            }
 
            leaf-list root-leaf-list {
                type string;
            }
 
            container container-nested {
                leaf nested-leaf {
                    type uint32;
                }
            }
        }
    }
 
    grouping list-root {
        container list-root {
            list top-list {
                key "key-a key-b";
 
                leaf key-a {
                    type string;
                }
                leaf key-b {
                    type string;
                }
                list nested-list {
                    key "identifier";
 
                    leaf identifier {
                        type string;
                    }
 
                    leaf weight {
                        type int16;
                    }
                }
            }
        }
    }
 
    grouping choice {
        choice choice {
            case case-a {
                container case-a-container {
                    leaf case-a-leaf {
                        type int32;
                    }
                }
            }
            case case-b {
                list case-b-container {
                    key "key-cb";
                    leaf key-cb {
                        type string;
                    }
                }
            }
        }
    }
 
    container root {
        uses container-root;
        uses list-root;
        uses choice;
    }
}

Then, we will build and create a Binding Awareness model, with some test data from the provided YANG model.

public Root generateQueryData() {
    HashMap<NestedListKey, NestedList> nestedMap = new HashMap<>() {{
        put(new NestedListKey("NestedId"), new NestedListBuilder()
            .setIdentifier("NestedId")
            .setWeight((short) 10)
            .build());
        put(new NestedListKey("NestedId2"), new NestedListBuilder()
            .setIdentifier("NestedId2")
            .setWeight((short) 15)
            .build());
    }};

    HashMap<NestedListKey, NestedList> nestedMap2 = new HashMap<>() {{
        put(new NestedListKey("Nested2Id"), new NestedListBuilder()
            .setIdentifier("Nested2Id")
            .setWeight((short) 10)
            .build());
    }};

    HashMap<TopListKey, TopList> topMap = new HashMap<>() {{
        put(new TopListKey("keyA", "keyB"),
            new TopListBuilder()
                .setKeyA("keyA")
                .setKeyB("keyB")
                .setNestedList(nestedMap)
                .build());
        put(new TopListKey("keyA2", "keyB2"),
            new TopListBuilder()
                .setKeyA("keyA2")
                .setKeyB("keyB2")
                .setNestedList(nestedMap2)
                .build());
    }};

    HashMap<CaseBContainerKey, CaseBContainer> caseBMap = new HashMap<>() {{
        put(new CaseBContainerKey("test@test.com"),
            new CaseBContainerBuilder()
                .setKeyCb("test@test.com")
                .build());
        put(new CaseBContainerKey("test"),
            new CaseBContainerBuilder()
                .setKeyCb("test")
                .build());
    }};

    RootBuilder rootBuilder = new RootBuilder();
    rootBuilder.setContainerRoot(new ContainerRootBuilder()
                                     .setRootLeaf("root leaf")
                                     .setContainerNested(new ContainerNestedBuilder()
                                                             .setNestedLeaf(Uint32.valueOf(10))
                                                             .build())
                                     .setRootLeafList(new ArrayList<>() {{
                                         add("data1");
                                         add("data2");
                                         add("data3");
                                     }})
                                     .build());
    rootBuilder.setListRoot(new ListRootBuilder().setTopList(topMap).build());
    rootBuilder.setChoiceRoot(new CaseBBuilder()
                                  .setCaseBContainer(caseBMap)
                                  .build());
    return rootBuilder.build();
}

For better orientation in the test-data structure, there is also a JSON representation of the data we will use:

{
  "queryTest:root": {
    "container-root": {
      "root-leaf": "root leaf",
      "root-leaf-list": [
        "data1",
        "data2",
        "data3"
      ],
      "container-nested": {
        "nested-leaf": 10
      }
    },
    "list-root": {
      "top-list": [
        {
          "key-a": "keyA",
          "key-b": "keyB",
          "nested-list": [
            {
              "identifier": "NestedId",
              "weight": 10
            },
            {
              "identifier": "NestedId2",
              "weight": 15
            }
          ]
        },
        {
          "key-a": "keyA2",
          "key-b": "keyB2",
          "nested-list": []
        }
      ]
    },
    "choice": {
      "case-b-container": {
        "top-list": [
          {
            "key-cb": "test@test.com"
          },
          {
            "key-cb": "test"
          }
        ]
      }
    }
  }
}

From the Binding Awareness model queryTest shown above, we can create a QueryExecutor. In this example, we will use the SimpleQueryExecutor. As a builder parameter, we entered BindingCodecTree. Afterwards, this will be added into the Binding Awareness data by method, which we created above.

public QueryExecutor createExecutor() {
    return SimpleQueryExecutor.builder(CODEC)
        .add(generateQueryData())
        .build();
}

Create a Query & Filter Data

Now, we can start with an example on how to create a query and filter some data. In the first example, we will describe how to filter the container by the value of his leaf. In the next steps, we will create a QueryExpression.

1. First, we will create a QueryFactory from the DefaultQueryFactory. The DefaultQueryFactory constructor takes BindingCodecTree as a parameter.

   QueryFactory factory = new DefaultQueryFactory(CODEC);

2. The next step is to create the DescendantQueryBuilder from QueryFactory. The querySubtree method takes the instance identifier as a parameter. This identifier should be a root node from our model. In this case, it is a container with the name root.

   DescendantQueryBuilder<Root> decadentQueryRootBuilder
       = factory.querySubtree(InstanceIdentifier.create(Root.class));

3. Then we will set the path to the parent container of leaf, depending on which value we want to filter.

   DescendantQueryBuilder<ContainerRoot> decadentQueryContainerRootBuilder 
   = decadentQueryRootBuilder.extractChild(ContainerRoot.class);

4. Now we create the StringMatchingBuilder, with the value of the leaf and name root-leaf, which we want to match.

   StringMatchBuilder<ContainerRoot> stringMatchBuilder = decadentQueryContainerRootBuilder.matching()
       .leaf(ContainerRoot::getRootLeaf);

5. The last step is to define which values should be filtered and then build the QueryExpression. For this case, we will filter a specific leaf, with the value “root leaf”.

   QueryExpression<ContainerRoot> matchRootLeaf = stringMatchBuilder.valueEquals("root leaf").build();

    

Now, the QueryExpression can be used to filter data from QueryExecutor. For creating QueryExecutor, we use the method defined above in “test query data”.

QueryExecutor executor = createExecutor();
      QueryResult<ContainerRoot> items = executor.executeQuery(matchRootLeaf);

The entire previous example in one block will look like this:

QueryFactory factory = new DefaultQueryFactory(CODEC);
        QueryExpression<ContainerRoot> rootLeafQueryExpression = factory
            .querySubtree(InstanceIdentifier.create(Root.class))
            .extractChild(ContainerRoot.class)
            .matching()
            .leaf(ContainerRoot::getRootLeaf)
            .valueEquals("root leaf")
            .build();
        
        QueryExecutor executor = createExecutor();
        QueryResult<ContainerRoot> result = executor.executeQuery(rootLeafQueryExpression);

When we validate the result, we will find, that only one item matched our condition in the query:

assertEquals(1, result.getItems().size());
      String resultItem = result.getItems().stream()
          .map(item -> item.object().getRootLeaf())
          .findFirst()
          .orElse(null);
      assertEquals("root leaf", resultItem);

Filter Nested-List Data

The next example will show how to use Binding Query to filter data from nested-list. This example will filter nested-list items, where the weight parameter equals 10.

QueryFactory factory = new DefaultQueryFactory(CODEC);
 QueryExpression<NestedList> queryExpression = factory
     .querySubtree(InstanceIdentifier.create(Root.class))
     .extractChild(ListRoot.class)
     .extractChild(TopList.class)
     .extractChild(NestedList.class)
     .matching()
     .leaf(NestedList::getWeight)
     .valueEquals((short) 10)
     .build();

 QueryExecutor executor = createExecutor();
 QueryResult<NestedList> result = executor.executeQuery(queryExpression);
 assertEquals(2, result.getItems().size())

If we are required to filter nested-list items, but only from top-list with specific keys, then it will look like this:

QueryFactory factory = new DefaultQueryFactory(CODEC);
        QueryExpression<NestedList> queryExpression = factory
            .querySubtree(InstanceIdentifier.create(Root.class))
            .extractChild(ListRoot.class)
            .extractChild(TopList.class, new TopListKey("keyA", "keyB"))
            .extractChild(NestedList.class)
            .matching()
            .leaf(NestedList::getWeight)
            .valueEquals((short) 10)
            .build();

        QueryExecutor executor = createExecutor();
        QueryResult<NestedList> result = executor.executeQuery(queryExpression);
        assertEquals(1, result.getItems().size())

In case that we wanted to get top-list elements, but only those which contain nested-leaf items with a weight greater than, or equals to, 15. It is possible to set a match on top-list containers and then continue with a condition to nested-list. With number operations, we can execute greaterThanOrEqual, lessThanOrEqual, greaterThan, and lessThan methods.

QueryExpression<TopList> queryExpression = factory
            .querySubtree(InstanceIdentifier.create(Root.class))
            .extractChild(ListRoot.class)
            .extractChild(TopList.class)
            .matching()
            .childObject(NestedList.class)
            .leaf(NestedList::getWeight).greaterThanOrEqual((short) 15)
            .build();

        QueryExecutor executor = createExecutor();
        QueryResult<TopList> result = executor.executeQuery(queryExpression);
        assertEquals(1, result.getItems().size());

        List<TopList> topListResult = result.getItems().stream()
            .map(Item::object)
            .filter(item -> item.getKeyA().equals("keyA"))
            .filter(item -> item.getKeyB().equals("keyB"))
            .collect(Collectors.toList());
        assertEquals(1, topListResult.size());

The last example shows how to filter choice data and matching their values in key-cb leaf. Conditions that are required to meet are defined in the pattern, which matches the email address.

QueryFactory factory = new DefaultQueryFactory(CODEC);
       QueryExpression<CaseBContainer> queryExpression = factory
           .querySubtree(InstanceIdentifier.create(Root.class))
           .extractChild(CaseBContainer.class)
           .matching()
           .leaf(CaseBContainer::getKeyCb)
           .matchesPattern(Pattern.compile("^[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,6}$",
                                           Pattern.CASE_INSENSITIVE))
           .build();

       QueryExecutor executor = createExecutor();
       QueryResult<CaseBContainer> result = executor.executeQuery(queryExpression);

       assertEquals(1, result.getItems().size());

Binding Query can be used to filter important data, as is shown in previous examples. With Binding Query, it is possible to filter data with various options and get all the required information. Binding Query can also support matching string by patterns and simple filter operations with numbers.

by Peter Šuňa | Leave us your feedback on this post!

You can contact us at https://pantheon.tech/

Explore our Pantheon GitHub.

Watch our YouTube Channel.

PANTHEON.tech has created a commit in the official OpenDaylight repository, which updates the version of Swagger generator to OpenAPI 3.0.

This feature allows us to easily generate a JSON with RESTCONF API documentation of OpenDaylight RESTCONF applications and import it into various services, such as ServiceNow®. This feature is not only about the generation of JSON with OpenAPI. It also includes Swagger UI based on generated JSON.

What is RESTCONF API?

RESTCONF API is an interface, which allows access to datastores in the controller, via HTTP requests. OpenDaylight supports two versions of RESTCONF protocol:

• draft-bierman-netconf-restconf-02
• RFC8040.

What is OpenAPI?

OpenAPI, formerly known as Swagger UI, visualizes API resources and enables the user to interact with them. This kind of visualization provides an easier way to implement APIs in the back-end while automating the creation of documentation for the APIs in question.

OpenAPI Specification on the other hand (OAS for short), is a language-agnostic interface description for RESTful APIs. Its purpose is to visualize them and make the APIs readable for people and PCs alike, in YAML or JSON formats.

OAS 3.0 introduced several major changes, which made the specification structure clearer and more efficient. For a rundown of changes from OpenAPI 2 to version 3, make sure to visit this page detailing them.

How does it work?

OpenAPI is generated on the fly, with every manual request for the OpenAPI specification of the selected resource. The resource can be the OpenDaylight datastore or a device mount point. 

You can conveniently access the list of all available resources over the apidoc web application. The resources are located on the top right part of the screen. Once you select the resource you want to generate the OpenAPI specification for, you just pick the desired resource and the OpenAPI specification will be displayed below.

The apidoc is packed within the odl-restconf-all Karaf feature. To access it, you only need to type

feature:install odl-restconf-all

in the Karaf console. Then, you can use a web browser of your choice to access the apidoc web application over the following URL:

http://localhost:8181/apidoc/explorer/index.html

Once an option is selected, the page will load the documentation of your chosen resource, with the chosen protocol version.

The documentation of any resource endpoint (node, RPC’s, actions), is located under its module spoiler. When you click on the link:

http://localhost:8181/apidoc/openapi3/${RESTCONF_version}/apis/${RESOURCE}

you will get the OpenAPI JSON for the particular RESTCONF version and selected resource. Here is a code snippet from the resulting OpenAPI specification:

{
  "openapi": "3.0.3",
  "info": {
    "version": "1.0.0",
    "title": "simulator-device21 modules of RestConf version RFC8040"
  },
  "servers": [
    {
      "url": "http://localhost:8181/"
    }
  ],
  "paths": {
    "/rests/data/network-topology:network-topology/topology=topology-netconf/node=simulator-device21/yang-ext:mount": {
      "get": {
        "description": "Queries the operational (running) datastore on the mounted hosted.",
        "summary": "GET - simulator-device21 - data",
        "tags": [
          "mounted simulator-device21 GET root"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/rests/operations/network-topology:network-topology/topology=topology-netconf/node=simulator-device21/yang-ext:mount": {
      "get": {
        "description": "Queries the available operations (RPC calls) on the mounted hosted.",
        "summary": "GET - simulator-device21 - operations",
        "tags": [
          "mounted simulator-device21 GET root"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
...

You can look through the entire export by clicking here.

Our Commitment to Open-Source

PANTHEON.tech is one of the largest contributors to the OpenDaylight source-code, with extensive knowledge that goes beyond a general service or integration.

This just goes to show, that PANTHEON.tech is heavily involved in the development and progress of OpenDaylight. We are glad to be part of the open-source community and contributors.

You can contact us at https://pantheon.tech/

Explore our PANTHEOn.tech GitHub.

Watch our YouTube Channel.