wiki:GAPI_AM_API_V2

Version 3 (modified by Aaron Helsinger, 12 years ago) (diff)

--

GENI Aggregate Manager API Version 2

The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers.

This is the GENI AM API Version 2.

See Also:

Versions

  • Latest: 2 - Documented on this page. Changes since v1 include:
    • Includes Change Sets A and B from the v2 Deltas page
    • Specify that GENI RSpecs are XML documents following standard schemas published on geni.net and documented on the ProtoGENI wiki
    • Include additional options in GetVersion and ListResources to allow aggregates to specify the RSpec formats they support
    • Add an 'options' argument, an XML-RPC struct, to all methods with no required values. This allows Aggregates to innovate or support resource-specific functionality.
    • Modify all methods to return an XML-RPC struct consisting of at least (1) a return 'code', (2) the 'value' specified by v1 of the API, and (3) a human-readable 'output' on errors. Aggregates are free to innovate by adding additional return values.
  • Previous: Version 1
  • Draft change for version 3+
    • Covers changes proposed for future versions of this API. Documented changes include:
    • Change Set C: Add an UpdateSliver method to add/remove/modify resources from a slice at an aggregate
    • Change Set D: Modify the API methods to explicitly support multiple slivers per slice at an aggregate
    • Change Set E: Add the use of Tickets to API methods
    • Others to be proposed

Changes since Version 1

Includes Change Sets A and B from the v2 Deltas page.

Change Set A: RSpecs are XML documents following GENI schemas

Note: At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change

  • Removed the default_ad_rspec value from GetVersion
  • Made the rspec_version argument to ListResources required and renamed it geni_rspec_version
  • Renamed the other return values from GetVersion to use the geni_ naming prefix

Other parts of this change set have been discussed and most current aggregates already implement them. The community has agreed to include this change in version 2 of this API. This change will:

Change Set B: Flexible arguments and returns

This change set was adopted at GEC12 for inclusion in AM API version 2.

  • All methods take an options argument, which is a non null XML-RPC struct. No required options are added with this change - the struct may be empty (except at ListResources). Details are on the version 2 Details wiki page.
  • Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs.
    • code indicates success or error return. This itself is an XML-RPC struct, whose content is defined.
    • value is the return value as specified in AM API v1 or as modified by Change Set A (RSpec, etc), and
    • output is a human readable indication of the nature of the return or error.
    • Aggregates are free to use other additional name/value pairs in the return struct.
    • Commentary on the return structure is documented.
  • Aggregates are free to support additional options and return values, but must document them as discussed
  • Aggregate may support multiple versions of the AM API, as discussed

API Overview

The GENI Aggregate Manager API is the control plane interface by which experimenters discover, reserve and control resources at resource providers. It does not include resource specific interactions, application level interactions, or monitoring and management functions.

API Protocols and Data Structures

GENI specifies that the AM API is provided via XML-RPC over an SSL connection. Aggregate Managers shall require client side GENI certificates to authenticate users, accepting only certificates that comply with the adopted GENI certificates standards. The GENI AM API therefore assumes that users have already been authenticated, and that the aggregate manager has available the client certificate to identify the user.

Clients are authorized to take actions at aggregates using GENI credentials. To that end, all methods that require authorization take an argument credentials. In particular, operations on a single GENI slice will require a credential that authorizes the client whose certificate was used to authenticate to operate on the slice named by a slice_urn argument to the method.

The primary data structure used within this API is a resource specification, known as an RSpec. These XML documents follow a specific set of schemas. They are used by aggregates to list and describe local resources (advertisement RSpecs), by experimenters to describe desired resources (request RSpecs), and then by aggregates to describe reserved resources (manifest RSpecs). For more information on RSpecs, see the details page.

Using the GENI AM API

Clients (experimenters) use the AM API to discover resources (ListResources), request resources (CreateSliver), check the status of resources as they are started (SliverStatus), extend their reservation (RenewSliver), and then return the resources when done (DeleteSliver). Client tools may use GetVersion to ensure aggregates speak a compatible version of the AM API and known formats for RSpecs. Administrators may call Shutdown to stop the resources of a slice at this aggregate, perhaps if that slice is misbehaving.

ListResources returns to the client an advertisement RSpec - a detailed listing of the resources available at that aggregate. From this information, the experimenter may determine which resources to reserve for their use. The RSpec should also have enough information to help the experimenter set the initial configuration for their resources.

