Changes between Version 90 and Version 91 of GAPI_AM_API_DRAFT

Timestamp:

10/24/13 11:59:52 (11 years ago)

Author:

Aaron Helsinger

Comment:

--

GAPI_AM_API_DRAFT

@@ -438 +438 @@
 Besides the usual return error codes, the `PerformOperationalAction` method with this action may return `REFUSED` if the sliver is in the wrong operational state.
 
+== Change Set R: Allow `Renew` to extend slivers as much as possible ==
+
+In 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. 
+
+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.
+
+This proposed change set would accommodate an experimenter attempting to extend their reservation as long as possible
+
+Proposal:
+Add a new option: `geni_extend_alap` (as long as possible), default is `False` (XML-RPC boolean) (preserving current behavior).
+Option is valid in AM API v2 in `RenewSliver`, or in v3 or higher in `Renew`. AMs are not required to support it.
+When `True`, the AM should extend the life of the slice/sliver (depending on the API version), to the minimum of the requested new expiration time, the expiration time in the slice credential (of course), and the AM local maximum based on local policy (which may be resource or slice dependent).
+
+When the AM successfully extends the life of the slice/sliver using this new option:
+ - return value is success (`True` or the API v3 struct)
+ - 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.
+
+Something like this:
+
+{{{
+<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)]
+}}}
+
+Note that this string return allows APIv2 AMs to report the new expiration time since that cannot be reliably known otherwise.
+
+When 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).
+
+Note that this would be a new option that AMs are not required to honor - making things backwards compatible.
+
 == Older Proposals ==
 Older proposals, withdrawn, superseded, or postponed: