[[TOC]]

= DETER Containers API =

The containers API is a set of simple and extensible operations to control testbed elements.  It is primarily a way for the testbed control to communicate with experiment elements. As such it is not usually visible to users.  For power users we do supply a passtrough interface so that they can access specializations of containers.

== Testbed to Containers Operations ==

Each of these is sent to a container controller with a distinct address.  A controller is often responsible for more than one container.  In general we attempt to scale the number of controllers with the number of physical resources so that the testbed can communicate with them directly.  In very large testbeds, there may be interconnected controllers acting as relays.

All the control commands can be applied to multiple containers simultaneously.

There are only a few things all containers can do:

Begin operating as an experiment element. For a computer, boot; for a flux capacitor, begin travelling in time:

 * '''Service:''' Containers
 * '''Operation:''' start
 * '''Input Parameters:'''
 * '''Input Parameters:'''
   * NameRE - an optional list of regular expressions to match against container names
   * Types - a list of container types to restrict the operations to
 * '''Return Values:'''
  * None

Become quiescent. Only containers API requests will work on a stopped container

 * '''Service:''' Containers
 * '''Operation:''' stop
 * '''Input Parameters:'''
   * NameRE - an optional list of regular expressions to match against container names
   * Types - a list of container types to restrict the operations to
 * '''Return Values:'''
  * None

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).  Configuration can be a multi-step process to facilitate configuring many containers at once.  A base configuration can be distributed broadly and sub-configurations passes to specialized elements.  The semantics of combining configurations can vary per-container-type, but are generally a sequential application of configurations.

 * '''Service:''' Containers
 * '''Operation:''' configure
 * '''Input Parameters:'''
   * NameRE - an optional list of regular expressions to match against container names
   * Types - a list of container types to restrict the operations to
   * ConfigData - an opaque field used to configure the container
   * Commit - a flag indicating that this is the configuration is complete and the container can begin applying it
 * '''Return Values:'''
  * None

Containers can describe themselves.  Again, controllers can collapse multiple like containers into one operation.

 * '''Service:''' Containers
 * '''Operation:''' describe
 * '''Input Parameters:'''
 * '''Input Parameters:'''
   * NameRE - an optional list of regular expressions to match against container names
   * Types - a list of container types to restrict the operations to
 * '''Return Values:'''
  * An array of structures with the following fields
   * Names - an array of strings naming containers
   * Type - a string giving the container type
   * ConfigFormat - the configuration format that the container supports
   * Interfaces - a list of pre-defined extension interfaces supported by the container.  If "custom" is given ExtendedOps is required
   * ExtendedOps - an optional list of URIs from which the WSDL for custom extended operations can be gathered