Changes between Version 6 and Version 7 of DRAFT_GAPI_AM_API_ISSUES


Ignore:
Timestamp:
12/13/11 16:15:51 (8 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DRAFT_GAPI_AM_API_ISSUES

    v6 v7  
    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 
     1See wiki:GAPI_AM_API_ISSUES