Discussions on design & implementation of Resources in 5.4¶

This is the 3rd iteration of this design document, which should include discussions up to January 2011.

The previous iterations are available here: 1st Iteration and 2nd Iteration

1. Definitions¶

• A resource: an asset that can be used in an experiment
  • Example of resources: a software application, a device (network, graphic, i/o), a yellow-box, a robot, a virtual machine (vm), etc...

• In the context of OMF resources:
  • a Slice : a collection of different resources which have been made available to the sole use of a project.
  • an Experiment: a collection of different resources available within a slice (i.e. a project) which are used to test a specific hypothese, or prototype, or algorithm,...
  • given resource may be part of 0 or 1 slice. Only when a resource is part of one slice, then it may be part of 0 or many experiments within that slice.

2. Design¶

2.1. Resource Basic Overview¶

2.1.1. Creation/Release - Parent/Child¶

• A resource can create another resource and is itself created by another resource. The exception is the "root" resources, which does not have a parent (e.g. the "testbed" resource is the root for an OMF deployment on a testbed).
• There is a parent/children hierarchical relationship between resources:
  • if resource A creates resource B, then A is the 'parent' of B and B is the 'child' of A.
  • therefore a resource can have 1 parent (except the root) and 0...N children.
• A resource can be released. In the context of OMF, a released resource is unavailable to any slice or experiment.
• A resource can be asked by another resource or an OMF entity to be released. However, only the resource itself knows if it is ok do to so (e.g. if it has finished whatever un-interruptible tasks it had to do). Thus a resource may accept or refuse to be released.
• Each resource must keep a record of its parent and its children.
• Motivation to have a parent/children relationship which derives from resource creation/release:
  • easier design of a resource discovery system (not part of this document).
  • a resource discovery system could "walk down" the parent/children tree to find out which resources exist.
  • similarly, one can browse the resources being used by an existing experiment by "walking down" the parent/children tree.

2.1.2. Naming¶

• A resources must have a unique name which identifies it.
• The parent (i.e. the creator) of a resource X must select and assign a name for the this resource X.
• A parent resource must keep a list of all the names of children resources it created and which have not yet released.
• A child resource must keep a record of its parent's name.

2.1.3. Communication¶

• A resource can receive and send messages.
• The communication between resources is asynchronous.
• A resource must have a primary address on which it may receive messages. In addition it may have multiple secondary addresses (or aliases) on which it may also receive messages.
• The parent (i.e. the creator) of a resource X must assign a primary address to X.
• The parent must keep a list of all the primary addresses for all the children resources it created and which have not yet released.
• A resource can send a message to any addresses.
• Important about name and address:
  • the name of a resource and its address are 2 different attributes of a resource.
  • the mapping of a resource's name's to its address is out of the scope of this document. Thus this design does not assume any relationship between the name and address of a resource.
  • the mapping of a name to/from address is the concern of a Resource Discovery system, not discussed in this document. For example, some implementation of resource discovery may decide to have the address derived from the name of a resource or have them completely uncorrelated.

• In the context of OMF resources:
  • OMF uses a Publish and Subscribe (PubSub) Asynchronous communication paradigm between all its entities. A 'PubSub node' is the board (aka group or point) where a message is sent and retrieved in the context of a PubSub system. OMF does not require a specific type/brand of PubSub system, currently XMPP-based pubsub is used.
  • In this context an address as described above is a PubSub node.
  • Thus a resource must subscribe to at least one primary PubSub node after its creation.
  • The parent (i.e. the creator) of a resource X must assign a primary PubSub node to X for it to subscribe to. If that primary PubSub node does not exist on the PubSub system, then the parent resource must request and ensure its creation before creating the resource.
  • The parent must subscribe to the primary PubSub node of the child that it creates.
  • Messages from/to a parent to/from a child must be published to the child's primary PubSub node.
  • Any resource may be requested to subscribe to other additional PubSub nodes during its lifetime, and may comply to this request. Thus a resource may subscribe to more than one PubSub node.

2.1.4. Properties¶

• A resource has some properties or attributes.
• A property has a name and an associated value. This value can be of many types.
  (e.g. 1, 2, 'text', a range [1,5], a set of constraints 'the ones that are blue', etc...)
• There are 2 types of properties:
  • static properties must be set at the resource's creation and are immutable.
  • dynamic properties can have their values changed throughout the resource's life. A resource may execute a predefined action when a given dynamic property has its value changed.
• All resources must have at least the following properties:
  • type (static): a string which holds the type of the resource
  • name (static): a string which holds the name of the resource
  • primaryAddress (static): an address (e.g. a PubSub node) which is the primary address subscribed to by the resource
  • parent (static): a string which holds the name of the resource's parent
  • children (dynamic): a list of pair (name, primaryAddress) for each child of this resource
    (this list can be empty if this resource has no children)
• All resources used in the context of OMF must have the following 2 properties:
  • sliceID (dynamic): a string which holds the ID of the slice within which this resource is available, can be empty if this resource is not associated to a slice
  • expID (dynamic): a string which holds the ID of the experiment within which this resource is currently used, can be empty if this resources is not used in any experiment

