Changes between Version 22 and Version 23 of GAPI_AM_API_V3


Ignore:
Timestamp:
07/17/12 10:53:42 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3

    v22 v23  
    77This page documents the GENI Aggregate Manager API Version '''3'''.
    88
    9 See Also:
    10  * [wiki:GAPI_AM_API_V3/CommonConcepts API Version 3 Common concepts, arguments, and returns]
    11  * [wiki:GAPI_AM_API_V3_DETAILS API Version 3 Details page]
     9For API details, see:
     10 * [wiki:GAPI_AM_API_V3/CommonConcepts API Version 3 Common Concepts, Arguments, and Returns]
     11 * [wiki:GAPI_AM_API_V3_DETAILS API Version 3 Details]
     12 * [wiki:GeniApi GENI API] implementation status
     13 * [wiki:GeniApiCredentials GENI credentials] for authorization
     14 * [wiki:GeniApiCertificates GENI certificates] for authentication. The GENI AM API uses XML-RPC over SSL with client authentication using certificates.
     15
     16For background, see:
    1217 * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf Slice-based Facility Architecture (SFA) specification]
    1318 * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa-impl.pdf PlanetLab Implementation of the Slice-Based Facility Architecture]
    1419 * [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 ProtoGENI Component Manager API revision 2]
    15  * [wiki:GeniApi GENI API] implementation status
    16  * [wiki:GeniApiCredentials GENI credentials] for authorization
    17  * [wiki:GeniApiCertificates GENI certificates] for authentication. The GENI AM API uses XML-RPC over SSL with client authentication using certificates.
     20
     21See also:
    1822 * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for future versions of this API
    1923 * [wiki:GAPI_AM_API_ISSUES Open issues with this API]
    20 
    21 For a summary of the Aggregate Manager API common concepts, arguments, and returns, see [wiki:GAPI_AM_API_V3/CommonConcepts this sub page].
     24 * [wiki:GAPI_AM_API_V3_DELTAS Changes since AM API Version 2]
    2225
    2326== Versions ==
    2427
    2528 * Latest: 3 - Documented here. [wiki:GAPI_AM_API_V3_DELTAS Changes since version 2] include:
    26   * All new method names
     29  * Mostly new method names
    2730  * Addressable slivers: the ability to add or delete resources from an existing slice reservation at a single aggregate
    2831  * New sliver allocation states & methods.
    … …  
    3033   * Operational states, and a way for aggregates to advertise resource specific operational states and methods in the Ad RSpec.
    3134   * Generalized credential argument, allowing aggregates to accept and tools to supply credentials of alternate types
    32    * Return sliver expiration in most method returns
     35   * Return sliver expiration in several method returns
    3336   * Specify SSH node login information in a standard RSpec extension
    3437   * Standardize certificate contents, specifically including a UUID and email address with particular semantics
    3538   * Standardize slice and user name character and length restrictions
    36    * Split !ListResources in two: !ListResources for Ad RSpecs, and Describe for a slice' manifest RSpec
     39   * Split `ListResources` in two: `ListResources` for Ad RSpecs, and `Describe` for a slice's manifest RSpec
    3740
    3841 * Previous: 2 - Documented on [wiki:GAPI_AM_API_V2 the v2 page]. Changes since v1 include:
    3942  * Includes Change Sets A and B from the [wiki:GAPI_AM_API_V2_DELTAS v2 Deltas page]
    4043  * Specify that GENI RSpecs are XML documents following standard schemas published [http://www.geni.net/resources/rspec on geni.net] and documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec on the ProtoGENI wiki]
    41   * Include additional options in !GetVersion and !ListResources to allow aggregates to specify the RSpec formats they support
     44  * Include additional options in `GetVersion` and `ListResources` to allow aggregates to specify the RSpec formats they support
    4245  * Add an 'options' argument, an XML-RPC struct, to all methods with no required values. This allows Aggregates to innovate or support resource-specific functionality.
    4346  * Modify all methods to return an XML-RPC 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.
    … …  
    113116
    114117-----
    115  == !GetVersion ==
     118 == `GetVersion` ==
    116119Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.
    117120
    … …  
    165168=== Return Summary ===
    166169
    167 As with all AM API methods, the return is an XML-RPC struct. For !GetVersion, it includes:
     170As with all AM API methods, the return is an XML-RPC struct. For `GetVersion`, it includes:
    168171 * The standard AM API {{{code}}}, {{{value}}}, and {{{output}}} entries. For details, see [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct the Common Concepts page]
    169172 * {{{geni_api}}}: integer version of this API ('''3'''). Repeated here for backwards compatibility.
    170173
    171 !GetVersion {{{value}}} required return members:
     174`GetVersion` {{{value}}} required return members:
    172175 * {{{geni_api}}} = '''3''' (Integer current version of this API).
    173176 * List of versions of the API supported by this aggregate. For details on doing this, see [wiki:GAPI_AM_API_V3/CommonConcepts#SupportingMultipleAPIVersions the Common Concepts page].
    … …  
    177180 * Options on how sliver allocation works. See [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers the Common Concepts page].
    178181
    179 For details on !GetVersion arguments, returns, and semantics, and a sample minimal return, see [wiki:GAPI_AM_API_V3_DETAILS#GetVersionDetails the Details page].
    180 
    181  == !ListResources ==
     182For details on `GetVersion` arguments, returns, and semantics, and a sample minimal return, see [wiki:GAPI_AM_API_V3_DETAILS#GetVersionDetails the Details page].
     183
     184 == `ListResources` ==
    182185Return a listing and description of available resources at this aggregate. The resource listing and description provides sufficient information for clients to select among available resources. These listings are known as RSpecs.
    183186
    … …  
    203206A `geni.rspec` advertisment RSpec. For details on RSpecs, see [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecs the Common Concepts page].
    204207
    205 Note 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()`.
     208Note 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()`.
    206209
    207210This 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).
    … …  
    209212For details on the options (which are required), see [wiki:GAPI_AM_API_V3_DETAILS#ListResourcesDetails the Details page].
    210213
    211  == Describe ==
     214 == `Describe` ==
    212215Retrieve a manifest RSpec describing the resources contained by the entities named, e.g. a single slice or a set of the slivers in a slice. This listing and description should be sufficient to allow experimenters to use the resources.
    213 
    214 Note this functionality was previously part of !ListResources when supplied a slice URN.
    215216
    216217{{{
    … …  
    233234For details on the options, see [wiki:GAPI_AM_API_V3_DETAILS#DescribeDetails the Details page].
    234235
    235 This method is part of what !ListResources used to do, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve Resolve].
     236This method is part of what `ListResources` used to do, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve Resolve].
    236237
    237238Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain at struct:
    … …  
    261262See the Common Concepts page about the [wiki:GAPI_AM_API_V3/CommonConcepts#credentials credentials], [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype rspec], and [wiki:GAPI_AM_API_V3/CommonConcepts#urns urns] arguments, and also for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation states], [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], and [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype datetime values]. See GeniApiIdentifiers for details on URN structure.
    262263
    263  == Allocate ==
     264 == `Allocate` ==
    264265Allocate resources as described in a request RSpec argument to a slice with the named URN.  On success, one or more slivers are allocated, containing resources satisfying the request, and assigned to the given slice. This method returns a listing and description of the resources reserved for the slice by this operation, in the form of a manifest RSpec.
    265266Allocated slivers are held for an aggregate-determined period. Clients must `Renew` or `Provision` slivers before the expiration time (given in the return struct), or the aggregate will automatically `Delete` them.
    … …  
    267268`Allocate` is an all or nothing request: if the aggregate cannot completely satisfy the request RSpec, it should fail the request entirely.
    268269
    269 This method is the first part of what was previously known as !CreateSliver.
    270 
    271270{{{
    272271struct Allocate(string slice_urn,
    … …  
    276275}}}
    277276
    278 This is the first part of what !CreateSliver used to do. The second part is now done by `Provision`, and the final part is done by `PerformOperationalAction`.
     277This is the first part of what `CreateSliver` used to do. The second part is now done by `Provision`, and the final part is done by `PerformOperationalAction`.
    279278
    280279This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetTicket GetTicket] operation.
    … …  
    311310See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#geni_end_time geni_end_time], [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype RSpecs], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype expiration dateTime], and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation states].
    312311
    313  == Renew ==
     312 == `Renew` ==
    314313Request that the named slivers be renewed, with their expiration extended. If possible, the aggregate should extend the slivers to the requested expiration time, or to a sooner time if policy limits apply. This method applies to slivers that are `geni_allocated` or to slivers that are `geni_provisioned`, though different policies may apply to slivers in the different states, resulting in much shorter max expiration times for `geni_allocated` slivers.
    315314
    … …  
    321320}}}
    322321
    323 This operation used to be called !RenewSliver. Use `Renew(<slice_urn>)` to get the equivalent functionality.
     322This operation used to be called `RenewSliver`. Use `Renew(<slice_urn>)` to get the equivalent functionality.
    324323
    325324Options include {{{geni_best_effort}}}, specifying whether the client prefers all included slivers to be renewed or none, or wants a partial success if possible. See the Common Concepts page under [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort geni_best_effort] and [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers Operations on Individual Slivers].
    … …  
    354353{{{
    355354#!comment
    356  == !UpdateAllocations ==
    357 AKA !UpdateAllocated()
     355 == `UpdateAllocations` ==
     356AKA `UpdateAllocated()`
    358357This method modifies a set of allocated slivers in place. The existing reservations are not lost if the newly requested allocations cannot be satisfied by the aggregate.
    359358
    … …  
    393392}}}
    394393
    395  == Provision ==
     394 == `Provision` ==
    396395Request 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.
    397396
    … …  
    401400}}}
    402401
    403 This 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`.
     402This 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`.
    404403
    405404The operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RedeemTicket RedeemTicket] method.
    … …  
    432431}}}
    433432
    434 Note that previously allocated slivers may have expired (been deleted) by the time you call Provision.
     433Note that previously allocated slivers may have expired (been deleted) by the time you call `Provision`.
    435434
    436435See 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], and [wiki:GAPI_AM_API_V3/CommonConcepts#geni_users geni_users].
    … …  
    438437{{{
    439438#!comment
    440  == !UpdateSlivers ==
    441 AKA Update()
     439 == `UpdateSlivers` ==
     440AKA `Update()`
    442441This method requests a modification to 1 or more provisioned slivers. The slivers end up in a new `geni_allocated+geni_provisioned` state.
    443442
    … …  
    479478}}}
    480479
    481  == Status ==
    482 Get 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.
     480 == `Status` ==
     481Get 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.
    483482
    484483{{{
    … …  
    486485}}}
    487486
    488 This 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`.
     487This 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`.
    489488
    490489This method has no required options.
    … …  
    517516See 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#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns urns], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials credentials].
    518517
    519  == !PerformOperationalAction ==
     518 == `PerformOperationalAction` ==
    520519Perform 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 advertisement RSpec.
    521520
    … …  
    529528Aggregate 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`).
    530529
    531 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].
     530While 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].
    532531
    533532Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none).
    … …  
    550549See 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#SliverOperationalActions operational methods], [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].
    551550
    552  == Delete ==
     551 == `Delete` ==
    553552Delete the named slivers, making them `geni_unallocated`. Resources are stopped if necessary, and both de-provisioned and de-allocated. No further AM API operations may be performed on slivers that have been deleted.
    554553
    … …  
    557556}}}
    558557
    559 This operation used to be called !DeleteSliver in earlier versions of this API. To get the functionality of !DeleteSliver, call `Delete` with the slice URN.
    560 
    561 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).
     558This operation used to be called `DeleteSliver` in earlier versions of this API. To get the functionality of `DeleteSliver`, call `Delete` with the slice URN.
     559
     560This 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).
    562561
    563562Options include: {{{geni_best_effort}}}
    … …  
    582581See 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].
    583582
    584  == Shutdown ==
     583 == `Shutdown` ==
    585584Perform 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.
    586585
    … …  
    589588}}}
    590589
    591 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.
     590This 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.
    592591
    593592No options are required.