Changes between Version 15 and Version 16 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
11/03/11 09:34:24 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_DRAFT

    v15 v16  
    1010
    1111This page documents proposed changes for AM API version '''2'''. These changes are grouped into sets. API Version 2 will be the collection of changes from the change sets below which we next agree on. Change sets still under discussion will then be targeted at a future release.
    12  A. Agreed upon and generally implemented: RSpec related changes, specifying that RSpecs are XML following GENI standard schemas.
     12 A. To be in version 2, agreed upon and generally implemented: RSpec related changes, specifying that RSpecs are XML following GENI standard schemas.
    1313  * Since June 2011, the latest software from ProtoGENI and SFA (as of code tag 1.0-24) has complied with these changes.
    1414  * Omni version 1.3 (released June 2011) added client software support for these changes.
    15  B. New and changing proposal: Supporting flexible arguments and returns. Specifically, adding a property list to all calls, and making all returns be a property list.
     15 B. To be in version 2, subject to ongoing discussion: Supporting flexible arguments and returns. Specifically, adding a property list to all calls, and making all returns be a property list.
    1616 C. New and changing proposal: Add a new method: !UpdateSliver
    1717 D. Undefined: Support for clients manipulating individual slivers or groups of slivers at an aggregate
    … …  
    2020== Summary of Proposed Changes ==
    2121=== Change Set A: RSpecs are XML documents following GENI schemas ===
    22 This change set has been discussed and well behaved aggregates already implement this change.
    23 
    24  * Specify that GENI RSpecs comply with GENI standard XML schemas as posted at http://www.geni.net/resources/rspec. GENI RSpec V3 is what was the ProtoGENI V2 schemas as documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec here].
     22This change set has been discussed and well behaved aggregates already implement this change. The community has agreed to include this change in version 2 of this API.
     23
     24 * Specify that GENI RSpecs comply with GENI standard XML schemas as posted at http://www.geni.net/resources/rspec. GENI RSpec v3 is what was the ProtoGENI v2 schemas as documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec here].
    2525 * Include additional options in !GetVersion and !ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format.
    2626
    2727=== Change Set B: Flexible arguments and returns ===
    28 This change set is new, not implemented, and currently under discussion.
     28This change set is new, not implemented, and currently under discussion. At GEC12 the community agreed to include it in version 2 of the API, but several small points remain under discussion.
    2929
    3030 * All methods take an ''options'' argument, which is a non null XML struct. No required options are added with this change - the struct may be empty.
    3131 * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs.
    3232  * {{{code}}} is an integer, with non-0 indicating error.
    33   * {{{value}}} is the return value as specified in AM API V1 (RSpec, etc), and
     33  * {{{value}}} is the return value as specified in AM API v1 (RSpec, etc), and
    3434  * {{{output}}} is a human readable indication of the nature of the return or error.
    3535  * Aggregates are free to use other additional name/value pairs in the return struct.
    … …  
    6161=== Change Set A ===
    6262
    63 ''Note: The change to GENI standard RSpec schemas originally referenced ProtoGENI V2 RSpec schemas, hosted at www.protogeni.net. These schemas have now been re-branded as GENI V3 RSpec schemas and are hosted at http://www.geni.net/resources/rspec/3.'''
     63''Note: The change to GENI standard RSpec schemas originally referenced ProtoGENI v2 RSpec schemas, hosted at www.protogeni.net. These schemas have now been re-branded as GENI v3 RSpec schemas and are hosted at http://www.geni.net/resources/rspec/3.'''
    6464
    6565''Note: Options in the geni_ namespace remain reserved, but not all GENI standard options need to be named with the geni_ prefix.''
    … …  
    6868
    6969==== Part 1: Standardized XML-based GENI RSpecs ====
    70 At GEC10 [wiki:GEC10RSpec the GENI community agreed] that GENI RSpecs would be in what was the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2 format] and is now known as GENI V3. 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].
     70At GEC10 [wiki:GEC10RSpec the GENI community agreed] that GENI RSpecs would be in what was the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI v2 format] and is now known as GENI v3. 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].
    7171
    7272For more information:
    73  * [http://www.geni.net/resources/rspec/3 Official GENI V3 RSpec schemas]
    74  * [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard (was ProtoGENI V2) format]
     73 * [http://www.geni.net/resources/rspec/3 Official GENI v3 RSpec schemas]
     74 * [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard (was ProtoGENI v2) format]
    7575 * [http://www.protogeni.net/trac/protogeni/wiki/RSpecExtensions2 RSpec extension information]
    7676 * [http://www.protogeni.net/trac/protogeni/wiki/RSpecSchema2 RSpec schemas listing]
    … …  
    9393
    9494==== Part 2: New RSpec Version Options ====
    95 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 (GENI V3, was ProtoGENI V2), we need new options to allow a client to request RSpecs in a particular format.
    96 
    97 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 GENI V3 manifest RSpec when given a GENI V3 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec).
     95In 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 (GENI v3, was ProtoGENI v2), we need new options to allow a client to request RSpecs in a particular format.
     96
     97Specifically, 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 GENI v3 manifest RSpec when given a GENI v3 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec).
    9898
    9999===== Contract details =====
    … …  
    210210
    211211===== New !CreateSliver behavior =====
    212 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 GENI V3 standard request is answered with a GENI V3 manifest).
     212If 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 GENI v3 standard request is answered with a GENI v3 manifest).
    213213
    214214=== Change Set B ===
    215 ''Note: This set of 2 distinct changes is currently under discussion and has gotten no unofficial or official agreement.''
    216 
    217 ''Note: There are 2 parts to this change set. They could be adopted independently, but are described as going together. Additionally, they are described as cumulative to Change Set A above, but are independent.''
     215''Note: This set of 2 distinct changes is currently under discussion. It was approved for inclusion in AM API v2 at GEC12.''
    218216
    219217==== Part 1: Additional options argument ====
    … …  
    226224Aggregates are compliant with this API change by accepting this argument; only for !ListResources are they required to handle any specific options. Similarly, clients are required to supply this argument to talk to compatible aggregates, but are only required to supply any particular options for !ListResources.
    227225
    228 In !GetVersion, this argument remains optional. Clients that only talk AM API V1 will get an error invoking most functions, when they leave off the {{{options}}} argument. Experimenters can then call !GetVersion (without the {{{options}}} argument). AM API V2 compliant Aggregates shall include the {{{geni_api}}} argument as a top-level entry in the return struct, specifying {{{2}}} to indicate to clients that this AM speaks version 2 of the AM API.  This allows experimenters to understand that they need to upgrade their client, or might instruct a clever client tool to automatically switch to version 2 syntax.
     226In !GetVersion, this argument remains optional. Clients that only talk AM API v1 will get an error invoking most functions, when they leave off the {{{options}}} argument. Experimenters can then call !GetVersion (without the {{{options}}} argument). AM API v2 compliant Aggregates shall include the {{{geni_api}}} argument as a top-level entry in the return struct, specifying {{{2}}} to indicate to clients that this AM speaks version 2 of the AM API.  This allows experimenters to understand that they need to upgrade their client, or might instruct a clever client tool to automatically switch to version 2 syntax.
    229227
    230228Aggregates should not ''require'' any new options to any method - they should always have a reasonable default for any such option. Clients must always be able to work with any aggregate by simply supplying the options required by this API.
    … …  
    238236       GetVersion:
    239237               {
    240                   myNewOption1:
     238                  verbose:
    241239                            {
    242                                  type=String,
    243                                  description="A useful but not critical option. This is a human parsable description."
     240                                 type=boolean,
     241                                 description="True means supply gory details on server internal versions. This is a human parsable description."
    244242                             },
    245243                  myOtherNewOption:.....
    … …  
    250248
    251249==== Part 2: Richer return values ====
    252 In AM API V1, method failures come back sometimes as XMLRPC Faults, sometimes as ''False'', and is occasionally inconsistent across aggregates. Failures typically do not indicate how the Experimenter should modify their request for it to succeed, or if this is a server error. This proposed change expands and formalizes the return structures, to support semantically richer returns, allowing Experimenters better insight into both successes and failures, and how to respond.
     250In AM API v1, method failures come back sometimes as XMLRPC Faults, sometimes as ''False'', and is occasionally inconsistent across aggregates. Failures typically do not indicate how the Experimenter should modify their request for it to succeed, or if this is a server error. This proposed change expands and formalizes the return structures, to support semantically richer returns, allowing Experimenters better insight into both successes and failures, and how to respond.
    253251
    254252Allowing aggregates to return more information, on both errors and success, will allow for a richer client-server communication. It would also allow aggregates to give clients hints on how to use successful returns, or otherwise innovate within the bounds of the AM API.
    … …  
    278276Aggregates are encouraged to use {{{code}}} values and {{{output}}} messages that help experimenters and tools distinguish between bad input, other experimenter error, temporary server errors, or server bugs.
    279277
     278GENI standard error codes will be documented on the GENI AM API Wiki page.
     279'''TODO''': The community must standardize on some GENI-wide error codes.
     280
    280281Aggregates are similarly encouraged to provide hints on how to fix bad requests using the {{{value}}} entry to experimenters on error or failures. For example, a failed !RenewSliver call that failed because you are not allowed to renew your sliver that far in the future, might return a new date string in the {{{value}}} field that would be allowed. Similarly, a failed !CreateSliver call might return a modified request RSpec in the {{{value}}} field.
    281282
    282283Aggregates should avoid raising an error (XMLRPC Fault) for application layer errors or any other cases where the XMLRPC specification does not require a Fault, but rather should attempt to return this struct, providing any error messages and stack traces in the {{{output}}} field or other additional fields.
     284
     285Aggregates are free to add additional return values to support aggregate or resource specific functionality, or to innovate within the bounds of the AM API. Aggregates are encouraged to document any such new return values which they return, to bootstrap coordination with clients, and provide documentation for human experimenters. One way to provide partial documentation, is to implement [http://xmlrpc-c.sourceforge.net/introspection.html XML-RPC introspection]. Through the use of method help, aggregates can provide human readable text describing return values. Alternatively or additionally, aggregates may document return values as part of their return from !GetVersion. We have not specified the format for advertising those extra return values in !GetVersion.
    283286
    284287For comparison, Orca functions return property lists internally. The ProtoGENI CMV2 API returns a struct with exactly these 3 values. ProtoGENI however uses a different range of return codes, and largely does not define the {{{value}}} slot on errors.
    … …  
    316319
    317320An exception:
    318 At the top level, !GetVersion adds a required entry: 'geni_api'=2. This allows V1 clients to determine that they are indeed talking to a
    319 GENI AM, but since the version is 2, that is why other function calls will fail.
     321At the top level, !GetVersion adds a required entry: 'geni_api'=2. This allows v1 clients to determine that they are indeed talking to a
     322GENI AM, but since the version is 2, that is why other function calls will fail with an XMLRPC Fault.
     323
     324Note: A counter proposal in the community would make error codes be strings.
     325
     326Note: There is some discussion in the community about how aggregate managers might support multiple versions of this API, and advertise that capability to clients.
    320327
    321328==== Changes Summary: New Method Signatures ====
    … …  
    344351{
    345352   code=0
    346    value= <GENI V3 Ad or Manifest RSpec string>
     353   value= <GENI v3 Ad or Manifest RSpec string>
    347354   output = <None>
    348355}
    … …  
    350357struct CreateSliver(string slice_urn,
    351358                    string credentials[],
    352                     <GENIV3 request RSpec schema compliant XML string> rspec,
     359                    <GENIv3 request RSpec schema compliant XML string> rspec,
    353360                    struct users[],
    354361                    struct options)
    … …  
    356363{
    357364   code=0
    358    value= <GENI V3 Manifest RSpec string>
     365   value= <GENI v3 Manifest RSpec string>
    359366   output = <None>
    360367}
    … …  
    372379{
    373380   code=0
    374    value= struct (as defined in V1)
     381   value= struct (as defined in v1)
    375382   output = <None>
    376383}
    … …  
    396403
    397404=== Change Set C: !UpdateSliver ===
    398 ''Note: This set of changes is currently under active discussion and has gotten no unofficial or official agreement.''
    399 
    400 A common complaint among experimenters about the current AM API V1 is that there is no way to add or remove resources from a slice at an aggregate, without completely deleting the slice at that aggregate and recreating it, possibly losing resources to another experimenter and certainly losing state. This proposal aims to address that, by introducing a method to update the slice at an aggregate.
     405''Note: This set of changes is currently under active discussion and has gotten no official or unofficial agreement.''
     406
     407A common complaint among experimenters about the current AM API v1 is that there is no way to add or remove resources from a slice at an aggregate, without completely deleting the slice at that aggregate and recreating it, possibly losing resources to another experimenter and certainly losing state. This proposal aims to address that, by introducing a method to update the slice at an aggregate.
    401408
    402409The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] calls for an !UpdateSlice method, "to request that additional resources—as specified in the RSpec—be allocated to the slice".
    … …  
    411418 - In both ProtoGENI and !PlanetLab, the method takes the full description of what the experimenter wants, and the server computes the difference. Note that 2 experimenters with permissions to modify the slice (say, 2 students of a professor) could issue conflicting update calls on the same aggregate. An alternative would be that experimenters must compute the difference themselves, and would just specify the incremental changes that they want in their reservation.
    412419 - Atomic: either the full request succeeds, or it fails. The alternative would be that if the experimenter wanted 5 more nodes and only 3 were available, then the server could give you those 3.
    413  - ProtoGENI and !PlanetLab differ on whether the changes are immediate or not. ProtoGENI uses tickets, allowing the experimenter to change their mind or coordinate their requests (See below). They also separate out reservation of the resources with restarting nodes. This allows the experimenter to control which nodes get rebooted and when. !PlanetLab in comparison handles all restarting of nodes for the experimenters, giving them a single operation to get their resources. This approach also more closely matches the behavior of !CreateSliver in the AM API V1.
     420 - ProtoGENI and !PlanetLab differ on whether the changes are immediate or not. ProtoGENI uses tickets, allowing the experimenter to change their mind or coordinate their requests (See below). They also separate out reservation of the resources with restarting nodes. This allows the experimenter to control which nodes get rebooted and when. !PlanetLab in comparison handles all restarting of nodes for the experimenters, giving them a single operation to get their resources. This approach also more closely matches the behavior of !CreateSliver in the AM API v1.
    414421
    415422''The community must discuss the alternatives above.''
    … …  
    419426struct UpdateSliver(string slice_urn,
    420427                    string credentials[],
    421                     <GENIV3 request RSpec schema compliant XML string> rspec,
     428                    <GENIv3 request RSpec schema compliant XML string> rspec,
    422429                    struct users[],
    423430                    struct options)
    … …  
    425432{
    426433   code=0
    427    value= <GENI V3 Manifest RSpec string>
     434   value= <GENI v3 Manifest RSpec string>
    428435   output = <None>
    429436}
    … …  
    437444
    438445=== Change Set D: Slivers and Sliver Groups ===
    439 ''Note: This set of changes is currently under active discussion and has gotten no unofficial or official agreement.''
     446''Note: This set of changes is currently under active discussion and has gotten no official or unofficial agreement.''
    440447
    441448''The current proposal in this change set is to do nothing. See the proposal for !UpdateSliver instead.''
    … …  
    459466
    460467=== Change Set E: Tickets ===
    461 ''Note: This set of changes is not defined, currently under active discussion and has gotten no unofficial or official agreement.''
     468''Note: This set of changes is not defined, currently under active discussion and has gotten no official or unofficial agreement.''
    462469
    463470The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] defines the concept of a ticket. SFA1.0 section 5.3 says "A component signs an RSpec to produce a ticket, indicating a promise by the component to bind resources to the ticket-holder at some point in time." Tickets are promises to allocate resources.