Changes between Version 25 and Version 26 of GAPI_AM_API_V3/CommonConcepts


Ignore:
Timestamp:
07/17/12 12:18:04 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3/CommonConcepts

    v25 v26  
    165165Slivers, once fully allocated, are said to be in a particular operational state. States may indicate that a sliver is configuring, running, ready, turning, etc. These states are used by tools to know what sliver-internal actions are relevant, and what aggregate-defined operational actions may be valid.
    166166
    167 The AM API defines a few operational states with particular semantics. AMs are not required to support the API defined states for all resources, but if the aggregate uses the API defined states, then the aggregate must follow the given semantics. AMs are however STRONGLY encouraged to support them, to provide maximum interoperability. There is one state that AMs are required to support, `geni_pending_allocation`, for a sliver which has not been fully allocated and provisioned (other operational states are not yet valid).
     167The AM API defines a few operational states with particular semantics. AMs are not required to support the API defined states for all resources, but if the aggregate uses the API defined states, then the aggregate must follow the given semantics. AMs are however STRONGLY encouraged to support them, to provide maximum interoperability. There is one state that AMs are required to support, `geni_pending_allocation`, for a sliver which has not been fully allocated and provisioned (other operational states are not yet valid). Operational states are generally only valid for slivers which have been provisioned (`geni_provisioned` allocation state).
    168168
    169169AMs may have their own operational states/state-machine internally. AMs are however required to advertise such states and actions that experimenters may see or use, by using an advertisement RSpec extension (if an AM does not advertise operational states, then tools can not know whether any actions are available). 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.
    … …  
    182182`Shutdown` is not an operational state for a sliver. The `Shutdown()` API method applies to an entire slice.
    183183
    184 Operational states are generally only valid for slivers which have been provisioned (`geni_provisioned` allocation state).
    185 
    186184States are generally of one of two forms:
    187185 1. 'wait' states: The AM will change the sliver, causing its operational state to change, without experimenter action.
    … …  
    192190Operational actions immediately change the sliver operational state (if any change will occur). Long running actions therefore require a 'wait' state, while the action is completing.
    193191
    194 GENI defined operational states:
    195  - `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. This state is generally not part of the AM's advertised state machine, as it represents 'operational states not valid yet'. Common next states (and first states of operational state machines) are `geni_notready`, `geni_ready`, and `geni_failed`.
     192GENI defined operational states (both required and optional for aggregates):
     193 - `geni_pending_allocation`: Required for aggregates to support. 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. This state is generally not part of the AM's advertised state machine, as it represents 'operational states not valid yet'. Common next states (and first states of operational state machines) are `geni_notready`, `geni_ready`, and `geni_failed`.
    196194 - `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`.
    197195 - `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.
    … …  
    202200
    203201=== Sliver Operational Actions ===
    204 Operational actions are commands that the aggregate exposes, allowing an experimenter tool to modify or act on a sliver from outside of the sliver, without modifying the sliver reservation. Actions may cause changes to sliver operational state.
     202Operational actions are commands that the aggregate exposes, allowing an experimenter tool to modify or act on a sliver from outside of the sliver (i.e. without logging in to a machine), without modifying the sliver reservation. Actions may cause changes to sliver operational state.
    205203
    206204The 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.
    … …  
    217215
    218216GENI defined operational actions:
    219  - `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.
    220  - `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.
    221  - `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.
     217 - `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. For example, booting a VM.
     218 - `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. For example, re-booting a VM.
     219 - `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. For example, powering down a VM.
    222220
    223221=== Return Struct ===
    … …  
    255253
    256254 `am_type`::
    257     Optional. A (case insensitive) string indicating the type of Aggregate Manager running locally. When an aggregate wants to return an aggregate specific return code in the {{{am_code}}} field, they supply an {{{am_type}}} to qualify the kind of aggregate specific return code they are supplying. This is the namespace of the aggregate specific return code. This field is optional: aggregates are not required to supply an aggregate specific return code, and clients need not look at it. This code further qualifies the kind of error or success that the aggregate is returning, as primarily defined by the value of {{{geni_code}}}. Standard values for {{{am_type}}} are defined [attachment:geni-am-types.xml in the attached XML document].
     255    Optional. A (case insensitive) string indicating the type of Aggregate Manager running locally. For example, `orca`. When an aggregate wants to return an aggregate specific return code in the {{{am_code}}} field, they supply an {{{am_type}}} to qualify the kind of aggregate specific return code they are supplying. This is the namespace of the aggregate specific return code. This field is optional: aggregates are not required to supply an aggregate specific return code, and clients need not look at it. This code further qualifies the kind of error or success that the aggregate is returning, as primarily defined by the value of {{{geni_code}}}. Standard values for {{{am_type}}} are defined [attachment:geni-am-types.xml in the attached XML document].
    258256 
    259257 `am_code`::
    … …  
    300298
    301299=== `geni_end_time` ===
    302 The `geni_end_time` argument requests an expiration of the specified slivers. It is in dateTime.!rfc3339 format (defined above).
     300The `geni_end_time` argument requests an expiration of the specified slivers. It is in dateTime.!rfc3339 format (defined [#datetimedatatype above]).
    303301When an explicit argument, it is required, and aggregates must honor the request to the extent local policy permits.
    304302When 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.
    … …  
    321319`struct geni_users[]` is an option for some methods.
    322320
    323 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:
     321Clients 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:
    324322{{{
    325323[
    … …  
    344342The new extension adds an entry per login username
    345343 - URN of the user
    346  - 1+ public SSH keys that can be used under that login
    347 
    348 Note that 1 of the `<user:services_user login>`s in the extension duplicates the default username already in the base `<login>` tag. The extension allows specifying the keys usable with that login username.
     344 - 1 or more public SSH keys that can be used under that login
     345
     346Note that one of the `<user:services_user login>`s in the extension duplicates the default username already in the base `<login>` tag. The extension allows specifying the keys usable with that login username.
    349347
    350348EG:
    … …  
    390388=== Supporting Multiple API Versions ===
    391389
    392 Aggregates are free to support multiple versions of the AM API. They do so by providing different URLs for each version of the API that they support. Aggregates should have a 'default' URL (the one typically advertised). That version runs whichever version of the API the server chooses (could be the latest, could be something else.)
     390Aggregates are free to support multiple versions of the AM API. They do so by providing different URLs for each version of the API that they support. Aggregates should have a 'default' URL (the one typically advertised). That url runs whichever version of the API the server chooses (could be the latest, could be something else.)
    393391
    394392When aggregates start supporting a new version of the API, they should keep running the old version of the API for a suitable transition period.
    … …  
    396394Aggregates running multiple versions of the API must advertise the URLs and versions of the API supported using the new `GetVersion` return as part of the {{{value}}} entry:
    397395{{{
    398 geni_api_versions: an XML-RPC struct containing 1+ entries of:
     396geni_api_versions: an XML-RPC struct containing 1 or more entries of:
    399397  Name: Integer - supported GENI AM API version
    400398  Value: String - URL to the XML-RPC server implementing that version of the GENI AM API