Changes between Version 2 and Version 3 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
10/07/11 09:25:19 (13 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_DRAFT

    v2 v3  
    33= GENI Aggregate Manager API Draft Revisions =
    44
    5 This page documents DRAFT revisions to the GENI Aggregate Manager API, proposed for the next version of the API.
     5This page documents DRAFT revisions to the GENI Aggregate Manager API, proposed for the next version of the API. Revisions documented here have been agreed to in discussions on the geni dev mailing list, and during at least on GEC, but not formally adopted. Well behaved aggregates will typically already implement these revisions.
    66
    77The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers. A Sliver is the set of resources allocated by one Aggregate to one Slice.
    88
    9 The current version of the API is 1 and documented on the main API page [wiki:GAPI_AM_API here].
     9The current officially adopted version of the API is 1 and documented on the main API page [wiki:GAPI_AM_API here].
    1010
    11 This page documents proposed changes for AM API version 2.
     11This page documents proposed and generally accepted changes for AM API version 2.
    1212  * As of June 2011, the latest software from ProtoGENI and SFA (as of code tag 1.0-24) comply with these changes.
    1313  * Omni version 1.3 (released June 2011) adds client software support for these changes.
    1414
    1515== Summary of Proposed Changes ==
    16  * Specify GENI RSpecs as complying with the ProtoGENI V2 RSpecs as documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec here]
    17  * Include additional options in !GetResources and !ListResources to allow aggregates to support the PG RSpecs in addition to their own native format
     16 * Specify GENI RSpecs as complying with schemas documented as the ProtoGENI V2 RSpecs as documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec here]
     17 * Include additional options in !GetResources and !ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format.
    1818
    1919== Proposing Additional Changes ==
    … …  
    2626== Proposed Change Details ==
    2727
    28 === ProtoGENI V2 RSpecs ===
     28=== GENI Standard RSpecs ===
    2929At GEC10 [wiki:GEC10RSpec the GENI community agreed] that GENI RSpecs would be in the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2 format]. Aggregates are free to use an alternate format internally, but must accept and produce compliant RSpecs on demand. Note that individual aggregates may use RSpec extensions to describe custom resources or properties of resources. For RSpec extension information, see the ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/RSpecExtensions2 wiki].
    3030
    … …  
    3737 * !ListResources: Return value of !ListResources remains an [http://www.xmlrpc.com/spec XMLRPC] string, but its format and meaning are now proscribed.
    3838
    39  The return value is an RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2] RSpec in text format if {{{geni_compressed}}} is unspecified or set to {{{false}}}. The return value will be a ZLib compressed and then base 64 encoded string representation of the RSpec if {{{geni_compressed}}} is specified and set to {{{true}}}.
     39 The return value is an RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2] RSpec schema in text format if {{{geni_compressed}}} is unspecified or set to {{{false}}}. The return value will be a ZLib compressed and then base 64 encoded string representation of the RSpec if {{{geni_compressed}}} is specified and set to {{{true}}}.
    4040
    4141This RSpec will be a [http://www.protogeni.net/resources/rspec/2/ad.xsd advertisement RSpec] when invoked with no {{{geni_slice_urn}}} option, representing the resources available at this aggregate. When the client supplies the {{{geni_slice_urn}}} option, then the aggregate will return a [http://www.protogeni.net/resources/rspec/2/manifest.xsd manifest RSpec], representing all resources allocated to that slice by this aggregate.
    … …  
    5151
    5252=== New RSpec Version Options ===
    53 In order to allow aggregates to support both a native RSpec format (e.g. the standard !PlanetLab / SFA RSpecs) as well as the GENI-standard format (ProtoGENI V2), we need new options to allow a client to request RSpecs in a particular format.
     53In order to allow aggregates to support both a native RSpec format (e.g. the standard !PlanetLab / SFA RSpecs) as well as the GENI-standard format (ProtoGENI V2 schemas), we need new options to allow a client to request RSpecs in a particular format.
    5454
    55 Specifically, aggregates will advertise (in !GetVersion) the list of Advertisement and Request RSpec types they are willing to accept, as well as the default Advertisement RSpec type. And they will produce manifest RSpecs in a format matching the format of the !CreateSliver input request RSpec (e.g. return a ProtoGENI V2 manifest RSpec when given a ProtoGENI V2 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec).
     55Specifically, aggregates will advertise (in !GetVersion) the list of Advertisement and Request RSpec types they are willing to accept, as well as the default Advertisement RSpec type. And they will produce manifest RSpecs in a format matching the format of the !CreateSliver input request RSpec (e.g. return a manifest RSpec matching ProtoGENI V2 manifest schema when given a ProtoGENI V2 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec).
    5656
    5757==== Contract details ====
    … …  
    5959Aggregates advertise the {{{type}}} and {{{version}}} of RSpec formats that they support. If available, they specify the {{{schema}}}, {{{namespace}}} and {{{extensions}}} combination which is the authoritative definition of that format. Clients of the API should understand that combination in order to know how to understand the resources available at that aggregate.
    6060
    61 If an aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{ad_rspec_versions}}} attribute of !GetVersion, then it promises to send a correct Advertisement RSpec in response to a !ListResources call which supplies an {{{rspec_version}}} option containing that {{{type}}}/{{{version}}}. ({{{rspec_version}}} is a {{{struct}}} with 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-sensitive'' strings, matching those in {{{ad_rspec_versions}}}).
     61If an aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{ad_rspec_versions}}} attribute of !GetVersion, then it promises to send a correct Advertisement RSpec in response to a !ListResources call which supplies an {{{rspec_version}}} option containing that {{{type}}}/{{{version}}}. ({{{rspec_version}}} is a {{{struct}}} with 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{ad_rspec_versions}}}).
    6262
    6363If an Aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{request_rspec_versions}}} attribute of !GetVersion then it promises to correctly honor a !CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (ie a PGV2 request is answered with a PG V2 manifest). The aggregate also promises to send a correctly formatted Manifest RSpec in response to a !ListResources call which supplies a valid {{{geni_slice_urn}}} option and an {{{rspec_version}}} option containing that supported {{{type}}}/{{{version}}}.
    … …  
    100100
    101101 `geni_api`::
    102     An integer indicating the revision of the Aggregate Manager API that an aggregate supports. The current version of the API is 2 (two).
     102    An integer indicating the revision of the Aggregate Manager API that an aggregate supports. The version of the API documented here is 2 (two).
    103103
    104104 `request_rspec_versions`::
    … …  
    113113Elements used within {{{request_rspec_versions}}}, {{{ad_rspec_versions}}}, and {{{default_ad_rspec}}}:
    114114 `type`, `version`::
    115    Two ''case-sensitive'' strings which together comprise the type of RSpec. The RSpec `type` should be one of "protogeni", "sfa", "orca", "openflow", or "orbit" and `version` should be a type-specific version identifier as specified by the appropriate control framework.
     115   Two ''case-insensitive'' strings which together comprise the type of RSpec. The RSpec `type` should be one of "protogeni", "sfa", "orca", "openflow", or "orbit" and `version` should be a type-specific version identifier as specified by the appropriate control framework.
    116116
    117117 `schema`::
    … …  
    124124   An array of cluster-specific strings denoting which extensions are supported. In the case of ProtoGENI, these are XML namespaces which denote the extension as a whole.
    125125
    126 Implementations can add additional members to the struct as desired. The prefix {{{geni_}}} is reserved for members that are part of this API specification. Implementation should choose an appropriate prefix to avoid conflicts.
     126Implementations can add additional members to the struct as desired. Implementations should choose an appropriate prefix to avoid conflicts, but avoid {{{geni_}}} which should be reserved for common options.
    127127
    128128This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetVersion GetVersion] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
    … …  
    142142
    143143 `options`::
    144     An [http://www.xmlrpc.com/spec XMLRPC] struct containing members indicating the set of resources the caller is interested in or the format of the result. In addition to the members specified below, callers can pass additional members that specific aggregate manager implementations might honor. The prefix {{{geni_}}} is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts.
     144    An [http://www.xmlrpc.com/spec XMLRPC] struct containing members indicating the set of resources the caller is interested in or the format of the result. In addition to the members specified below, callers can pass additional members that specific aggregate manager implementations might honor. Implementations can add additional members to the struct as desired. Implementations should choose an appropriate prefix to avoid conflicts, but avoid {{{geni_}}} which should be reserved for common options.
    145145
    146146The following members are available for use in the options parameter. All aggregate managers are required to implement these options.
    … …  
    161161
    162162 `rspec_version`::
    163     An [http://www.xmlrpc.com/spec XMLRPC] struct indicating the type and version of Advertisement or Manifest RSpec to return. The struct contains 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-sensitive'' strings, matching those in {{{ad_rspec_versions}}} as returned by !GetVersion at this aggregate.
     163    An [http://www.xmlrpc.com/spec XMLRPC] struct indicating the type and version of Advertisement or Manifest RSpec to return. The struct contains 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{ad_rspec_versions}}} as returned by !GetVersion at this aggregate.
    164164
    165165    If this option is not included in the request, then the returned RSpec will be of the type specified in {{{default_ad_rspec}}}. That Rspec will be an Advertisement RSpec when no {{{geni_slice_urn}}} option is supplied. When a valid {{{geni_slice_urn}}} option is supplied, the returned RSpec will be a Manifest RSpec of the type corresponding to {{{default_ad_rspec}}}, but in manifest format.
    … …  
    168168
    169169==== New !CreateSliver behavior ====
    170 If an Aggregate advertises a {{{type}}}/{{{version}}} pair in its {{{request_rspec_versions}}} as returned by !GetVersion, then it promises to correctly honor a !CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (ie a PGV2 request is answered with a PG V2 manifest).
     170If an Aggregate advertises a {{{type}}}/{{{version}}} pair in its {{{request_rspec_versions}}} as returned by !GetVersion, then it promises to correctly honor a !CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (ie a request in PGV2 schema is answered with a manifest in PG V2 format).