Creating drivers with Node Agent component

Overview

Drivers with Node Agent components require two parts - the part that is executed on the substrate by the Node Agent and the part residing in site authority that instructs the Node Agent to perform actions on the substrate. The part residing with the site authority is generally referred to as 'driver client'.

Fully testing drivers with node agent components requires setting up a Node Agent and creating a security association with it, described in Handler-Testing.

You can use the sample driver template to get started on writing a new Orca driver. The driver template consists of 3 projects:

  • core
    • specifies the API for all drivers of the given family, e.g., drivers for creating virtual machines
    • provides ANT tasks that invoke the driver API
  • specific device driver implementation
    • contains the implementation of a specific driver from the device family, e.g, a driver that creates Xen virtual machines
  • tests
    • contains tests for the driver and its ant taske

Setting up directory structure and generating driver GUID

To use the template to generate a working skeleton for your driver do the following:

1. Make a work directory

mkdir scratch

2. Download the template

cd scratch
svn export https://geni-orca.renci.org/svn/orca/drivers/template/trunk template
mv template/convert.sh .

3. Edit the conversion script.

The following variables must be changed:

DEST=test
DEVICE_FAMILY=test
DEVICE_FAMILY_PREFIX=Test
VERSION=1.0-SNAPSHOT
FAMILY_NAME='Orca Test Device'
DEVICE_INSTANCE=testdevice
DEVICE_INSTANCE_PREFIX=TestDevice
DEVICE_INSTANCE_GUID=4d739173-8588-42b3-b301-b744e978de25
INSTANCE_NAME='Orca Test Device Driver'
TESTS_NAME='Orca Test Device Driver Tests'
  • DEST - top level directory for your driver, e.g., mydriver
  • DEVICE_FAMILY - package name for the driver family. The full package name will become: orca.drivers.${DEVICE_FAMILY}, e.g, mydriver
  • DEVICE_FAMILY_PREFIX - prefix to use for class file names for the driver family, e.g., MyDriver?
  • VERSION - you can leave it as it is
  • FAMILY_NAME - name you want to use in the pom for the driver family
  • DEVICE_INSTANCE - package name for the specific device. The full package name will become: orca.drivers.${DEVICE_FAMILY}.${DEVICE_INSTANCE}, e.g, mydevice
  • DEVICE_INSTANCE_PREFIX - prefix to use for class file names for the specific device, e.g., MyDevice?
  • DEVICE_INSTANCE_GUID - guid for your device driver. NOTE: you must generate a new one.
  • INSTANCE_NAME - name you want to use in the pom for the specific device
  • TESTS_NAME - name you want to use in the pom for the device family tests

4. After you modify the template settings, invoke the script

bash convert.sh

5. The script will generate a new directory ($DEST). You can compile the generate code by doing:

cd ${DEST}
mvn install

Testing the driver

Once you have coded all the tasks, it is time to test them. Testing drivers is a multi-layered process that includes:

  1. Running unit-tests built into the code. This is strongly recommended. Please familiarize yourself with JUnit framework.
  2. Creating and invoking a handler script to invoke the tasks and pass appropriate parameters to them. This begins the process of integration of the driver with policies and is described in the next section. See handler testing for more information.

Running unit tests on drivers

Each driver should contain a number of unit tests. Please familiarize yourself with JUnit and create a number of tests for your new driver.

To run unit tests on the driver you need to install it on in a node-agent service. Orca provides two helper projects to simplify this process:

  • orca/tools/config/trunk - contains tools to install and configure a node agent service
  • orca/tools/drivers/trunk - contains tools to simplify the installation of drivers

You will need to check out orca/tools/config/trunk and follow the instructions listed on this page. Once you have installed your node agent, you will need to check out orca/tools/drivers/trunk and add a link to the runtime directory from the config project, e.g.:

cd ORCA_TOOLS_DRIVERS_DIR
ln -s -f ORCA_TOOLS_CONFIG_DIR/runtime

Finally, you will need to add a link to the driver tools project in the top-level directory of your newly generated driver:

cd ${DEST}
ln -s -f ORCA_TOOLS_DRIVERS_DIR tools

The template assumes that your node agent is running on the localhost on port 6. If this is not the case with your setup you will need to do the following:

cd ${DEST}/$DEVICE_INSTANCE/ant
cp tests.properties user.properties

Edit user.properties and specify the location and port of your node agent service. Place a copy of the resulting file in ${DEST}/tests/ant

Once you have successfully run mvn install in ${DEST}. You can install the driver by:

cd $DEVICE_INSTANCE
ant install

To run the unit tests for the driver:

cd tests
ant copy.local   (do this to make sure log4j will log to a file)
ant tests.device

To test the ant tasks:

cd tests
ant -f test.xml clean
ant -f test.xml greet