Once the experimenter has selected the resources they want and how to configure them, they produce a request RSpec, detailing the resources they want and how they should be configured. They separately contact their slice authority to obtain a slice credential, granting them rights to reserve resources for that slice. The experimenter then calls CreateSliver on this API, passing in both the slice credential and the request RSpec. The aggregate then attempts to satisfy the experimenter's resource request. If the aggregate can satisfy the request, the aggregate reserves the resources for the experimenter. The aggregate then starts the process of instantiating the resources and configuring them as requested in the request RSpec. Once that process has started, the CreateSliver call returns with a manifest RSpec, listing the resources as reserved and initially configured for the experimenter.

The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling SliverStatus. Once the resources are ready for use, the experimenter will start using the resources. The experimenter will also call RenewSliver to request that their reservation lasts as long as they require the resources for. When the experimenter is done using the resources, they call DeleteSliver to end their reservation. The aggregate then stops and clears the resources, freeing them for use by other clients.

Client work flow:

  1. <Experimenter gets a GENI certificate and slice credential>
  2. GetVersion(): learn RSpec formats supported at this aggregate
  3. ListResources(<user credential>, options): get Ad RSpec describing available resources
  4. <Experimenter constructs a request RSpec>
  5. CreateSliver(<slice URN>, <slice credential>, <request RSpec>, <users struct>, {}):
    • Aggregate reserves and starts resources
    • Return is a manifest RSpec describing the reserved resources
  6. SliverStatus(<slice URN>, <slice credential>, <new time>, {}) to check that resources are starting
  7. RenewSliver(<slice URN>, <slice credential>, {}) to extend reservation
  8. <Experimenter uses resources>
  9. DeleteSliver(<slice URN>, <slice credential>, {}) when done

API Methods

GetVersion

Get static version and configuration information about this aggregate. Return includes:

  • The version of the GENI Aggregate Manager API supported by this aggregate manager instance
  • URLs for other versions of this API supported by this aggregate
  • The RSpec formats accepted at this aggregate
  • Other information about the configuration of this aggregate.

For details on the arguments, return structure, and semantics, see the details page.

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

struct GetVersion([optional: struct options])

The result is an XML-RPC struct with at least the following members:

{
  int geni_api;
  struct code = {
       int geni_code;
       [optional: string am_type;]
       [optional: int am_code;]
         }
  struct value
      {
        int geni_api;
        struct geni_api_versions {
             URL <this API version #>; # value is a URL, name (key) is a number represented as a string
             [optional: other supported API versions and the URLs where they run]
        }
        array geni_request_rspec_versions of {
             string type;
             string version;
             string schema;
             string namespace;
             array extensions of string;
        };
        array geni_ad_rspec_versions of {
             string type;
             string version;
             string schema;
             string namespace;
             array extensions of string;
        };
      }
  string output;
}

Arguments Summary

Return Summary

As with all AM API methods, the return is an XML-RPC struct. For GetVersion, it includes:

  • The standard AM API code, value, and output entries. For details, see the Details page
  • geni_api: integer version of this API (2). Repeated here for backwards compatibility.

GetVersion value return members:

  • geni_api = 2 (Integer current version of this API).
  • List of versions of the API supported by this aggregate. For details on doing this, see the Details page.
  • List of request RSpec formats supported by this aggregate. For details on RSpecs, see the Details page.
  • List of advertisement RSpec formats supported by this aggregate. For details on RSpecs, see the Details page.

For details on GetVersion arguments, returns, and semantics, and a sample minimal return, see the Details page.


ListResources

Return a listing and description of available resources at this aggregate, or resources allocated to a named slice at this aggregate. The resource listing and description provides sufficient information for clients to select among available resources, or to use reserved resources. These listings are known as RSpecs.

struct ListResources(string credentials[], struct options)

Note that the options argument includes one required option geni_rspec_version.

As with all AM API methods, the return is an XML-RPC struct with at least the following members:

{
  struct code = {
       int geni_code;
       [optional: string am_type;]
       [optional: int am_code;]
         }
  string value;
  string output;
}

For details on the standard AM API return struct and code, value, and output entries, see the Details page.

This operation is similar to ProtoGENI's DiscoverResources operation and to the SFA's GetResources operation (sec. 6.2.4).

Arguments Summary

The following members are available for use in the options parameter. All aggregate managers are required to implement these options. See the details page for an explanation of the meaning and semantics of each.

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

Return Summary

For ListResources, value is an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be an advertisement RSpec showing all local resources, or one showing only available local resources, or a manifest RSpec of resources reserved for a particular slice.

