Changes between Version 9 and Version 10 of AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures


Ignore:
Timestamp:
04/16/12 10:16:39 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures

    v9 v10  
    7373-----
    7474
    75 == Common Arguments and Returns ==
     75== Common Arguments, Returns, and Concepts ==
    7676=== structs and optional arguments ===
    7777Unless otherwise specified, all arguments and returns of type `struct` may include aggregate or resource-specific entries. As arguments, such options must be optional for the client to supply, with the aggregate providing a reasonable default.
    7878
    79 === datetime data type ===
    80 All datetime arguments and returns in this API shall conform to [http://tools.ietf.org/html/rfc3339 RFC 3339]. This represents a subset of the valid date/time strings permissible by the standard XML-RPC date/time data type, [http://xmlrpc.scripting.com/spec dateTime.iso8601].
    81  - Full date and time with explicit timezone: offset from UTC or in UTC)
    82  - e.g.: 1985-04-12T23:20:50.52Z or 1996-12-19T16:39:57-08:00
    83 
    84 
    85 In the specification of this API, this is described as `dateTime.rfc3339`.
    8679
    8780=== RSpec data type ===
     
    124117At least one subset of the credentials (e.g. a single SFA style slice credential) must authorize operations for the slice specified in `slice_urn` if that is an argument, or for the slice that contains the named slivers, if sliver urns are an argument, or a valid set of administrative credentials with sufficient privileges. When sliver_urns are supplied, all such slivers must belong to the same slice, over which the given credential set provides access. Credentials must be valid (signed by a valid GENI certificate authority either directly or by chain, not expired, and grant privileges to the client identified by the SSL client certificate). Each method requires specific privileges, which must be granted by the provided credentials. Note that the semantics of this argument is not clear: most implementations require a single credential to provide all needed privileges. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. For details on GENI AM API format credentials, see [wiki:GeniApiCredentials the GENI wiki].
    125118
    126 === `geni_end_time` ===
    127 The `geni_end_time` argument requests an expiration of the specified slivers. It is in dateTime.rfc3339 format (defined above).
    128 When an explicit argument, it is required, and aggregates must honor the request to the extent local policy permits.
    129 When an option in the `options` struct, clients may omit the option, and AMs may choose not to or be unable to honor this option, but may still succeed the overall request.
    130 
    131 === `geni_best_effort` ===
    132  {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
    133 Clients may omit this option, but aggregates must honor the option if possible. This option modifies the way that the operation applies to all named slivers. By default (`geni_best_effort`=false), the operation must apply equally to all slivers, either succeeding or failing for all. When true, the aggregate may succeed the operation for some slivers, while failing the operation for other slivers.
    134 
    135 === `geni_users` ===
    136 `struct geni_users[]` is an option for some methods.
    137 
    138 Clients may omit this option. Aggregates should honor this option for any resource that accepts the provided login keys, and ignore it for other resources. This option is an array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. For example, this option is the mechanism by which users supply their SSH public keys, permitting SSH login to allocated nodes. In such cases, the corresponding manifest RSpec will contain the `ssh-users` element on each such node, showing the login username and applicable public keys. When this option is supplied, each struct must include the key 'keys', which is an array of strings and can be empty. The struct must also include the key 'urn', which is the user’s URN string. For example:
    139 {{{
    140 [
    141   {
    142     urn: urn:publicid:IDN+geni.net:gcf+user+alice
    143     keys: [<ssh key>, <ssh key>]
    144   },
    145   {
    146     urn: urn:publicid:IDN+geni.net:gcf+user+bob
    147     keys: [<ssh key>]
    148   }
    149 ]
    150 }}}
    151 
    152119=== `options` ===
    153120An XML-RPC struct. For !GetVersion only, this argument is optional. In all other methods, it is required. Only !ListResources has required entries in the options struct. Aggregates are compliant with this API change by accepting this argument. Aggregates may accept entries to this struct. Aggregates should not require any new options to any method - they should always have a reasonable default for any such option. Aggregates should document new `options` arguments. The prefix `geni_` is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts.
     121
     122=== Operations on Individual Slivers ===
     123A Sliver is an aggregate defined grouping of resources within a slice at this aggregate, whose URN identifies the sliver, and can be used as an argument to methods such as Delete or Renew, and whose status can be independently reported in the return from Status. The AM defines 1 or more of these groupings to satisfy a given resource request for a slice. All reserved resources are directly contained by exactly 1 such sliver container, which is in precisely 1 slice.
     124
     125One or more slivers are created by an aggregate when the experimenter calls Allocate(). This API encourages aggregates to independently manage each sliver, allowing experimenters to selectively Delete, Renew, or Provision each sliver. As such, these methods take a list of sliver urns (or a slice urn), and return a struct reporting results for each sliver URN independently. However, slivers at an aggregate may have interdependencies, and an individual aggregate may not be able to independently manage each sliver, without also modifying other related slivers. This API defines a number of aggregate configuration options returned by !GetVersion, and an option to many methods, allowing aggregates to advertise their behavior, and experimenters to request particular behavior.
     126
     127 1. `geni_single_allocation: <XML-RPC boolean 1/0, default 0>`: When performing one of (Describe, Allocate, Renew, Provision, Delete), the AM requires you to include either the slice urn or the urn of all the slivers in the same state. If you attempt to run one of those operations on just some slivers in a given state, the AM will return an error.
     128For example, you must Provision all `geni_allocated` slivers at once: At an aggregate with `geni_single_allocation` true, if you supply a list of sliver URNs to Provision that is only 'some' of the `geni_allocated` slivers for this slice at this AM, then the AM will return an error. Similarly, such an aggregate would return an error from Describe if you request a set of sliver URNs that is only some of the `geni_provisioned` slivers.
     129
     130 2. `geni_allocate: A string, one of fixed set of possible values. Default is `geni_single``. This option defines whether this AM allows adding slivers to a slices at an AM (i.e. calling Allocate() multiple times, without first deleting the allocated slivers). Possible values:
     131  - `geni_single`: Performing multiple Allocates without a delete is an error condition because the aggregate only supports a single sliver per slice or does not allow incrementally adding new slivers. This is the AM API v2 behavior.
     132  - `geni_disjoint`: Additional calls to Allocate must be disjoint from slivers allocated with previous calls (no references or dependencies on existing slivers). The topologies must be disjoint in that there can be no connection or other reference from one topology to the other.
     133  - `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.
     134
     135Many methods also take a new option (aggregates must support it, clients do not need to supply it):
     136{{{
     137   geni_best_effort: <XML-RPC boolean 1/0, default 0>
     138}}}
     139If 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. 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.
     140
     141It is expected that many aggregates will implement one of the following combinations of options:
     142 - Accept requests for `geni_best_effort` = true, and advertise `geni_allocate` = `geni_many`, `geni_single_allocation` = false (E.G. FOAM, PlanetLab).
     143 - Operate as though all requests were `geni_best_effort` = false, and advertise `geni_allocate` = `geni_disjoint`, `geni_single_allocation` = true (E.G. ProtoGENI).
    154144
    155145=== `urns[]` ===
     
    157147This API defines two kinds of URNs that may be supplied here, slice URNs and sliver URNs (see [wiki:GeniApiIdentifiers the GENI identifiers page], and [wiki:AaronHelsinger/GAPI_AM_API_DRAFT#Adopted:ChangeSetK:Standardizecertificatesandcredentials Change Set K]). Some aggregates may understand other URNs, but these are not defined or required here. Aggregates that accept only URNs defined by this API will return an error when given URNs not in one of those forms.
    158148This API requires that aggregates accept either a single slice URN, or 1+ sliver URNs that all belong to the same slice. Aggregates are not required to accept both a slice URN and sliver URNs, 2+ slice URNs, or a set of sliver URNs that crosses multiple slices. Some aggregates may choose to accept other such combinations of URNs. Aggregates that accept only arguments defined by this API will return an error when given more than 1 slice URN, a combination of both slice and sliver URNs, or a set of sliver URNs that belong to more than 1 slice.
     149
     150=== Sliver Allocation States ===
     151Many operations in this API create slivers or change the allocation status of slivers, and often return the current allocation status of each sliver.
     152Valid sliver allocation states are:
     153 1. `geni_unallocated` (alternatively called 'null'). The sliver does not exist. This is the small black circle in typical state diagrams.
     154 2. `geni_allocated` (alternatively called 'offered' or 'promised'). The sliver exists, defines particular resources, and is in a sliver. The aggregate has not (if possible) done any time consuming or expensive work to instantiate the resources, provision them, or make it difficult to revert the slice to the state prior to allocating this sliver. This state is what the aggregate is offering the experimenter.
     155 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.
     156
     157`geni_allocated` represents resources that have been allocated to a slice without provisioning the resources. This represents a cheap and un-doable 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 un-do without impacting the state of slivers which are fully provisioned. For some aggregates, transitioning to this state may be a no-op.
     158
     159States 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`.
     160
     161State 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.
     162
     163If the transition from one state to another fails, the sliver shall remain in its original state.
     164
     165 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.
     166 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.
     167 3. Renew, when given allocated slivers, requests an extended timeout for slivers in state 2 (`geni_allocated`).
     168 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.
     169 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.
     170
     171These 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.
     172
     173'''FIXME''': Add picture
     174
     175=== Sliver Operational States ===
     176The AM API defines a few operational states with particular semantics. AMs are not required to support them for a given set of resources, but if they use them, they must follow the given semantics. AMs are however STRONGLY encouraged to support them, to provide maximum utility. There is one state that AMs are required to support, `geni_pending_allocation`, for a sliver which has not been fully allocated and provisioned.
     177
     178AMs may have their own operational states/state-machine internally. AMs are required to advertise such states and actions that  experimenters may see or use, by using Ad RSpec extensions. Operational states which the experimenter never sees, need not be advertised. Operational states and actions are generally by resource type. The standard RSpec extension attaches such definitions to the `sliver_type` element of RSpecs.
     179
     180States should be defined in terms of (a) whether the resource is accessible to the experimenter on the data or control planes, (b) whether an experimenter action is required to change from this state,
     181and if so, (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.
     182
     183Note 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.
     184
     185There 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.
     186
     187`shutdown` is not an operational state for a sliver. The Shutdown() API method applies to an entire slice.
     188
     189Operational states are generally only valid for slivers which have been provisioned (`geni_provisioned` allocation state).
     190
     191GENI defined operational states:
     192 - `geni_pending_allocation`: A wait state. The sliver is still being allocated and provisioned, and other operational states are not yet valid. !PerformOperationalAction may not yet be called on this sliver.  For example, the sliver is in allocation state `geni_provisioned`, but has not been fully provisioned (e.g., the VM has not been fully imaged). Once the sliver has been fully allocated, the AM will transition the sliver to some other valid operational state, as specified by the advertised operational state machine. Common next states are `geni_notready`, `geni_ready`, and `geni_failed`.
     193 - `geni_notready`: A final state. The resource is not usable / accessible by the experimenter, and requires explicit experimenter action before it is usable/accessible by the experimenter. For some resources, `geni_start` will move the resource out of this state and towards `geni_ready`.
     194 - `geni_configuring`: A wait state. The resource is in process of changing to `geni_ready`, and on success will do so without additional experimenter action. For example, the resource may be powering on.
     195 - `geni_stopping`: A wait state. The resource is in process of changing to `geni_notready`, and on success will do so without additional experimenter action. For example, the resource may be powering off.
     196 - `geni_ready`: A final state. The resource is usable/accessible by the experimenter, and ready for slice operations.
     197 - `geni_ready_busy`: A wait state. The resource is performing some operational action, but remains accessible/usable by the experimenter. Upon completion of the action, the resource will return to `geni_ready`.
     198 - `geni_failed`: A final state. Some operational action failed, rendering the resource unusable. An administrator action, undefined by this API, may be required to return the resource to another operational state.
     199
     200=== Sliver Operational Actions ===
     201The API defines a few operational actions: these need not be supported. AMs are encouraged to support these if possible, but only if they can be supported following the defined semantics.
     202
     203AMs may have their own operational states/state-machine internally. AMs are required to advertise such states and actions that  experimenters may see or use, by using Ad RSpec extensions. Operational states which the experimenter never sees, need not be advertised. Operational states and actions are generally by resource type. The standard RSpec extension attaches such definitions to the `sliver_type` element of RSpecs.
     204
     205Tools must use the operational states and actions advertisement to determine what operational actions to offer to  experimenters, and what actions to perform for the experimenter. Tools may choose to offer actions which the tool does not understand, relying on the experimenter to understand the meaning of the new action.
     206
     207Any operational action may fail. When this happens, the API method should return an error code. The sliver may remain in the  original state. In some cases, the sliver may transition to the `geni_failed` state.
     208
     209GENI defined operational actions:
     210 - `geni_start`: This action results in the sliver becoming `geni_ready` eventually. The operation may fail (move to `geni_failed`), or move through some number of transition states. See EG booting a VM.
     211 - `geni_restart`: This action results in the sliver becoming `geni_ready` eventually. The operation may fail (move to `geni_failed`), or move through some number of transition states. During this operation, the resource may or may not remain accessible. Dynamic state associated with this resource may be lost by performing this operation. See EG re-booting a VM.
     212 - `geni_stop`: This action results in the sliver becoming `geni_notready` eventually. The operation may fail (move to `geni_failed`), or move through some number of transition states. See EG powering down a VM.
    159213
    160214=== Return Struct ===
     
    228282Note also that servers may respond with other HTTP error codes, and clients must be prepared to deal with those situations. Specifically, a server that is busy might return HTTP code 503, or just refuse the connection.
    229283
     284=== datetime data type ===
     285All datetime arguments and returns in this API shall conform to [http://tools.ietf.org/html/rfc3339 RFC 3339]. This represents a subset of the valid date/time strings permissible by the standard XML-RPC date/time data type, [http://xmlrpc.scripting.com/spec dateTime.iso8601].
     286 - Full date and time with explicit timezone: offset from UTC or in UTC)
     287 - e.g.: 1985-04-12T23:20:50.52Z or 1996-12-19T16:39:57-08:00
     288
     289
     290In the specification of this API, this is described as `dateTime.rfc3339`.
     291=== `geni_end_time` ===
     292The `geni_end_time` argument requests an expiration of the specified slivers. It is in dateTime.rfc3339 format (defined above).
     293When an explicit argument, it is required, and aggregates must honor the request to the extent local policy permits.
     294When an option in the `options` struct, clients may omit the option, and AMs may choose not to or be unable to honor this option, but may still succeed the overall request.
     295
     296=== `geni_best_effort` ===
     297 {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
     298Clients may omit this option, but aggregates must honor the option if possible. This option modifies the way that the operation applies to all named slivers. By default (`geni_best_effort`=false), the operation must apply equally to all slivers, either succeeding or failing for all. When true, the aggregate may succeed the operation for some slivers, while failing the operation for other slivers.
     299
     300=== `geni_users` ===
     301`struct geni_users[]` is an option for some methods.
     302
     303Clients may omit this option. Aggregates should honor this option for any resource that accepts the provided login keys, and ignore it for other resources. This option is an array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. For example, this option is the mechanism by which users supply their SSH public keys, permitting SSH login to allocated nodes. In such cases, the corresponding manifest RSpec will contain the `ssh-users` element on each such node, showing the login username and applicable public keys. When this option is supplied, each struct must include the key 'keys', which is an array of strings and can be empty. The struct must also include the key 'urn', which is the user’s URN string. For example:
     304{{{
     305[
     306  {
     307    urn: urn:publicid:IDN+geni.net:gcf+user+alice
     308    keys: [<ssh key>, <ssh key>]
     309  },
     310  {
     311    urn: urn:publicid:IDN+geni.net:gcf+user+bob
     312    keys: [<ssh key>]
     313  }
     314]
     315}}}
     316
     317
    230318-----
    231319=== Documenting Aggregate Additions ===
     
    258346The entries indicate versions of the API that are supported, and URLs are absolute URLs where that version of the API is supported.
    259347
    260 === Sliver Allocation States ===
    261 Many operations in this API create slivers or change the allocation status of slivers, and often return the current allocation status of each sliver.
    262 Valid sliver allocation states are:
    263  1. `geni_unallocated` (alternatively called 'null'). The sliver does not exist. This is the small black circle in typical state diagrams.
    264  2. `geni_allocated` (alternatively called 'offered' or 'promised'). The sliver exists, defines particular resources, and is in a sliver. The aggregate has not (if possible) done any time consuming or expensive work to instantiate the resources, provision them, or make it difficult to revert the slice to the state prior to allocating this sliver. This state is what the aggregate is offering the experimenter.
    265  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.
    266 
    267 `geni_allocated` represents resources that have been allocated to a slice without provisioning the resources. This represents a cheap and un-doable 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 un-do without impacting the state of slivers which are fully provisioned. For some aggregates, transitioning to this state may be a no-op.
    268 
    269 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`.
    270 
    271 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.
    272 
    273 If the transition from one state to another fails, the sliver shall remain in its original state.
    274 
    275  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.
    276  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.
    277  3. Renew, when given allocated slivers, requests an extended timeout for slivers in state 2 (`geni_allocated`).
    278  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.
    279  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.
    280 
    281 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.
    282 
    283 '''FIXME''': Add picture
    284 
    285 === Sliver Operational States ===
    286 The AM API defines a few operational states with particular semantics. AMs are not required to support them for a given set of resources, but if they use them, they must follow the given semantics. AMs are however STRONGLY encouraged to support them, to provide maximum utility. There is one state that AMs are required to support, `geni_pending_allocation`, for a sliver which has not been fully allocated and provisioned.
    287 
    288 AMs may have their own operational states/state-machine internally. AMs are required to advertise such states and actions that  experimenters may see or use, by using Ad RSpec extensions. Operational states which the experimenter never sees, need not be advertised. Operational states and actions are generally by resource type. The standard RSpec extension attaches such definitions to the `sliver_type` element of RSpecs.
    289 
    290 States should be defined in terms of (a) whether the resource is accessible to the experimenter on the data or control planes, (b) whether an experimenter action is required to change from this state,
    291 and if so, (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.
    292 
    293 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.
    294 
    295 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.
    296 
    297 `shutdown` is not an operational state for a sliver. The Shutdown() API method applies to an entire slice.
    298 
    299 Operational states are generally only valid for slivers which have been provisioned (`geni_provisioned` allocation state).
    300 
    301 GENI defined operational states:
    302  - `geni_pending_allocation`: A wait state. The sliver is still being allocated and provisioned, and other operational states are not yet valid. !PerformOperationalAction may not yet be called on this sliver.  For example, the sliver is in allocation state `geni_provisioned`, but has not been fully provisioned (e.g., the VM has not been fully imaged). Once the sliver has been fully allocated, the AM will transition the sliver to some other valid operational state, as specified by the advertised operational state machine. Common next states are `geni_notready`, `geni_ready`, and `geni_failed`.
    303  - `geni_notready`: A final state. The resource is not usable / accessible by the experimenter, and requires explicit experimenter action before it is usable/accessible by the experimenter. For some resources, `geni_start` will move the resource out of this state and towards `geni_ready`.
    304  - `geni_configuring`: A wait state. The resource is in process of changing to `geni_ready`, and on success will do so without additional experimenter action. For example, the resource may be powering on.
    305  - `geni_stopping`: A wait state. The resource is in process of changing to `geni_notready`, and on success will do so without additional experimenter action. For example, the resource may be powering off.
    306  - `geni_ready`: A final state. The resource is usable/accessible by the experimenter, and ready for slice operations.
    307  - `geni_ready_busy`: A wait state. The resource is performing some operational action, but remains accessible/usable by the experimenter. Upon completion of the action, the resource will return to `geni_ready`.
    308  - `geni_failed`: A final state. Some operational action failed, rendering the resource unusable. An administrator action, undefined by this API, may be required to return the resource to another operational state.
    309 
    310 === Sliver Operational Actions ===
    311 The API defines a few operational actions: these need not be supported. AMs are encouraged to support these if possible, but only if they can be supported following the defined semantics.
    312 
    313 AMs may have their own operational states/state-machine internally. AMs are required to advertise such states and actions that  experimenters may see or use, by using Ad RSpec extensions. Operational states which the experimenter never sees, need not be advertised. Operational states and actions are generally by resource type. The standard RSpec extension attaches such definitions to the `sliver_type` element of RSpecs.
    314 
    315 Tools must use the operational states and actions advertisement to determine what operational actions to offer to  experimenters, and what actions to perform for the experimenter. Tools may choose to offer actions which the tool does not understand, relying on the experimenter to understand the meaning of the new action.
    316 
    317 Any operational action may fail. When this happens, the API method should return an error code. The sliver may remain in the  original state. In some cases, the sliver may transition to the `geni_failed` state.
    318 
    319 GENI defined operational actions:
    320  - `geni_start`: This action results in the sliver becoming `geni_ready` eventually. The operation may fail (move to `geni_failed`), or move through some number of transition states. See EG booting a VM.
    321  - `geni_restart`: This action results in the sliver becoming `geni_ready` eventually. The operation may fail (move to `geni_failed`), or move through some number of transition states. During this operation, the resource may or may not remain accessible. Dynamic state associated with this resource may be lost by performing this operation. See EG re-booting a VM.
    322  - `geni_stop`: This action results in the sliver becoming `geni_notready` eventually. The operation may fail (move to `geni_failed`), or move through some number of transition states. See EG powering down a VM.
    323348
    324349----