[[PageOutline]] = GENI Aggregate Manager API Outstanding Issues = The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers. This page lists un-specified areas of the API, known problems, or gaps. See Also: * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for the next version of this API * [wiki:GeniApi GENI API] implementation status * [wiki:DRAFT_GAPI_AM_API_V2 The latest API specification] == Overall Issues == 1. Add a state diagram in the [wiki:DRAFT_GAPI_AM_API_V2#SliverStatus SliverStatus] section to indicate that a component starts in {{{configuring}}}, can go from {{{configuring}}} to either {{{ready}}} or {{{failed}}}, and can go from {{{ready}}} to {{{failed}}}. {{{failed}}} is a terminal status. * More generally, we need to define the state of the resources before/after each operation. Diagrams help. 2. No way to modify a reservation at an aggregate for a slice without deleting and recreating it * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetC:UpdateSliver1 UpdateSliver proposal] 3. No way to delete or renew part of a reservation at an aggregate separate from other parts * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetD:SliversandSliverGroups Sliver group proposal] 4. Method names suggest you are operating on slivers, but really you are operating on all slivers at an aggregate in a slice * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetD:SliversandSliverGroups Sliver group proposal] 5. Tickets * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetE:Tickets1 Tickets proposal] 6. Define privileges required for each operation * But see the ABAC proposal 7. Clarify use of error codes, possibly add more detailed codes * Proposal: Add more specific error codes for credential issues, specific bad argument cases || 18 || MISSINGARGS || "Required argument(s) missing" || || 19 || OUTOFRANGE || "Requested expiration time or other argument not valid" || || 20 || CREDENTIAL_INVALID || "Not authorized: Supplied credential is invalid" || || 21 || CREDENTIAL_EXPIRED || "Not authorized: Supplied credential expired" || || 22 || CREDENTIAL_MISMATCH || "Not authorized: Supplied credential does not match the supplied client certificate or does not match the given slice URN" || || 23 || CREDENTIAL_SIGNER_UNTRUSTED || "Not authorized: Supplied credential not signed by trusted authority" || * What error code should be used for a bad RSpec version requested or used? (In !ListResources and !CreateSliver, be consistent) * 1=BADARGS, 4=BADVERSION, or 13=UNSUPPORTED? 4 seems appropriate, but maybe the semantics of BADVERSION are something else. PG does 1 * Proposal: {{{BADVERSION}}} * What error code should be used for various 'nothing found' cases? (Be consistent across !ListResources, !DeleteSliver, !SliverStatus, !Shutdown, !RenewSliver.) * Use EXPIRED? SEARCHFAILED? Other? * There never was such a slice here * Proposal: Should be same as deleted. * That slice was here but expired * Proposal: {{{EXPIRED}}} * That slice was here but is empty * That slice was here but was deleted * Proposal: Should be same as 'was never here'. * That slice was here but was shutdown 8. Should {{{am_type}}} and the RSpec {{{type}}} and prefixes for new options, etc be the same? * Should the RSpec {{{type}}} fields be the {{{am_type}}} values defined for return codes? * Remove 'openflow' as unused here? * Should it be 'sfa' or 'planetlab'? * We say that implementations should name new options or returns to avoid naming conflicts. Should we specify that prefixes are registered? * Should the prefixes be the {{{am_type}}} values * Proposal: Yes to all the above 9. We do not define the semantics of supplying a list of credentials: are they additive to accumulate privileges? Or must 1 credential supply all needed privileges? 10. Operations that return false: what does that really mean? Not an error but ??? == !GetVersion Issues == == !ListResources Issues == * Since v1 we have said that if there are no resources attached to this slice at the aggregate, an empty RSpec should be returned. Do all AMs do this? * PG uses BADARGS instead of BADVERSION. OK? * Proposal: Change to {{{BADVERSION}}} * PG does not use BUSY, SERVERERROR, UNAVAILABLE, EXPIRED - OK? * Proposal: probably - up to them == !CreateSliver Issues == * Define the behavior if you call !CreateSliver twice for the same slice. PG says you return REFUSED. !PlanetLab accepts it though. What about {{{ALREADYEXISTS}}}? || `REFUSED` || Slice already exists; must be deleted first (ie you called !CreateSliver twice without a !DeleteSliver in between) || * Proposal: {{{ALREADYEXISTS}}} * Define the behavior if the AM can only give you some of what you requested * Proposal: {{{TOOBIG}}}? * Define status of sliver(s) immediately on success of this method (need a diagram?) * Define how many sliver(s) this creates * Note there is no way to see the expiration time of your resources * Proposal: include in manifest * Point to restrictions on slice names, sliver names? == !DeleteSliver Issues == * What is failure (return false) as opposed to an Error? * Define status (relative to !SliverStatus or ...) of the sliver(s) after success, failure, or error. Diagram? * What happens to resources if your credential expires? Does the AM delete them for you? == !SliverStatus Issues == * Are the {{{configuring}}}, {{{ready}}}, etc strings case-sensitive? * Proposal: no * Further specify what kinds of things go in specific {{{geni_resources}}} vs the whole * Further specify what kinds of things this method might optionally additionally include and still be consistent with the intent * Document the convention on specifying expiration time: should it be required? * Proposal: Yes == !RenewSliver Issues == * All resources indicated by the supplied URN should be renewed to the given time, or else the entire call should fail. We don't specify that currently. * Proposal: Add that requirement * Specify the behavior if you fail to renew and the reservation expires * Specify the behavior if you try to renew past the life of your credential(s). * Proposal: Fails with {{{OUTOFRANGE}}} * Specify the behavior if there are no local resources in that slice * Is it legal to try to 'renew' your sliver until earlier than the previous expiration time, shortening your reservation? Some aggregates at least allow this now. == Shutdown Issues == * What is the state of resources after this? Startable? Is there a procedure for this? * Proposal: Not restartable, not de-commissioned, not reservable, not accessible by the experimenters * What happens if you call this twice? * What happens if the slice has nothing local?