Changes between Version 6 and Version 7 of FeddPluginCalls

Timestamp:

Jun 29, 2010 10:39:14 AM (14 years ago)

Author:

faber

Comment:

--

FeddPluginCalls

@@ -11 +11 @@
 
 Each method should return the python dict encoding the response or raise a [source:fedd/trunk/federation/service_error.py service_error] containing information about the error.  The service_error class contains error codes (in either the [source:wsdl/trunk/fedd_types.xsd XSD] or [source:fedd/trunk/federation/service_error.py python] definitions.
+
+Many requests and responses include attribute/value pairs set by the experiment controller to plug-ins that understand them.  They are not commonly used but do represent a lightweight extension mechanism.  If a plug-in adds one to a sub-experiment description or topology element, the experiment controller generally passes it through transparently.
 
 == Initialization ==
@@ -123 +125 @@
 }
 }}}
+
+To get the topdl representation out of the (potentially large and complex) dict that describes it, the simplest mechanism is to just call the topdl.Topology constructor on the dict:
+
+{{{
+top = topdl.Topology(**request['segmentdescription']['topdldescription'])
+}}}
+
+That is done in all the existing plug-in code.  The various plug-ins walk, alter, and write topologies in several ways, and that code is a good guide to them.  The [source:fedd/trunk/federation/topdl.py topdl source] is also available.
+
+The connection information explains how the connectivity is established between the sub-experiments.  Now there are two ways to establish connections - ssh tunnels and direct transit connections.  The ssh connection implies a portal in this experiment (it will be in the topology description) that will connect to the peer.  Generally the port on which to communicate will be a parameter as it is here.  Parameters are set using the SetValue interface, which is demonstrated in most existing plug-ins.
+
+A plug-in should export its connection parameters as soon as it can determine them, and import connection parameters as late as it can in the experiment creation process.
+
+The service parameters are the same format, and for services exported from this sub-experiment often the same content, as those returned from a !RequestAccess request. 
+
+The connectivity and service information is particularly useful if the service and connectivity set-up is being done using [FeddAbout#TheFederationKit the DETER federation kit].  While other systems for providing this connectivity are fine, the federation kit provides a robust implementation that runs across several Unix based platforms.  The [source:fedd/trunk/federation/emulab_access.py Emulab plug-in] is a good place to look at the details of configuring the federation kit.
+
+In addition to configuring and establishing connectivity, the plug-in must convert the topology description into an embeddable topology.  The [source:fedd/trunk/federation/topdl.py topdl source] includes several conversions into different formats, including emulab ns2 and [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI RSpecs (v1.0)].
+
+While there is considerable support available, !StartSegment is the operation that is the most tricky for the plug-in developer.
+
+The response has the format:
+
+{{{
+
+response = {
+    # Same as in the request
+    'allocID': { 'fedid': fedid_object },
+    'allocationLog': 'a log of the allocation from the plug-in's perspective.  This may be edited or complete.',
+    'segmentdescription' : { 'topdldescription': # Topdl description 
+         },
+    # Description of the allocation
+    'embedding': [ { 'topname': 'name_from_topdl', 'physname': 'testbed_name', 'testbed': 'testbed_id_from_topdl' }, #... 
+         ],
+    # Generic attribute value pairs, rarely used.
+    'fedAttr' : [ { 'attribute': 'a1', 'value': 'v1'}, {'attribute': 'a2', 'value: 'v2' } ],
+}
+}}}
+
+The allocation log is a plug-in's eye view of the allocation.  It is output by the experiment controller and can be viewed by the user using [FeddCommands#fedd_spewlog.py fedd_spewlog.py].
+
+The segment description that is returned may be annotated with more detail about the segment as constructed.  For example specifics of the hardware on which an element was instantiated could be filled in.
+
+The embedding provides a way for the experiment controller to map elements from the global experiment description into a name in the plug-in's name space.  Currently this is available to the user from the [FeddCommands#fedd_ftopo.py fedd_ftopo.py] command and is used in ad hoc ways.  In a future release this information will be useful in executing remote operations from the experiment controller.
+
+== !TerminateSegment ===
+