nuagenetworks

Java and the Nuage VSPK - Part 1 - Introduction

April 17, 2017 - Leonard Paquette

Product Overview

The VSP (Virtualized Services Platform) is a product from Nuage Networks that provides SDN (Software-Defined Network) automation. One of its key components is VSD (Virtualized Services Directory), a programmable engine that supports the abstract definition of network services. The VSD provides a RESTful API through which network administrators can implement the service designs and access policies of their enterprise.

The VSD RESTful API, just like any standard RESTFul web service, can be consumed in various ways, from a simple browser-based URI request, to a programming language like Python or Java. Nuage Networks has published open-source projects in several popular programming languages that provide adaptive layers to the RESTful API. Besides Java, the focus of this blog, there are SDKs for Go, Objective-J and Python.

Underlying each language specific SDK is a low-level communications library known as Bambou. Each implementation of Bambou provides an objected oriented layer for manipulating REST objects within the VSD.

Here are some references for downloads and details about the SDK’s that support the VSD RESTful API:

Go Library

Python Library

Objective-J Library

Java Library

Getting Started

To start using the VSPK-Java library, you will need to deploy 2 Jar files into your development environment. The vspk jar file provides the layer through which your custom Java code will make calls to manipulate VSD entities such as domains, virtual machines and access policies. The bambou jar file is a dependency of the vspk jar file and provides an object-oriented abstraction layer for the lower-level REST calls that are managed by the Spring Framework HTTP Client/Server package.

At the time of this writing, the latest versions of the 2 files are vspk-4.0.8.jar and bambou-2.0.2.jar. In the future, we expect to make these libraries available in the Central Maven Repository. The link below will direct you to the latest, public versions of the jar files, along with their prior releases and any notes on JRE dependencies. You can download the latest versions here.

Setup with Maven

Since most Java developers are using Maven to build their projects, the 2 jar files are accompanied by pom.xml files that provide build profiles and project dependencies. If you are using Maven, ensure that the jar files are copied into your local Maven cache repository.

For vspk , the path from your local repository will look similar to this:

C:\Users\lpaquett\.m2\repository\net\nuagenetworks\vspk\4.0.8

For bambou , the path from your local repository will look similar to this:

C:\Users\lpaquett\.m2\repository\net\nuagenetworks\bambou\2.0.2

Setup without Maven

If you are not using Maven as a build tool, then you will have some extra work to do to install the vspk and bambou files. Instead of copying the 2 jar files to a Maven cache structure, you will need to places the files and their dependencies on your project’s build path.

First, copy the 2 jar files into the directory matching the libraries location on your Java build path. In many cases, this will be named lib, and there may already be some files installed there that are referenced in your project.

Second, review the pom.xml files for both jar files to determine their dependencies and then manually download and copy dependent jar files onto your build path. You will see details such as groupId, artifactId and version for first-level dependencies that can be used to search for the appropriate downloadable files in the Central Maven Repository.

You will see entries, like those shown below, from the 2 pom files:

<dependencies>
	<dependency>
		<groupId>org.slf4j</groupId>
		<artifactId>slf4j-api</artifactId>
		<version>1.7.18</version>
	</dependency>
	<dependency>
		<groupId>com.fasterxml.jackson.core</groupId>
		<artifactId>jackson-databind</artifactId>
		<version>2.7.2</version>
	</dependency>
	<dependency>
		<groupId>org.springframework</groupId>
		<artifactId>spring-web</artifactId>
		<version>4.2.5.RELEASE</version>
	</dependency>
	<dependency>
		<groupId>commons-codec</groupId>
		<artifactId>commons-codec</artifactId>
		<version>1.10</version>
	</dependency>
	<dependency>
		<groupId>org.jboss.as</groupId>
		<artifactId>jboss-as-jms-client-bom</artifactId>
		<version>7.1.1.Final</version>
		<type>pom</type>
	</dependency>
	<dependency>
		<groupId>org.springframework</groupId>
		<artifactId>spring-test</artifactId>
		<version>4.2.5.RELEASE</version>
		<scope>test</scope>
	</dependency>
	<dependency>
		<groupId>junit</groupId>
		<artifactId>junit</artifactId>
		<version>4.12</version>
		<scope>test</scope>
	</dependency>
	<dependency>
		<groupId>org.easymock</groupId>
		<artifactId>easymock</artifactId>
		<version>3.4</version>
		<scope>test</scope>
	</dependency>
	<dependency>
		<groupId>org.slf4j</groupId>
		<artifactId>slf4j-simple</artifactId>
		<version>1.7.18</version>
		<scope>test</scope>
	</dependency>
</dependencies>

From the pom file snippet above, you can see that bambou has a dependency on the Spring Framework. This means you will need to supply not only the Spring Web artifact, but also all its dependencies. Your Java IDE environment will throw build errors until all nested dependencies have been resolved. In this particular case, you need to download and install file spring-web-4.2.5.RELEASE.jar. To locate this file, you can search the Central Maven Repository here.

VSD Setup

Note that as a precondition to using the VSPK-Java library, you will need to have a running VSD server with sufficient update permissions. If you have access to a VSD test environment, then it has likely been configured with an administrative user having username/password credentials csproot/csproot, a default enterprise csp and a port number 8443. Please contact your administration team for connection details such as network address.

