GENI Aggregate Manager API

Wed, 1300-1430

Organizer: Aaron Helsinger, GPO

Dial In: 866-453-5550; Participant pin: 6513886#

The Aggregate Manager API has been in use for over a year. This session will seek agreement on several proposed changes to the API. These changes include (1) supporting optional per-aggregate options, (2) changing all method return structures to provide richer feedback, (3) adding support for UpdateSliver to dynamically add or remove resources from your slice, and (4) beginning discussions about tickets to support negotiated reservations, brokering, scheduling, and other future features.

Note: The Coding Sprint session on Friday afternoon will be used to further specify some of the changes discussed here. That session will ensure common handling of edge cases, error conditions, and other implementation details.


Background Reading

Meeting Summary

  • We agreed to two change sets, completing the list of changes to include in AM API version 2. We will:
  • Adopt change set A for inclusion in AM API version 2: RSpecs are GENI schema XML
  • Adopt change set B part 1 for inclusion in AM API version 2:
    • All methods include a new 'options' XML-RPC struct argument with no required values, supporting aggregate innovation
  • We expect to also include set B part 2 in API version 2, assuming we can quickly address a few outstanding questions:
    • All methods return an XML-RPC struct consisting of (1) a return 'code', (2) the return 'value' from API v1, and (3) a human readable 'output' on errors, plus optional aggregate specific entries
  • We will continue to discuss details on some parts of change set B part 2, to finalize AM API version 2:
    • This discussion to continue at the coding sprint
    • Error codes: integers? or strings? (including a specific namespace rather than the more discrete and arbitrary integers)
    • Supporting multiple AM API versions: How can servers do this? Multiple URLs as at ProtoGENI? If so, how do aggregates advertise those versions/URLs? (Perhaps in GetVersion?)
    • How are GENI error codes documented? A wiki page?
    • How are new aggregate-specific options or returns documented? XML-RPC introspection? New GetVersion entries?
    • Define GENI error codes
  • Continue discussion of UpdateSliver, slivers and sliver groups, and the addition of tickets on the geni developer mailing list
    • That discussion will also continue at the Coding Sprint session
  • We began the discussion of tickets, hearing details of the meaning of tickets, their semantics, and their lifecycle, from Rob Ricci, Ilia Baldine (channeling Jeff Chase), and Andy Bavier

NOTE We continued discussing AM API changes during the Coding Sprint session. At that session, we resolved outstanding questions on change set B part 2, made a few modifications to change set A, and adopted those changes as AM API version 2. Those present agreed to implement all of API version 2 in the coming weeks, and to continue discussing other changes (like updateSliver) for version 3 in the coming weeks.

Selected Discussion Points

  • Change set A (RSpecs are XML) was adopted without discussion
  • Change set B part 1 (new options argument) was adopted with minor discussion.
  • Change set B part 2 (methods return XML-RPC structs) has a few minor open questions, and should be in API version 2 if we can resolve these issues shortly:
    • We must agree to and document GENI error codes
    • Error codes were proposed as integers, with the space divided by aggregate developer. That either wastes codes or limits or both, while also hiding in a translation table whose codes these are. Why not use strings?
    • On errors, maybe aggregates should return the version of the API that they speak?
    • Some aggregates will desire to speak multiple versions of the API
    • ProtoGENI uses distinct URLs to allow the client to indicate to the server which version they are speaking
    • Servers must then advertise those URLs to clients in some standard way
    • Clarification: the 'output' return is human-readable and not machine parsable
  • UpdateSliver turned into a discussion of how resources get partitioned between aggregates and between slivers, which led into the discussion of slivers vs groups of slivers vs slices. We postponed this discussion.
  • Rob Ricci focused on the lifecycle of tickets.
    • Tickets support two phase commit
    • Tickets are a promise of resources, that make the resources unavailable to others
    • Tickets can be further delegated
    • In PG tickets are for specific resources, though they could be generic
    • In PG reservations either wholly succeed or fail; that decision is orthogonal to the use of tickets
  • Ilia Baldine / Jeff Chase described tickets in Orca as a contract
    • Tickets are a signed contract promising future resources for a particular time window
    • Tickets indicate what, where, how many, and other properties, restrictions, and whether they can be delegated
    • Tickets can be delegated, split
    • The ticket holder redeems the ticket at the resource provider to get the resources
    • Tickets may be for generic or specific resources
    • Tickets name the resource provider (the AM), which allows brokers.
    • Brokers allow aggregates to concentrate power, to collaborate on policy, etc
  • Larry Peterson expressed some concern with tickets because they are a promise, and all allocations are only best-effort in PlanetLab
  • Andy Bavier of PlanetLab described a desire to use tickets for future reservations
    • They are just experimenting with tickets now
    • They have no need for coordinated reservations
    • They do not want tickets mandated in the API because it adds overhead for them