<?xml version="1.0"?>
<!--
  User's Guide  Chapter
  $Header$

  <chapter>
    <title>Title of the chapter</title>
    <filename>Filename of the chapter</filename>
    <shortname>Shortname for the chapter</shortname>
    <stylesheet>stylesheet filename (optional)</stylesheet>
    <scripts>script filename (optional)</scripts>
    <contents>
      <section>
        <title>Heading of the section</title>
        <tag>Tag used to reference (optional)</tag>
        <updated>Date last updated</updated>
        <contents>
          Contents of the section.
          May include either HTML within paragraphs ("p")
          or more section's
        </contents>
      </section>
    </contents>
  </chapter>
  
-->
<chapter
	xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
	xmlns:h="http://ww.w3.org/1999/xhtml" 
	>
	<r:revisions xmlns:r="http://psepr.org/schemas/servcomp/revisions-1.0.xsd">
		<r:revision>
			<r:version>1.1</r:version>
			<r:person>Robert Adams</r:person>
			<r:date>2005-05-18</r:date>
			<r:changes>Corrected details in the event list example.</r:changes>
		</r:revision>
		<r:revision>
			<r:version>1.0</r:version>
			<r:person>Robert Adams</r:person>
			<r:date>2005-05-16</r:date>
			<r:changes>Initial version</r:changes>
		</r:revision>
	</r:revisions>
  <title>DSMT Architecture Guide</title>
  <filename>DSMTArch.php</filename>
  <shortname>DSMTArch</shortname>
  <contents>
    <section>
      <title>Overview</title>
      <tag>Overview</tag>
      <contents>
        <p>
          The Distributed Service Management Toolkit ("DSMT")
          provides the framework and tools to
          install, monitor and control a distributed
          application on
          <a href="http://planet-lab.org/">PlanetLab</a>.
          It uses the
          <a href="http://psepr.org/">PsEPR eventing service</a>
          to move status messages and commands between
          instances of an application and to monitor
          it's installation and operation.
        </p>
        <p>
          DSMT does not solve all the problems of control
          of a distributed application.
          Deciding where to locate the application or 
          how to recover from a sudden increase in application
          demand needs application specific knowledege.
          DSMT provides some simple solutions but also
          provides the structure for adding solutions for
          the specific application.
        </p>
        <p>
          DSMT is focused on creating and managing distributed, long running
          services with particular focus on decentralized operation.
          Additionally, people who have built long running, fault resilient
          services have had to invest large amounts of their effort to build
          status, monitoring and repair of their services. 
        </p>
        <p>
        DSMT provides:
        <ol>
          <li>
            tools that enable new users to quickly get their applications
            running on PlanetLab
          </li>
          <li>
            a framework and initial tools for deployment and management;
          </li>
          <li>
            libraries and command for connecting an application to PlanetLab
            slice management, resource allocation, management and control;
          </li>
          <li>
            Libraries and commands for monitoring and controlling the
            distributed application or service.
          </li>
        </ol>
        </p>
        <p>
          In particular, DSMT provides the following items:
          <ol>
            <li>
              PsEPR: Event service for location independent, loosely-bound
              application command and control;
            </li>
            <li>
              DSMTC: a command line interface to slice creation and
              application installation.
            </li>
            <li>
              Container Manager: A resource manager who creates and monitors
              PlanetLab sliver application containers;
            </li>
            <li>
              Deployment agent: An application installation service and
              monitoring component;
            </li>
            <li>
              DSMTViewer: A visualization and reporting system for monitoring
              and controlling the application
            </li>
          </ol>
        </p>
        <p>
          This toolkit has to straddle several conflicting goals: to provide a
          complete startup kit for users while at the same time not proscribing
          a solution or building a non-extensible, monolithic deployment
          application.  It does this by creating a simple solution for the
          overall problem built from smaller, reusable components.
        </p>
        <p>
          There are some projects to develop execution environment provisioning
          and application deployment tools
          (these are discussed in the
          <ref t="PlanetLabDeploymentPackageComparison">
          PlanetLab Deployment Comparison
          </ref>
          section.
          DSMT focuses more on the application needs and
          the lifetime management of the application rather than just the
          get-it-there-and-run-it problem that is addressed in part by these
          tools.
        </p>
      </contents>
    </section>
    <section>
      <title>Architecture</title>
      <tag>Architecture</tag>
      <contents>
        <section>
          <title>Distributed Application Model</title>
          <tag>DistributedApplicationModel</tag>
          <contents>
            <p>
              The toolkit is geared to loosely-coupled, 
              long lasting, distributed
              applications.  
              This means applications that consist of many instances of it
              that runs in different virtual 
              machines on different computers scattered around the planet.  
              In practical terms, this means that the application must
              choose PlanetLab nodes to run on, 
              install itself on those nodes and then
              operate in the ever changing resource environment 
              that is the Internet.
            </p>
            <section>
              <title>Loosely-Coupled</title>
              <tag>LooselyCoupled</tag>
              <contents>
                <p>
                  DSMT promotes a distributed application that 
                  is loosely-coupled.  
                  This means that the separate instances of the 
                  application do not tightly bind to each
                  other with either tight state synchrony 
                  requirements or required stimulus/response handshakes.
                </p>
                <p>
                  Consider the organs in your body  
                  the pancreas does not make a call to the
                  liver for something to happen and wait for an ACK.  
                  Instead, the pancreas puts out messages in the 
                  bloodstream staying things are this way.  
                  The liver is listening to the blood stream and it hears 
                  the pancreass report.  
                  The liver starts to do things differently and it 
                  eventually puts messages in the blood
                  stream as a consequence if its actions.  
                  Any organ in the body can hear the liver but they dont 
                  necessarily know the message if from the liver but they do
                  know if the message they see requires their action.
                </p>
                <p>
                  This is similar to chalk board or bus architectures but, 
                  as applied to application design, it means that 
                  instances of an application dont talk
                  directly to each other.  
                  Instead, each instance evaluates the environment
                  (which includes messages from the other instances) 
                  and decides on individual, necessary operations.
                </p>
                <p>
                  Another dimension of loosely-coupled operation
                  is demonstrated in the design of most multi-tier'ed
                  web server solutions.
                  It is now general practice to not tightly
                  couple the layers (by, for instance, using
                  a call/return type link to move control through
                  the tiers) but to loosely-couple the layers
                  with message queues between them with 
                  "state-less" linkage.
                </p>
                <p>
                  DSMT provides tools for this type of application 
                  by providing a loosely-coupled command and control 
                  messaging system and tools for managing distributed state.  
                  In particular, a service named the Planetary Scale Event
                  Propagation and Routing (PsEPR pronounced pepper) 
                  provides an event transport service moves small, 
                  XML event messages between different components of the
                  application.
                </p>
                <p>
                  Using PsEPR, application components emit PsEPR 
                  events stating their intentions, wishes and status.  
                  Other components of the application receive
                  these events and change their operation based on 
                  the distributed state of the other components.
                </p>
              </contents>
            </section>
            <section>
              <title>Decentralized</title>
              <tag>Decentralized</tag>
              <contents>
                <p>
                Consider a service that is made up of 10 instances.  
                Each of these instances can perform the operation 
                of the whole service but, since there are 10, the
                application can quickly handle requests from different 
                parts of the world, can survive the crash of one or 
                more hosting computers and can adapt to changing
                resource availability.
                </p>
                <p>
                  more stuff about how to build applications
                </p>
              </contents>
            </section>
            <p>
              
            </p>
          </contents>
        </section>
        <section>
          <title>Instance Installation Steps</title>
          <tag>Instance InstallationSteps</tag>
          <contents>
          </contents>
        </section>
        <section>
          <title>Client Components</title>
          <tag>ClientComponents</tag>
          <contents>
            <p>
              The client is built from several different layers
              of control.  
              First a manager for the container -- the virtual
              machine or the 'sliver' in PlanetLab terminology.
              Within the container, a deployment agent is 
              installed.
              This third component, the deployment agent,
              manages the installation and running of the application.
            </p>
            <p>
              Each of these three components are installed on
              the client and there is, at least conceptually,
              a components that monitors the installation of
              the component.
              These <i>installation monitors</i> report the
              installation progress with
              <ref t="StatusMessages">status messages</ref>.
            </p>
            <p>
              This organization is shown in the following diagram.
            </p>
            <div>
              <center>
                <img src="images/ClientLayers.jpg" alt="Client layers"/>
              </center>
            </div>
            <p>
              To be precise, this is merely a conceptual structure.
              The status reporting will look like it comes from a
              structure like this, but, for instance, the bottom
              most installation monitor cannot output the 'request'
              event because the client container has not been
              created yet.
              These details, though, should only be a concern to
              framework implementers.
            </p>
          </contents>
        </section>
        <section>
          <title>Status Messages</title>
          <tag>StatusMessages</tag>
          <contents>
            <p>
              Each of the <code>install monitors</code> in the
              client, which are monitoring the installation of
              the components above them, output status messages
              that report the state of the installation of the
              component above.
            </p>
            <p>
              A components goes through the following states
              as it is installed:
              <center>
              <img src="images/InstallationStates.jpg"
                alt="Installation states"/>
              </center>
              These states are definied as followed:
              <ul>
                <li>requested:</li>
                <li>instantiated:</li>
                <li>initialized:</li>
                <li>running:</li>
                <li>failed:</li>
                <li>terminated:</li>
                <li>undefined:</li>
              </ul>
            </p>
            <p>
              Referring to the 
              client layer's diagram,
              it was described how the install monitors each monitor
              the installation of the component above them.
              Once that component is installed and running, the next
              component above is installed and the install monitor
              tracks the status of that installation.
            </p>
            <p>
              Since each of the install monitors output 
              <psepr>PsEPR</psepr>
              messages as the installation state changes,
              anyone listing on the installation status channel
              will see messages first about the installation of the
              client container manager
              (messages from <code>org.dsmt.component.slice-mgr</code>)
              then there will be messages about the installation of 
              the deployment agent
              (messages from <code>org.dsmt.component.slice-bootstrap</code>)
              then messages about the installation of the application
              itself
              (messages from
              <code>org.dsmt.component.deployment-agent</code>)
              .
            </p>
            <p>
              Since the container manager is also outputing messages
              about what it thinks of the status of the container
              installation, a complex series of messages are available
              to display the state of the application installation.
            </p>
            <p>
              The following table lists all the <psepr>PsEPR</psepr>
              messages one should see when an application is
              being installed.
              Presume that a service planner has commanded
              the system to install the application XYZ onto
              five random PlanetLab nodes using the slice named xyz1.
              The following messages should occur.
            </p>
            <table border="1" cellpadding="0px" cellspacing="0px">
              <tr>
                <th>Event</th>
                <th>Description</th>
              </tr>
              <eventList>
                <attributeClass>installDetailT</attributeClass>
                <valueClass>installDetail</valueClass>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-mgr/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-mgr</av>
                      <av>managed=org.dsmt.component.container</av>
                      <av>slice=xyz1</av>
                      <av>status=requested</av>
                    </avpairs>
                  </value>
                  <description>
                    For each of the selected nodes, one will see
                    the initial 'requested' messages.
                  </description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-mgr/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>>hostname=planet-lab1.stanford.edu</av>
                      <av>component=org.dsmt.component.sliver-mgr</av>
                      <av>managed=org.dsmt.component.container</av>
                      <av>slice=xyz1</av>
                      <av>status=requested</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-mgr/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab3.cs.cmu.edu</av>
                      <av>component=org.dsmt.component.sliver-mgr</av>
                      <av>managed=org.dsmt.component.container</av>
                      <av>slice=xyz1</av>
                      <av>status=requested</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-mgr/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>d: deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab-1.cn</av>
                      <av>component=org.dsmt.component.sliver-mgr</av>
                      <av>managed=org.dsmt.component.container</av>
                      <av>slice=xyz1</av>
                      <av>status=requested</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <ev-description>
                    For brevity, the messages after this are for one
                    host only.  There will be similar messages for each
                    of the nodes as they are initialized
                  </ev-description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-mgr/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>d: deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-mgr</av>
                      <av>managed=org.dsmt.component.container</av>
                      <av>slice=xyz1</av>
                      <av>status=instantiated</av>
                    </avpairs>
                  </value>
                  <description>
                    after requested, 'instantiated' means the code has
                    been loaded onto the node.
                  </description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-mgr/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-mgr</av>
                      <av>managed=org.dsmt.component.container</av>
                      <av>slice=xyz1</av>
                      <av>status=initialized</av>
                    </avpairs>
                  </value>
                  <description>
                    initialized reports that the managed code has been
                    unpacked and configured and is ready to run
                  </description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-mgr/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-mgr</av>
                      <av>managed=org.dsmt.component.container</av>
                      <av>slice=xyz1</av>
                      <av>status=running</av>
                    </avpairs>
                  </value>
                  <description>
                    the managed code is now in the running state.
                  </description>
                </event>
                <event>
                  <ev-description>
                    Now, the managed component
                    (<code>org.dsmt.component.container</code>)
                    is installed and running.
                    It starts managing the container and also starts the
                    installation of the deployment-agent.
                    Events about the status of that installation will now
                    be seen.
                  </ev-description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-bootstrap/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-bootstrap</av>
                      <av>managed=org.dsmt.component.deployment-agent</av>
                      <av>slice=xyz1</av>
                      <av>status=requested</av>
                    </avpairs>
                  </value>
                  <description>
                    The deployment agent has been requested to 
                    be installed.
                  </description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-bootstrap/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-bootstrap</av>
                      <av>managed=org.dsmt.component.deployment-agent</av>
                      <av>slice=xyz1</av>
                      <av>status=instantiated</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-bootstrap/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-bootstrap</av>
                      <av>managed=org.dsmt.component.deployment-agent</av>
                      <av>slice=xyz1</av>
                      <av>status=initialized</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-bootstrap/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-bootstrap</av>
                      <av>managed=org.dsmt.component.deployment-agent</av>
                      <av>slice=xyz1</av>
                      <av>status=installed</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.sliver-bootstrap/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.sliver-bootstrap</av>
                      <av>managed=org.dsmt.component.deployment-agent</av>
                      <av>slice=xyz1</av>
                      <av>status=running</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <ev-description>
                    The deployment-agent is now installed and running.
                    It waits for an APPCONFIG message that tells it
                    what application should be on this node.
                    Once that information is received, it 
                    starts the installation of the application
                    and the installation monitor outputs status events
                    tracking this installation.
                  </ev-description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.deployment-agent/command/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>status</field>
                  <value>
                    APPCONFIG,planetlab5.nbgisp.com,XYZ,XYZ-proc
                  </value>
                  <description>
                    The service planner outputs these messages to
                    inform the nodes which applications should be running
                    on them.
                  </description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.deployment-agent/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.deployment-agent</av>
                      <av>managed=XYZ</av>
                      <av>slice=xyz1</av>
                      <av>status=requested</av>
                    </avpairs>
                  </value>
                  <description>
                    The deployment-agent for the node has received
                    the mapping of the application to the node
                    and this event says that the request is being
                    processed.
                  </description>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.deployment-agent/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.deployment-agent</av>
                      <av>managed=XYZ</av>
                      <av>slice=xyz1</av>
                      <av>status=instantiated</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.deployment-agent/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.deployment-agent</av>
                      <av>managed=XYZ</av>
                      <av>slice=xyz1</av>
                      <av>status=initialized</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <channel>/org/dsmt/ns/deployment/xyz1/org.dsmt.component.deployment-agent/status/</channel>
                  <service>xyz1_mgr</service>
                  <payload>http://psepr.org/ns/payload/attribute</payload>
                  <field>deployment-status</field>
                  <value>
                    <avpairs>
                      <av>hostname=planetlab5.nbgisp.com</av>
                      <av>component=org.dsmt.component.deployment-agent</av>
                      <av>managed=XYZ</av>
                      <av>slice=xyz1</av>
                      <av>status=running</av>
                    </avpairs>
                  </value>
                </event>
                <event>
                  <ev-description>
                    The application is now up and running.
                  </ev-description>
                </event>
              </eventList>
            </table>
          </contents>
        </section>
      </contents>
    </section>
    <section>
      <title>PlanetLab Deployment Package Comparison</title>
      <tag>PlanetLabDeploymentPackageComparison</tag>
      <contents>
        <p>
          There are several packages that assist in the deployment
          and operation of applications on PlanetLab.
          This table is a feature comparison of the major packages.
          This does not compare some of the command line toolsets
          like pssh, ...
        </p>
        <table>
          <tr>
            <th></th>
            <th><a href="">appmanger</a></th>
            <th><a href="">stork</a></th>
            <th><a href="">plush</a></th>
            <th><a href="">emulab</a></th>
            <th><a href="">pldeploy</a></th>
            <th><a href="http://dsmt.org/">DSMT</a></th>
          </tr>
          <tr>
            <td>allocates nodes [<a href="#Note1">1</a>]</td>
            <td>.</td> <td>.</td> <td>.</td> <td>.</td> <td>.</td> <td>.</td>
          </tr>
          <tr>
            <td>selects nodes [<a href="#Note2">2</a>]</td>
            <td>.</td> <td>.</td> <td>.</td> <td>.</td> <td>.</td> <td>.</td>
          </tr>
          <tr>
            <td>changes</td>
            <td>.</td> <td>.</td> <td>.</td> <td>.</td> <td>.</td> <td>.</td>
          </tr>
          <tr>
            <td>centralized control</td>
            <td>.</td> <td>.</td> <td>.</td> <td>. </td> <td>.</td> <td>.</td>
          </tr>
        </table>
        <ol>
          <li><a name="Note1"/>Contacts PLC and adds node to the slice as
            opposed to the user manually performing this operation</li>
          <li><a name="Note2"/>Performs a selection of nodes for the slice
            based on some criteria</li>
        </ol>
      </contents>
    </section>
  </contents>
</chapter>
<!-- vim: tabstop=2 shiftwidth=2 autoindent expandtab
-->

