1. Sponsored by the National Science Foundation1November 2, 2011 Aggregate Manager API Proposed Updates Aaron Helsinger November 2, 2011 www.geni.net

2. Sponsored by the National Science Foundation2November 2, 2011 Agenda (5 minutes): AM API Status Review (5 minutes): Review change already approved for API Version 2 –Change Set A: RSpecs are XML following standard schemas (GENI v3) (25 minutes): Review two new changes for Version 2 –Change Set B: New options argument; Richer return Structures –Change Set C: UpdateSliver (5 Minutes): Review a gap we don’t need to address right now –Change Set D: Slivers and Sliver groups (45 minutes): Invited Talks and Discussion –Change Set E: Tickets –What are tickets and why do we want them? –Perspectives and Implementations: Rob Ricci and ProtoGENI Andy Bavier and PlanetLab Ilia Baldine and Orca –Discussion

3. Sponsored by the National Science Foundation3November 2, 2011 AM API Status Review Pre-GEC7: Multiple aggregate implementations did not interoperate, experimenter clients were specific to particular implementations. GENI was just stovepipe systems. AM API V1 Published at GEC7, and implemented by GEC8. By GEC9, AM API enabled cross-technology experiments. But multiple areas for improvement were identified. By GEC11, we discussed and implemented changes to specify RSpec schemas.

