Changes between Version 14 and Version 15 of GAPI_AM_API_V3_DETAILS


Ignore:
Timestamp:
07/13/12 11:24:50 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3_DETAILS

    v14 v15  
    1919''' This page is a work in progress! '''
    2020
    21 == !GetVersion Details ==
    22 !GetVersion is intended to provide information about the configuration of this aggregate, helping experimenter tools determine how to communicate with this aggregate.
     21== `GetVersion` Details ==
     22`GetVersion` is intended to provide information about the configuration of this aggregate, helping experimenter tools determine how to communicate with this aggregate.
    2323
    2424Sample output:
    … …  
    6464
    6565=== Return ===
    66 !GetVersion returns the version of the Aggregate Manager API running locally, the RSpec schemas supported, and the URLs where versions of the AM API are running. The return is an XML-RPC struct whose members are described below.
     66`GetVersion` returns the version of the Aggregate Manager API running locally, the RSpec schemas supported, and the URLs where versions of the AM API are running. The return is an XML-RPC struct whose members are described below.
    6767
    6868 `geni_api`::
    … …  
    7272
    7373  `value`::
    74        For !GetVersion, {{{value}}} is an XML-RPC struct containing the actual return for the method. On success, this is required. Optional (and not defined) on failure or error.
    75 
    76 ==== !GetVersion return codes ====
     74       For `GetVersion`, {{{value}}} is an XML-RPC struct containing the actual return for the method. On success, this is required. Optional (and not defined) on failure or error.
     75
     76==== `GetVersion` return codes ====
    7777Aggregates shall return consistent values for {{{geni_code}}} as described here. Success is always indicated using a {{{geni_code}}} value of {{{0}}}. On error, return the appropriate GENI error code in {{{geni_code}}}, as listed in this table. These error codes are part of a [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct larger set of codes with specific meanings required by this API, described on the Common Concepts page].
    7878
    … …  
    9696
    9797 `geni_ad_rspec_versions`::
    98     An array of data structures indicating what types of RSpec advertisements may be produced by this AM in !ListResources.
     98    An array of data structures indicating what types of RSpec advertisements may be produced by this AM in `ListResources`.
    9999
    100100{{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}} refer to the RSpec formats supported at this aggregate. The [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype contract for RSpec versions is described with links to further reading on the Common Concepts page].
    … …  
    115115
    116116-----
    117 == !ListResources Details ==
    118 !ListResources returns the advertised or available resources that can be reserved at this aggregate.
     117== `ListResources` Details ==
     118`ListResources` returns the advertised or available resources that can be reserved at this aggregate.
    119119
    120120 `geni_available`::
    … …  
    125125
    126126 `geni_rspec_version`::
    127     Required. An [http://www.xmlrpc.com/spec XML-RPC] struct indicating the type and version of Advertisement RSpec to return. The struct contains 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{geni_ad_rspec_versions}}} as returned by !GetVersion at this aggregate. This option is ''required'', and aggregates are expected to return a {{{geni_code}}} of {{{1}}} ('Bad Arguments') if it is missing. Aggregates should return a {{{geni_code}}} of {{{4}}} ({{{BADVERSION}}}) if the requested RSpec version is not one advertised in !GetVersion as supported. The [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype contract for RSpec versions is described with links to further reading on the Common Concepts page].
     127    Required. An [http://www.xmlrpc.com/spec XML-RPC] struct indicating the type and version of Advertisement RSpec to return. The struct contains 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{geni_ad_rspec_versions}}} as returned by `GetVersion` at this aggregate. This option is ''required'', and aggregates are expected to return a {{{geni_code}}} of {{{1}}} ('Bad Arguments') if it is missing. Aggregates should return a {{{geni_code}}} of {{{4}}} ({{{BADVERSION}}}) if the requested RSpec version is not one advertised in `GetVersion` as supported. The [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype contract for RSpec versions is described with links to further reading on the Common Concepts page].
    128128
    129129
    130130=== Return ===
    131 !ListResources returns a `value` containing an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be all local resources, only available local resources.
    132 
    133 !ListResources returns the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct standard return from all AM API methods], which has a specific [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct structure and semantics described on the Common Concepts page], including specific requirements for the {{{code}}} and {{{output}}} members.
    134 
     131`ListResources` returns a `value` containing an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be all local resources, only available local resources.
     132
     133`ListResources` returns the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct standard return from all AM API methods], which has a specific [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct structure and semantics described on the Common Concepts page], including specific requirements for the {{{code}}} and {{{output}}} members.
    135134
    136135  `value`::
    137      !ListResources returns an RSpec in GENI standard schema.
    138 
     136     `ListResources` returns an RSpec in GENI standard schema.
    139137
    140138    If the aggregate cannot support the requested {{{type}}}/{{{version}}} (that pair is not listed in {{{geni_ad_rspec_versions}}}), then the aggregate returns an error ({{{geni_code}}}) of {{{4}}} ({{{BADVERSION}}}), and the {{{value}}} is not defined.
    141139
    142 ==== !ListResources return codes ====
     140==== `ListResources` return codes ====
    143141On error, return the appropriate GENI error code in {{{geni_code}}}, as listed in this table. These error codes are part of a [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct larger set of codes with specific meanings required by this API, described on the Common Concepts page].
    144142
    … …  
    152150
    153151-----
    154 == Describe Details ==
     152== `Describe` Details ==
    155153`Describe` is used to list the resources belonging to a particular reservation. The return is always a single manifest RSpec, whose contents cover the set of slivers whose URNs were supplied, or which are contained in the single slice whose URN was supplied as an argument.
    156154
    … …  
    196194|| `BADVERSION`    || Bad Version of RSpec requested ||
    197195
    198 == Allocate Details ==
     196== `Allocate` Details ==
    199197`Allocate` is used to request a reservation of resources. If the request can be completely satisfied, the manifest RSpec is returned. Otherwise, an error is returned.
    200198
    201199 `rspec`::
    202     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}}}. These are expected to be consistent with the resources returned by a previous invocation of [wiki:GAPI_AM_API_V3#ListResources ListResources]. If this RSpec is in a format not listed as supported by !GetVersion, then the aggregate will return an error of {{{BADVERSION}}} ({{{4}}}).
     200    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}}}. These are expected to be consistent with the resources returned by a previous invocation of [wiki:GAPI_AM_API_V3#ListResources ListResources]. If this RSpec is in a format not listed as supported by `GetVersion`, then the aggregate will return an error of {{{BADVERSION}}} ({{{4}}}).
    203201
    204202If `geni_end_time` is supplied, the experimenter is requesting a particular sliver reservation expiration date. Local policy may however dictate the expiration date. The AM therefore may ignore this argument; the `Allocate` call should still succeed, even if the date argument cannot be satisfied.
    … …  
    218216|| `UNSUPPORTED` || The aggregate does not permit multiple allocations to the same slice of this form ||
    219217
    220 == Renew Details ==
     218== `Renew` Details ==
    221219`Renew` requests a changed expiration for one or more slivers in a slice. At some aggregates, this expiration may be shorter. This method applies both to slivers that are `geni_allocated` and to those that are already `geni_provisioned`. Depending on local aggregate configuration, the aggregate may only support `Renew` on all current slivers in the slice, or may permit renewing only some slivers. Local policy will dictate maximum expiration times. These times are typically quite short (~ 10 minutes initially, ~120 minutes maximum) for reservations (`geni_allocated`), and longer for provisioned slivers (~ 5-8 days initially). Since these expiration times are different, typically `Renew` is used only for slivers in the same allocation state.
    222220
    … …  
    251249|| `UNSUPPORTED` || This aggregate does not support partial renewals of this form ||
    252250
    253 == Provision Details ==
     251== `Provision` Details ==
    254252Redeem a reservation, requesting that the listed slivers move from `geni_allocated` to `geni_provisioned`. Only when slivers are provisioned are the resources 'instantiated' and made ready for operational use. Note that at some aggregates and for some resource types, this operation may be a no-op. At other aggregates, this operation starts a long running process (e.g. loading an image on a machine and booting it). Tools should monitor the sliver status (by calling `Status`), looking for an operational state other than `geni_pending_allocation`. Depending on the resource type, that next state may differ. See the advertisement RSpec for the resource type specific operational states and actions.
    255253
    … …  
    311309|| `UNSUPPORTED` || The aggregate does not permit operations on individual slivers in the same slice of this form ||
    312310
    313 == !PerformOperationalAction Details ==
     311== `PerformOperationalAction` Details ==
    314312Perform an operational action on one or more named slivers. Operational actions modify the running state of the resource, not the nature of the resources in the reservation. To add or remove resources from the reservation, use `Delete` and `Allocate`.
    315313
    … …  
    334332|| `INPROGRESS` || Requested operation is already in progress ||
    335333
    336 == Delete Details ==
     334== `Delete` Details ==
    337335`Delete` the given slivers, stopping any running resources and freeing the reservation. This method applies to slivers in any state.
    338336
    … …  
    353351|| `EXPIRED`       || Sliver(s) already expired and gone ||
    354352
    355 == Shutdown Details ==
     353== `Shutdown` Details ==
    356354This operation is for operator use, to stop a misbehaving resource. Once shut down, the slivers are not available for experimenter use. The underlying resources may be returned to the pool of available resources, depending on resource type and aggregate implementation.
    357355