wiki:GAPI_AM_API

Version 6 (modified by tmitchel@bbn.com, 9 years ago) (diff)

--

GENI Aggregate Manager API

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.

See Also:

To Do

  1. Add a state diagram in the SliverStatus section to indicate that a component starts in configuring, can go from configuring to either ready or failed, and can go from ready to failed. failed is a terminal status.
  2. Add pages with details on the structure & format & requirements of URNs, Credentials, Certificates, and Privileges.
  3. Discuss areas for extension of the API and for improving API implementation

GetVersion

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

struct GetVersion()

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

{
  int geni_api;
}
geni_api
An integer indicating the revision of the Aggregate Manager API that an aggregate supports. The current version of the API is 1 (one).

Implementations can add additional members to the struct as desired. The prefix geni_ is reserved for members that are part of this API specification. Implementation should choose an appropriate prefix to avoid conflicts.

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


ListResources

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

string ListResources(string credentials[], struct options)
credentials[]
An array of credentials. At least one credential must be valid for this operation (signed by a valid GENI certificate authority either directly or by chain, and not expired). Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions.
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. The prefix geni_ is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts.

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;
}
geni_available
An XMLRPC boolean value indicating whether the caller is interested in all resources or available resources. If this value is true, the result should contain only available resources. If this value is false both available and allocated resources should be returned. The Aggregate Manager is free to limit visibility of certain resources based on the credentials parameter.
geni_compressed
An XMLRPC boolean value indicating whether the caller would like the result to be compressed. If the value is true, the returned resource list will be compressed according to RFC 1950.
geni_slice_urn
An XMLRPC string indicating that the caller is interested in the set of resources allocated to the slice named by this URN. If no resources are allocated to the indicated slice by this aggregate, an empty RSPEC should be returned.

The return value is an RSPEC in text format if geni_compressed is unspecified or set to false. The return value will be a base 64 encoded if geni_compressed is specified and set to true.

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


CreateSliver

Allocate resources to a slice. 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.

string CreateSliver(string slice_urn,
                    string credentials[],
                    string rspec,
                    struct users[])
slice_urn
The URN of the slice to which the resources specified in rspec will be allocated.
credentials
An array of credentials. At least one credential must be a valid slice credential for the slice specified in slice_urn. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions.
rspec
An RSPEC 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.
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. Each struct must include the key 'keys', which is an array of strings and can be empty. The struct must also include the key 'urn', which is the user’s URN string. The users array can be empty. For example:
[
  {
    urn: urn:publicid:IDN+geni.net:gcf+user+alice
    keys: [<ssh key>, <ssh key>]
  },
  {
    urn: urn:publicid:IDN+geni.net:gcf+user+bob
    keys: [<ssh key>]
  }
]

The return value is an RSPEC indicating the resources that were allocated to the slice. The result RSPEC may contain additional information about the allocated resources.

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


DeleteSliver

Delete a sliver by stopping it if it is still running, and then deallocating the resources associated with it.

boolean DeleteSliver(string slice_urn, string credentials[])
slice_urn
The URN of the slice whose sliver should be deleted.
credentials
An array of credentials. At least one credential must be a valid slice credential for the slice specified in slice_urn. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions.

Returns true on success and false on failure.

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


SliverStatus

Get the status of a sliver.

struct SliverStatus(string slice_urn, string credentials[])
slice_urn
The URN of the slice for which the sliver status is requested.
credentials
An array of credentials. At least one credential must be a valid slice credential for the slice specified in slice_urn. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions.

Returns an XMLRPC struct upon successful completion. The struct is of the following form:

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

The top level members of the returned struct pertain to the sliver as a whole. These members are:

geni_urn
The URN of the sliver as a string.
geni_status
A string indicating the status of the sliver. Possible values are: configuring, ready, failed, and unknown. Configuring indicates that at least one resource is being configured and none have failed. Ready indicates that all resources in the sliver are ready. Failed indicates that at least one resource in the sliver has failed. Unknown indicates that the state of the sliver is not one of the known states. More detailed information can be found in the value of the geni_resources member.
geni_resources
An array of structs. Each struct in the array gives the status of each resource in the sliver. The members of these structs are described below.

The members of the resource struct(s) are as follows:

geni_urn
The URN of the resource as a string.
geni_status
A string indicating the status of the resource. Possible values are: configuring, ready, failed, and unknown. Configuring indicates that the resources is being configured and is not yet ready for use. Ready indicates that the resource is ready. Failed indicates that the resource has failed. Unknown indicates that the state of the resource is not one of the known states.
geni_error
A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the resource if its status is failed.

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


RenewSliver

Renews the resources in a sliver, extending the lifetime of the slice.

boolean RenewSliver(string slice_urn,
                    string credentials[],
                    string expiration_time)
slice_urn
The URN of the slice that is to have its sliver renewed.
credentials
An array of credentials. At least one credential must be a valid slice credential for the slice specified in slice_urn. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions.
expiration_time
A string in RFC 3339 format indicating the expiration_time desired by the caller. Note these times, per the RFC, must be in or relative to UTC. This time must be less than or equal to the slice duration in the slice credential. In other words, at least one supplied (slice) credential must still be valid at the desired new expiration time for this call to succeed.

Returns true on successful completion, false otherwise. It is assumed that the caller will have already extended the lifetime of the slice credential with the appropriate slice authority prior to calling RenewSliver.

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


Shutdown

Perform an emergency shut down of a sliver. This operation is intended for administrative use. The sliver is shut down but remains available for further forensics.

boolean Shutdown(string slice_urn, string credentials[])
slice_urn
The URN of the slice is to have its sliver shut down.
credentials
An array of credentials. At least one credential must be a valid slice credential for the slice specified in slice_urn or a valid administrative credential with sufficient privileges. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions.

Returns true on success, false otherwise.

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