DSMT User Guide

Getting Your Application Distributed GettingYourApplicationDistributed

The steps to use DSMT are:

have PI create a managed node (or, make an existing node 'managed')
select the deployment system you're using
load your application into the deployment repository
specify the node selection rules you wish
watch your application be installed and run

Using dsmtc to run an rpm on 10 randomly selected PlanetLab nodes and keep selecting nodes until 10 are running, the steps look like:

# Assuming the PI has created a slice 'my_slice' for user 'me@example.com'
> dsmtc --cli --slice my_slice
dsmtc me@example.com [user] my_slice> manage
dsmtc me@example.com [user] my_slice> depot put my-application.rpm
dsmtc me@example.com [user] my_slice> setagent --agent deployment-agent
dsmtc me@example.com [user] my_slice> plan set --plan goodNodes --base minus left=all_nodes right=failed
dsmtc me@example.com [user] my_slice> plan set --plan only10 --base limit parent=goodNodes count=10
dsmtc me@example.com [user] my_slice> setplan --plan only10
dsmtc me@example.com [user] my_slice> 
dsmtc me@example.com [user] my_slice> status
...

DSMT is for building a service on PlanetLab. A service is made up of instances that run on multiple PlanetLab nodes. Independent of these instances is a (possibly distributed) Service Planner. The Service Planner makes placement and control decisions for the overall service. For instance, the service planner would decide that, because of an increased load on the service, new instances need to be created.

DSMT does not implement a Service Planner -- later versions will include the tools for building these (this is an interesting research area that we hope will be filled by someone) but it does provide a command line interface for an individual to act as the service planner. Additionally, DSMT includes a Container Manager that can allocate and install the service instances on PlanetLab nodes. For instance, the Container Manager can install a service on 10 geographically dispersed PlanetLab nodes and re-install the instances and nodes go down.

Creation of Slice CreationofSlice

PlanetLab requires a slice to be created by a site's principle investigator ("PI"). If you don't know the PI for your site, visit the PlanetLab institiutions page.

There are two ways to create a slice that will be managed by DSMT: the PI can use the dsmtc command to create a managed slice or the user can use the dsmtc command to make an existing slice managed.

PI Creation of a Managed Slice PICreationofaManagedSlice

After installing dsmtc, the PI creates the slice with:

dsmtc create --user PIACCOUNT --password PIPASSWORD --role PI 
         --user SLICEUSER --slice SLICENAME

This will create the slice named SLICENAME and add the PlanetLab user SLICEUSER to it. The SLICEUSER must be specified as the person the PI is creating the slice for. This will allow that user to ssh to the slice.

Making an Existing Slice Managed MakinganExistingSliceManaged

If the site's PI has already created a slice for a user, that user can make the slice managed by DSMT with the command:

dsmtc manage -slice SLICENAME

Setting Accounts and Passwords SettingAccountsandPasswords

dsmtc requires accounts and passwords for access to PlanetLab for the user. There are two of these: the PlanetLab account name and password (the ones the user uses to log into PlanetLab) and the public/private key pair that is associated with the PlanetLab account.

The PlanetLab account and password can be entered everytime dsmtc is used. The parameters are:

dsmtc op --user ACCOUNT --password PASSWORD --role user otherParameters

One can save this input by creating a file named $HOME/.slices. This file contains:

account: planetlabuser@user.example.com
password: PASSWORD
role: user

Where planetlabuser@user.example.com and PASSWORD are replaced with your account specifics. Once this file is created, it will be read by dsmtc every time it is run.

dsmtc also uses the PlanetLab account's public/private key to provide additional authorization. Invoking dsmtc will ask for the passphrase for the private key associated with the PlanetLab account's key. dsmtc currently does not use ssh-agent so the passphrase must be entered every time.

Preparing Application PreparingApplication

The installation of your application on the PlanetLab nodes is done by the installation agent you set. These are instructions for using deployment-agent. The steps will be different for other installation agents.

