Changes between Version 7 and Version 8 of GAPI_AM_API_V3_DETAILS


Ignore:
Timestamp:
05/08/12 12:08:15 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3_DETAILS

    v7 v8  
    2020
    2121== !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.
    2223
    2324Sample output:
    … …  
    102103Elements used within {{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}}:
    103104 `type`, `version`::
    104    Two ''case-insensitive'' strings which together comprise the type of RSpec. The RSpec `type` should be one of "geni", "protogeni", "sfa", "orca", "openflow", or "orbit". `version` should be a type-specific version identifier as specified by the appropriate control framework. The "geni" type is reserved for GENI standard format RSpecs, following the schemas hosted at http://www.geni.net/resources/rspec.
     105   Two ''case-insensitive'' strings which together comprise the type of RSpec. The RSpec `type` should be one of "geni", "protogeni", "sfa", or "orbit". `version` should be a type-specific version identifier as specified by the appropriate control framework. The "geni" type is reserved for GENI standard format RSpecs, following the schemas hosted at http://www.geni.net/resources/rspec.
    105106
    106107 `schema`::
    … …  
    115116-----
    116117== !ListResources Details ==
     118!ListResources returns the advertised or available resources that can be reserved at this aggregate.
     119
    117120 `geni_available`::
    118121    Optional. An [http://www.xmlrpc.com/spec XML-RPC] boolean value indicating whether the caller is interested in all resources or available resources. If this value is {{{true}}}, the result should contain only available resources. If this value is {{{false}}} or unspecified, both available and allocated resources should be returned. The Aggregate Manager is free to limit visibility of certain resources based on the {{{credentials}}} parameter.
    … …  
    122125
    123126 `geni_rspec_version`::
    124     Required. An [http://www.xmlrpc.com/spec XML-RPC] struct indicating the type and version of Advertisement or Manifest 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].
    125128
    126129
    127130=== Return ===
    128 !ListResources returns an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be all local resources, only available local resources, or a manifest of resources reserved for a particular slice.
     131!ListResources returns an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be all local resources, only available local resources.
    129132
    130133!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.
    … …  
    150153-----
    151154== Describe Details ==
     155`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.
     156
     157The manifest RSpec should contain all necessary details about resource identity, configuration, and access information necessary for experimenters to use the resources. As that configuration information may change as the resource becomes operationally `geni_ready`, this information may change. Otherwise, the manifest is mostly static.
     158
     159Additionally, `Describe` returns basic state and expiration information for all queried slivers.
     160
     161For details on options to `Describe`, see !ListResources above, and the Common Concepts page.
     162
     163Error codes:
    152164|| '''''Error''''' || '''''Condition''''' ||
    153165|| `BADARGS`       || One of the required arguments is badly formed or missing ||
    154166|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
    155167|| `FORBIDDEN`     || Slice has been shutdown by the Clearinghouse ||
    156 || `BUSY`          || Slice is temporarily locked, try again later ||
    157 || `ERROR`         || Internal error ||
    158 || `SERVERERROR`   || Server error ||
    159 || `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
    160 || `EXPIRED`       || Slice expired ||
     168|| `BUSY`          || Slice or sliver is temporarily locked, try again later ||
     169|| `ERROR`         || Internal error ||
     170|| `SERVERERROR`   || Server error ||
     171|| `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
     172|| `EXPIRED`       || Slice or sliver expired ||
    161173|| `BADVERSION`    || Bad Version of RSpec requested ||
    162174
    163175== Allocate Details ==
     176`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.
     177
    164178 `rspec`::
    165179    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}}}).
    166180
    167 FIXME: These same errors for Provision?
    168 
     181If `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.
     182
     183At some aggregates, experimenters may call `Allocate` multiple times, to add resources to the existing reservation for the same slice. Other aggregates may limit such requests or forbid them entirely. See the Common Concepts page for details on Operations on Individual Slivers.
     184
     185Error codes:
    169186|| '''''Error''''' || '''''Condition''''' ||
    170187|| `BADARGS`       || One of the required arguments is missing or badly formed ||
    171188|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
    172189|| `FORBIDDEN`     || Slice has been shutdown by the Clearinghouse ||
    173 || `UNAVAILABLE`   || AM is temporarily not allowing external users to create slices ||
    174 || `ERROR`         || Internal error ||
    175 || `SERVERERROR`   || Server error ||
     190|| `UNAVAILABLE`   || AM is temporarily not allowing external users to create slivers ||
     191|| `ERROR`         || Internal error ||
     192|| `SERVERERROR`   || Server error ||
     193|| `TOOBIG` || Request is too big to be satisfied ||
    176194|| `BADVERSION`    || Bad Version of RSpec requested ||
     195|| `UNSUPPORTED` || The aggregate does not permit multiple allocations to the same slice of this form ||
    177196
    178197== Renew Details ==
    179 
     198`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.
     199
     200Error codes:
     201|| '''''Error''''' || '''''Condition''''' ||
     202|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     203|| `SEARCHFAILED`  || Slice or sliver does not exist at this AM ||
     204|| `FORBIDDEN`     || Credential does not grant permission to the slice or sliver ||
     205|| `FORBIDDEN`     || Slice has been shutdown by the Clearinghouse ||
     206|| `BUSY`          || Slice or sliver is temporarily locked, try again later ||
     207|| `ERROR`         || Internal error ||
     208|| `SERVERERROR`   || Server error ||
     209|| `EXPIRED`       || Resources already expired ||
     210|| `UNSUPPORTED` || This aggregate does not support partial renewals of this form ||
     211
     212== Provision Details ==
     213Redeem 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.
     214
     215As with the `Allocate` method, some aggregates may not support provisioning only some reserved resources. Also as with the `Allocate` method, experimenters may request a sliver expiration time; aggregates may succeed the operation while ignoring the requested expiration time or granting a different expiration time.
     216
     217Some resources types allow experimenter access. The `geni_users` option allows specifying login key material to be installed on the resources (e.g. SSH public keys).
     218
     219 `geni_error`::
     220    A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the sliver if this operation fails for a given sliver.
     221
     222Error codes:
     223|| '''''Error''''' || '''''Condition''''' ||
     224|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     225|| `SEARCHFAILED`  || Slice or sliver does not exist at this AM ||
     226|| `FORBIDDEN`     || Credential does not grant permission to the slice or sliver ||
     227|| `BUSY`          || Slice or sliver is temporarily locked, try again later ||
     228|| `ERROR`         || Internal error ||
     229|| `SERVERERROR`   || Server error ||
     230|| `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
     231|| `EXPIRED`       || Slivers expired ||
     232|| `UNSUPPORTED` || The aggregate does not permit operations on individual slivers in the same slice of this form ||
     233
     234== Status Details ==
     235Get dynamic status about one or more slivers in a given slice. In contrast to `Describe`, `Status` is used to query dynamic state information about slivers. Aggregates may include detailed configuration information at their own discretion.
     236
     237Error codes:
     238|| '''''Error''''' || '''''Condition''''' ||
     239|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     240|| `SEARCHFAILED`  || Slice or sliver does not exist at this AM ||
     241|| `FORBIDDEN`     || Credential does not grant permission to the slice or sliver ||
     242|| `BUSY`          || Slice or sliver is temporarily locked, try again later ||
     243|| `ERROR`         || Internal error ||
     244|| `SERVERERROR`   || Server error ||
     245|| `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
     246|| `EXPIRED`       || Slivers expired ||
     247|| `UNSUPPORTED` || The aggregate does not permit operations on individual slivers in the same slice of this form ||
     248
     249== !PerformOperationalAction Details ==
     250
     251
     252As with the `Allocate` method, some aggregates may not support provisioning only some reserved resources.
     253
     254 `geni_error`::
     255    A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the sliver if this operation fails for a given sliver.
     256
     257Error codes:
     258|| '''''Error''''' || '''''Condition''''' ||
     259|| `BADARGS`       || One of the required arguments is badly formed or missing (unknown operation or not applicable to sliver in this state) ||
     260|| `SEARCHFAILED`  || Slice or sliver does not exist at this AM ||
     261|| `FORBIDDEN`     || Credential does not grant permission to the slice or sliver ||
     262|| `BUSY`          || Slice or sliver is temporarily locked, try again later ||
     263|| `ERROR`         || Internal error ||
     264|| `SERVERERROR`   || Server error ||
     265|| `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
     266|| `EXPIRED`       || Slivers expired ||
     267|| `UNSUPPORTED` || The aggregate does not permit operations on individual slivers in the same slice of this form ||
     268|| `INPROGRESS` || Requested operation is already in progress ||
     269
     270== Delete Details ==
     271`Delete` the given slivers, stopping any running resources and freeing the reservation. This method applies to slivers in any state.
     272
     273As with the `Allocate` method, some aggregates may not support deleting only some slivers.
     274
     275Attempting 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. Details are aggregate specific.
     276
     277This operation should generally succeed for a valid sliver, despite the `geni_best_effort` option. However, when `geni_best_effort` is supplied and is false, and an aggregate cannot delete all the named slivers, no slivers are deleted.
     278
     279Error codes:
     280|| '''''Error''''' || '''''Condition''''' ||
     281|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     282|| `SEARCHFAILED`  || Slice or sliver does not exist at this AM ||
     283|| `FORBIDDEN`     || Credential does not grant permission to the slice or slivers ||
     284|| `BUSY`          || Slice or sliver is temporarily locked, try again later ||
     285|| `ERROR`         || Internal error ||
     286|| `SERVERERROR`   || Server error ||
     287|| `EXPIRED`       || Sliver(s) already expired and gone ||
     288
     289== Shutdown Details ==
     290This 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.
     291
     292This method returns true, unless resource remain running in the slice after this operation.
     293
     294Error codes:
    180295|| '''''Error''''' || '''''Condition''''' ||
    181296|| `BADARGS`       || One of the required arguments is badly formed or missing ||
    182297|| `SEARCHFAILED`  || Slice does not exist at this AM ||
    183298|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
    184 || `FORBIDDEN`     || Slice has been shutdown by the Clearinghouse ||
    185 || `BUSY`          || Slice is temporarily locked, try again later ||
    186 || `ERROR`         || Internal error ||
    187 || `SERVERERROR`   || Server error ||
    188 || `EXPIRED`       || Resources already expired ||
    189 
    190 == Provision Details ==
    191 
    192 == Status Details ==
    193 || '''''Error''''' || '''''Condition''''' ||
    194 || `BADARGS`       || One of the required arguments is badly formed or missing ||
    195 || `SEARCHFAILED`  || Slice does not exist at this AM ||
    196 || `FORBIDDEN`     || Credential does not grant permission to the slice ||
    197 || `BUSY`          || Slice is temporarily locked, try again later ||
    198 || `ERROR`         || Internal error ||
    199 || `SERVERERROR`   || Server error ||
    200 || `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
    201 || `EXPIRED`       || Slivers expired ||
    202 
    203 
    204  `geni_error`::
    205     A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the resource if its status is {{{failed}}}.
    206 
    207 == !PerformOperationalAction Details ==
    208 
    209 == Delete Details ==
    210 || '''''Error''''' || '''''Condition''''' ||
    211 || `BADARGS`       || One of the required arguments is badly formed or missing ||
    212 || `SEARCHFAILED`  || Slice does not exist at this AM ||
    213 || `FORBIDDEN`     || Credential does not grant permission to the slice ||
    214 || `BUSY`          || Slice is temporarily locked, try again later ||
    215 || `ERROR`         || Internal error ||
    216 || `SERVERERROR`   || Server error ||
    217 || `EXPIRED`       || Sliver(s) already expired and gone ||
    218 
    219 
    220 == Shutdown Details ==
    221 || '''''Error''''' || '''''Condition''''' ||
    222 || `BADARGS`       || One of the required arguments is badly formed or missing ||
    223 || `SEARCHFAILED`  || Slice does not exist at this AM ||
    224 || `FORBIDDEN`     || Credential does not grant permission to the slice ||
    225299|| `ERROR`         || Internal error ||
    226300|| `SERVERERROR`   || Server error ||