Changes between Initial Version and Version 1 of GAPI_AM_API


Ignore:
Timestamp:
03/09/10 11:24:43 (14 years ago)
Author:
tmitchel@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API

    v1 v1  
     1[[PageOutline]]
     2
     3= GENI Aggregate Manager API =
     4
     5The 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.
     6
     7See Also:
     8 * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf Slice-based Facility Architecture (SFA) specification]
     9 * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa-impl.pdf PlanetLab Implementation of the Slice-Based Facility Architecture]
     10 * [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 ProtoGENI Component Manager API revision 2]
     11
     12== To Do ==
     13 1. Add a state diagram in the [wiki:GAPI_AM_API#SliverStatus 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.
     14
     15
     16-----
     17== !GetVersion ==
     18
     19Return the version of the GENI Aggregate API supported by this aggregate.
     20
     21{{{
     22struct GetVersion()
     23}}}
     24
     25The result is an [http://www.xmlrpc.com/spec XMLRPC] struct with at least the following members:
     26
     27{{{
     28{
     29  int geni_api;
     30}
     31}}}
     32
     33 `geni_api`::
     34    An integer indicating the revision of the Aggregate Manager API that an aggregate supports. The current version of the API is 1 (one).
     35
     36Implementations 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.
     37
     38This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetVersion GetVersion] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
     39
     40-----
     41== !ListResources ==
     42
     43Return information about available resources or resources allocated to a slice.
     44
     45{{{
     46string ListResources(string credentials[], struct options)
     47}}}
     48
     49 `credentials[]`::
     50    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).
     51
     52 `options`::
     53    An [http://www.xmlrpc.com/spec 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.
     54
     55The following members are available for use in the options parameter. All aggregate managers are required to implement these options.
     56
     57{{{
     58{
     59  boolean geni_available;
     60  boolean geni_compressed;
     61  string geni_slice_urn;
     62}
     63}}}
     64
     65 `geni_available`::
     66    An [http://www.xmlrpc.com/spec 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.
     67
     68 `geni_compressed`::
     69    An [http://www.xmlrpc.com/spec 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 [http://www.ietf.org/rfc/rfc1950.txt RFC 1950].
     70
     71 `geni_slice_urn`::
     72    An [http://www.xmlrpc.com/spec 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.
     73
     74
     75The 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.
     76
     77This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DiscoverResources DiscoverResources] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !GetResources operation (sec. 6.2.4).
     78
     79
     80-----
     81== !CreateSliver ==
     82
     83Allocate 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 [wiki:GAPI_AM_API#SliverStatus SliverStatus].
     84
     85{{{
     86string CreateSliver(string slice_urn,
     87                    string credentials[],
     88                    string rspec)
     89}}}
     90
     91 `slice_urn`::
     92   The URN of the slice to which the resources specified in {{{rspec}}} will be allocated.
     93
     94 `credentials`::
     95   An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}}.
     96
     97 `rspec`::
     98   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 [wiki:GAPI_AM_API#ListResources ListResources].
     99
     100The 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.
     101
     102This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#CreateSliver CreateSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !CreateSlice operation (sec. 6.2.1).
     103
     104
     105-----
     106== !DeleteSliver ==
     107
     108Delete a sliver by stopping it if it is still running, and then deallocating the resources associated with it.
     109
     110{{{
     111boolean DeleteSliver(string slice_urn, string credentials[])
     112}}}
     113
     114 `slice_urn`::
     115   The URN of the slice whose sliver should be deleted.
     116
     117 `credentials`::
     118   An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}}.
     119
     120Returns true on success and false on failure.
     121
     122This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DeleteSliver DeleteSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !DeleteSlice operation (sec. 6.2.3).
     123
     124
     125-----
     126== !SliverStatus ==
     127
     128Get the status of a sliver.
     129
     130{{{
     131struct SliverStatus(string slice_urn, string credentials[])
     132}}}
     133
     134 `slice_urn`::
     135   The URN of the slice for which the sliver status is requested.
     136
     137 `credentials`::
     138   An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}}.
     139
     140Returns an XMLRPC struct upon successful completion. The struct is of the following form:
     141
     142{{{
     143{
     144  geni_urn: <sliver URN>
     145  geni_status: ready
     146  geni_resources: [ { geni_urn: <resource URN>
     147                      geni_status: ready
     148                      geni_error: ''},
     149                    { geni_urn: <resource URN>
     150                      geni_status: ready
     151                      geni_error: ''}
     152                  ]
     153}
     154}}}
     155
     156The top level members of the returned struct pertain to the sliver as a whole. These members are:
     157
     158 `geni_urn`::
     159    The URN of the sliver as a string.
     160
     161 `geni_status`::
     162    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.
     163
     164 `geni_resources`::
     165    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.
     166
     167The members of the resource struct(s) are as follows:
     168
     169 `geni_urn`::
     170    The URN of the resource as a string.
     171
     172 `geni_status`::
     173    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.
     174
     175 `geni_error`::
     176    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}}}.
     177
     178
     179This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#SliverStatus,WaitForStatus SliverStatus] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
     180
     181
     182-----
     183== !RenewSliver ==
     184
     185Renews the resources in a sliver, extending the lifetime of the slice.
     186
     187{{{
     188boolean RenewSliver(string slice_urn,
     189                    string credentials[],
     190                    string expiration_time)
     191}}}
     192
     193 `slice_urn`::
     194   The URN of the slice that is to have its sliver renewed.
     195
     196 `credentials`::
     197   An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}}.
     198
     199 `expiration_time`::
     200    A string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format indicating the expiration_time desired by the caller. This time must be less than or equal to the slice duration in the slice credential.
     201
     202
     203Returns 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.
     204
     205This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RenewSlice RenewSlice] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
     206
     207
     208-----
     209== Shutdown ==
     210
     211Perform 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.
     212
     213{{{
     214boolean Shutdown(string slice_urn, string credentials[])
     215}}}
     216
     217 `slice_urn`::
     218   The URN of the slice is to have its sliver shut down.
     219
     220 `credentials`::
     221   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.
     222
     223Returns true on success, false otherwise.
     224
     225This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Shutdown Shutdown] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.