2.2. Resource Life-Cycle¶

2.1.1. Overview¶

• A resource has a life-cycle, which consists of 2 states: active and inactive
• A resource must receive a message to trigger its transition from a source state to a destination state. The source and destination state may be the same.
• An overview of the resource's state machine is described below. The next section will describe in details the format of the messages presented below.

* create was sent to parent resource; ** creates new child resource

2.1.2. Description in the context of OMF¶

• A resource X must be created by another resource Z (exception is the "root" resource). The life-cycle of X starts when Z receives a message create, asking for it to create the resource X.
• The values for the static properties of X must be given to its creator inside the create message. The creator must pass these values to X upon creation. The creation of X may fail if all its static properties are not set with valide values.
• INACTIVE state:
  • After its successful creation, X must be in the inactive state. In that state, X can only receive configure, request, activate or release messages.
  • When X receives a configure message, this message must contain a list of the names of the specific dynamic properties to update and their new values values. Upon reception of such a message, X must update the values of its mentioned properties accordingly. X may have some pre-defined tasks that can be triggered by the update of a specific dynamic properties. After updating the properties, X must publish a message on its PubSub node to inform on the outcome of the update.
  • When X receives a request message, this message is a request for information from X and must contain a description of what information from X is requested. X must publish a reply to this request on its PubSub node.
  • When X receives a activate message, it must transition into the active state. Once in the active state, X may start some pre-defined tasks triggered by fact that it enters this state. X must also publish a message on its PubSub node to inform its change of state.
  • When X receives a release message, it must check if it can be released or not. This check depends on the type of the resource, and may include checking that some properties have some specific acceptable values or that some tasks ran by X have completed. X must publish its decision of being released or not on its PubSub node. Then if it decided to be released, it may perform some cleaning tasks, and finally it must terminate itself.
• ACTIVE state:
  • In that state, X can receive the following messages: {create, execute, configure, request}
  • When X receives a create message, this message must contain a complete set of information for the creation of a child resource. Upon receiving this message, X must try to create a child resource according to this information. X must also publish on its PubSub node the outcome of this creation.
  • When X receives a execute message, this message must contain the name and the options for the command that X must try to execute. The list of commands that X understand depends on the type of X. For example, a robot-type of resource might understand commands like turn(angle) or move_forward(distance), or a P2P file transfer application-type of resource might understand commands like add_download(option) or stop_seeding(option).
  • When X receives a deactivate message, X must stop all of the tasks it started since entering the active state and it must then transition to the inactive state. X must also publish a message on its PubSub node to inform its change of state.
  • X's behaviours when receiving configure and request messages are similar to previously described in the inactive state above.

2.3. Description of Resource Messages and Protocol¶

• During its life-time, a resource must accept the following type of messages when they are published on an address (e.g. a PubSub node) to which it subscribes:
  • In an inactive state: configure, request, activate or release
  • In an active state: configure, request, deactivate, create, or execute

• During its life-time, a resource may publish the following type of messages to an address to which it subscribes:
  • In an inactive state: inform, or error
  • In an active state: inform, error, or event

• Resource Messages are XML stanzas.

• Thus in the context of OMF, entities exchange XML stanzas via a Publish and Subscribe communication medium. This PubSub medium may be provided by XMPP-based systems or other such as P2P-based PubSub systems.

2.3.1. General Message Format:¶

<body xmlns:omf="http://omf.mytestbed.net/omfprotocol">
    <omf:msg id="SomeUniqueID1">
        <aValidMessageType>
            ....
        </aValidMessageType>             
    </omf:msg>
    <omf:signature over="SomeUniqueID1" from="Sender's ID">
         SomeHashGoesHere
    </omf:signature>
    <omf:assertion id="SomeUniqueID2">
         ....
    </omf:assertion>
    <omf:signature over="SomeUniqueID2" from="Sender's ID">
         SomeHashGoesHere
    </omf:signature>
</body>

• The element omf:msg
  • contains the actual message being published in this XML stanza
  • must have an attribute id which has a unique value across all messages. For example, this value could be a Hash generated by the message's sender based on its unique ID and a timestamp.
  • must have a child element aValideMessageType, which must be any of: { create, release, activate, deactivate, configure, request, execute, inform, error, event }. The detailed syntax of these message types are given in the next sections

