Changes between Version 13 and Version 14 of FeddPluginCalls


Ignore:
Timestamp:
Dec 4, 2010 5:20:34 PM (9 years ago)
Author:
mikeryan
Comment:

fix links to source

Legend:

Unmodified
Added
Removed
Modified
  • FeddPluginCalls

    v13 v14  
    33Access controllers respond to a series of standard calls from the experiment controller to create local allocations. These are described in conceptual detail [FeddPluginArchitecture elsewhere on this site] and in a [http://groups.geni.net/geni/attachment/wiki/TIEDProtoGENIPlugin/TIED_CF_plugin_design_spec_v1.0.pdf document about the design of the ProtoGENI plug-in].  This section discussed the calls and their encoding for developers interested in reading and extending existing plug-in code, developers will likely want to [FeddSkelPlugin configure and play with the skeleton plug-in] when you have completed this page (or before reading it, depending on how one's neurons are arranged).
    44
    5 The interfaces are all described in xsd and SOAP, and these are easy enough to convert into python data structures [SoapToPython once you know how].  Below we describe the semantics of each call, and the tools available to plug-in writers to assist in implementation.  These tools are available when plug-ins derive from [source:fedd/trunk/federation/access.py federation.access], as [source:fedd/trunk/federation/skeleton_access.py federation.skeleton_access] is.
     5The interfaces are all described in xsd and SOAP, and these are easy enough to convert into python data structures [SoapToPython once you know how].  Below we describe the semantics of each call, and the tools available to plug-in writers to assist in implementation.  These tools are available when plug-ins derive from [source:fedd/federation/access.py federation.access], as [source:fedd/federation/skeleton_access.py federation.skeleton_access] is.
    66
    77Each python method in the plug-in that corresponds to a plug-in interface is called with the same parameters:
    88
    99 * the request: a python dict representing the parameters to the call as encoded in SOAP
    10  * the calling fid: a [source:fedd/trunk/federation/fedid.py fedid object] holding the caller's identity
    11 
    12 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.
     10 * the calling fid: a [source:fedd/federation/fedid.py fedid object] holding the caller's identity
     11
     12Each method should return the python dict encoding the response or raise a [source:fedd/federation/service_error.py service_error] containing information about the error.  The service_error class contains error codes (in either the [source:wsdl/fedd_types.xsd XSD] or [source:fedd/federation/service_error.py python] definitions.
    1313
    1414Many 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.
     
    1616== Initialization ==
    1717
    18 This is not an interface from the experiment controller, but we discuss it to mention the tools available for implementors.  These include routines to save state and interpret the standard parts of the [FeddDatabases#AccessComponentAccessDB access database], including specializing for testbed dependent data.  The method {{{read_access(file, local_info_parser)}}} takes the file to read and a function that takes the string following the access attribute and returns the local testbed attributes, stored into the self.access dict, keyed by the [FeddAbout#GlobalIdentifiers:Three-levelNames three-name] being authorized.  The {{{___init___()}}} routine of source:fedd/trunk/federation/skeleton_access.py federation.skeleton_access] includes an example of this.
    19 
    20 The base class also creates {{{self.auth}}}, which is an [source:fedd/trunk/federation/authorizer.py authorizer object].  This object keeps track of the authorization attributes associated with the three-level names and fedids that the plug-in knows.  When reading the authorization database, the base class assigns the attributes given by the attribute field of the database to the relevant names.  Generally this will an '''access''' attribute tp three-level names allowed to make allocations.  Other attributes can be added by the plug-in, and the authorizer used to control acces to them.  The [source:fedd/trunk/federation/skeleton_access.py skeleton plug-in] includes code to do ths.
    21 
    22 In addition, the initializer of the [source:fedd/trunk/federation/access.py federation.access] base class parses standard parameters from {{{[access]}}} section from the configuration file.  The fields and corresponding class instance attributes are:
     18This is not an interface from the experiment controller, but we discuss it to mention the tools available for implementors.  These include routines to save state and interpret the standard parts of the [FeddDatabases#AccessComponentAccessDB access database], including specializing for testbed dependent data.  The method {{{read_access(file, local_info_parser)}}} takes the file to read and a function that takes the string following the access attribute and returns the local testbed attributes, stored into the self.access dict, keyed by the [FeddAbout#GlobalIdentifiers:Three-levelNames three-name] being authorized.  The {{{___init___()}}} routine of [source:fedd/federation/skeleton_access.py federation.skeleton_access] includes an example of this.
     19
     20The base class also creates {{{self.auth}}}, which is an [source:fedd/federation/authorizer.py authorizer object].  This object keeps track of the authorization attributes associated with the three-level names and fedids that the plug-in knows.  When reading the authorization database, the base class assigns the attributes given by the attribute field of the database to the relevant names.  Generally this will an '''access''' attribute tp three-level names allowed to make allocations.  Other attributes can be added by the plug-in, and the authorizer used to control acces to them.  The [source:fedd/federation/skeleton_access.py skeleton plug-in] includes code to do ths.
     21
     22In addition, the initializer of the [source:fedd/federation/access.py federation.access] base class parses standard parameters from {{{[access]}}} section from the configuration file.  The fields and corresponding class instance attributes are:
    2323
    2424 '''cert_file'''::
     
    5353The !RequestAccess command asks the testbed to map the [FeddAbout#GlobalIdentifiers:Three-levelNames three-level name] on the call into local permissions and to do any bookkeeping associated with later attachment of resources to that allocation.  Specifically, a [http://fedd.isi.deterlab.net/trac/wiki/FeddAbout#GlobalIdentifiers:Fedids fedid] must be created.  Requests from this allocation back to the central experiment controller will be made under that principal/fedid.  Such requests gather configuration information or parameters passed between sub-experiments during creation.  The per-allocation fedid allows fine-grained control of access to thie information at the experiment controller, as well as the ability to name (and therefore request operation on) the various allocations made on this plug-in.
    5454
    55 The plug-in should add an authorization attribute to the creator of the allocation that indicates that the creator can manipulate the allocation via any of the other commands.  Existing plug-ins do this by adding an attribute with the same value as the allocation's fedid to the [source:fedd/trunk/federation/authorizer.py authorization object].
     55The plug-in should add an authorization attribute to the creator of the allocation that indicates that the creator can manipulate the allocation via any of the other commands.  Existing plug-ins do this by adding an attribute with the same value as the allocation's fedid to the [source:fedd/federation/authorizer.py authorization object].
    5656
    5757A !RequestAccess message has the following format:
     
    6969}}}
    7070
    71 The credentials are opaquely and correctly handled by the [source:fedd/trunk/federation/access.py access controller base class].  Service requests encode the various [FeddAbout#ExperimentServices services] that the facility will be asked for in this allocation.
     71The credentials are opaquely and correctly handled by the [source:fedd/federation/access.py access controller base class].  Service requests encode the various [FeddAbout#ExperimentServices services] that the facility will be asked for in this allocation.
    7272
    7373There are also some scheduling fields that are for future expansion.  The DETER experiment controller never includes them.
     
    8686}}}
    8787
    88 The response includes the fedid of the allocation and the actual services exported.  Note that in the example the single '''export_project''' request has become 2 specific service exports.  See the [sources:fedd/trunk/federation/emulab_access.py emulab plug-in] for an example of how services are decoded and managed.
     88The response includes the fedid of the allocation and the actual services exported.  Note that in the example the single '''export_project''' request has become 2 specific service exports.  See the [sources:fedd/federation/emulab_access.py emulab plug-in] for an example of how services are decoded and managed.
    8989
    9090
     
    136136}}}
    137137
    138 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.
     138That 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/federation/topdl.py topdl source] is also available.
    139139
    140140The 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.
     
    144144The 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.
    145145
    146 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.
    147 
    148 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)].
     146The 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/federation/emulab_access.py Emulab plug-in] is a good place to look at the details of configuring the federation kit.
     147
     148In addition to configuring and establishing connectivity, the plug-in must convert the topology description into an embeddable topology.  The [source:fedd/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)].
    149149
    150150While there is considerable support available, !StartSegment is the operation that is the most tricky for the plug-in developer.