| 1 | [[PageOutline]] |
| 2 | |
| 3 | = GENI Aggregate Manager API Outstanding Issues = |
| 4 | |
| 5 | The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers. A Sliver is the set of resources allocated by one Aggregate to one Slice. |
| 6 | |
| 7 | This page lists un-specified areas of the API, known problems, or gaps. |
| 8 | |
| 9 | See Also: |
| 10 | * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for the next version of this API |
| 11 | * [wiki:GeniApi GENI API] implementation status |
| 12 | * [wiki:DRAFT_GAPI_AM_API_V2 The latest API specification] |
| 13 | |
| 14 | == Overall Issues == |
| 15 | 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. |
| 16 | * More generally, we need to define the state of the resources before/after each operation. Diagrams help. |
| 17 | 1. No way to modify a reservation at an aggregate for a slice without deleting and recreating it |
| 18 | * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetC:UpdateSliver1 UpdateSliver proposal] |
| 19 | 1. No way to delete or renew part of a reservation at an aggregate separate from other parts |
| 20 | * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetD:SliversandSliverGroups Sliver group proposal] |
| 21 | 1. Method names suggest you are operating on slivers, but really you are operating on all slivers at an aggregate in a slice |
| 22 | * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetD:SliversandSliverGroups Sliver group proposal] |
| 23 | 1. Tickets |
| 24 | * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetE:Tickets1 Tickets proposal] |
| 25 | 1. Define privileges required for each operation |
| 26 | * But see the ABAC proposal |
| 27 | 1. Clarify use of error codes, possibly add more detailed codes |
| 28 | * Proposal: Add more specific error codes for credential issues, specific bad argument cases |
| 29 | || 18 || MISSINGARGS || "Required argument(s) missing" || |
| 30 | || 19 || OUTOFRANGE || "Requested expiration time or other argument not valid" || |
| 31 | || 20 || CREDENTIAL_INVALID || "Not authorized: Supplied credential is invalid" || |
| 32 | || 21 || CREDENTIAL_EXPIRED || "Not authorized: Supplied credential expired" || |
| 33 | || 22 || CREDENTIAL_MISMATCH || "Not authorized: Supplied credential does not match the supplied client certificate or does not match the given slice URN" || |
| 34 | || 23 || CREDENTIAL_SIGNER_UNTRUSTED || "Not authorized: Supplied credential not signed by trusted authority" || |
| 35 | * What error code should be used for a bad RSpec version requested or used? (In !ListResources and !CreateSliver, be consistent) |
| 36 | * 1=BADARGS, 4=BADVERSION, or 13=UNSUPPORTED? 4 seems appropriate, but maybe the semantics of BADVERSION are something else. PG does 1 |
| 37 | * Proposal: {{{BADVERSION}}} |
| 38 | * What error code should be used for various 'nothing found' cases? (Be consistent across !ListResources, !DeleteSliver, !SliverStatus, !Shutdown, !RenewSliver.) |
| 39 | * Use EXPIRED? SEARCHFAILED? Other? |
| 40 | * There never was such a slice here |
| 41 | * Proposal: Should be same as deleted. |
| 42 | * That slice was here but expired |
| 43 | * Proposal: {{{EXPIRED}}} |
| 44 | * That slice was here but is empty |
| 45 | * That slice was here but was deleted |
| 46 | * Proposal: Should be same as 'was never here'. |
| 47 | * That slice was here but was shutdown |
| 48 | 1. Should {{{am_type}}} and the RSpec {{{type}} and prefixes for new options, etc be the same? |
| 49 | * Should the RSpec {{{type}}} fields be the {{{am_type}}} values defined for return codes? |
| 50 | * Remove 'openflow' as unused here? |
| 51 | * Should it be 'sfa' or 'planetlab'? |
| 52 | * We say that implementations should name new options or returns to avoid naming conflicts. Should we specify that prefixes are registered? |
| 53 | * Should the prefixes be the {{{am_type}}} values |
| 54 | * Proposal: Yes to all the above |
| 55 | 1. 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? |
| 56 | 1. Operations that return false: what does that really mean? Not an error but ??? |
| 57 | |
| 58 | == !GetVersion Issues == |
| 59 | |
| 60 | == !ListResources Issues == |
| 61 | * 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? |
| 62 | * PG uses BADARGS instead of BADVERSION. OK? |
| 63 | * Proposal: Change to {{{BADVERSION}}} |
| 64 | * PG does not use BUSY, SERVERERROR, UNAVAILABLE, EXPIRED - OK? |
| 65 | * Proposal: probably - up to them |
| 66 | |
| 67 | == !CreateSliver Issues == |
| 68 | * Define the behavior if you call !CreateSliver twice for the same slice. PG says you return REFUSED. !PlanetLab accepts it though. What about {{{ALREADYEXISTS}}}? |
| 69 | || `REFUSED` || Slice already exists; must be deleted first (ie you called !CreateSliver twice without a !DeleteSliver in between) || |
| 70 | * Proposal: {{{ALREADYEXISTS}}} |
| 71 | * Define the behavior if the AM can only give you some of what you requested |
| 72 | * Proposal: {{{TOOBIG}}}? |
| 73 | * Define status of sliver(s) immediately on success of this method (need a diagram?) |
| 74 | * Define how many sliver(s) this creates |
| 75 | * Note there is no way to see the expiration time of your resources |
| 76 | * Proposal: include in manifest |
| 77 | * Point to restrictions on slice names, sliver names? |
| 78 | |
| 79 | == !DeleteSliver Issues == |
| 80 | * What is failure (return false) as opposed to an Error? |
| 81 | * Define status (relative to !SliverStatus or ...) of the sliver(s) after success, failure, or error. Diagram? |
| 82 | * What happens to resources if your credential expires? Does the AM delete them for you? |
| 83 | |
| 84 | == !SliverStatus Issues == |
| 85 | * Are the {{{configuring}}}, {{{ready}}}, etc strings case-sensitive? |
| 86 | * Proposal: no |
| 87 | * Further specify what kinds of things go in specific {{{geni_resources}}} vs the whole |
| 88 | * Further specify what kinds of things this method might optionally additionally include and still be consistent with the intent |
| 89 | * Document the convention on specifying expiration time: should it be required? |
| 90 | * Proposal: Yes |
| 91 | |
| 92 | == !RenewSliver Issues == |
| 93 | * 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. |
| 94 | * Proposal: Add that requirement |
| 95 | * Specify the behavior if you fail to renew and the reservation expires |
| 96 | * Specify the behavior if you try to renew past the life of your credential(s). |
| 97 | * Proposal: Fails with {{{OUTOFRANGE}}} |
| 98 | * Specify the behavior if there are no local resources in that slice |
| 99 | |
| 100 | == Shutdown Issues == |
| 101 | * What is the state of resources after this? Startable? Is there a procedure for this? |
| 102 | * Proposal: Not restartable, not de-commissioned, not reservable, not accessible by the experimenters |
| 103 | * What happens if you call this twice? |
| 104 | * What happens if the slice has nothing local? |
| 105 | |