Nuage Networks offers a well-designed VSD web interface known as VSA (Virtualized Services Architect) that provides a visual representation of your VSP and allows you to actually update your SDN entities directly. For our purposes, we can use the VSA to test our login credentials and verify that our Java programs are working.

To access the VSA, enter an appropriate address and port in your browser based on the network location of your local VSD. Your URL should resemble this:

https://135.121.118.59:8443/

If your VSD is running on the port that you have provided, you will see a login screen similar to this:

VSA login screen

After entering valid credentials and enterprise (a.k.a. organization), you will see a home page similar to this:

VSA home page

Hello Enterprise

Once you have verified that your VSD is running and that you have credentials to access it, let’s continue with everyone’s favorite and traditional Hello World sanity test to make sure that all of the software components are installed correctly in your development environment. But instead of just logging Hello World to your console, you will initialize a new Enterprise entity called Hello Enterprise in your VSD. Here is a runnable Java program to do just that:

import net.nuagenetworks.bambou.RestException;
import net.nuagenetworks.vspk.v4_0.Enterprise;
import net.nuagenetworks.vspk.v4_0.Me;
import net.nuagenetworks.vspk.v4_0.VSDSession;

public class CreateHelloEnterprise {
  public static void main(String[] args) throws RestException {
    VSDSession session = new VSDSession
        ("csproot", "csproot", "csp", "https://135.121.118.59:8443"); // 1
    session.start(); // 2
    Me me = session.getMe(); // 3
    Enterprise enterprise = new Enterprise(); // 4
    enterprise.setName("HelloEnterprise"); // 5
    me.createChild(enterprise); // 6
  }
}

The first step is to establish a VSD session. In line 1, we provide a valid set of username/password credentials and the location of the VSD. You will need to provide an appropriate address for your VSD. In Line 2, we start the session.

  VSDSession session = new VSDSession
        ("csproot", "csproot", "csp", "https://135.121.118.59:8443"); // 1
  session.start(); // 2

Recall that the Bambou layer provides an object-oriented approach for us to manage our network objects in the VSD. Consider the Me object as the root of your network object hierarchy. In Line 3, we need to instantiate a Me object to serve as the root for all of our enterprise specific network objects.

  Me me = session.getMe(); // 3

Now that we have a Me root object, we can begin to build child objects and attach them. In lines 4 and 5, we initialize a new Enterprise object and give it a name. Finally, in Line 6, we attach the new Enterprise object to our root Me Object.

  Enterprise enterprise = new Enterprise(); // 4
  enterprise.setName("HelloEnterprise"); // 5
  me.createChild(enterprise); // 6

Behind the scenes, as our Java code was executed, REST calls were constructed by the Spring Framework and sent to the VSD, where our session was authenticated and our new Enterprise resource was created. If the code completed successfully, you will see an update in VSA.

VSA home page with enterprise

Goodbye Enterprise

Let’s be a good citizen and clean up the VSD. Here is another Java program to remove the Enterprise that we just created:

import net.nuagenetworks.bambou.RestException;
import net.nuagenetworks.vspk.v4_0.Enterprise;
import net.nuagenetworks.vspk.v4_0.Me;
import net.nuagenetworks.vspk.v4_0.VSDSession;
import net.nuagenetworks.vspk.v4_0.fetchers.EnterprisesFetcher;

public class DeleteHelloEnterprise {
  public static void main(String[] args) throws RestException {
    VSDSession session = new VSDSession
        ("csproot", "csproot", "csp", "https://135.121.118.59:8443"); // 1
    session.start(); // 2
    Me me = session.getMe(); // 3
    String filter = String.format("name == '%s'", "HelloEnterprise"); // 4
    EnterprisesFetcher fetcher = me.getEnterprises(); // 5
    Enterprise enterprise =
        fetcher.getFirst(filter, null, null, null, null, null, true); // 6
    enterprise.delete(); // 7
  }
}

Lines 1 through 3 should be very familiar, since they are identical to the lines at the start of CreateHelloEnterprise.java. Then in Line 4, we construct a name filter so that we can search for Enterprise HelloEnterprise among other existing enterprises in the VSD.

  String filter = String.format("name == '%s'", "HelloEnterprise"); // 4

In Line 5, we execute the getEnterprises() method on the Me object to return a collection of all Enterprise objects in the VSD. The object type actually returned is EnterprisesFetcher, which supports various operations for searching and fetching from a collection of Enterprises.

  EnterprisesFetcher fetcher = me.getEnterprises(); // 5

In Line 6, we apply the name filter against the collection of Enterprises to return a reference to our HelloEnterprise resource. Then, in Line 7 we execute a typical CRUD-styled method to delete the entity from the VSD.

  Enterprise enterprise =
    fetcher.getFirst(filter, null, null, null, null, null, true); // 6
  enterprise.delete(); // 7

Once again, REST calls were constructed by the Spring Framework and sent to the VSD, where our session was authenticated and our Enterprise resource was deleted. If the code completed successfully, you will no longer see the Enterprise in VSA.

VSA home page without enterprise

Next steps

We’ve covered the basics of using the VSPK-Java library. This is just one of the tools available from Nuage Networks for the management of your SDN. Network objects can be generated directly using the VSA, through REST calls from a browser, from Python, etc. The VSPK-Java library offers a viable alternative for customers with expertise or a preference for Java solutions.

For additional Java examples, please check here.