Changes between Version 4 and Version 5 of NewTestbedAPISpec


Ignore:
Timestamp:
Jun 27, 2013 5:37:15 PM (11 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • NewTestbedAPISpec

    v4 v5  
    239239Filters are cumulative: specifying a regular expression and an owner will match on both.
    240240
    241 == Manipulating Projects ==
     241=== Manipulating Projects ===
    242242
    243243With appropriate rights a user can add another user to a project they are in:
     
    301301   * None
    302302
    303 === Manipulating Projects ===
     303=== Creating and Deleting Projects ===
    304304
    305305Non-vetting projects can be created and deleted with little overhead:
     
    368368
    369369And then the admin adds the requesting user to the project makes them owner and removes themselves.
     370
     371== Experiments ==
     372
     373The experiment interface controls managing experiment definitions and realizing experimnets (allocating and initializing resources). The experimnet definition is in some flux, which is reflected in this section.
     374
     375=== Viewing Experiments ===
     376
     377One or more experiments can be viewed by an authorized user assuming that user has the proper permissions.  The creator of a project owns it and that userid scopes its name.  That is an experiment's name is a pair: (owner, name).  This allows experiments to be instantiated in different projects.
     378
     379
     380 * '''Service:''' Experiments
     381 * '''Operation:''' viewExperiments
     382 * '''Input Parameters:'''
     383   * Userid - the user making the request
     384   * ExperimentRE - a string containing a regular expression matched against project names (may be omitted)
     385   * Owner - a string holding the owner of experiments to find (may be omitted)
     386   * Components - a 32-bit integer containing a mask of fields to include
     387     * EXPERIMENT_TOPOLOGY - include the topology
     388     * EXPERIMENT_ACTIONS - include the actions
     389     * EXPERIMENT_CONSTRAINTS - include constraints
     390     * EXPERIMENT_DATACOLLECTION - include data collection
     391     * EXPERIMENT_RESOURCES - include resources needed or allocated
     392     * EXPERIMENT_CONTAINERS - include components if realized
     393     * EXPERIMENT_LOG - include realization log and fault
     394     * EXPERIMENT_PERMISSIONS - include project permissions
     395   * TopologyFormat - an optional 32-bit int naming the topology format
     396     * TOPOLOGY_TOPDL - return a topdl file
     397     * TOPOLOGY_NS2 - return an ns2 file
     398   * TopologyFilter - an optional filter for limiting scope of the topology file format TBD
     399   * ActionFormat - an optional 32-bit int naming the action file format (values TBD)
     400   * ActionFilter - an optional filter for limiting scope of the constraint file format TBD
     401   * ConstraintFormat - an optional 32-bit int naming the constraint format (values TBD)
     402   * ConstraintFilter - an optional filter for limiting scope of the constraint file format TBD
     403   * DataCollectionFormat - an optional 32-bit int naming the data collection format (values TBD)
     404   * DataCollectionFilter - an optional filter for limiting scope of the data collection file format TBD
     405   * ResourceFilter - an optional filter for limiting scope of the resouces returned format TBD
     406   * ContainerFilter - an optional filter for limiting scope of the constainers returned format TBD
     407
     408 * '''Return Values:'''
     409   * One or more structures with the following fields
     410     * Name - a string containing the experiment name
     411     * Owner - a string containing the owner's userid
     412     * Project - an optional string. If present the experiment is realized under this project
     413     * Topology - an optional file describing the experiment topology subject to filters and format constraints
     414     * Actions - an optional file describing the experiment actions subject to filters and format constraints
     415     * Constraints - an optional file describing the experiment constraints subject to filters and format constraints
     416     * DataCollection - an optional file describing the experiment data collection subject to filters and format constraints
     417     * Containers - an optional list with the following fields describing the containers in the experimnet, if it is realized. Subject to filtering.
     418       * Name - the container name
     419       * State - a string indicating state (Up, Down, Configured, Pinned, None)
     420       * Type - a string indicating the container type
     421     * Resources - an optional list of structures giving resources needed by or allocated to the experiment, subject to filtering.
     422       * Name - resource name
     423       * Type - resource type
     424     * State - a string, one of
     425       * "Unrealized", "Realized", "Changing", "Pinned" (Pinned means that some modification other than realization is underway)
     426     * StateDetail - a string giving additional state information.  values TBD
     427     * Log - an optional file containing messages from the last realization attempt for debugging
     428     * FaultInfo - an optional structure containing the high level error message (if any) from the last realization.  It contains the error fields from a DeterFault:
     429        * ErrorCode - a 32-bit integer encoding the type of error.  Constants are available in the [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/DeterFault.html javadoc for DeterFault].  Values are:
     430          * access - access denied
     431          * request - bad request
     432          * internal - internal server error
     433        * ErrorString - a string describing the broad error
     434        * DetailString - a string describing the details that caused the error
     435     * ReadProjects - a list of project names allowed to read this experiment
     436     * WriteProjects - a list of project names allowed to modify this experiment
     437     * RealizeProjects - a list of project names allowed to realize this experiment
     438
     439=== Creating and Deleting Experiments ===
     440
     441An experiment is created using:
     442
     443 * '''Service:''' Experiments
     444 * '''Operation:''' createExperiment
     445 * '''Input Parameters:'''
     446   * Userid - the user making the request (the owner on success)
     447   * Name - a string containing a new experiment's name
     448   * Topology - an optional file describing the experiment topology
     449   * Actions - an optional file describing the experiment actions
     450   * Constraints - an optional file describing the experiment constraints s
     451   * DataCollection - an optional file describing the experiment data collection
     452   * ReadProjects - a list of project names allowed to read this experiment
     453   * WriteProjects - a list of project names allowed to modify this experiment
     454   * RealizeProjects - a list of project names allowed to realize this experiment
     455 * '''Return Values:'''
     456   * None
     457
     458An experiment is modified using:
     459
     460 * '''Service:''' Experiments
     461 * '''Operation:''' modifyExperiment
     462 * '''Input Parameters:'''
     463   * Userid - the user making the request (the owner on success)
     464   * Owner - the experiment owner
     465   * Name - a string containing the experiment's name
     466   * Topology - an optional file describing the experiment topology
     467   * Actions - an optional file describing the experiment actions
     468   * Constraints - an optional file describing the experiment constraints s
     469   * DataCollection - an optional file describing the experiment data collection
     470   * ReadProjects - a list of project names allowed to read this experiment
     471   * WriteProjects - a list of project names allowed to modify this experiment
     472   * RealizeProjects - a list of project names allowed to realize this experiment
     473 * '''Return Values:'''
     474   * None
     475
     476Omitted arguments are not overwritten.  To delete a field supply an empty description.
     477
     478There will also be filter-based modification interfaces, but these are TBD.
     479
     480An experiment is deleted using:
     481 
     482 * '''Service:''' Experiments
     483 * '''Operation:''' removeExperiment
     484 * '''Input Parameters:'''
     485   * Userid - the user making the request (the owner on success)
     486   * Owner - the experiment owner
     487   * Name - a string containing the experiment to delete
     488 * '''Return Values:'''
     489   * None
     490
     491After {{{removeExperiment}}} succeeds, experiment state is removed from the testbed completely.
     492
     493=== Realizing and Releasing Experiments ===
     494
     495To realize an experiment use:
     496 
     497 * '''Service:''' Experiments
     498 * '''Operation:''' realizeExperiment
     499 * '''Input Parameters:'''
     500   * Userid - the user making the request (the owner on success)
     501   * Owner - the experiment owner
     502   * Name - a string containing the experiment to realize
     503   * Notify - a flag, if true send the user a notification when realization is complete
     504 * '''Return Values:'''
     505   * None
     506
     507The user can either poll the experiment using {{{viewExperiments}}} and examining the {{{StateDetail}}} field or poll for a notification that the realization is complete.
     508
     509If the realization fails - as indicated by the {{{State}}} variable in a {{{viewExperiments}}} response, the {{{Log}}} and {{{FaultInfo}}} fields characterize the error.
     510
     511To release an experiment's resources:
     512
     513 * '''Service:''' Experiments
     514 * '''Operation:''' releaseExperiment
     515 * '''Input Parameters:'''
     516   * Userid - the user making the request (the owner on success)
     517   * Owner - the experiment owner
     518   * Name - a string containing the experiment to release
     519   * Notify - a flag, if true send the user a notification when realization is complete
     520 * '''Return Values:'''
     521   * None
     522
     523After {{{releaseExperiment}}} succeeds, experiment state remains in the testbed, but containers are stopped and resources are returned to the testbed.