GENI Aggregate Manager API Draft Revisions

This page documents DRAFT revisions to the GENI Aggregate Manager API, proposed for the next version of the API. Revisions documented here have been agreed to in discussions on the geni dev mailing list, and during at least on GEC, but not formally adopted. Well behaved aggregates will typically already implement these revisions.

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.

The current officially adopted version of the API is 1 and documented on the main API page here.

This page documents proposed and generally accepted changes for AM API version 2.

• As of June 2011, the latest software from ProtoGENI and SFA (as of code tag 1.0-24) comply with these changes.
• Omni version 1.3 (released June 2011) adds client software support for these changes.

Summary of Proposed Changes

• Specify GENI RSpecs as complying with schemas documented as the ProtoGENI V2 RSpecs as documented ​here
• Include additional options in GetResources and ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format.

Proposing Additional Changes

GENI community members are encouraged to propose changes to the GENI Aggregate Manager API.

Technical discussions are generally held on the ​Developers mailing list

Specific questions may be directed to the software team at the GPO (Tom Mitchell, Aaron Helsinger, and Sarah Edwards) at {tmitchel, ahelsing, sedwards} at geni.net

Proposed Change Details

GENI Standard RSpecs

At GEC10 the GENI community agreed that GENI RSpecs would be in the ​ProtoGENI V2 format. Aggregates are free to use an alternate format internally, but must accept and produce compliant RSpecs on demand. Note that individual aggregates may use RSpec extensions to describe custom resources or properties of resources. For RSpec extension information, see the ProtoGENI ​wiki.

For more information:

• ​ProtoGENI V2 format
• ​RSpec extension information
• ​RSpec schemas

Specific changes include:

• ListResources: Return value of ListResources remains an ​XMLRPC string, but its format and meaning are now proscribed.

The return value is an RSpec matching the ​ProtoGENI V2 RSpec schema in text format if geni_compressed is unspecified or set to false. The return value will be a ZLib compressed and then base 64 encoded string representation of the RSpec if geni_compressed is specified and set to true.

This RSpec will be a ​advertisement RSpec when invoked with no geni_slice_urn option, representing the resources available at this aggregate. When the client supplies the geni_slice_urn option, then the aggregate will return a ​manifest RSpec, representing all resources allocated to that slice by this aggregate.

• CreateSliver: rspec argument remains an ​XMLRPC string, but its format and meaning are now proscribed.

rspec

An RSpec matching the ​ProtoGENI V2 request RSpec ​schema containing the resources that the caller is requesting for allocation to the slice specified in slice_urn. These are expected to be based on resources returned by a previous invocation of ListResources.

• CreateSliver: return value remains an ​XMLRPC string, but its format and meaning are now proscribed.

The return value is an RSpec matching the ​ProtoGENI V2 manifest RSpec ​schema indicating the resources that were allocated to the slice. The result RSpec may contain additional information about the allocated resources.

New RSpec Version Options

In order to allow aggregates to support both a native RSpec format (e.g. the standard PlanetLab / SFA RSpecs) as well as the GENI-standard format (ProtoGENI V2 schemas), we need new options to allow a client to request RSpecs in a particular format.

Specifically, aggregates will advertise (in GetVersion) the list of Advertisement and Request RSpec types they are willing to accept, as well as the default Advertisement RSpec type. And they will produce manifest RSpecs in a format matching the format of the CreateSliver input request RSpec (e.g. return a manifest RSpec matching ProtoGENI V2 manifest schema when given a ProtoGENI V2 request RSpec, and a native PlanetLab manifest RSpec when given a PlanetLab request RSpec).

Contract details

Aggregates advertise the type and version of RSpec formats that they support. If available, they specify the schema, namespace and extensions combination which is the authoritative definition of that format. Clients of the API should understand that combination in order to know how to understand the resources available at that aggregate.

If an aggregate advertises a particular type/version (optionally defined with a combination of schema, namespace and extensions) in the ad_rspec_versions attribute of GetVersion, then it promises to send a correct Advertisement RSpec in response to a ListResources call which supplies an rspec_version option containing that type/version. (rspec_version is a struct with 2 members, type and version. type and version are case-insensitive strings, matching those in ad_rspec_versions).

