Changes between Version 15 and Version 16 of GAPI_AM_API_DRAFT
- Timestamp:
- 11/03/11 09:34:24 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
GAPI_AM_API_DRAFT
v15 v16 10 10 11 11 This 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. 13 13 * Since June 2011, the latest software from ProtoGENI and SFA (as of code tag 1.0-24) has complied with these changes. 14 14 * 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. 16 16 C. New and changing proposal: Add a new method: !UpdateSliver 17 17 D. Undefined: Support for clients manipulating individual slivers or groups of slivers at an aggregate … … 20 20 == Summary of Proposed Changes == 21 21 === 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].22 This 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]. 25 25 * Include additional options in !GetVersion and !ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format. 26 26 27 27 === Change Set B: Flexible arguments and returns === 28 This change set is new, not implemented, and currently under discussion. 28 This 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. 29 29 30 30 * 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. 31 31 * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs. 32 32 * {{{code}}} is an integer, with non-0 indicating error. 33 * {{{value}}} is the return value as specified in AM API V1 (RSpec, etc), and33 * {{{value}}} is the return value as specified in AM API v1 (RSpec, etc), and 34 34 * {{{output}}} is a human readable indication of the nature of the return or error. 35 35 * Aggregates are free to use other additional name/value pairs in the return struct. … … 61 61 === Change Set A === 62 62 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.''' 64 64 65 65 ''Note: Options in the geni_ namespace remain reserved, but not all GENI standard options need to be named with the geni_ prefix.'' … … 68 68 69 69 ==== 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].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]. 71 71 72 72 For 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] 75 75 * [http://www.protogeni.net/trac/protogeni/wiki/RSpecExtensions2 RSpec extension information] 76 76 * [http://www.protogeni.net/trac/protogeni/wiki/RSpecSchema2 RSpec schemas listing] … … 93 93 94 94 ==== 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).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). 98 98 99 99 ===== Contract details ===== … … 210 210 211 211 ===== 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).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). 213 213 214 214 === 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.'' 218 216 219 217 ==== Part 1: Additional options argument ==== … … 226 224 Aggregates 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. 227 225 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.226 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. 229 227 230 228 Aggregates 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. … … 238 236 GetVersion: 239 237 { 240 myNewOption1:238 verbose: 241 239 { 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." 244 242 }, 245 243 myOtherNewOption:..... … … 250 248 251 249 ==== 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.250 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. 253 251 254 252 Allowing 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. … … 278 276 Aggregates 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. 279 277 278 GENI 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 280 281 Aggregates 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. 281 282 282 283 Aggregates 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 285 Aggregates 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. 283 286 284 287 For 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. … … 316 319 317 320 An 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. 321 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 322 GENI AM, but since the version is 2, that is why other function calls will fail with an XMLRPC Fault. 323 324 Note: A counter proposal in the community would make error codes be strings. 325 326 Note: There is some discussion in the community about how aggregate managers might support multiple versions of this API, and advertise that capability to clients. 320 327 321 328 ==== Changes Summary: New Method Signatures ==== … … 344 351 { 345 352 code=0 346 value= <GENI V3 Ad or Manifest RSpec string>353 value= <GENI v3 Ad or Manifest RSpec string> 347 354 output = <None> 348 355 } … … 350 357 struct CreateSliver(string slice_urn, 351 358 string credentials[], 352 <GENI V3 request RSpec schema compliant XML string> rspec,359 <GENIv3 request RSpec schema compliant XML string> rspec, 353 360 struct users[], 354 361 struct options) … … 356 363 { 357 364 code=0 358 value= <GENI V3 Manifest RSpec string>365 value= <GENI v3 Manifest RSpec string> 359 366 output = <None> 360 367 } … … 372 379 { 373 380 code=0 374 value= struct (as defined in V1)381 value= struct (as defined in v1) 375 382 output = <None> 376 383 } … … 396 403 397 404 === Change Set C: !UpdateSliver === 398 ''Note: This set of changes is currently under active discussion and has gotten no unofficial orofficial 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 407 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. 401 408 402 409 The [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". … … 411 418 - 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. 412 419 - 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. 414 421 415 422 ''The community must discuss the alternatives above.'' … … 419 426 struct UpdateSliver(string slice_urn, 420 427 string credentials[], 421 <GENI V3 request RSpec schema compliant XML string> rspec,428 <GENIv3 request RSpec schema compliant XML string> rspec, 422 429 struct users[], 423 430 struct options) … … 425 432 { 426 433 code=0 427 value= <GENI V3 Manifest RSpec string>434 value= <GENI v3 Manifest RSpec string> 428 435 output = <None> 429 436 } … … 437 444 438 445 === Change Set D: Slivers and Sliver Groups === 439 ''Note: This set of changes is currently under active discussion and has gotten no unofficial orofficial agreement.''446 ''Note: This set of changes is currently under active discussion and has gotten no official or unofficial agreement.'' 440 447 441 448 ''The current proposal in this change set is to do nothing. See the proposal for !UpdateSliver instead.'' … … 459 466 460 467 === Change Set E: Tickets === 461 ''Note: This set of changes is not defined, currently under active discussion and has gotten no unofficial orofficial agreement.''468 ''Note: This set of changes is not defined, currently under active discussion and has gotten no official or unofficial agreement.'' 462 469 463 470 The [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.