Changes between Version 12 and Version 13 of GAPI_AM_API


Ignore:
Timestamp:
12/12/11 11:05:01 (13 years ago)
Author:
Aaron Helsinger
Comment:

Updating to AM API v2

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API

    v12 v13  
    33= GENI Aggregate Manager API =
    44
    5 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.
     5The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers.
    66
    7 This is the GENI AM API Version 1.
     7The latest version of the GENI AM API is [wiki:GAPI_AM_API_V2 Version 2].
    88
    9 See Also:
     9== See Also ==
    1010 * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf Slice-based Facility Architecture (SFA) specification]
    1111 * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa-impl.pdf PlanetLab Implementation of the Slice-Based Facility Architecture]
    1212 * [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 ProtoGENI Component Manager API revision 2]
    1313 * [wiki:GeniApi GENI API] implementation status
    14  * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for the next version of this API
     14 * [wiki:GAPI_AM_API_ISSUES Open issues with this API]
     15 * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for future versions of this API
    1516
    1617== Versions ==
    1718
    18  * Latest: 1 - Documented on this page
    19  * Draft: 2 - Documented [wiki:GAPI_AM_API_DRAFT here]
    20   * Includes Change Sets A and B from the Draft wiki page
    21   * Specify that GENI RSpecs adopt the ProtoGENI V2 RSpecs format as documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec here]
    22   * Include additional options in !GetResources and !ListResources to allow aggregates to support the PG RSpecs in addition to their own native format
    23   * Add an 'options' argument, an XMLRPC struct, to all methods with no required values. This allows Aggregates to innovate or support resource-specific functionality.
    24   * Modify all methods to return an XMLRPC 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.
    25  * Next: 3 - Also documented [wiki:GAPI_AM_API_DRAFT here]
    26   * Change Set C: Add an !UpdateSliver method to add/remove/modify resources from a slice at an aggregate
    27   * Change Set D: Modify the API methods to explicitly support multiple slivers per slice at an aggregate
    28   * Change Set E: Add the use of Tickets to API methods
    29   * Others to be proposed
    30  * Previous: None
    31 
    32 == To Do ==
    33  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.
    34  1. Add pages with details on the structure & format & requirements of URNs, Credentials, Certificates, and Privileges.
    35  1. Discuss areas for extension of the API and for improving API implementation
    36 
    37 
    38 -----
    39 == !GetVersion ==
    40 
    41 Return the version of the GENI Aggregate API supported by this aggregate.
    42 
    43 {{{
    44 struct GetVersion()
    45 }}}
    46 
    47 The result is an [http://www.xmlrpc.com/spec XMLRPC] struct with at least the following members:
    48 
    49 {{{
    50 {
    51   int geni_api;
    52 }
    53 }}}
    54 
    55  `geni_api`::
    56     An integer indicating the revision of the Aggregate Manager API that an aggregate supports. The current version of the API is 1 (one).
    57 
    58 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.
    59 
    60 This 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.
    61 
    62 -----
    63 == !ListResources ==
    64 
    65 Return information about available resources or resources allocated to a slice.
    66 
    67 {{{
    68 string ListResources(string credentials[], struct options)
    69 }}}
    70 
    71  `credentials[]`::
    72     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.
    73 
    74  `options`::
    75     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.
    76 
    77 The following members are available for use in the options parameter. All aggregate managers are required to implement these options.
    78 
    79 {{{
    80 {
    81   boolean geni_available;
    82   boolean geni_compressed;
    83   string geni_slice_urn;
    84 }
    85 }}}
    86 
    87  `geni_available`::
    88     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.
    89 
    90  `geni_compressed`::
    91     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].
    92 
    93  `geni_slice_urn`::
    94     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.
    95 
    96 
    97 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.
    98 
    99 This 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).
    100 
    101 
    102 -----
    103 == !CreateSliver ==
    104 
    105 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 [wiki:GAPI_AM_API#SliverStatus SliverStatus].
    106 
    107 {{{
    108 string CreateSliver(string slice_urn,
    109                     string credentials[],
    110                     string rspec,
    111                     struct users[])
    112 }}}
    113 
    114  `slice_urn`::
    115    The URN of the slice to which the resources specified in {{{rspec}}} will be allocated.
    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}}}. 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.  Aggregates should ensure that the expiration time of the slice does not exceed the expiration time of the slice credential used to perform this operation.
    119 
    120  `rspec`::
    121    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].
    122 
    123   `users`::
    124   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:
    125 {{{
    126 [
    127   {
    128     urn: urn:publicid:IDN+geni.net:gcf+user+alice
    129     keys: [<ssh key>, <ssh key>]
    130   },
    131   {
    132     urn: urn:publicid:IDN+geni.net:gcf+user+bob
    133     keys: [<ssh key>]
    134   }
    135 ]
    136 }}}
    137 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.
    138 
    139 This 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).
    140 
    141 
    142 -----
    143 == !DeleteSliver ==
    144 
    145 Delete a sliver by stopping it if it is still running, and then deallocating the resources associated with it.  This call will stop and deallocate all resources associated with the given slice URN.
    146 
    147 {{{
    148 boolean DeleteSliver(string slice_urn, string credentials[])
    149 }}}
    150 
    151  `slice_urn`::
    152    The URN of the slice whose sliver should be deleted.
    153 
    154  `credentials`::
    155    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.
    156 
    157 Returns true on success and false on failure.
    158 
    159 This 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).
    160 
    161 
    162 -----
    163 == !SliverStatus ==
    164 
    165 Get the status of a sliver.
    166 
    167 {{{
    168 struct SliverStatus(string slice_urn, string credentials[])
    169 }}}
    170 
    171  `slice_urn`::
    172    The URN of the slice for which the sliver status is requested.
    173 
    174  `credentials`::
    175    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.
    176 
    177 Returns an XMLRPC struct upon successful completion. The struct is of the following form:
    178 
    179 {{{
    180 {
    181   geni_urn: <sliver URN>
    182   geni_status: ready
    183   geni_resources: [ { geni_urn: <resource URN>
    184                       geni_status: ready
    185                       geni_error: ''},
    186                     { geni_urn: <resource URN>
    187                       geni_status: ready
    188                       geni_error: ''}
    189                   ]
    190 }
    191 }}}
    192 
    193 The top level members of the returned struct pertain to the sliver as a whole. These members are:
    194 
    195  `geni_urn`::
    196     The URN of the sliver as a string. This is the ''sliver'' and not the ''slice'', and should be selected by the aggregate manager.
    197 
    198  `geni_status`::
    199     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.
    200 
    201  `geni_resources`::
    202     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.
    203 
    204 The members of the resource struct(s) are as follows:
    205 
    206  `geni_urn`::
    207     The URN of the resource as a string. This is specific to the ''sliver'', and should be selected by the aggregate manager to allow status reporting and control at the finest level supported at that aggregate. It may be a sliver URN if there is only 1 resource in the sliver.
    208 
    209  `geni_status`::
    210     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.
    211 
    212  `geni_error`::
    213     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}}}.
    214 
    215 
    216 This 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.
    217 
    218 
    219 -----
    220 == !RenewSliver ==
    221 
    222 Renews the resources in a sliver, extending the lifetime of the slice.
    223 
    224 {{{
    225 boolean RenewSliver(string slice_urn,
    226                     string credentials[],
    227                     string expiration_time)
    228 }}}
    229 
    230  `slice_urn`::
    231    The URN of the slice that is to have its sliver renewed.
    232 
    233  `credentials`::
    234    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.
    235 
    236  `expiration_time`::
    237     A string in [http://tools.ietf.org/html/rfc3339 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.
    238 
    239 
    240 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.
    241 
    242 This 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.
    243 
    244 
    245 -----
    246 == Shutdown ==
    247 
    248 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.
    249 
    250 {{{
    251 boolean Shutdown(string slice_urn, string credentials[])
    252 }}}
    253 
    254  `slice_urn`::
    255    The URN of the slice is to have its sliver shut down.
    256 
    257  `credentials`::
    258    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.
    259 
    260 Returns true on success, false otherwise.
    261 
    262 This 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.
     19 * Latest: [wiki:GAPI_AM_API_V2 Version 2].
     20 * Previous: [wiki:GAPI_AM_API_V1 Version 1]
     21 * [wiki:GAPI_AM_API_DRAFT Draft Changes for Version 3+]