If an Aggregate advertises a particular type/version (optionally defined with a combination of schema, namespace and extensions) in the request_rspec_versions attribute of GetVersion then it promises to correctly honor a CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (ie a PGV2 request is answered with a PG V2 manifest). The aggregate also promises to send a correctly formatted Manifest RSpec in response to a ListResources call which supplies a valid geni_slice_urn option and an rspec_version option containing that supported type/version.

The GetVersion attribute default_ad_rspec will be one of the values in the GetVersion ad_rspec_versions array.

New GetVersion required attributes

Return the version of the GENI Aggregate API and RSpecs supported by this aggregate.

struct GetVersion()

The result is an ​XMLRPC struct with at least the following members:

{
  int geni_api;
  array request_rspec_versions of {
    string type;
    string version;
    string schema;
    string namespace;
    array extensions of string;
  };
  array ad_rspec_versions of {
    string type;
    string version;
    string schema;
    string namespace;
    array extensions of string;
  };
  default_ad_rspec of {
    string type;
    string version;
  };
}

geni_api

An integer indicating the revision of the Aggregate Manager API that an aggregate supports. The version of the API documented here is 2 (two).

request_rspec_versions

An array of data structures indicating the RSpec types accepted by this AM in a request.

ad_rspec_versions

An array of data structures indicating what types of RSpec advertisements may be produced by this AM in ListResources.

default_ad_rspec

A data structure indicating the default type of advertisement RSpec produced by this AM in ListResources. Matches one of the values from ad_rspec_versions

Elements used within request_rspec_versions, ad_rspec_versions, and default_ad_rspec:

type, version

Two case-insensitive strings which together comprise the type of RSpec. The RSpec type should be one of "protogeni", "sfa", "orca", "openflow", or "orbit" and version should be a type-specific version identifier as specified by the appropriate control framework.

schema

An optional URL pointing to a schema which can be used to verify the given type of RSpec.

namespace

An optional XML namespace which the RSpec of the given type belongs to.

extensions

An array of cluster-specific strings denoting which extensions are supported. In the case of ProtoGENI, these are XML namespaces which denote the extension as a whole.

Implementations can add additional members to the struct as desired. Implementations should choose an appropriate prefix to avoid conflicts, but avoid geni_ which should be reserved for common options.

This operation is similar to ProtoGENI's ​GetVersion operation. The ​SFA specification does not include this operation.

New ListResources Option

ListResources will take an additional option, rspec_version, allowing a user to request an Advertisement or Manifest Rspec in a particular format. This struct must contain a type and version matching one of this Aggregate's advertised ad_rspec_versions.

Specifics:

Return information about available resources or resources allocated to a slice.

string ListResources(string credentials[], struct options)

....

options

An ​XMLRPC struct containing members indicating the set of resources the caller is interested in or the format of the result. In addition to the members specified below, callers can pass additional members that specific aggregate manager implementations might honor. Implementations can add additional members to the struct as desired. Implementations should choose an appropriate prefix to avoid conflicts, but avoid geni_ which should be reserved for common options.

The following members are available for use in the options parameter. All aggregate managers are required to implement these options.

{
  boolean geni_available;
  boolean geni_compressed;
  string geni_slice_urn;
  struct rspec_version {
    string type;
    string version;
  };
}

....

rspec_version

An ​XMLRPC struct indicating the type and version of Advertisement or Manifest RSpec to return. The struct contains 2 members, type and version. type and version are case-insensitive strings, matching those in ad_rspec_versions as returned by GetVersion at this aggregate.

If this option is not included in the request, then the returned RSpec will be of the type specified in default_ad_rspec. That Rspec will be an Advertisement RSpec when no geni_slice_urn option is supplied. When a valid geni_slice_urn option is supplied, the returned RSpec will be a Manifest RSpec of the type corresponding to default_ad_rspec, but in manifest format.

If the aggregate cannot support the requested type/version (that pair is not listed in ad_rspec_versions), then the aggregate returns an Exception.

New CreateSliver behavior

If an Aggregate advertises a type/version pair in its request_rspec_versions as returned by GetVersion, then it promises to correctly honor a CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (ie a request in PGV2 schema is answered with a manifest in PG V2 format).