4. Sponsored by the National Science Foundation4November 2, 2011 AM API: Making Changes AM API V1 was an initial stake in the ground The AM API must be dynamic as resource types and requirements evolve. AM API changes are discussed on the dev@geni.net mailing list, and published on the GENI wiki (http://groups.geni.net/geni/wiki/GAPI_AM_API_DRAFT)dev@geni.nethttp://groups.geni.net/geni/wiki/GAPI_AM_API_DRAFT 5 Change sets are on the wiki –Pick and choose those we agree on The next ‘batch’ of changes will be AM API Version 2 – subsequent changes will be for AM API Version 3+

5. Sponsored by the National Science Foundation5November 2, 2011 Summary: 5 Proposed Changes Change Set A: RSpecs are XML documents with specific Schemas –Discussed and agreed at GEC11. Implemented Widely. Change Set B: Discussed on dev@geni.net in Octoberdev@geni.net –Part 1: New Options argument to all methods for per- AM or experimental options –Part 2: Richer return structure for richer error messages, etc Change Set C: UpdateSliver –Discussed on dev@geni.net in Octoberdev@geni.net –Some details TBD

6. Sponsored by the National Science Foundation6November 2, 2011 Summary: 5 Proposed Changes (cont.) Change Set D: Slivers and Sliver Groups –Not discussed lately –No changes proposed for now Change Set E: Tickets –Large change –Discussion Today… Discussion focus for today

7. Sponsored by the National Science Foundation7November 2, 2011 Change Set A: RSpecs Aggregate Managers must advertise what RSpec formats they support AM API must specify that the RSpec arguments and returns are in GENI standard format (GENI v3) –Was ProtoGENI v2 –Same schemas, now on geni.net with a new namepace –SFA, emulab-devel, Flack, and Omni support in place Jon Duerig of ProtoGENI proposed AM API revisions to support this and we discussed it on dev@geni.net Published to GENI wiki and dev@geni.netdev@geni.net –http://groups.geni.net/geni/wiki/GAPI_AM_API_DRAFThttp://groups.geni.net/geni/wiki/GAPI_AM_API_DRAFT Revisions will be in AM API v2

8. Sponsored by the National Science Foundation8November 2, 2011 Change Set B Part 1: New Options Note: This set of 2 distinct changes is currently under discussion and has gotten no official or unofficial agreement. Part 1: Additional options argument Motivation: –Support innovation –Support aggregate/resource specific configuration options –Examples: Tree or chain mode in stitching; whether user keys in CreateSliver add or replace existing keys on the slice Proposal –Add an XMLRPC struct (name-value pairs) called options –No required options, but argument is required (except in GetVersion)

9. Sponsored by the National Science Foundation9November 2, 2011 Change Set B Part 1: Semantics Aggregates are compliant with this API change by accepting this argument Clients are required to supply this argument In GetVersion, this argument remains optional. –V1 clients will get errors calling other methods –V2 AMs will include the geni_api argument as a top-level entry in the return struct, specifying 2 to indicate to clients that this AM speaks version 2 of the AM API. This allows experimenters to understand that they need to upgrade their client, or might instruct a clever client tool to automatically switch to version 2 syntax. Aggregates should not require any new options to any method –Use defaults for any options –Clients must always be able to work with any aggregate using the AM API

10. Sponsored by the National Science Foundation10November 2, 2011 Change Set B Part 1 continued Aggregates are encouraged to document any new options –to bootstrap coordination with clients, and –provide documentation for human experimenters. –One way to provide partial documentation, is to implement XML-RPC introspection.XML-RPC introspection Through the use of method help, aggregates can provide human readable text describing options. –Alternatively or additionally, aggregates may provide a capability descriptor as part of their return from GetVersion. We have not specified the format for advertising this capability descriptor and those extra options in GetVersion.

11. Sponsored by the National Science Foundation11November 2, 2011 Change Set B Part 1: Sample Ad A possible option advertisement in GetVersion: methodOptions: { GetVersion: { verbose: { type=boolean, description=“True means supply gory detail on AM internals and versions." }, myOtherNewOption:..... }, ListResources.... }

12. Sponsored by the National Science Foundation12November 2, 2011 Change Set B Part 1: Discussion To Date Points from email discussion –Not ioctl; use the server to determine you have a valid method signature –Don’t add new methods for each new option – that isn’t an API –Could have just allowed arbitrary optional arguments - equivalent –AMs should advertise new options XMLRPC introspection, but that gives us only the help string GetVersion (not standardized) –Could specify syntax during coding sprint Nothing specific required No significant objections on the mailing list AMs must not require any new options – provide defaults General agreement on details Does anyone have new concerns, comments or objections that they want to raise now?

13. Sponsored by the National Science Foundation13November 2, 2011 Change Set B Part 2: Return Structures Change Set B Part 2: Methods return rich structures Motivation –AM API v1 method failures are inconsistent, confusing XMLRPC faults wrapping messages from the server Sometimes returns ‘False’ with no feedback Proposal –Expand and formalize returns to give better feedback on both failure and success AMs will –Return more information –Support richer client-server communication. –Give clients hints on how to use successful returns, –Innovate within the bounds of the AM API.

14. Sponsored by the National Science Foundation14November 2, 2011 Change Set B Part 2: Proposal The proposal changes the return values of all methods Return an XMLRPC struct (aka property list) –On any application layer success, failure, and even on an error or for most exceptions. –Note that a malformed XMLRPC request should still raise an XMLRPC Fault, and other Faults dictated by the XMLRPC specification should still be raised. –This struct will contain the return value from the previous revision of the AM API as an entry. This struct will have 3 defined entries, and aggregates are free to include other entries to give more information to clients.

15. Sponsored by the National Science Foundation15November 2, 2011 Change Set B Part 2: Sample Return For example, SliverStatus could return on success: { code: 0 value: { geni_urn: geni_status: ready geni_resources: [ { geni_urn: geni_status: ready geni_error: ''}, { geni_urn: geni_status: ready geni_error: ''} ] } output: }

16. Sponsored by the National Science Foundation16November 2, 2011 Change Set B Part 2 continued On failure, DeleteSliver might return: (That code and output are merely examples.) An exception: At the top level, GetVersion adds a required entry: 'geni_api'=2. –This allows v1 clients to determine that they are indeed talking to a GENI AM, but since the version is 2, that is why other function calls will fail. { code: 1 value: False output: 'No such slice here' }

17. Sponsored by the National Science Foundation17November 2, 2011 Change Set B Part 2: Specification The three required entries in the return structure are code, value, and output: code: An integer, non-zero on error. –0 = Success –<0 = XMLRPC required error codes –1-1000 = GENI negotiated return codes (none so far) –1001-2000 = ProtoGENI specific return codes –2001-3000 = PlanetLab specific return codes –3001-4000 = Orca specific return codes –4001-5000 = OpenFlow specific return codes –others as needed

18. Sponsored by the National Science Foundation18November 2, 2011 Change Set B Part 2 Spec. continued value: On success, this is required. Optional on failure or error. Object representing the successful return value. The value is not defined on error, though aggregates are free to use it. –For GetVersion, the value is an XMLRPC struct –For ListResources, the value is an RSpec –For CreateSliver, the value is an RSpec –For RenewSliver, the value is a boolean –For DeleteSliver, the value is a boolean –For SliverStatus, the value is an XMLRPC struct –For Shutdown, the value is a boolean output: On failure or error, this is required. Optional on success. This is a String with a human readable message explaining the result. –Specifically, this might include an error string, a stacktrace, or other useful messages to help the Experimenter resolve or report the failure or error. It is not defined on success, though aggregates are free to use it.

19. Sponsored by the National Science Foundation19November 2, 2011 Change Set B Part 2 continued AMs should use code values and output messages that help experimenters distinguish among bad input, temporary server errors, or server bugs. AMs may use returns to suggest solutions to failed requests –A failed RenewSliver call might return a new date string in the value field that would be allowed. –A failed CreateSliver call might return a modified request RSpec in the value field. Avoid raising an error (XMLRPC Fault) for application layer errors or any other cases where the XMLRPC specification does not require a Fault For comparison, –Orca functions return property lists internally. –The ProtoGENI CMv2 API returns a struct with exactly these 3 values. ProtoGENI however uses a different range of return codes, and largely does not define the value slot on errors.

20. Sponsored by the National Science Foundation20November 2, 2011 Change Set B Part 2: Agreed? No significant objections on the mailing list Details seem fairly worked out To do: GENI standard error codes –Start with ProtoGENI codes as starting point? –Discuss at the coding sprint? Compatibility –AMs will likely switch to AM API v2, not support both versions –AMs can support both if they choose Note that ListResources arguments have not changed, so the AM may not know which API version is desired without a further hint, like the server URL –Clients will need to support both v1 and v2 clients if they want to talk to all aggregates during the transition –Future API changes will have similar transitions Does anyone have new concerns, comments or objects that they want to raise now?

21. Sponsored by the National Science Foundation21November 2, 2011 Change Set C: UpdateSliver Change Set C: Add UpdateSliver Motivation –Coffee girl: ‘make my slice bigger’ –In current API, you must delete your slice and recreate it – possibly losing state and even resources Approaches to UpdateSliver in the community –Orca: can modify resources, depending on the resource. Working on add/remove resources –PG: UpdateSliver in CMv2 API. Takes request RSpec, returns a ticket Experimenter separately redeems the ticket and restarts the sliver Aggregate computes the difference from the existing state –PL: SFA has UpdateSlice, which is a synonym for CreateSliver in AM API.

22. Sponsored by the National Science Foundation22November 2, 2011 Change Set C: Proposal Proposal struct UpdateSliver(string slice_urn, string credentials[], string rspec, struct users[], struct options) Success Return: { code=0 value= output = } Note: rspec is in the GENI v3 request schema

23. Sponsored by the National Science Foundation23November 2, 2011 Change Set C: Semantics Proposed Semantics: –RSpec argument is a complete request RSpec Question: Can we support a request from an edited manifest easily? Should we instead support 2 modes: complete and diff? –Atomic operations: all changes succeed or all fail, with an explanation of why it failed and how to modify the request to succeed if possible –AM automatically starts/restarts resources Do not wait for tickets or adding Start and Restart calls to the API. But perhaps support that variation later –AM API requires no guarantees about whether unchanged resources in the reservation will be moved or restarted A per aggregate/resource decision For example, aggregates may load balance VMs Aggregates should document any guarantees or behavior in this respect

24. Sponsored by the National Science Foundation24November 2, 2011 Change Set C: Discussion Points Differences and options –Take full desired state or a delta? Who calculates the delta? Who synchronizes requests among multiple experimenters within a slice? Ilia and Nick argued we should support BOTH deltas AND full RSpecs PG argues that new resource requests to link to existing reserved resources are hard to express, and merging RSpecs is hard –Should the AM partially fulfill requests? (Give you 3 out of 5 new nodes, while deleting the ones you asked to drop) But giving you nodes without a link to connect them is silly –Does the AM restart nodes immediately? Or does the experimenter pick which nodes to restart and when? Leigh and Rob argued the AM should not restart nodes –RSpec: request? Or a manifest, to allow mods to what you got? PG specifies a request but accepts manifests. We must discuss!

25. Sponsored by the National Science Foundation25November 2, 2011 Change Set C: Discuss Any new concerns? New comments or suggestions? Approaches to address Ilia, Leigh, and Rob’s comments? Agree to include in AM API v2?

26. Sponsored by the National Science Foundation26November 2, 2011 Change Set D: Slivers and sliver groups Problem: Current API methods take a Slice URN –Create, delete, renew everything in the slice at an Aggregate. –No way to add to a slice at an aggregate, delete part of a slice at an aggregate, etc. Definitions –Sliver: Some of the resources at one aggregate in one slice NOT ALL the resources at the aggregate in the slice Typically the smallest set of resources that the AM will independently reserve or allocate 1 Slice may have multiple slivers at a single aggregate 1 Sliver may contain multiple components ProtoGENI definitions for comparison: –AggregateSliver: all resources in the slice at an aggregate This is what CreateSliver creates –ComponentSliver: things with a sliver_id, roughly 1 resource in each

27. Sponsored by the National Science Foundation27November 2, 2011 Change Set D: Function implications This change would make methods operate on individual slivers or on other groups of slivers – specifically CreateSliver, DeleteSliver, RenewSliver, and new methods not yet in the API UpdateSliver gives us the ability to add/remove slivers within an aggregate Start, Stop, Restart and similar functions don’t exist in the AM API – yet RenewSliver is not addressed (yet)

28. Sponsored by the National Science Foundation28November 2, 2011 Change Set D: Proposing Nothing Proposal: Given we add UpdateSliver, do nothing else (for now) –CreateSliver gives a bunch of slivers, DeleteSliver deletes all slivers at the AM, and we only support Renewing all slivers at an AM Anyone have serious concerns with not changing the AM API to address this now? We can discuss this on the GENI dev mailing list and include changes in a future API revision

29. Sponsored by the National Science Foundation29November 2, 2011 Change Set E: Tickets What are tickets? –A promise to deliver (like a reservation) –Proof of purchase (like a receipt that can be turned in for your goods) –A way to reference and trade resources without physically moving boxes –A feature which, in name, appears in Orca, SFA, PlanetLab, and ProtoGENI Benefits and features of tickets –Support brokers to allocate, consolidate resources on behalf of others –Allow transferring, lending resources –Support scheduled reservations –Negotiated reservations, or coordinated reservations across aggregates –2 phase commit

30. Sponsored by the National Science Foundation30November 2, 2011 Change Set E: Implementations Implementations in the community –Concept defined in SFA as a signed RSpec that promises to allocate resources. –ProtoGENI CM interface constructs them similarly, using them for 2 phase commit –Orca uses leases and tickets extensively for brokering, lending resources and for negotiated reservations / 2 phase commit. But they are structured differently. Parts of a proposal –Structure –Semantics –Additional ticket related methods or changes to existing methods

31. Sponsored by the National Science Foundation31November 2, 2011 Change Set E: Ticket Viewpoints Rob Ricci, ProtoGENI Andy Bavier, PlanetLab Ilia Baldine, Orca

32. Sponsored by the National Science Foundation32November 2, 2011 Discussion

33. Sponsored by the National Science Foundation33November 2, 2011 Status Review A: RSpec change will be included in AM API v2 B: Options and Return Structures Change C: UpdateSliver added D: No action on slivers and sliver groups E: Tickets: good discussion, much to do AM API v2 definition

34. Sponsored by the National Science Foundation34November 2, 2011 Future Work Come to the Coding Sprint Friday 1pm to start working out details –Error codes –Update Sliver Specific Proposal on Tickets Finalize AM API v2 change sets Implement AM API v2 by GEC13? –AMs and Clients New proposals for AM API v3