Changes between Version 13 and Version 14 of AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures


Ignore:
Timestamp:
04/18/12 15:40:07 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures

    v13 v14  
    9999}}}
    100100
    101 
    102 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required.
     101Note that all options may be omitted by the client, except `geni_rspec_version` which is required.
    103102
    104103Return:
    105104A `geni.rspec` advertisment RSpec.
     105
     106Note that this is only part of what !ListResources did in earlier versions of this API. For the what-is-in-my-slice functionality, see `Describe()`.
    106107
    107108This 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).
     
    128129Note that all options may be omitted by the client, exception `geni_rspec_version` which is required.
    129130
    130 Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers.
     131This method is part of what !ListResources used to do, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve Resolve].
    131132
    132133Return struct:
     
    147148}}}
    148149
    149 Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec. Note that a manifest returned here for only some of the slivers in a slice at this aggregate, may contain references to resources not described in this manifest (they are in other slivers). As a result, such manifests may not be directly usable as a subsequent request.
     150Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers. Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec. Note that a manifest returned here for only some of the slivers in a slice at this aggregate, may contain references to resources not described in this manifest (they are in other slivers). As a result, such manifests may not be directly usable as a subsequent request.
    150151
    151152 == Allocate ==
     
    163164}}}
    164165
    165 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).
     166This is the first part of what !CreateSliver used to do. The next part is now done by Provision.
     167
     168This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetTicket GetTicket] operation.
    166169
    167170 * {{{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 [wiki:GeniApiIdentifiers GENI wiki page].
     
    172175{{{
    173176{
    174   [optional geni_end_time: <dateTime.rfc3339>]
     177  [optional geni_end_time: <dateTime.rfc3339: requested expiration of all new slivers, may be ignored by aggregates>]
    175178}
    176179}}}
     
    203206                    struct options)
    204207}}}
     208
     209This operation used to be called !RenewSliver. Use Renew(<slice_urn>) to get the equivalent functionality.
     210
     211This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RenewSlice RenewSlice] operation.
    205212
    206213Options include {{{geni_best_effort}}}, specifying whether the client prefers all included slivers to be renewed or none, or wants a partial success if possible.
     
    262269 == Provision ==
    263270AKA !ProvisionSlivers()
    264 Request that the named `geni_allocated` slivers be made `geni_provisioned`, instantiating or otherwise realizing the resources, such that they have a valid `geni_operational_status` and may possibly be made `geni_ready` for experimenter use.
     271Request that the named `geni_allocated` slivers be made `geni_provisioned`, instantiating or otherwise realizing the resources, such that they have a valid `geni_operational_status` and may possibly be made `geni_ready` for experimenter use. This operation is synchronous, but may start a longer process, such as creating and imaging a virtual machine.
    265272
    266273{{{
     
    269276}}}
    270277
    271 `credentials` is the standard argument defined above.
     278This operation is part of what !CreateSliver used to do. The first part of what !CreateSliver did is now in `Allocate()`. Note that resources are not necessarily ready for experimenter use after the work that this function initiates finally completes. Consult the `geni_operational_status`, and the advertised operational state machine. Consider calling `PerformOperationalAction`, e.g. with the command name `geni_start`.
     279
     280The operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RedeemTicket RedeemTicket] method.
    272281
    273282Options include:
     
    291300}}}
    292301
    293 FIXME: Is the returned manifest only for newly provisioned slivers? Or all slivers at this AM for this slice?
     302The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers.
    294303
    295304 == !UpdateSlivers ==
     
    337346 == Status ==
    338347AKA !SliverStatus
    339 Retrieve status information about the named slivers. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec.
    340 
     348
     349Get the status of a sliver or slivers belonging to a single 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 Provision, which began to asynchronously provision the resources. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec.
    341350
    342351{{{
     
    344353}}}
    345354
    346 `credentials` is the standard argument defined above.
    347 
    348 Return:
     355This operation used to be called !SliverStatus in earlier versions of the AM API. `geni_slivers` has replaced `geni_resources` and `geni_sliver_urn` replaces `geni_urn`. `geni_status` is replaced with 2 fields, `geni_allocation_status` and `geni_operational_status`.
     356
     357This 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.
     358
     359Return `value` is a struct:
    349360{{{
    350361{
     
    368379
    369380 == !PerformOperationalAction ==
    370 Perform the named operational action on the named slivers, possibly changing the `geni_operational_status` of the named slivers.
     381Perform the named operational action on the named slivers, possibly changing the `geni_operational_status` of the named slivers. E.G. 'start' a VM. For valid operations and expected states, consult the state diagram advertised in the Aggregate's Ad RSpec.
    371382
    372383{{{
     
    375386}}}
    376387
    377 `credentials` is the standard argument defined above.
     388This operation is similar to ProtoGENI functions like `StartSliver`, `StopSliver`, `RestartSliver` in the [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 PG CMv2 API].
    378389
    379390Options include: {{{geni_best_effort}}}
    380391
    381 Return list of structs:
     392Return value is a list of structs:
    382393{{{
    383394[ {
     
    394405 == Delete ==
    395406AKA !DeleteSliver
    396 Delete the named slivers, making them `geni_unallocated`. Resources are de-provisioned. No further AM API operations may be performed on slivers that have been deleted.
     407Delete the named slivers, making them `geni_unallocated`. Resources are stopped in necessary, and both de-provisioned and de-allocated. No further AM API operations may be performed on slivers that have been deleted.
    397408
    398409{{{
     
    400411}}}
    401412
    402 `credentials` is the standard argument defined above.
     413This operation used to be called !DeleteSliver in earlier versions of this API. To get the functionality of !DeleteSliver, call Delete with the slice URN.
     414
     415This 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).
    403416
    404417Options include: {{{geni_best_effort}}}
     
    417430
    418431 == Shutdown ==
    419 Perform an emergency shutdown on the slice at this aggregate. Resources should be taken offline, such that experimenter access (on both the control and data plane) is cut off. No further actions on the slice should be possible at this aggregate, until an un-specified operator action restores the slice.
     432Perform an emergency shutdown on the slice at this aggregate. Resources should be taken offline, such that experimenter access (on both the control and data plane) is cut off. No further actions on the slice should be possible at this aggregate, until an un-specified operator action restores the slice. This operation is intended for operator use. The sliver is shut down but remains available for further forensics.
    420433{{{
    421434struct Shutdown(string slice_urn, struct credentials[], struct options)
    422435}}}
    423436
    424 `credentials` is the standard argument defined above.
    425 
    426 Return: XML-RPC boolean
     437This 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.
     438
     439Return: XML-RPC boolean, indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics.