Changes between Version 93 and Version 94 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
10/29/13 14:47:50 (10 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_DRAFT

    v93 v94  
    5252= Proposed Changes for GENI Aggregate Manager API version 4 =
    5353
    54 From the below, Change Sets C, N, and O were all adopted at the GEC15 coding sprint.
     54From the below, Change Sets C, N, and O were all adopted at the GEC15 coding sprint. Change Set R was adopted at the GEC 18 coding sprint.
    5555
    5656== Change Set C: `Update()` ==
     
    440440== Change Set R: Allow `Renew` to extend slivers as much as possible ==
    441441
     442'''Adopted at the GEC 18 Coding Sprint.'''
     443This proposal was discussed at the GEC 18 Coding Sprint. ProtoGENI/InstaGENI, ION/MAX, Orca/ExoGENI, and FOAM all agreed to implement and support this option.
     444
    442445In the current AM API, aggregates are free to restrict how long a reservation can be extended with local policy. AM API v2 says the aggregate should return false if the reservation cannot be extended as requested. V3 allows the `geni_best_effort` option, which would allow some slivers to be extended, while other requests failed. But it still does not permit an aggregate to extend a reservation for less than the full request. This makes things difficult for experimenters.
    443446
    444 Currently, if an experiment request a renewal past the aggregate's local policy maximum, the request fails - and there is no standard way to determine from the error message in v3 (you may get none in v2) what renewal time 'would' work. The problem is compounded if you try to renew slivers at multiple aggregates.
     447Currently, if an experiment requests a renewal past the aggregate's local policy maximum, the request fails - and there is no standard way to determine from the error message in v3 (you may get none in v2) what renewal time 'would' work. The problem is compounded if you try to renew slivers at multiple aggregates.
    445448
    446449This proposed change set would accommodate an experimenter attempting to extend their reservation as long as possible
    447450
    448 Proposal:
     451'''Proposal''':
    449452Add a new option: `geni_extend_alap` (as long as possible), default is `False` (XML-RPC boolean) (preserving current behavior).
    450453Option is valid in AM API v2 in `RenewSliver`, or in v3 or higher in `Renew`. AMs are not required to support it.
     
    453456When the AM successfully extends the life of the slice/sliver using this new option:
    454457 - return value is success (`True` or the API v3 struct)
    455  - the `output` slot of the AM API triple or the `geni_error` field in the per-sliver return struct (depending on the API version) should be a string conveying at least 2 pieces of information in a well known structure that could be parsed by tools: the new expiration time, and whether that is the time you requested or an 'as long as possible' time.
    456 
    457 Something like this:
    458 
    459 {{{
    460 <URN of slice or sliver> expires at <new time> [- which is as long as possible | - which is the slice expiration | - as requested | - which is the AM maximum for a single renew request (9999 seconds)]
    461 }}}
    462 
    463 Note that this string return allows APIv2 AMs to report the new expiration time since that cannot be reliably known otherwise.
     458 - AM API v3 `Renew` return struct will be as previously defined, including the new sliver expiration time
     459 - For AM API v2 aggregates, the `output` slot of the AM API triple should be the new sliver expiration time - either the time requested, or the 'as long as possible' time. This expiration time should be a standard [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype GENI AM API datetime] complying with RFC 3339.
    464460
    465461When the AM cannot extend the life of the slice/sliver at all (because it does not honor the new option, or because no expiration is possible), then it fails the request (return `False` in APIv2, return an error code in APIv3 unless `geni_best_effort` is `True`, in which case it may return success and indicate the individual per-sliver errors in the return struct; v3 error code may be one of `UNSUPPORTED` for an AM that does not support this option, or `BADARGS` or `ERROR` for other failures).
     
    468464
    469465=== Comments ===
    470 Nick and Leigh provided some feedback:
    471  - Maybe there should be different proposals for use with AM API v2 and with v3+, to let v3+ AMs take advantage of the sliver expiration already being reported.
    472  - Maybe we should not try to convey AM local policy in the return from `Renew`, but instead include that in `GetVersion` or the Ad RSpec ('before' you try to reserve or renew the resources).
    473 
    474 To accommodate these, we could modify the proposal's specification of the `output` field as follows:
    475  - For AM API v2 aggregates, the `output` slot of the AM API triple should be the new sliver expiration time - either the time requested, or the 'as long as possible' time. This expiration time should be a standard [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype GENI AM API datetime] complying with RFC 3339.
    476 
    477 Note that this string allows APIv2 AMs to report the new expiration time since that cannot be reliably known otherwise.
    478 
    479 Additionally, we can separately discuss an RSpec extension or additions to the return from `GetVersion` for advertising AM local policy on maximum sliver renewal times.
     466 - Maybe we should try to convey AM local policy on max renewal times (which may be per resource type) in `GetVersion` or the Ad RSpec ('before' you try to reserve or renew the resources). That is a separate discussion.
    480467
    481468== Older Proposals ==