• The element omf:signature
  • is used for authentication
  • contains the signature of the message's publisher (attribute from) over a given element E of this message (attribute over)
  • must have a text value, which is the signature
  • the signature is a Hash over the entire text of the element E using the publisher's private key
  • the authenticity of element E can then be checked with the publisher's public key, which should be retrieved from a trusted authority
  • an OMF resource may choose not to enforce the authentification check on a given message (this is the choice of the resource's owner/operator)

• The element omf:assertion
  • is used for authorisation
  • must have an attribute id which has a unique value across all assertions
  • the exact syntax of the content (values or child elements) of an assertion has yet to be defined (- input from Max?)
  • basic idea: an assertion is a chain of statement with its root in a trusted entity, which has full rights on a resource X. Through the chain, this root delegates parts (or all) of these rights to this message's publisher. The message's recipient can check if the publisher has a given right on the resource X by verifying each step of that authorisation chain
  • an OMF resource may choose not to enforce the authorisation check on a given message (this is the choice of the resource's owner/operator)

2.3.2. Format of Messages accepted by a Resource¶

• create
  

  <create>
      <to>theParentResource</to>
      <name>resourceName</name>
      <type>resourceType</type>
      <address>primaryPubSubNode</address>
      <property>
          <key>somePropertyName1</key>
          <value> ... </value>
      </property>
      <property>
          <key>somePropertyName2</key>
          <value> ... </value>
      </property>
      ....
  </create>             
  

  • to - the unique name of the existing parent resource which will create the new resource
  • name - a unique name for the child resource that we would like to create
  • type - the type of resource that we wold like to create. A list of existing types could be maintained on mytestbed.net
  • address - the primary address (e.g. PubSub node) to which the newly created resource should subscribe to
  • property - (optional) none or many element(s). Each property element is used to configure a unique static property of the newly created resource
    • key - the unique name of the property to configure
    • value - the value to give to that property, this must be either a text, some number, or some child XML element

• release, activate, deactivate
  

  <release>
      <to>resourceName</to>
  </release>
  
  <activate>
      <to>resourceName</to>
  </activate>         
  
  <deactivate>
      <to>resourceName</to>
  </deactivate>                      
  

  • to - the unique name of the existing resource which this message is addressed to and which should be released, activated, or deactivated

• configure
  

  <create>
      <to>resourceName</to>
      <property>
          <key>somePropertyName1</key>
          <value> ... </value>
      </property>
      <property>
          <key>somePropertyName2</key>
          <value> ... </value>
      </property>
      ....
  </create>             
  

  • to - the unique name of the existing resource that we would like to configure
  • property - One or many element(s). Each property element is used to configure a unique dynamic property of the resource
    • key - the unique name of the property to configure
    • value - the value to give to that property, this must be either a text, some number, or some child XML element

• request
  

  <request>
      <to>resourceName</to>
      <query>
          ...
      </query>
      <query>
          ...
      </query>
      ....
  </request>             
  

  • to - the unique name of the existing resource that we would like to request information from
  • query - One or many element(s). Each query element is used to ask the resource about a given piece of information
  • the simplest form of query is to request the value of a given property of the resource:
    

    <query><key>somePropertyName</key></query>
    

  • more complex query can be made to the resource: Input from Max on how to represent such queries should go here

• execute
  

  <execute>
      <to>resourceName</to>
      <command>aCommandName</command>
      <option>
        <key>someOption1</key><value>someValue1</value>
      </option>
       <option>
        <key>someOption2</key><value>someValue2</value>
      </option>
      ...   
  </execute>             
  

  • to - the unique name of the existing resource which should execute this command
  • command - a unique name for the command that this resource should execute
    • each resource has its own list of acceptable commands (which may depend on the resource's type, its state, etc...)
    • however all resources must accept the command "list", which is asking the resource to list the names and options of all the commands that it recognise. Upon receiving a "list" command, a resource must publish a "inform" message containing that list.
    • an example of the "list" execute message and its reply are given later in this document
  • option - (optional) these elements provide additional parameters to the command to execute
    • some examples of options for potential commands are given later in this document

2.3.3. Format of Messages sent by a Resource¶

• inform
  

  <inform>
      <from>resourceName</from>
      <type>informationType</type>
      <info>
        ...
      </info>
      <info>
        ...
      </info>
      ...   
  </inform>             
  

  • from - the unique name of the existing resource which published this message
  • type - the type of information that this message contains
  • info - a text or more sub-elements with the details of one piece of information that this message is providing

• error
  

  <error>
      <from>resourceName</from>
      <type>errorType</type>
      <description>
        ...
      </description>
  </inform>             
  

  • from - the unique name of the existing resource which reports this error this message
  • type - the type of information that this message contains
  • description - a text or more sub-elements with the detailed description of this error

• event

2.4. Sets of Resources¶

• Everything is a resource, thus a set of resources is itself a resource

(more details to follow)

2.5. Examples¶

Implementation notes:¶

• A Resource Controller (RC): a software entity associated to a given resource.
  • a given resource is only associated to a unique RC, and a given RC is only associated with a unique resource (= one-to-one relationship).
  • the granularity of a resource is left to the provider of that resource. Examples:
    • Alice operates testbed A and decides that each machine from A will only be viewed as a single resource by the experimenter.
      • so machine X will be viewed as a unique resource and only one RC will exist to control it.
    • Bob operates testbed B and decides that each machine from B will be viewed as a collection of resources by the expeirmenter.
      • so machine Y will be composed of a "bare machine" Y1, a network card Y2, another device Y3, etc..
      • different RCs will exist to control Y1, Y2, Y3, etc...