Changes between Version 51 and Version 52 of GAPI_AM_API_DRAFT


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

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_DRAFT

    v51 v52  
    114114
    115115 2. Some methods that take {{{slice_urn}}} now take a {{{urn}}} that may be a slice or sliver:
    116   - E.G. Renew, Delete, Status
     116  - E.G. `Renew`, `Delete`, `Status`
    117117  - AMs are responsible for distinguishing whether the request operates on a slice or a sliver (see [#ChangeSetK:Standardizecertificatesandcredentials Change Set K] which defines how slice and sliver URNs differ).
    118   - AMs are free to refuse to Renew, Delete, or provide status on an individual sliver, if the local AM or that resource type does not support it.
     118  - AMs are free to refuse to `Renew`, `Delete`, or provide status on an individual sliver, if the local AM or that resource type does not support it.
    119119   - AMs should return an error message if the operation is not supported.
    120120   - See below for ways that aggregates advertise their supported behavior.
    … …  
    131131   - `geni_many`: Multiple slivers can exist and be incrementally added, including those which connect or overlap in some way. New aggregates should strive for this capability.
    132132
    133 Note that these options interact with `geni_best_effort` defined in Change Set F3, defining whether operations on a set of slivers (or whole slice) should either all fail/succeed together, or if some slivers can succeed and others fail. Default behavior is false - all slivers succeed or all fail.
     133Note that these options interact with `geni_best_effort` defined in Change Set F3, defining whether operations on a set of slivers (or whole slice) should either all fail/succeed together, or if some slivers can succeed and others fail. Default behavior is false - all slivers succeed or all fail.  If the aggregate cannot guarantee all or nothing success or failure given the included slivers and resource types, the aggregate shall fail the request, returning an appropriate error code. If this option is true, then some slivers may transition to the new state, and some not. Experimenters must examine the return closely to know the state of their slivers - such methods will return data about all requested slivers. Aggregates may optionally return `geni_error` for each sliver for which the operation failed, to indicate further details.  Note that `Allocate` is always all-or-nothing.
    134134
    135135It is expected that many aggregates will implement one of the following combinations of options:
    … …  
    170170 3. `geni_provisioned`. The aggregate has started instantiating resources, and otherwise making changes to resources and the slice to make the resources available to the experimenter. At this point, operational states are valid to specify further when the resources are available for experimenter use.
    171171
     172plus in select situations:
     173
     174 4. `geni_failed`: A call to `Provision` failed for this sliver. The sliver is in indeterminate state. Check the `geni_error` return if provided, or call `Status`. The sliver may require operator action to recover it.
     175
    172176The key change is the addition of state 2, representing resources that have been allocated to a slice without provisioning the resources. This represents a cheap and un-doable resource allocation, such as we previously discussed in the context of tickets. This compares reasonably well to the 'transaction' proposal written up by Gary Wong (http://www.protogeni.net/trac/protogeni/wiki/AM_API_proposals). When a sliver is created and moved into state 2 (`geni_allocated`), the aggregate produces a manifest RSpec identifying which resources are included in the sliver. This is something like the current !CreateSliver, except that it does not provision nor start the resources. These resources are exclusively available to the containing sliver, but are not ready for use. In particular, allocating a sliver should be a cheap and quick operation, which the aggregate can readily un-do without impacting the state of slivers which are fully provisioned. For some aggregates, transitioning to this state may be a no-op.
    173177
    … …  
    179183
    180184These are the only allocation states supported by this API. Since the state transitions are finite, but include potentially multiple transitions between the same two states, this API uses separate methods to perform each state transition, rather than a single method for requesting a new state for the sliver.
    181  1. Allocate moves 1+ slivers from `geni_unallocated` (state 1)  to `geni_allocated` (state 2). This method can be described as creating an instance of the state machine for each sliver. If the aggregate cannot fully satisfy the request, the whole request fails. This is a change from the version 2 !CreateSliver, which also provisioned the resources, and 'started' them. That is Allocate does 1 of the 3 things that !CreateSliver did previously.
    182  2. Delete moves 1+ slivers from either state 2 or 3 (`geni_allocated` or `geni_provisioned`), back to state 1 (`geni_unallocated`). This is similar to the AM API version 2 !DeleteSliver.
    183  3. Renew, when given allocated slivers, requests an extended timeout for slivers in state 2 (`geni_allocated`).
    184  4. Renew can also be used to request an extended timeout for slivers in state 3 - the `geni_provisioned` state. That is, this method's semantics can be the same as !RenewSliver from AM API v2.
    185  5. Provision moves 1+ slivers from state 2 (`geni_allocated`) to state 3 (`geni_provisioned`). This is some of what version 2 !CreateSliver did. Note however that this does not 'start' the resources, or otherwise change their operational state. This method only fully instantiates the resources in the slice. This may be a no-op for some aggregates or resources.
     185 1. `Allocate` moves 1+ slivers from `geni_unallocated` (state 1)  to `geni_allocated` (state 2). This method can be described as creating an instance of the state machine for each sliver. If the aggregate cannot fully satisfy the request, the whole request fails. This is a change from the version 2 !CreateSliver, which also provisioned the resources, and 'started' them. That is `Allocate` does 1 of the 3 things that !CreateSliver did previously.
     186 2. `Delete` moves 1+ slivers from either state 2 or 3 (`geni_allocated` or `geni_provisioned`), back to state 1 (`geni_unallocated`). This is similar to the AM API version 2 !DeleteSliver.
     187 3. `Renew`, when given allocated slivers, requests an extended timeout for slivers in state 2 (`geni_allocated`).
     188 4. `Renew` can also be used to request an extended timeout for slivers in state 3 - the `geni_provisioned` state. That is, this method's semantics can be the same as !RenewSliver from AM API v2.
     189 5. `Provision` moves 1+ slivers from state 2 (`geni_allocated`) to state 3 (`geni_provisioned`). This is some of what version 2 !CreateSliver did. Note however that this does not 'start' the resources, or otherwise change their operational state. This method only fully instantiates the resources in the slice. This may be a no-op for some aggregates or resources.
     190
     191When `Provision` fails for only some slivers, and `geni_best_effort` option was supplied, the aggregate will return the status of each requested sliver individually. The `geni_allocation_state` for slivers that failed may remain `geni_allocated`. This typically suggests that the experimenter may retry the call. The state may instead become `geni_unallocated`. This indicates that the sliver is being deleted, and all resource reservations under this sliver have been freed. Alternatively, the state may be `geni_failed`, indicating an error or refusal by the AM to complete the operation. An operator may need to intervene. Alternatively, the sliver may shortly self transition and become either `geni_allocated` again or `geni_unallocated`.
    186192
    187193These states apply to each sliver individually. Logically, the state transition methods then take a single sliver URN. For convenience, these methods accept a list of sliver URNs, or a slice URN as a simple alias for all slivers in this slice at this aggregate.
    … …  
    194200   geni_allocation_status: <string>,
    195201   geni_expires: <time when the sliver expires from its current state>,
     202   [optional: geni_error: string indicating why an operation failed on this sliver]
    196203   <others AM or method specific>
    197204   <Provision returns geni_operational_status>
    … …  
    210217}}}
    211218If false, the client is requesting that the aggregate either fully satisfy the request, moving all listed slivers to the desired state, or fully fail the request, leaving all slivers in their original state.
    212 If the aggregate cannot guarantee all or nothing success or failure given the included slivers and resource types, the aggregate shall fail the request, returning an appropriate error code. If this option is true, then some slivers may transition to the new state, and some note. Aggregates must examine the return closely to know the state of their slivers.
     219If the aggregate cannot guarantee all or nothing success or failure given the included slivers and resource types, the aggregate shall fail the request, returning an appropriate error code. If this option is true, then some slivers may transition to the new state, and some not. Experimenters must examine the return closely to know the state of their slivers.
    213220
    214221'''Note''': Allocate remains (like v2 !CreateSliver) all or nothing (either the aggregate can allocate all desired resources as requested, or the call fails).