Changes between Version 8 and Version 9 of GAPI_AM_API_V3


Ignore:
Timestamp:
05/04/12 10:00:12 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V3

    v8 v9  
    7171Once the experimenter has selected the resources they want and how to configure them, they produce a request RSpec, detailing the resources they want and how they should be configured. They separately contact their slice authority to obtain a slice credential (or set of credentials), granting them rights to reserve resources for that slice. The experimenter then calls `Allocate` on this API, passing in both the slice credential and the request RSpec. The aggregate then attempts to satisfy the experimenter's resource request. If the aggregate can satisfy the request, the aggregate reserves the resources for the experimenter. The resources have not been provisioned yet, giving the experimenter a chance to verify the reservation, or check for corresponding resource availability in another aggregate. If it is acceptable, the experimenter calls `Provision` to set up the resources. The aggregate then starts the process of instantiating the resources and configuring them as requested in the request RSpec. Once that process has started, the `Provision` call returns with a manifest RSpec, listing the resources as reserved and initially configured for the experimenter. 
    7272
    73 The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling `Status`, looking for an operational state other than `geni_pending_allocation. A given aggregate and sliver type may use a different set of states once provisioning is complete, and further operational actions are possible - see the AM's Ad RSpec. In many cases, this indication comes with a `geni_operational_state` value of `geni_notready`.  Once the resources are ready for use, the experimenter will typically call `!PerformOperationalAction(geni_start)` to start the resources (e.g. boot a machine). The experimenter will also call `Renew` to request that their reservation lasts as long as they require the resources for. When the experimenter is done using the resources, they call `Delete` to end their reservation. The aggregate then stops and clears the resources, freeing them for use by other clients.
     73The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling `Status`, looking for an operational state other than `geni_pending_allocation`. A given aggregate and sliver type may use a different set of states once provisioning is complete, and further operational actions are possible - see the AM's Ad RSpec. In many cases, this indication comes with a `geni_operational_state` value of `geni_notready`.  Once the resources are ready for use, the experimenter will typically call `!PerformOperationalAction(geni_start)` to start the resources (e.g. boot a machine). The experimenter will also call `Renew` to request that their reservation lasts as long as they require the resources for. When the experimenter is done using the resources, they call `Delete` to end their reservation. The aggregate then stops and clears the resources, freeing them for use by other clients.
    7474
    7575Typical client work flow:
     
    247247                  geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from SliversStatus>,
    248248                  geni_allocation_status: <string sliver state - allocated or ?? >,
    249                   geni_operational_status: <string sliver operational state>
     249                  geni_operational_status: <string sliver operational state>,
     250                  geni_error: <optional string, may be omitted entirely, explaining any failure for a sliver>
    250251               },
    251252               ...
     
    262263Allocated 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.
    263264Aggregates should implement `Allocate()` as quick, cheap, and not impacting provisioned resources, such that it can be readily undone.
     265`Allocate` is an all or nothing request: if the aggregate cannot completely satisfy the request RSpec, it should fail the request entirely.
    264266
    265267This method is part of what was previously known as !CreateSliver.
     
    323325Options 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].
    324326
     327When `Renew` is called with `geni_best_effort` false, the entire method will fail if any requested sliver cannot be renewed to the requested time, and all slivers will keep their original expiration time. When `Renew` is called with `geni_best_effort` true, some sliver may fail to be renewed. In this case, the allocation state and expiration times do not change. `geni_error` may optionally be returned by the aggregate to explain this failure.
     328
    325329Arguments:
    326330{{{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 [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype the Common Concepts page].
    327331
    328 See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns[]`] and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials[]`] arguments.
     332See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns`] and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials`] arguments.
    329333
    330334Return value is a list of structs:
     
    336340   geni_operational_status: <string>,
    337341   geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>,
     342   geni_error: <optional string, may be omitted entirely, explaining any renewal failure for this sliver>
    338343  },
    339344  ...
     
    341346}}}
    342347
    343 See 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[]`].
     348See 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`].
    344349
    345350{{{
     
    371376                  geni_sliver_urn: <string sliver urn>
    372377                  geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from SliversStatus>,
    373                   geni_allocation_status: <string sliver state - allocated or ?? >
     378                  geni_allocation_status: <string sliver state - allocated or ?? >.
     379                  geni_error: <optional string, may be omitted entirely, explaining any update failure>
    374380        },
    375381        ...
     
    410416     geni_operational_status: <string>,
    411417     geni_expires <dateTime.rfc3339 when the sliver expires from its current state>,
     418     geni_error: <optional string, may be omitted entirely, explaining any failure to Provision this sliver>
    412419    },
    413420    ...
     
    415422}}}
    416423
    417 The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers.
    418 
    419 See 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`].
     424The 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` may be `geni_failed` or `geni_unallocated` or remain `geni_allocated`. Check `geni_error` for details.
     425
     426See 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`].
    420427
    421428{{{
     
    498505Note that aggregates may return other information, such as details on sliver contents, etc.
    499506
    500 See 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[]`].
     507See 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`].
    501508
    502509 == !PerformOperationalAction ==
     
    512519Aggregate 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`).
    513520
    514 Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none.
     521Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none).
    515522
    516523Return value is a list of structs:
     
    518525[ {
    519526        geni_sliver_urn : <string>,
    520         geni_allocation_status: <string, eg provisioned>
     527        geni_allocation_status: <string, eg provisioned>,
    521528        geni_operational_status : <string>,
    522         geni_expires: <dateTime.rfc3339 of individual sliver expiration>
    523         [optional: 'geni_resource_status' : string]
     529        geni_expires: <dateTime.rfc3339 of individual sliver expiration>,
     530        [optional: 'geni_resource_status' : string],
     531        [optional: 'geni_error': string explanation of operation failure for this sliver]
    524532        },
    525533        ...
     
    528536}}}
    529537
    530 See 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[]`].
     538See 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`].
    531539
    532540 == Delete ==
     
    550558   geni_allocation_status: <string>,
    551559   geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>,
     560   [optional: 'geni_error': string indicating any AM failure deleting the sliver.]
    552561  },
    553562  ...
     
    555564}}}
    556565
    557 See 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[]`].
     566See 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`].
    558567
    559568 == Shutdown ==
     
    570579Return: XML-RPC boolean, indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics.
    571580
    572 See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials[]` argument].
     581See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials` argument].