Sponsored by the National Science Foundation1November 2, 2011 Aggregate Manager API Proposed Updates Aaron Helsinger November 2, 2011

Sponsored by the National Science Foundation 1November 2, 2011

Aggregate Manager APIProposed Updates

Aaron HelsingerNovember 2, 2011

www.geni.net


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


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.


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 [email protected]

mailing list, and published on the GENI wiki (http://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+


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 [email protected] in October– 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 [email protected] in October– Some details TBD


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


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 [email protected]

• Published to GENI wiki and [email protected]– http://groups.geni.net/geni/wiki/GAPI_AM_API_DRAFT

• Revisions will be in AM API v2


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)


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


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. • 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.


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.... }


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?


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.


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.


Change Set B Part 2: Sample Return

• For example, SliverStatus could return on success:

{ code: 0 value: {

geni_urn: <sliver URN> geni_status: ready geni_resources: [ { geni_urn: <resource URN> geni_status: ready geni_error: ''}, { geni_urn: <resource URN> geni_status: ready geni_error: ''} ] }

output: <none> }



• 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'

}


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


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.



• 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.


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?


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.


Change Set C: Proposal

• Proposalstruct UpdateSliver(string slice_urn,

string credentials[], string rspec, struct users[], struct options)

Success Return: { code=0 value= <GENI v3 manifest RSpec string> output = <None>

} Note: rspec is in the GENI v3 request schema


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


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!


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?


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


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)


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


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


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


Change Set E: Ticket Viewpoints

• Rob Ricci, ProtoGENI

• Andy Bavier, PlanetLab

• Ilia Baldine, Orca


Discussion


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


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

Documents

Sponsored by the National Science Foundation1November 2, 2011 Aggregate Manager API Proposed Updates Aaron Helsinger November 2, 2011