Introduction

This document will guide you through the process of creating a slice and deploying a service in that slice.

Some general concepts are important. A slice is set of PlanetLab virtual machines allocated to a service. The slice is created through PlanetLab Central using either the web interface or the "plslice" tool. A slice is properly thought of as a container in which your service can be placed. A cog is one module of a service. It is general a single, self-contained package that will be executed inside one or more virtual machines in the slice. The local control structure is the set of directories created by pldeploy where information about a service is stored. The local control structure contains the code for each of the cogs, a mapping of cogs to virtual machines, virtual machine specific configuration information, and possibly data collected from the machines.

The following sequence of steps will deploy a service on a set of PlanetLab nodes:

1. create a PlanetLab slice
2. create the local control structure for the slice
3. add a cog to the local control structure
4. add the cog to the nodes in the slice
5. deploy the service
6. start and manage the service

These steps are explained in detail below.

Create a Planetlab slice

The "plslice" tool can be used to create a slice on PlanetLab using the following sequence of steps.

1. Create a file called ".slices" in your home directory with the following configuration information:

   account: your planetlab web account
   password: your planetlab web account password

2. Create a PlanetLab slice. Only principal investigators can create a PlanetLab slice. To use plslice to create the slice, run the following command:

   plslice createslice --slice name>

3. Add users to the slice (make sure you add yourself):

   plslice adduser --user planetlab web account

4. Add nodes to the slice. Three variants of plslice can be used to add nodes to the slice: one node at a time, a file that contains a list of nodes, or all nodes in PlanetLab. See the documentation for plslice for more information. To add a single node, use the following command:

   plslice addnode --node planetlab node

Actual slice creation can take several minutes after the request has been queued.

Create the local control structure

Once you have created a slice, the pldeploy tool will help you build, deploy, and manage your service within the collection of virtual machines. The first step is to create the local control structure. To do that, create a directory to hold the local control structure and execute the command

pldeploy createslice --slice name

The following are created:

root/SD	file with configuration information
root/Cogs	directory in which cog code is placed
root/Nodes	directory where node configuration and data is placed
root/Sliver	root directory pushed to all nodes
root/Sliver/PLServiceCntl	control application for a virtual machine

Add a cog to the local control structure

Once the framework is created, you can create a cog that will be deployed in your slice. You can create a cog with pldeploy using the command from within the slice directory:

pldeploy createcog --cog name

The following are created:

root/Cogs/cog	directory for code to be deployed in the slice
root/Cogs/cog/PLCogCntl	control application

Add a cog to nodes in the slice

Initially a cog is not assigned to any node. You can assign it to a node with the following pldeploy command:

pldeploy add --cog cog --node node

The node parameter can be specified multiple times, as a file (--node @<file>), or as standard input (--node --). For example, you could assign a cog to all nodes in the slice with the following command:

plslice listslice --slice s --node | pldeploy add --cog c --node --

When you assign a cog to a node, the following directories are created in the local control structure:

root/Nodes/cog/node	node-specific data for the cog
root/Nodes/cog/node/OUTBOUND	data pulled from the virtual machine

Deploy the service

Once you have created the local directory structure, populated it with cogs, and assigned the cogs to nodes, you can deploy the result on PlanetLab using the following command:

pldeploy deploy

For every node that has at least one cog assigned to it, the deploy command performs the following steps (note that root is on the local control machine while slice is on a PlanetLab node):

1. Copy the root/Sliver directory and its contents into the directory slice/PL on the PlanetLab virtual machine. The slice directory is generally /home/slice in the virtual machine.
2. For every cog assigned to the node, copy the contents of root/Cog/cog to the directory slice/PL/Cogs/cog in the virtual machine. After that is complete, the contents of root/Nodes/cog/node are copied to slice/PL/Cogs/cog in the virtual machine. This enables node specific configuration information to be placed in root/Nodes/cog/node.

Start/control the service

Once the structure has been pushed out to the virtual machines in the slice, pldeploy can be used to control the service with the start, stop, status, clean, and pull commands. For exmaple, to start the service on a node use the command:

pldeploy start --cog cog --node node

Both cog and node parameters are optional. If the cog parameter is missing, all cogs on the node(s) will be started. If the node parameter is missing, the cog will be started on all nodes. If neither is specified, all cogs will be started on all nodes.

The start command for a cog and a node uses ssh to execute the following command on the node:

slice/PL/PLServiceCntl start --cog cog

The default behavior for PLServiceCntl is to invoke the start command on each of the specified cogs:

slice/PL/Cogs/cog/PLCogCntl start

You can edit PLServiceCntl and PLCogCntl to change the default behavior, for example to invoke an operation that will actually start the service in a cog.