deployment-agent will take your application in two ways: as your own rpm package or as a tarball that is converted into an installable rpm with rpmgen.

Once the rpms are created, they are uploaded to the repositry using the dsmtc depot commands.

Deploying Your Application RPM DeployingYourApplicationRPM

Deploying Your Application with <cdoe>rpmgen</cdoe> DeployingYourApplicationwithrpmgen

rpmgen takes an application tarball and some scripts that start and stop the application and creates an rpm for the managed applicaiton.

One way of building your application is to place the application in a deployment tree and add to that tree the files start.sh stop.sh and status.sh.

Assume the application is named pinger and it will be installed, on the PlanetLab nodes, in the directory /usr/local. We create the tar file that, in part, contains:

tar -tzf pinger-1.8.tgz
pinger-1.8/
pinger-1.8/pinger
pinger-1.8/start.sh
pinger-1.8/stop.sh
pinger-1.8/status.sh
...

The start.sh and stop.sh scripts start and top the application while status.sh returns the status of the application and, specificly, returns the exit code of zero if the application is healthy and non-sero if something is wrong.

Then the following invocation of rpmgen would create the deployable application.

rpmgen --installdir /usr/local --file pinger-1.8.tgz 
           --start /usr/local/pinger/start.sh 
           --stop /usr/local/pinger/stop.sh 
           --status /usr/local/pinger/status.sh

This invocation of rpmgen will create the files pinger-1.8.i386.rpm and dsmtw_pinger-1.8.i386.rpm. These files are then uploaded to the deployment repository with the following dsmtc commands:

dsmtc depot put pinger-1.8.i386.rpm
dsmtc depot put dsmtw_pinger-1.8.i386.rpm

You can view the contents of the repository with dsmtc depot ls.

Selecting Nodes Selecting Nodes

Once you have your application in the repository, you give the container-mgr the selection of PlanetLab nodes to add to the slice. Several examples of this is given in the DSMTC Reference Guide.

Here are some examples of node selection:

Selecting all nodes:

dsmtc setplan --plan all_nodes

Selecting 10 random nodes. Here we define our own plan ("only10") and then set it to the slice.

dsmtc plan set --plan only10 --base limit count=10
dsmtc setplan --plan only10

Selecting 10 nodes but removing nodes that 'fail'. This uses the 'failed' set which collects nodes that timeout for various reasons. This creates the set 'goodNodes' which are all the nodes minus the failed ones, then chooses 10 from that set.

dsmtc plan set --plan myFailed --base failed
dsmtc plan set --plan goodNodes --base minus left=all_nodes right=myFailed
dsmtc plan set --plan only10GoodNodes --base limit parent=goodNodes count=10
dsmtc setplan --plan only10GoodNodes

One can select nodes based on geographic location, operational status and more complex rulesets by using query systems like SWORD . Refer to the DSMTC Reference Guide for detailed descriptions of all the functions available.

Monitoring Deployment MonitoringDeployment

As the containers are created and the application is installed, status events are created. These status events are sent over PsEPR and can be received by anyone listening to the status channels.

The DSMTViewer is an application that listens to the messages and displays the status of the application as it is installed. As each of the components are instantiated, initialized and set running, the status will be displayed as going from yellow to green. The architecture guide has a section describing all the components and their installation status as well as giving a detailed list of all the events that will be output as the application is installed.

Monitoring Application MonitoringApplication

Once the application is installed, the deployment-agent periodically invokes /etc/init.d/dsmtw_APPNAME.sh status to get the status of the application. (Of course, "APPNAME" is replaced with the name of the application.) If this script has the exit status of zero, the application is happily running. If the exit status is non-zero, the application has failed for some reason. This will cause the deployment-agent to send out 'failed' events. Advanced application service planners can see this and change the appliction operation. This will also cause the 'running' timeout in the container-manager failed rule .

This does not preclude the application having it's own status reporting and operation management function.