Context Navigation

Changes between Version 35 and Version 36 of NewTestbedAPISpec

Timestamp:: Jul 25, 2015 6:58:18 PM (9 years ago)
Author:: faber
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

NewTestbedAPISpec

-                      v35
+                      v36
 == Resources ==
+Resources are things that make up experiments.  There are several specialized resources used in experimentation that have their own suite of operations, and there is a general set of operations for future expansion.
+=== Computers ===
+Computers are the physical computing resources of the testbed.  A user may be interested in specific instances of a computer - {{{pc23}}} - or in information about types or classes of computers.  Both are possible to view with these calls.
+A user can view computers or classes by:
+Resources are things that make up experiments. They are fairly generic at this point, though we expect to specialize them.  Currently system resources - like computers and VMs - are primarily manipulated by the testbed.  Like circles, resources have names scoped by user or project.  A user can create local resources in their namespace and the testbed creates resources in the admin or system namespaces.
+Users primarily see system resources when an experiment is realized.
+A resource consists a type, an optional description, zero or more facets, zero or more tags and an ACL that allows circle members to manipulate it.  Types are identifiers that control how the testbed and user can manipulate them.  Common resource types include "VM" and "computer".
+A resource encapsulates the ability to
+ * Compute
+ * Store data
+ * Communicate
+ * Sense the world
+ * Manipulate the world
+Each of those capabilities is described by a facet data structure attached to the resource.  A facet describes the available powers of a resource.  When a resource is realized inside another, the inner resource provides its facets by consuming the outer resource's facets.
+Tags are name value pairs associated with a resource or facet thereof.  They are a simple extension mechanism, akin to attributes in [wiki:LayoutAspect#ViewExchangeFormattopdlv2 topdl].
+Operations on resources include:
  * '''Service:''' Resources
+ * '''Operation:''' viewComputers
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Owner - an optional string the computer owner
+   * NameRE - an optional string containing a regular expression matched against the name
+   * Type - an optional string containing the computer types to look for
+ * '''Return Values:'''
+   * Zero or more structures with the following fields:
+     * Name - a string, the name of this computer, if absent this is a class
+     * Owner - a string, the owner of the computer or class
+     * Type - a string containing the type of computer
+     * Description - a string describing this computer or class
+     * Allocated - an optional flag indicating whether this computer is allocated.  The field is absent all together if this structure describes a class
+     * AllocatedExperiment - an optional string containing the experiment name if the computer is allocated and the user has the right to read the experiment
+     * AllocatedProject - an optional string containing the project name in which the experiment is realized if the computer is allocated and the user has the right to read the project
+     * ProjectDelete - an optional list of project names that can delete this resource
+     * ProjectModify - an optional list of project names that can modify this resource
+     * ProjectUse - an optional list of project names that can use this resource
+     * ProjectRead - an optional list of projects names that can read this resource
+If any of the permission fields are not present, the class permissions apply.  If they are present for a specific computer, they specific computer's permissions override the class permissions.
+Administrators can add new computers or classes using
+ * '''Service:''' Resources
+ * '''Operation:''' createComputer
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Name - an optional string, the name of this computer, if absent this is a class
+   * Type - a string containing the type of computer
+   * Description - an optional string describing this computer or class (If omitted for a computer, the type description is used)
+   * ProjectDelete - an optional list of project names that can delete this resource
+   * ProjectModify - an optional list of project names that can modify this resource
+   * ProjectUse - an optional list of project names that can use this resource
+   * ProjectRead - an optional list of projects names that can read this resource
+ * '''Return Values:'''
+   None
+Note that missing fields in a computer creation are generally filled in from the type.  Creating a computer or class without any projects that can use it is of questionable value.
+Similarly, they can modify an existing computer using (assuming they are in a project that allows modification of the class or computer):
+ * '''Service:''' Resources
+ * '''Operation:''' modifyComputer
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Name - an optional string, the name of this computer, if absent this is a class
+   * Type - an optional string containing the type of computer
+   * Description - an optional string describing this computer or class (If omitted for a computer, the type description is used)
+   * ProjectDelete - an optional list of project names that can delete this resource
+   * ProjectModify - an optional list of project names that can modify this resource
+   * ProjectUse - an optional list of project names that can use this resource
+   * ProjectRead - an optional list of projects names that can read this resource
+ * '''Return Values:'''
+   None
+Values passed in overwrite the current values if the user had modify rights.  One of Name or Type must be present.
+Finally an administrator can delete a computer:
+ * '''Service:''' Resources
+ * '''Operation:''' removeComputer
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Name - an optional string, the name of this computer, if absent this is a class
+   * Type - an optional string, the type of computer.  May be omitted for specific computers
+ * '''Return Values:'''
+   None
+=== Images ===
+Images are saved container state - including saved physical container state.  These are selected in the experiment definition, but users may need to manipulate them directly.
+To read image information:
+ * '''Service:''' Resources
+ * '''Operation:''' viewImages
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Owner - an optional string the computer owner
+   * NameRE - an optional string containing a regular expression matched against the name
+ * '''Return Values:'''
+   * Zero or more structures with the following fields:
+     * Name - a string, the name of this image
+     * Owner - a string, the owner of the image
+     * Description - a string describing this image
+     * ValidIn - a list of container types that can use this image
+     * ProjectDelete - a list of project names that can delete this resource
+     * ProjectModify - a list of project names that can modify this resource
+     * ProjectUse - a list of project names that can use this resource
+     * ProjectRead - a list of projects names that can read this resource
+Images are created by operations on a container, but users can modify or delete their metadata:
+ * '''Service:''' Resources
+ * '''Operation:''' modifyImage
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Name - a string, the name of this image
+   * Description - an optional string describing this computer or class
+   * ValidIn - an optional list of container types that can use this image
+   * ProjectDelete - an optional list of project names that can delete this resource
+   * ProjectModify - an optional list of project names that can modify this resource
+   * ProjectUse - an optional list of project names that can use this resource
+   * ProjectRead - an optional list of projects names that can read this resource
+ * '''Return Values:'''
+   None
+As with other resources, these values overwrite the existing parameters (except for name which is a selector).
+A user can delete an image:
+ * '''Service:''' Resources
+ * '''Operation:''' removeImage
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Name - a string, the image to remove
+ * '''Return Values:'''
+   None
+=== Pubkey ===
+Public/Private keypairs are used several places in the testbed for authentication and access.  For example, access to containers that present a computer interface is done using the ssh protocol.  These interfaces allow users to manipulate their keys.
+Viewing keys:
+* '''Service:''' Resources
+ * '''Operation:''' viewKeys
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Owner - an optional string the computer owner
+   * type - an optional string containing the kind of keys to report
+ * '''Return Values:'''
+   * Zero or more structures with the following fields:
+     * Name - a string, the name of this key
+     * Owner - a string, the owner of the key
+     * Description - a string describing this key
+     * KeyData - an opaque data value - the key data
+     * ProjectDelete - a list of project names that can delete this resource
+     * ProjectModify - a list of project names that can modify this resource
+     * ProjectUse - a list of project names that can use this resource
+     * ProjectRead - a list of projects names that can read this resource
+Users can add and delete keys:
+ * '''Service:''' Resources
+ * '''Operation:''' addKey
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Owner - an optional string the computer owner
+   * Name - an optional string, the name of this key (system will assign if omitted)
+   * Description - an optional string describing this key
+   * KeyData - an opaque data value - the key data
+   * ProjectDelete - a list of project names that can delete this resource
+   * ProjectModify - a list of project names that can modify this resource
+   * ProjectUse - a list of project names that can use this resource
+   * ProjectRead - a list of projects names that can read this resource
+ * '''Return Values:'''
+   * None
+ * '''Service:''' Resources
+ * '''Operation:''' removeKey
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Name - a string, the name of this key
+ * '''Operation:''' createResource
+String name, String type, Boolean persist, String description, ResourceFacet[] facets, ResourceTag[] tags, AccessMember[] accessLists
+ * '''Input Parameters:'''
+   * Name - a string, the scoped, unique identifier of the resource
+   * Type - a string, the resource type
+   * Persist - a boolean, true if the resource is independent of an experiment realization.  Non persistent resources resource disappear once bound to a realization and then released.
+   * Description - a string, an optional human readable description of the resource
+   * A list of zero or more facets that describe the capabilities and requirements of the resource.  Each facet includes
+    * A name, scoped by the resource
+    * A type (CPU, Storage, Communication, Sensing, Manipulation)
+    * A value, the real-valued amount of the type
+    * A units value that scales and defined the value
+    * Zero or more tags.
+  * An access control list
+ * '''Return Values:'''
+  * A boolean indicating success
 == Realizations ==