Context Navigation

Changes between Version 24 and Version 25 of GAPI_AM_API_V3/CommonConcepts

Timestamp:: 07/17/12 12:09:19 (12 years ago)
Author:: Aaron Helsinger
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

GAPI_AM_API_V3/CommonConcepts

-                      v24
+                      v25
 . `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.
 }}}
+[[Image(sliver-alloc-states3.jpg)]]
+'''Sliver Allocation States and AM API Method Transitions'''
 `geni_allocated` represents resources that have been allocated to a slice without provisioning the resources. This represents a cheap and reversible resource allocation. 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. 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 undo without impacting the state of slivers which are fully provisioned. For some aggregates, transitioning to this state may be a no-op.
 States 2 and 3 (`geni_allocated` and `geni_provisioned`) have aggregate and possibly resource specific timeouts. By convention the `geni_allocated` state timeout is typically short. The `geni_provisioned` state timeout is the sliver expiration. If the client does not transition the sliver from `geni_allocated` to `geni_provisioned` before the end of the `geni_allocated` state timeout, the sliver reverts to `geni_unallocated`. If the experimenter needs more time, the experimenter should be allowed to request a renewal of either timeout.  Note that typically the sliver expiration time (timeout for state 3, `geni_provisioned`) will be notably longer than the timeout for state 2, `geni_allocated`.
+States 2 and 3 (`geni_allocated` and `geni_provisioned`) have aggregate and possibly resource specific timeouts. By convention the `geni_allocated` state timeout is typically short, to keep most resources available. The `geni_provisioned` state timeout is the sliver expiration. If the client does not transition the sliver from `geni_allocated` to `geni_provisioned` before the end of the `geni_allocated` state timeout, the sliver reverts to `geni_unallocated`. If the experimenter needs more time, the experimenter should be allowed to request a renewal of either timeout.  Note that typically the sliver expiration time (timeout for state 3, `geni_provisioned`) will be notably longer than the timeout for state 2, `geni_allocated`.
 State 3, `geni_provisioned`, is the state of the sliver allocation after the aggregate begins to instantiate the sliver. Note that fully provisioning a sliver may take noticeable time. This state also includes a timeout - the sliver expiration time (which is not necessarily related to the time it takes to provision a resource). `Renew` extends this timeout. For some aggregates and resource types, moving to this state from state 2 (`geni_allocated`) may be a no-op.
 …
 If the transition from one state to another fails, the sliver shall remain in its original state.
+. `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.
+. `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`.
+Several AM API methods can be described in terms of transitions among allocation states.
+. `Allocate` moves 1 or more 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 AM API V2 `CreateSliver`, which also provisioned the resources, and 'started' them. That is `Allocate` does one of the three things that `CreateSliver` did previously.
+. `Delete` moves 1 or more 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 AM API V2 `DeleteSliver`.
 . `Renew`, when given allocated slivers, requests an extended timeout for slivers in state 2 (`geni_allocated`).
 . `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.
 . `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.
+. `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.
+. `Provision` moves 1 or more slivers from state 2 (`geni_allocated`) to state 3 (`geni_provisioned`). This is some of what AM API V2 `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.
 When `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 will remain `geni_allocated`. This typically suggests that the experimenter may retry the call. For some aggregates or resource types, the sliver may be 'dead', and `Provision` may never succeed. Experimenters should check `geni_error` for more information.
 …
 These 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.
-[[Image(sliver-alloc-states3.jpg)]]
 === Sliver Operational States ===
 …
  c. what action or actions are useful. If the resource will change states without explicit experimenter action, what is the expected next state on success.
 Note that states represent the AM's view of the operational condition of the resource. This state represents what the AM has done or learned about the resource, but experimenter actions may cause failures that the AM does not know about.
 There is no `busy` state. Instead, AMs are encouraged to define separate such transition states for each separate transition path, allowing experimenters to distinguish the start and end states for this transition.
+Note that states represent the AM's view of the operational condition of the resource. Each state represents what the AM has done or learned about the resource, but experimenter actions may cause failures that the AM does not know about. For example, the AM may advertise a state of `geni_ready` for a machine when the experimenter has manually rebooted the machine.
+There is no generic `busy` state. Instead, AMs are encouraged to define separate similar transition states for each separate transition path, allowing experimenters to distinguish the start and end states for this transition.
 `Shutdown` is not an operational state for a sliver. The `Shutdown()` API method applies to an entire slice.