The details page has details on ListResources arguments, returns, and semantics.


CreateSliver

Allocate resources as described in a request RSpec argument to a slice with the named URN. This operation is expected to start the allocated resources asynchronously after the operation has successfully completed. Callers can check on the status of the resources using SliverStatus. Resources will be reserved until a particular time, set by the aggregate according to policy. That expiration time will be no later than the expiration time of the provided slice credential. This method returns a listing and description of the resources reserved for the slice by this operation, in the form of a manifest RSpec.

struct CreateSliver(string slice_urn,
                    string credentials[],
                    string rspec,
                    struct users[],
                    struct options)

This operation is similar to ProtoGENI's CreateSliver operation and to the SFA's CreateSlice operation (sec. 6.2.1).

Arguments Summary

  • slice_urn: The URN of the slice to which the resources specified in rspec will be allocated. For details on GENI AM API URN identifiers, see the GENI wiki page.
  • rspec: An RSpec matching the GENI standard request RSpec schema containing the resources that the caller is requesting for allocation to the slice specified in slice_urn.
  • users[]: An array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. This struct has particular required members, documented on the V2 details page.

Return Summary

CreateSliver reserves the requested resources if possible. The aggregate then (asynchronously) starts those resources. As with all AM API methods, the return is an XML-RPC struct (see the Details page). The CreateSliver method returns in the value entry a manifest RSpec matching the GENI standard manifest RSpec schema listing and describing the resources that were allocated to the slice.

For details on CreateSliver arguments, returns, and semantics see the V2 details page.


DeleteSliver

Delete any slivers at the given aggregate belonging to the given slice, by stopping the resources if they are still running, and then deallocating the resources associated with the slice. When complete, this slice will own no resources on this aggregate - any such resources will have been stopped.

struct DeleteSliver(string slice_urn, string credentials[], struct options)

This operation is similar to ProtoGENI's DeleteSliver operation and to the SFA's DeleteSlice operation (sec. 6.2.3).

Arguments Summary

  • slice_urn: The URN of the slice for which all resources will be freed.

Return Summary

As with all AM API methods, the return is an XML-RPC struct (see the Details page). DeleteSliver stops all the slice's resources and removes the reservation. It returns in the value slot true or false indicating whether it did this successfully.

For details on DeleteSliver arguments, returns, and semantics, see the V2 details page.


SliverStatus

Get the status of a sliver or slivers belonging to the given slice at the given aggregate. Status may include other dynamic reservation or instantiation information as required by the resource type and aggregate. This method is used to provide updates on the state of the resources after the completion of CreateSliver, which began to asynchronously provision and start the resources.

struct SliverStatus(string slice_urn, string credentials[], struct options)

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

Arguments Summary

  • slice_urn: The URN of the slice for which the resource status is desired.

Return Summary

As with all AM API methods, the return is an XML-RPC struct (see the Details page). SliverStatus returns the status of the overall reservation, and of each addressable resource within the reservation in an XML-RPC struct in the value entry.

{
  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: ''}
                  ]
}

For details on SliverStatus arguments, returns, and semantics, see the V2 details page.


RenewSliver

Renews the resources in all slivers at this aggregate belonging to the given slice until the given time, extending the lifetime of the slice. Aggregates may limit how long reservations may be extended. Initial sliver expiration is set by aggregate policy, no later than the slice credential expiration time.

struct RenewSliver(string slice_urn,
                    string credentials[],
                    string expiration_time, 
                    struct options)

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

Arguments Summary

  • slice_urn: The URN of the slice for which the resource reservation will be extended.
  • expiration_time: The date-time string in RFC 3339 format in UTC when the reservation should be extended until.

Return Summary

As with all AM API methods, the return is an XML-RPC struct (see the Details page). The actual return in value is true or false indicating whether the reservation was successfully extended to the requested date and time.

For details on RenewSliver arguments, returns, and semantics, see the V2 details wiki page.


Shutdown

Perform an emergency shut down of a sliver or slivers at this aggregate belonging to the given slice. This operation is intended for administrative use. The sliver is shut down but remains available for further forensics.

struct Shutdown(string slice_urn, string credentials[], struct options)

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

Arguments Summary

  • slice_urn: The URN of the slice for which all resources will be halted.

Return Summary

As with all AM API methods, the return is an XML-RPC struct (see the Details page). The value return is a boolean indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics.

For details on Shutdown arguments, returns, and semantics, see the V2 details wiki.