Changes between Version 5 and Version 6 of GAPI_AM_API_V3


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

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3

    v5 v6  
    205205
    206206Return:
    207 A `geni.rspec` advertisment RSpec.
     207A `geni.rspec` advertisment RSpec. See the Common Concepts page.
    208208
    209209Note 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()`.
    … …  
    211211This 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).
    212212
     213For details on the options (which are required), see the Details page.
     214
    213215 == Describe ==
    214 AKA !ListResources when supplied a slice URN.
    215 
    216216Retrieve 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.
     217
     218Note this functionality was previously part of !ListResources when supplied a slice URN.
     219
    217220{{{
    218221struct Describe(string urns[], struct credentials[], struct options[])
    … …  
    231234
    232235Note that all options may be omitted by the client, exception `geni_rspec_version` which is required.
     236
     237For details on the options, see the Details page.
     238See the Common Concepts page about the credentials, rspec, and urns arguments.
    233239
    234240This method is part of what !ListResources used to do, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve Resolve].
    … …  
    253259Note 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.
    254260
     261For details on rspecs, allocation states, operational states, and datetime values, see the Common Concepts page. See GeniIdentifiers for details on URN structure.
     262
    255263 == Allocate ==
    256 AKA !CreateSlivers()
    257 
    258264Allocate 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.
    259 Allocated 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.
    260 Aggregates should implement Allocate() as quick, cheap, and not impacting Provisioned resources, such that it can be readily undone.
     265Allocated 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.
     266Aggregates should implement `Allocate()` as quick, cheap, and not impacting provisioned resources, such that it can be readily undone.
     267
     268This method is part of what was previously known as !CreateSliver.
    261269
    262270{{{
    … …  
    267275}}}
    268276
    269 This is the first part of what !CreateSliver used to do. The next part is now done by Provision.
     277This is the first part of what !CreateSliver used to do. The next part is now done by `Provision`.
    270278
    271279This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetTicket GetTicket] operation.
    272280
    273281 * {{{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].
    274 
    275  * {{{rspec}}}: An RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard] request RSpec [http://www.geni.net/resources/rspec/3/request.xsd schema] containing the resources that the caller is requesting for allocation to the slice specified in {{{slice_urn}}}.
     282 * {{{rspec}}}: An RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard] request RSpec [http://www.geni.net/resources/rspec/3/request.xsd schema] containing the resources that the caller is requesting for allocation to the slice specified in {{{slice_urn}}}.  See the Common Concepts page.
     283 * `credentials`: The standard authorization argument. See the Common Concepts page.
    276284
    277285Options include:
    … …  
    281289}
    282290}}}
     291
     292See the Common Concepts page for details on `geni_end_time`.
    283293
    284294Return struct:
    … …  
    299309The manifest is a manifest of only newly allocated slivers.
    300310
     311See the Common Concepts page for details on RSpecs, expiration dateTime, and allocation states.
     312
    301313 == Renew ==
    302 AKA !RenewSliver() or !RenewAllocated
    303314Request 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.
    304315
    … …  
    314325This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RenewSlice RenewSlice] operation.
    315326
    316 Options include {{{geni_best_effort}}}, specifying whether the client prefers all included slivers to be renewed or none, or wants a partial success if possible.
    317 
    318 {{{expiration_time}}}: The date-time string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format in UTC when the reservation(s) should be extended until.
     327Options 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 `geni_best_effort` and Operations on Individual Slivers.
     328
     329{{{expiration_time}}}: The date-time string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format in UTC when the reservation(s) should be extended until. See the Common Concepts page.
     330
     331See the Common Concepts page for details on the `urns[]` and `credentiasl[]` arguments.
    319332
    320333Return value is a list of structs:
    … …  
    331344}}}
    332345
     346See the Common Concepts page for details on allocation states, operational states, sliver expiration times, and operations on individual slivers.
     347
    333348{{{
    334349#!comment
    … …  
    372387
    373388 == Provision ==
    374 AKA !ProvisionSlivers()
    375389Request 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.
    376390
    … …  
    383397
    384398The operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RedeemTicket RedeemTicket] method.
     399
     400See the Common Concepts page for details on allocation states, `urns[]`, `credentials[]`, and operations on individual slivers.
    385401
    386402Options include:
    … …  
    388404 - {{{geni_end_time}}}
    389405 - `struct geni_users[]`
     406
     407See the Common Concepts page for details on each option.
    390408
    391409Return struct:
    … …  
    406424The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers.
    407425
     426See the Common concepts page for details on allocation states, operational states, sliver expiration, and operations on individual slivers.
     427
    408428{{{
    409429#!comment
    … …  
    450470
    451471 == Status ==
    452 AKA !SliverStatus
    453 
    454 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.
     472Get 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.
    455473
    456474{{{
    … …  
    461479
    462480This 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.
     481
     482See the common concepts page for details on the `urns[]` and `credentials[]` arguments.
     483
     484This method has no required options.
    463485
    464486Return `value` is a struct:
    … …  
    483505}}}
    484506
     507See the Common Concepts page for details on allocation states, operational states, and sliver expiration times.
     508
     509Note that aggregates may provide other information, details on sliver contents, etc.
     510
    485511 == !PerformOperationalAction ==
    486512Perform 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.
    … …  
    495521Aggregate 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`).
    496522
    497 Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none.
     523Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none.
     524
     525See the Common Concepts page for details on operational states and methods, `geni_best_effort`, operations on individual slivers, and the `urns[]` and `credentials[]` arguments.
    498526
    499527Return value is a list of structs:
    … …  
    511539}}}
    512540
     541See the Common Concepts page for details on operational states, allocation states, and sliver expiration time formats.
     542
    513543 == Delete ==
    514 AKA !DeleteSliver
    515 Delete 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.
    516 
    517 {{{
    518 struct Delete(string urns, struct credentials[], struct options)
    519 }}}
    520 
    521 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.
     544Delete 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.
     545
     546{{{
     547struct Delete(string urns[], struct credentials[], struct options)
     548}}}
     549
     550This operation used to be called !DeleteSliver in earlier versions of this API. To get the functionality of !DeleteSliver, call `Delete` with the slice URN.
    522551
    523552This 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).
    … …  
    537566}}}
    538567
     568See the Common Concepts page for details on allocation and operational states, operations on individual slivers, `geni_best_effort, sliver expiration times, `urns[]`, and `credentials[]`.
     569
    539570 == Shutdown ==
    540571Perform 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.
     572
    541573{{{
    542574struct Shutdown(string slice_urn, struct credentials[], struct options)
    … …  
    545577This 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.
    546578
     579No options are required.
     580
    547581Return: XML-RPC boolean, indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics.
     582
     583See the Common Concepts page for details on the `credentials[]` argument.