Changes between Version 21 and Version 22 of SPIDocs


Ignore:
Timestamp:
Sep 24, 2014 11:16:35 AM (8 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • SPIDocs

    v21 v22  
    3434  A realization is the binding of resources to an experiment.  Users can inspect and modify such bindings in carrying out their experiments.
    3535
    36 We describe each of these in more detail below.
     36We describe each of these in more detail below.  They are interrelated and the descriptions link to one another in this document.  We intend for readers to jump between sections to help intuition.
    3737
    3838=== The Implementation ===
     
    305305
    306306||= Permission Name =||= Meaning =||
    307 || ADD_USER || Request that a user be added to the project or confirm a request by a user to join the project ||
    308 || CREATE_CIRCLE ||Create a new circle in the project's namespace (a name prepended by ''projectid'':)||
    309 || CREATE_EXPERIMENT ||Create a new experiment in the project's namespace (a name prepended by ''projectid'':) ||
    310 || CREATE_LIBRARY || Create a new library in the project's namespace (a name prepended by ''projectid'':) ||
    311 || REMOVE_USER || Remove a user from the project.  Any objects they have created in the project's namespace remain ||
     307|| ADD_USER || This user may request that a user be added to the project or confirm a request by a user to join the project ||
     308|| CREATE_CIRCLE || This user may create a new circle in the project's namespace (a name prepended by ''projectid'':) ||
     309|| CREATE_EXPERIMENT || This user may create a new experiment in the project's namespace (a name prepended by ''projectid'':) ||
     310|| CREATE_LIBRARY || This user may create a new library in the project's namespace (a name prepended by ''projectid'':) ||
     311|| REMOVE_USER || This user may remove a user from the project.  Any objects they have created in the project's namespace remain ||
    312312
    313313
     
    316316A user creates a project using the `createProject` operation on the `Projects` [wiki:SPIDocs#Services service].  Mechanically, the procedure to create a project is very similar to [wiki:SPIDocs#CreatingNewUsers creating a user].  An application will:
    317317
    318  * User the `getProfileDescription` operation on the `Projects` service to get an empty project profile
     318 * Call the `getProfileDescription` operation on the `Projects` service to get an empty project profile
    319319 * Gather data from the user to fill in the project description, including non-optional fields and proper formatting
    320320 * Call the `createProject` with a project name from the user and that user as the project's owner.  (Administrators can create projects owned by other users).
     
    366366The key distinction between the two kinds of user groups is that a project confers access to the testbed resources in the large based on delegation of trust.  A circle confers rights to specific experiments and libraries.  Project membership is a prerequisite to accessing the testbed at all; circle memberships control access to specific abstraction instances inside the testbed.
    367367
    368 Once the testbed administration has palced their trust in a user through the project abstraction, they are free to collaborate without any further significant administrative oversight through the circles system.
     368Once the testbed administration has placed their trust in a user through the project abstraction, they are free to collaborate without any further significant administrative oversight through the circles system.
    369369
    370370Projects and circles are related.  Each project has a linked circle that contains all the users who are members of the project.  The system keeps that circle and project membership synchronized.  One can think of assigning the rights to manipulate experiments and libraries to projects as existing Emulab code does.  Under the covers it is the linked circle that conveys the rights.
     
    391391
    392392||= Permission Name =||= Meaning =||
    393 || ADD_USER || Request that a user be added to the project or confirm a request by a user to join the project ||
    394 || REALIZE_EXPERIMENT ||Allocate resources to an experiment and carry it out so that it is accessible to the members of this circle ||
    395 || REMOVE_USER || Remove a user from the project.  Any objects they have created in the project's namespace remain ||
     393|| ADD_USER || This user may yequest that a user be added to the project or confirm a request by a user to join the project ||
     394|| REALIZE_EXPERIMENT ||This user may allocate resources to an experiment and carry it out so that it is accessible to the members of this circle ||
     395|| REMOVE_USER || This user may remove a user from the project.  Any objects they have created in the project's namespace remain ||
    396396
    397397The `REALIZE_EXPERIMENT` permission means that a user can carry out an experiment under this circle.  This means members of the circle will:
     
    402402==== Creating A Circle ====
    403403
    404 A user creates a circle using the `createCircle` operation on the `Circless` [wiki:SPIDocs#Services service].  Mechanically, the procedure to create a project is very similar to [wiki:SPIDocs#CreatingNewUsers creating a user] or [wiki:SPIDocs#CreatingAProject project].  An application will:
    405 
    406  * User the `getProfileDescription` operation on the `Circles` service to get an empty circle profile
    407  * Gather data from the user to fill in the project description, including non-optional fields and proper formatting
     404A user creates a circle using the `createCircle` operation on the `Circles` [wiki:SPIDocs#Services service].  Mechanically, the procedure to create a project is very similar to [wiki:SPIDocs#CreatingNewUsers creating a user] or [wiki:SPIDocs#CreatingAProject project].  An application will:
     405
     406 * Call the `getProfileDescription` operation on the `Circles` service to get an empty circle profile
     407 * Gather data from the user to fill in the circle profile, including non-optional fields and proper formatting
    408408 * Call the `createCircle` with a project name from the user and that user as the project's owner.  (Administrators can create projects owned by other users).
    409409
     
    446446
    447447These are documented below.
     448
     449== Experiments ==
     450
     451The ''experiment'' abstraction encapsulates the [wiki:SPIDocs#TheFundamentalAbstractions layout, procedure, data requirements, and constraints] on an activity a researcher using to play with ideas or test a hypothesis. An experiment is realized by DETERLab into an environment that meets those requirements.  Realizing an experiment allocates resources in the testbed and grants access to the members of the [wiki:SPIDocs#Circles circle] in which the experiment is realized.
     452
     453Experiments are the unit of testbed activity that are shared between users for understanding ideas and reproducing results.
     454
     455The layout, procedure, data requirements and constraints on an experiment are sub-abstractions of an experiment called ''aspects''.  An experiment does not necessarily contain all aspects.  When a researcher first comes to DETERLab, their models and ideas are likely to be loosely defined.  We expect them to realize experiments that have only layout aspects.  As their ideas become more concrete and their results more stable, the other aspects become more fleshed out.
     456
     457The SPI treats aspects as first class objects that can be directly manipulated.  Users can add or remove them from experiments, and aspects interact with one another.  One can specify a data gathering or procedure aspect that is inconsistent with the layout aspect, and the SPI will find the discrepancy.
     458
     459Internally, aspects are plug-in modules of code, written to a well-defined interface, that cooperate to
     460
     461 * Generate experiment realizations
     462   * Build layouts for experimentation and data gathering
     463   * Control virtualization and simulation implementations
     464   * Create layouts in the underlying hardware
     465 * Orchestrate experiments
     466   * Carry out procedures
     467   * Collect data from experiments
     468 * Present data
     469   * Collect datasets
     470   * Visualize ongoing and completed experiments
     471
     472To support the ongoing research in all these areas, and in areas we do not know about yet, the aspect interfaces are open, and the SPI implementation can easily import code written to it.  We expect to add SPI interfaces to dynamically add an aspect implementation to a running testbed.
     473
     474Because research on individual aspects is ongoing, the SPI presents fairly generic interfaces to them.  Each aspect is specified by a type, sub-type and name.  The operation of the aspect is controlled by a data block (often a file) attached to the (type, sub-type, name). The meanings of sub-types, names, and the interpretation of data blocks within aspects are controlled by the aspect.  Below we present a worked example of the layout aspect that illustrates this.
     475
     476Experiments also have [wiki:SPIDocs#Profiles profiles] attached to them so that other users can understand the purpose and goals of a project without investigating the aspects in detail.
     477
     478==== Experiment Names ====
     479
     480Like [wiki:SPIDocs#CircleNames circles], experiments are named within the scope of either a user (prefixed by userid) or project (prefixed by projectid).  The right to create an experiment in a project is controlled by the `CREATE_EXPERIMENT` [wiki:SPIDocs#ProjectPermissions project permission].
     481
     482==== Experiment Permissions ====
     483
     484As with other abstractions, access to experiments is controlled by permissions.  These permissions are assigned to circles rather than individual users.  Because each user is the sole member of an immutable circle named ''userid'':''userid'' permissions can be assigned per-user by assigning to that circle.  Similarly, assigning to the ''projectid'':''projectid'' circle assigns permissions to all members of a project.
     485
     486The permissions relevant to project are:
     487
     488||= Permission Name =||= Meaning ||
     489|| MODIFY_EXPERIMENT || Circle members can change aspects of an experiment ||
     490|| MODIFY_EXPERIMENT_ACCESS || Circle members can change the permissions of other circles ||
     491|| READ_EXPERIMENT || Circle members can read experiment aspects and information bout access control ||
     492
     493Experiments are realized in circles.  A user may realize an experiment - alloate resources to it and set it running - if that user holds the `REALIZE_EXPERIMENT` [wiki:SPIDocs#CirclePerimssions permission] to the circle and the `READ_EXPERIMENT` permission to the experiment.
     494
     495==== Creating A New Experiment ====
     496
     497A user creates a circle using the `createExperiment` operation on the `Experiments` [wiki:SPIDocs#Services service].  Mechanically, the procedure to create a project is very similar to [wiki:SPIDocs#CreatingACircle creating a circle] or [wiki:SPIDocs#CreatingAProject project], though aspect data is also included.  An application will:
     498
     499 * Call the `getProfileDescription` operation on the `Experiments` service to get an empty experiment profile
     500 * Gather data from the user to fill in the experiment profile, including non-optional fields and proper formatting
     501 * Call the `createExperiment` with an experiment name from the user and that user as the experiment's owner.  (Administrators can create projects owned by other users).  Additionally, initial aspect definitions and initial access control lists may be specified.
     502
     503When `createExperiment` returns the experiment can be further manipulated.  An experiment with no access control lists and no aspects is a valid experiment.   Experiment owners always implicitly have all permissions to the experiment as well as the rights to control ownership and profile contents.
     504
     505Because we expect some researchers to build some experiments incrementally from scratch, experiments are very liberal about their contents.  While an experiment with no access control lists and no aspects is valid, it is not very interesting to realize it until it has some aspects.
     506
     507A user can also specify all the experiment aspects and access control lists when `createExperiment` is called.
     508
     509==== Adding and Changing Experiment Aspects ====
     510
     511A user that is a member of a circle that has the `MODIFY_EXPERIMENT` [wiki:SPIDoc#ExperimentPerimissions permission] on an experiment can add or remove aspects from that experiment.  The operation to add aspects is `addExperimentAspects` in the `Experiments` service.  Changing existing aspects is done through `changeExperimentAspects`.
     512