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. A Sliver is the set of resources allocated by one Aggregate to one Slice.

This page lists un-specified areas of the API, known problems, or gaps.

See Also:

• Draft API Revisions proposed for the next version of this API
• GENI API implementation status
• The latest API specification

Overall Issues

1. Add a state diagram in the 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 UpdateSliver proposal
3. No way to delete or renew part of a reservation at an aggregate separate from other parts
   • Proposal: See the 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 Sliver group proposal
5. Tickets
   • Proposal: See the 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

1. 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
2. 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?
3. 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

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?