Changes between Version 7 and Version 8 of NewAPI


Ignore:
Timestamp:
Jun 26, 2013 3:38:33 PM (11 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • NewAPI

    v7 v8  
    3131== DETER Testbed API ==
    3232
    33 The testbed API manipulates a few entities to provide the experimentation environment.  We begin with a section detailing those entities conceptually and then discuss the specific actions that the API allows on them.
    34 
    35 === Testbed Entities ===
    36 
    37 ==== Users ====
     33The testbed API manipulates a few entities to provide the experimentation environment.  This section discusses the key abstractions of the testbed API and how they work together to create an experimental environment.
     34
     35=== Users ===
    3836
    3937A '''user''' is a researcher who uses the DETER testbed.  They request testbed services and allocate testbed resources.  Users are the actors that make things happen through test testbed API.
    … …  
    5856A user identifies themselves to the testbed API by proving that they hold a specific public/private keypair.  An initial such keypair is issued when the user is created, and a user can acquire another valid pair at any time by proving they know their password.  Generally those pairs are short-lived to guard against loss or theft, but the password is administered using local testbed policies.
    5957
    60 ==== Projects ====
     58=== Projects ===
    6159
    6260Projects are groups of users.  They are used to confer rights to groups of users, identify groups of users, and control how resources are configured when experiments are realized on the testbed.  This is a more general use of projects than an Emulab testbed.
    … …  
    8482If a user is removed from all vetting projects, they return to a powerless state.
    8583
    86 ==== Resources ====
     84=== Resources ===
    8785
    8886Resources are the physical and conceptual objects managed by the testbed that are used to build experimental environments.  They are the computers, network ports, externally routable addresses, virtual machine images, et al. from which experiments are constructed.
    … …  
    9997In addition, the membership in projects controls how resources will be configured.  A resource in use by a particular project will generally be configured to be accessible to all members of that project.  A student who allocates resources as a member of a small design group while implementing a class project may later allocate resources as a member of the whole class when presenting the work to the class's TA and professor.
    10098
    101 ==== Experiments ====
     99=== Experiments ===
    102100
    103101All of the testbed API is ultimately geared toward the creation of experiments.  An experiment is:
    … …  
    122120 * Initializing and supporting an experiment control system like MAGI to carry out the experiment's procedure, police invariants, and gather data.
    123121
     122These last three bullets construct the environment for experimentation.  We call that process ''realizing'' the experiment.
     123
    124124In order to support experiments that are making minimal use of experiment control systems, the API allows a user to manipulate a realized experiment, including
    125125
    … …  
    128128
    129129These interfaces use filtering and graph analysis to present useful views of large experiments.
     130
     131When realizing the experiment, the testbed uses the containers API to configure and control the hardware and software that create the environment.
     132
     133== The Containers API ==
     134
     135The containers API is responsible for allocating resources to an experiment and configuring that hardware in ways appropriate for the user's goals - realizing it.
     136
     137The key abstraction for realizing an experiment is the '''container'''.  A container holds some of a physical resource's computational and networking power and uses it to create part of the experiment at a level of realism appropriate to the researcher's goals.  A researcher who is interested in end-system behavior will not put very much computational power into realizing the routers that forward packets, but a lot into realizing end systems.
     138
     139The containers API coordinates:
     140
     141 * Allocating the resources from the testbed's pool of resources
     142 * Configuring the physcial resources to realize the experiment
     143 * Partitioning the computational and networking power of each resource into appropriate realizations
     144
     145This API supports communication between the testbed control system and the containers that make up an experiment being realized (and after it is realized).
     146
     147=== General Containers ===
     148
     149A clear kind of container is a computer running a virtual machine monitor that partitions its CPU resources between virtual machines.  This is a very useful kind of container, but not the only one.  The containers interface is intended to support new forms of computer virtualization, efficient network simulation, or new kinds of physical hardware that can be part of testbeds.
     150
     151To support these goals operations that the testbed can perform on a container are ''simple'' and ''can be specialized''.  In particular, the operations guaranteed to work on any container are:
     152
     153 Start::
     154  Begin operating as an experiment element. (For a computer, boot; for a flux capacitor, begin travelling in time)
     155 Stop::
     156  Become quiescent.  Only containers API requests will work on a stopped container
     157 Describe::
     158  Tell the testbed what the container's state is, extended operations the container supports, the configuration format to use, and resources allocated to it
     159 Configure::
     160  Set up the container's internal state.  (For a computer, establish accounts and mount filesystems; for a flux capacitor, set travel rate and destination date)
     161 Clean::
     162  Undo the effects of any Configure commands
     163
     164A container can be in the following states:
     165
     166 Down::
     167  The container is in communication with the testbed, but not yet configured to act as an experiment element
     168 Configured::
     169  The container is set up to act as an experiment element but is not yet doing so
     170 Pinned::
     171  The container is not acting as an experiment element, but is carrying out an operation that renders it otherwise unusable.  For example, a container that is capturing its state may be in this state.
     172 Up::
     173  The container is acting as an experiment element
     174 None::
     175  Nothing is known about the container. is is (as yet) unresponsive.
     176
     177Containers report state in response to a {{{describe}}} operation and can also spontaneously report changes in state to the testbed.
     178
     179Generally a container's life cycle looks like:
     180
     181 * Container starts in None state.
     182 * Hardware boots, containers code begins running on the resource, when that code comes up the container is Down and reports this state to the testbed.
     183 * The testbed asks the container to describe itself and sends an appropriate contfiguration request
     184 * When the configuration is successful the container moves to Configured and reports it
     185 * When the testbed tells the contatiner to start, it reports when it comes up and changes its state to Up. At this point, if an experiment control system like MAGI was part of the configuration, that system will take over running any experiment procedure.
     186 * When the experiment (or a phase of the experiment is done) the testbed can issue a Stop to the container, which will move to Configured.
     187
    130188
    131189=== Putting It All Together ===