| | 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:GAPI_AM_API_V2 The latest API specification] |
| | 13 | |
| | 14 | == Overall Issues == |
| | 15 | 1. Add a state diagram in the [wiki: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 | |
