Changes between Version 2 and Version 3 of DRAFT_GAPI_AM_API_V1


Ignore:
Timestamp:
12/13/11 16:16:26 (8 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DRAFT_GAPI_AM_API_V1

    v2 v3  
    1 [[PageOutline]]
    2 
    3 = GENI Aggregate Manager API Version 1 =
    4 
    5 The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers.
    6 
    7 This is the GENI AM API Version '''1'''.
    8 
    9 See Also:
    10  * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf Slice-based Facility Architecture (SFA) specification]
    11  * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa-impl.pdf PlanetLab Implementation of the Slice-Based Facility Architecture]
    12  * [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 ProtoGENI Component Manager API revision 2]
    13  * [wiki:GeniApi GENI API] implementation status
    14  * [wiki:GAPI_AM_API Latest] revision of this API
    15  * [wiki:DRAFT_GAPI_AM_API_DRAFT Draft API Revisions] proposed for future versions of this API
    16 
    17 == Versions ==
    18 
    19  * Latest: Always available on [wiki:GAPI_AM_API the main AM API page]
    20   * As of this writing, that is [wiki:DRAFT_GAPI_AM_API_V2 version 2]
    21  * Previous: Version 1 - Documented on this page
    22  * [wiki:DRAFT_GAPI_AM_API_DRAFT Draft Changes]
    23   * As of this writing, those will be for version 3 of the API
    24   * Documents proposed changes for future versions of the API
    25 
    26 -----
    27 == !GetVersion ==
    28 
    29 Return the version of the GENI Aggregate API supported by this aggregate.
    30 
    31 {{{
    32 struct GetVersion()
    33 }}}
    34 
    35 The result is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members:
    36 
    37 {{{
    38 {
    39   int geni_api;
    40 }
    41 }}}
    42 
    43  `geni_api`::
    44     An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 1 of the API.
    45 
    46 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.
    47 
    48 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.
    49 
    50 -----
    51 == !ListResources ==
    52 
    53 Return information about available resources or resources allocated to a slice.
    54 
    55 {{{
    56 string ListResources(string credentials[], struct options)
    57 }}}
    58 
    59  `credentials[]`::
    60     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.
    61 
    62  `options`::
    63     An [http://www.xmlrpc.com/spec XML-RPC] 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.
    64 
    65 The following members are available for use in the options parameter. All aggregate managers are required to implement these options.
    66 
    67 {{{
    68 {
    69   boolean geni_available;
    70   boolean geni_compressed;
    71   string geni_slice_urn;
    72 }
    73 }}}
    74 
    75  `geni_available`::
    76     An [http://www.xmlrpc.com/spec XML-RPC] 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.
    77 
    78  `geni_compressed`::
    79     An [http://www.xmlrpc.com/spec XML-RPC] 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].
    80 
    81  `geni_slice_urn`::
    82     An [http://www.xmlrpc.com/spec XML-RPC] 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.
    83 
    84 
    85 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.
    86 
    87 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).
    88 
    89 
    90 -----
    91 == !CreateSliver ==
    92 
    93 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].
    94 
    95 {{{
    96 string CreateSliver(string slice_urn,
    97                     string credentials[],
    98                     string rspec,
    99                     struct users[])
    100 }}}
    101 
    102  `slice_urn`::
    103    The URN of the slice to which the resources specified in {{{rspec}}} will be allocated.
    104 
    105  `credentials`::
    106    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.
    107 
    108  `rspec`::
    109    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 ListResources].
    110 
    111   `users`::
    112   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:
    113 {{{
    114 [
    115   {
    116     urn: urn:publicid:IDN+geni.net:gcf+user+alice
    117     keys: [<ssh key>, <ssh key>]
    118   },
    119   {
    120     urn: urn:publicid:IDN+geni.net:gcf+user+bob
    121     keys: [<ssh key>]
    122   }
    123 ]
    124 }}}
    125 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.
    126 
    127 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).
    128 
    129 
    130 -----
    131 == !DeleteSliver ==
    132 
    133 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.
    134 
    135 {{{
    136 boolean DeleteSliver(string slice_urn, string credentials[])
    137 }}}
    138 
    139  `slice_urn`::
    140    The URN of the slice whose sliver should be deleted.
    141 
    142  `credentials`::
    143    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.
    144 
    145 Returns true on success and false on failure.
    146 
    147 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).
    148 
    149 
    150 -----
    151 == !SliverStatus ==
    152 
    153 Get the status of a sliver.
    154 
    155 {{{
    156 struct SliverStatus(string slice_urn, string credentials[])
    157 }}}
    158 
    159  `slice_urn`::
    160    The URN of the slice for which the sliver status is requested.
    161 
    162  `credentials`::
    163    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.
    164 
    165 Returns an XML-RPC struct upon successful completion. The struct is of the following form:
    166 
    167 {{{
    168 {
    169   geni_urn: <sliver URN>
    170   geni_status: ready
    171   geni_resources: [ { geni_urn: <resource URN>
    172                       geni_status: ready
    173                       geni_error: ''},
    174                     { geni_urn: <resource URN>
    175                       geni_status: ready
    176                       geni_error: ''}
    177                   ]
    178 }
    179 }}}
    180 
    181 The top level members of the returned struct pertain to the sliver as a whole. These members are:
    182 
    183  `geni_urn`::
    184     The URN of the sliver as a string. This is the ''sliver'' and not the ''slice'', and should be selected by the aggregate manager.
    185 
    186  `geni_status`::
    187     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.
    188 
    189  `geni_resources`::
    190     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.
    191 
    192 The members of the resource struct(s) are as follows:
    193 
    194  `geni_urn`::
    195     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.
    196 
    197  `geni_status`::
    198     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.
    199 
    200  `geni_error`::
    201     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}}}.
    202 
    203 
    204 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.
    205 
    206 
    207 -----
    208 == !RenewSliver ==
    209 
    210 Renews the resources in a sliver, extending the lifetime of the slice.
    211 
    212 {{{
    213 boolean RenewSliver(string slice_urn,
    214                     string credentials[],
    215                     string expiration_time)
    216 }}}
    217 
    218  `slice_urn`::
    219    The URN of the slice that is to have its sliver renewed.
    220 
    221  `credentials`::
    222    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.
    223 
    224  `expiration_time`::
    225     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.
    226 
    227 
    228 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.
    229 
    230 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.
    231 
    232 
    233 -----
    234 == Shutdown ==
    235 
    236 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.
    237 
    238 {{{
    239 boolean Shutdown(string slice_urn, string credentials[])
    240 }}}
    241 
    242  `slice_urn`::
    243    The URN of the slice is to have its sliver shut down.
    244 
    245  `credentials`::
    246    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.
    247 
    248 Returns true on success, false otherwise.
    249 
    250 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.
     1See wiki:GAPI_AM_API_V1