For the last 9 months, I've been silently working on a little pet project. It's finally ready to be released in to the wild and to be used by one and all for creating Python-based SDN Applications for the HP VAN SDN Controller.
Introducing the hp-sdn-client
When I started working with the HP VAN SDN Controller (while it still had a cool code name) it became immediately apparent to me that extending the controller with Java applications is not for everyone. There's lots of heavy lifting to be done with things like Maven, OSGi and Remote Debugging. Not only that, but I am not a "Java guy" (or was not until recently to be more exact) and being able to rapidly prototype applications in Python appealed to me.
The HP VAN SDN Controller's REST API exposes a large amount of the functionality available to the Java API with the exception of handling OpenFlow Packet-In, Packet-Out events. For a large number of applications this is absolutely fine, and this is where I hope this library will be useful.
The library is licensed under the Apache 2.0 license so it's free for all to use. The source is hosted on GitHub, and while I retain the right to be BDFL (Benevolent Dictator For Life) contributions are welcome!
How it works
So my library is designed with a single goal in mind:
To make interacting with the HP VAN SDN Controller REST API easy.
I am a huge believer in getting the API right and so I started working on the API design first until I found something that I think is easy to use.
import hpsdnclient as hp
controller = '10.44.254.129'
# Set up Authentication
auth = hp.XAuthToken(user='sdn',password='skyline', server=controller)
# Create an API object
api = hp.Api(controller=controller, auth=auth)
#API calls are then just a method call using "natural language"
datapaths = api.get_datapaths()
for datapath in datapaths:
flows = api.get_flows(datapath.dpid)
for flow in flows:
print "This is a flow from {} to {} on DPID: {}".format(flow.eth_src,
flow.eth_dst,
datapath.dpid)
In the background, the library handles Token management, HTTP Requests and Deserialization/Serializtion of JSON/Python Objects.
No matter how good and API is, it's useless without documentation. All of the API Documentation can be found on the documentation site
A quick note on datatypes
When the objects are de-serialized from JSON, they are mapped to an object from hpsdnclient.datatypes. These datatypes are not only used for de-serilaization, but they can also be serialized too... One of the biggest issues I've seen from people using the REST API is "What is the right JSON for this resource?". The Python objects in the hpsdnclient.datatypes library offer an abstraction so the user doesn't need to worry about getting the JSON right, they just manipulate a standard Python Object. For example, I can create a flow like this:
# Assuming you already have an instance of the `Api` object called `api`...
from hpsdnclient.datatypes import Match, Action, Flow
match = Match(eth_type="ipv4", ipv4_src=ip)
action = Action(output=1)
flow = Flow(priority=30000, match=match, actions=action, hard_timeout=30)
api.add_flows("00:00:00:00:00:00:00:01", flow)
Getting Started
Full installation instructions are available here Installation is easy if you have a working Python 2.7 install:
pip install hp-sdn-client
I've noticed on some systems that the dependencies weren't correctly installed.If you have this issue you can:
pip install distribute requests
Once you have everything installed, you can follow the Quick Start tutorial
Found a bug?
If something breaks, raise an issue on GitHub and make sure to give an example of what it was you were trying to do and the full stack trace.
Call for Contributors
If you know Python and are interested in contributing, check out the Trello and ping me on the Twitterz if you need help getting started.
There are a few items on the immediate roadmap: - Improving Documentation - Implement a Cache (based on Cache-Control HTTP Header) - Integration/Functional Test coverage for OpenFlow 1.3 - CI integration
Your first application using the hp-sdn-client library
If you are new to Python and are looking at writing and SDN application using this library then please bear in mind that your application is running externally to the SDN controller. This means that you are responsible for providing a UI for you application. This can be a simple console application, or a fully-fledged web application.
Fortunately Python has a wide variety of frameworks and libraries to get you started. Here are some of my personal favourites:
- Console Applications
- Web Applications
- GUI Applications
Conclusion
If you are considering writing an application or even a prototype for the HP VAN SDN Controller, I hope you find this library useful! If you need help or advice feel free to reach out to me using the links on the sidebar of my blog.
@dave_tucker