Changes between Version 25 and Version 26 of GAPI_AM_API_V3


Ignore:
Timestamp:
07/17/12 11:25:37 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3

    v25 v26  
    281281}}}
    282282
    283 This is the first part of what `CreateSliver` used to do in previous versions of the AM API. The second part is now done by `Provision`, and the final part is done by `PerformOperationalAction`.
     283This is the first part of what `CreateSliver` used to do in previous versions of the AM API. The second part is now done by `Provision`, and the final part is done by `PerformOperationalAction`. See [#UsingtheGENIAMAPI above] for an overview of this process.
    284284
    285285This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetTicket GetTicket] operation.
    … …  
    300300}}}
    301301
    302 The manifest is a manifest RSpec of _only_ newly allocated slivers.
     302The manifest is a manifest RSpec of ''only'' newly allocated slivers.
    303303
    304304Arguments:
    … …  
    351351}}}
    352352
    353 Attempting to `Renew` an unknown sliver will result in an error (non zero `geni_code`). Attempting to `Renew` a previously deleted or expired sliver may result in an error - the aggregate may have forgotten about it entirely. Attempting to `Renew` a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted.
     353Attempting to `Renew` an unknown sliver will result in an error (`SEARCHFAILED` `geni_code`). Attempting to `Renew` a previously deleted or expired sliver may result in an error (`SEARCHFAILED` or `EXPIRED`) - the aggregate may have forgotten about it entirely. Attempting to `Renew` a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted.
    354354
    355355It is legal to attempt to renew a sliver to a sooner expiration time than the sliver was previously due to expire. Not all aggregates will support this however.
    … …  
    411411
    412412Options include:
    413  - {{{geni_best_effort}}}: Do all slivers fail if any fail?
     413 - {{{geni_best_effort}}}: Do all slivers fail if any single sliver fails?
    414414 - {{{geni_end_time}}}: Requested sliver expiration time
    415415 - `struct geni_users[]`: Resource login information. See [wiki:GAPI_AM_API_V3/CommonConcepts#geni_users the Common Concepts page].
    … …  
    431431}}}
    432432
    433 The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers. When `geni_best_effort` is true, all requested slivers are returned, but some slivers may have failed: `geni_allocation_status` will remain `geni_allocated`. Check `geni_error` for details.
     433The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers. When `geni_best_effort` is true, all requested slivers are returned, but some slivers may have failed (`geni_allocation_status` will remain `geni_allocated`). Check `geni_error` for details.
    434434{{{
    435435#!comment
    … …  
    534534Aggregate Managers SHOULD return an error code of `13` (`UNSUPPORTED`) if they do not support a given `action` for a given resource. An AM SHOULD constrain actions based on the current operational state of the resource. This is a fast synchronous operation, and MAY start long-running sliver transitions whose status can be queried using `Status`. This method should only be called, and is only valid, when the sliver is fully allocated (allocation state is not `geni_pending_allocation`).
    535535
    536 While the `action` argument may be aggregate and sliver type specific (none are required for all aggregates and sliver types), this API does define three common actions that AMs should support if possible: `geni_start`, `geni_stop`, and `geni_restart`. Calling `PerformOperationalAction` with the action`geni_start` corresponds to the final part of what `CreateSliver` did in AM API v2. For more information, see the Common Concepts page section on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalActions operational actions].
     536While the `action` argument may be aggregate and sliver type specific (none are required for all aggregates and sliver types), this API does define three common actions that AMs should support if possible: `geni_start`, `geni_stop`, and `geni_restart`. Calling `PerformOperationalAction` with the action `geni_start` corresponds to the final part of what `CreateSliver` did in AM API v2. For more information, see the Common Concepts page section on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalActions operational actions].
    537537
    538538Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none).
    … …  
    564564This operation used to be called `DeleteSliver` in earlier versions of this API. To get the functionality of `DeleteSliver`, call `Delete` with the slice URN.
    565565
    566 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).
     566This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DeleteSliver `DeleteSliver`] operation and to [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s `DeleteSlice` operation (sec. 6.2.3).
    567567
    568568Options include: {{{geni_best_effort}}}
    … …  
    583583Note that aggregates will automatically delete slivers whose expiration time is reached.
    584584
    585 Attempting to delete an unknown sliver will result in an error. Attempting to delete a previously deleted sliver may result in an error - the aggregate may have forgotten about it entirely. Attempting to delete a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted.
     585Attempting to delete an unknown sliver will result in an error (`SEARCHFAILED`). Attempting to delete a previously deleted sliver may result in an error (`SEARCHFAILED`) - the aggregate may have forgotten about it entirely. Attempting to delete a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted.
    586586
    587587See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort geni_best_effort], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns urns], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials credentials].
    588588
    589589 == `Shutdown` ==
    590 Perform an emergency shutdown on the slivers in the given 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 slivers in the given slice should be possible at this aggregate, until an un-specified operator action restores the slice's slivers. This operation is intended for operator use. The slivers are shut down but remains available for further forensics.
     590Perform an emergency shutdown on the slivers in the given 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 slivers in the given slice should be possible at this aggregate, until an un-specified operator action restores the slice's slivers (or deletes them). This operation is intended for operator use. The slivers are shut down but remain available for further forensics.
    591591
    592592{{{