| 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. |
| 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 | | 2. 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 | | 3. 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 | | 4. 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 | | 5. Tickets |
| 24 | | * Proposal: See the [wiki:GAPI_AM_API_DRAFT#ChangeSetE:Tickets1 Tickets proposal] |
| 25 | | 6. Define privileges required for each operation |
| 26 | | * But see the ABAC proposal |
| 27 | | 7. 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 | | 8. 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 | | 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? |
| 56 | | 10. Operations that return false: what does that really mean? Not an error but ??? |
| 57 | | |
| 58 | | == !GetVersion Issues == |
| 59 | | |
| 60 | | == !ListResources Issues == |
| 61 | | 1. 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 | | * Or should we change this to use an error code, more clearly distinguishing between errors, successfully reserving nothing, etc? |
| 63 | | 2. PG uses BADARGS instead of BADVERSION. OK? |
| 64 | | * Proposal: Change to {{{BADVERSION}}} |
| 65 | | 3. PG does not use BUSY, SERVERERROR, UNAVAILABLE, EXPIRED - OK? |
| 66 | | * Proposal: probably - up to them |
| 67 | | |
| 68 | | == !CreateSliver Issues == |
| 69 | | 1. Define the behavior if you call !CreateSliver twice for the same slice. PG says you return REFUSED. !PlanetLab accepts it though. What about {{{ALREADYEXISTS}}}? |
| 70 | | || `REFUSED` || Slice already exists; must be deleted first (ie you called !CreateSliver twice without a !DeleteSliver in between) || |
| 71 | | * Proposal: {{{ALREADYEXISTS}}} |
| 72 | | 2. Define the behavior if the AM can only give you some of what you requested |
| 73 | | * Proposal: {{{TOOBIG}}}? |
| 74 | | 3. Define status of sliver(s) immediately on success of this method (need a diagram?) |
| 75 | | 4. Define how many sliver(s) this creates |
| 76 | | 5. Note there is no way to see the expiration time of your resources |
| 77 | | * Proposal: include in manifest |
| 78 | | 6. Point to restrictions on slice names, sliver names? |
| 79 | | * Min 3 characters? |
| 80 | | * Max? 19? More? |
| 81 | | * Only characters in set: {{{'^[a-zA-Z][-\w]+$'}}} ? |
| 82 | | |
| 83 | | == !DeleteSliver Issues == |
| 84 | | 1. What is failure (return false) as opposed to an Error? |
| 85 | | * Define status (relative to !SliverStatus or ...) of the sliver(s) after success, failure, or error. Diagram? |
| 86 | | * Proposal: get rid of the false return - it should be true or error |
| 87 | | 2. What happens to resources if your credential expires? Does the AM delete them for you? |
| 88 | | * Proposal: AM deletes them for you - de-allocates the resources. (Required? Or may?) |
| 89 | | |
| 90 | | == !SliverStatus Issues == |
| 91 | | 1. Are the {{{configuring}}}, {{{ready}}}, etc strings case-sensitive? |
| 92 | | * Proposal: no |
| 93 | | 2. Further specify what kinds of things go in specific {{{geni_resources}}} vs the whole |
| 94 | | 3. Further specify what kinds of things this method might optionally additionally include and still be consistent with the intent |
| 95 | | 4. Document the convention on specifying expiration time: should it be required? |
| 96 | | * Proposal: Yes |
| 97 | | |
| 98 | | == !RenewSliver Issues == |
| 99 | | 1. 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. |
| 100 | | * Proposal: Add that requirement |
| 101 | | 2. Specify the behavior if you fail to renew and the reservation expires |
| 102 | | * Proposal: AM deletes the reservation, de-allocates the resources. (Required? May?) |
| 103 | | 3. Specify the behavior if you try to renew past the life of your credential(s). |
| 104 | | * Proposal: Fails with {{{OUTOFRANGE}}} |
| 105 | | 4. Specify the behavior if there are no local resources in that slice |
| 106 | | 5. 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. |
| 107 | | * Proposal: This is legal. Aggregates should support this, but that support is not required. |
| 108 | | |
| 109 | | == Shutdown Issues == |
| 110 | | 1. What is the state of resources after this? Startable? Is there a procedure for this? |
| 111 | | * Proposal: Not restartable, not de-commissioned, not reservable, not accessible by the experimenters |
| 112 | | 2. What happens if you call this twice? |
| 113 | | 3. What happens if the slice has nothing local? |
| 114 | | 4. What does a false return mean? |
| 115 | | * Proposal: Drop that as valid: return true or an error |
| 116 | | |
| 117 | | |
| | 1 | See wiki:GAPI_AM_API_ISSUES |
