Changes between Version 16 and Version 17 of GAPI_AM_API_V3/CommonConcepts


Ignore:
Timestamp:
05/21/12 13:03:31 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3/CommonConcepts

    v16 v17  
    4747
    4848 - An AM must pick credentials out of the list that it understands and be robust to receiving credentials it does not understand.
    49  - Current slice and user credentials will be recognizable for following the schema defined in Change Set K and GeniApiCredentials.
     49 - Current slice and user credentials will be recognizable for following the schema defined in GeniApiCredentials.
    5050 - AMs are required to continue to accept current-format credentials.
    5151  - In particular, a single standard slice credential remains sufficient for most authorization policies.
    … …  
    6666}}}
    6767
    68 ''sfa" slice credentials as defined pre AM API version 3 will have type=`geni_sfa` and version=`2`. "sfa" slice credentials as of AM API version 3 will be type=`geni_sfa`, version=`3`.
     68"sfa" slice credentials as defined pre-AM API version 3 will have type=`geni_sfa` and version=`2`. "sfa" slice credentials as of AM API version 3 will be type=`geni_sfa`, version=`3`.
    6969ABAC credentials as of AM API version 3 will be type=`geni_abac`, version=`1`.
    7070
    … …  
    117117=== `urns[]` ===
    118118Several methods take some URNs to identify what to operate on. These methods are defined as accepting a list of arbitrary strings we call URNs.
    119 This 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: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.
     119This API defines two kinds of URNs that may be supplied here, slice URNs and sliver URNs (see [wiki:GeniApiIdentifiers the GENI identifiers page]). 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.
    120120This 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.
    121121
    … …  
    159159
    160160=== Sliver Operational States ===
    161 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.
    162 
    163 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 advertisement 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.
    164 
    165 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,
    166 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.
     161Slivers, once fully allocated, are said to be in a particular operational state. This is something like configuring running, ready, turning, etc. These states are used by tools to know what sliver-internal actions are relevant, and what aggregate definer operational actions may be valid.
     162
     163The 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 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 (other operational states are not yet valid).
     164
     165AMs 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. 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.
     166
     167States should be defined in terms of
     168 a. whether the resource is accessible to the experimenter (on either the data or control planes),
     169 b. whether an experimenter action is required to change from this state, and if so,
     170 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.
    167171
    168172Note 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.
    … …  
    170174There 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.
    171175
    172 `shutdown` is not an operational state for a sliver. The Shutdown() API method applies to an entire slice.
     176`Shutdown` is not an operational state for a sliver. The `Shutdown()` API method applies to an entire slice.
    173177
    174178Operational states are generally only valid for slivers which have been provisioned (`geni_provisioned` allocation state).
    175179
     180States are generally of one of two forms:
     181 1. 'wait' states: The AM will change the sliver, causing its operational state to change, without experimenter action.
     182 2. 'final' states: The sliver will remain in this state, until and unless the experimenter invokes an operational action on the sliver.
     183
     184Some AMs may allow actions during 'wait' states, (e.g. 'Cancel').
     185
    176186GENI defined operational states:
    177  - `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`.
     187 - `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`.
    178188 - `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`.
    179189 - `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.
    … …  
    184194
    185195=== Sliver Operational Actions ===
     196Operational 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.
     197
    186198The 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.
    187199
    188 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.
    189 
    190 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.
    191 
    192 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.
     200AMs 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. 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.
     201
     202Tools 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 itself does not understand, relying on the experimenter to understand the meaning of the new action.
     203
     204Any 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.
    193205
    194206GENI defined operational actions: