Changes between Version 21 and Version 22 of AaronHelsinger/GAPI_AM_API_DRAFT

03/29/12 15:20:12 (7 years ago)
Aaron Helsinger



  • AaronHelsinger/GAPI_AM_API_DRAFT

    v21 v22  
    466466 5. !ProvisionSlivers 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.
     468'''Update''': Combine the 2 !RenewFoo methods into a single Renew() method which does different things for different sliver types.
    468470These 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.
    550552Currently, geni_status in !SliverStatus can have values `configuring`, `ready`, `failed`, `unknown`.
    552 This proposal expands that list, and renames those to use the standard 'geni_' prefix.
     554This proposal modifies that list, and renames those to use the standard 'geni_' prefix.
    554556These states would be reported by various AM API methods, specifically !SliverStatus. And would be used in reasoning about valid operations in !PerformOperationalAction
    556 Proposed GENI sliver operational states:
    558  - `geni_notready`: IE after the resource has been provisioned, but before doing `geni_start`
    559  - `geni_configuring`: IE after doing `geni_start`, but before it is fully ready.
    560  - `geni_busy`: The sliver is busy changing states. Could be eg after calling `geni_stop`, and before that completes.
    561  - `geni_ready`: the resource is fully ready for experimenter use
    562  - `geni_failed`: Something went wrong with the resource. Like it failed to boot. The sliver is unusable, and an operator must intervene.
    563  - `geni_unknown`: The AM cannot determine the state of the resource. The sliver state may become known, or may require an operator to intervene.
    564  - `geni_mixed`: For use only in reporting operational state of the full slice at an aggregate, when some resources are ready, and some are notready.
    565  - `geni_shutdown`: The sliver has been 'shutdown'. EG it has been brought down to a safe boot mode, where it can be inspected but not used.
     558The 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.
     560Similarly, 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.
     562AMs 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.
     564TODO: Jon Duerig will propose this extension, with examples covering PG/Emulab sliver_types.
     566Tools 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.
     568States 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,
     569and 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.
     571Note that states represent the AM's view of the operational condition of the resource. This state may be wrong due to faulty information at the AM.
     573Any 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.
     575There 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.
     577`shutdown` is not an operational state for a sliver. The Shutdown() API method applies to an entire slice.
     579GENI defined operational states:
     580 - `geni_notready`: A final state. The resource is not usable / accessible by the experimenter, and requires explicit experimenter action before it is
     581usable/accessible by the experimenter. For some resources, `geni_start` will move the resource out of this state and towards `geni_ready`.
     582 - `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.
     583 - `geni_ready`: A final state. The resource is usable/accessible by the experimenter, and ready for slice operations.
     584 - `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`.
     585 - `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 operations.
     587GENI defined operational actions:
     588 - `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.
     589 - `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 largely remain accessible/usable. Dynamic state associated with this resource may be lost by performing this operation. See EG re-booting a VM.
     590 - `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.
     592Actions are performed using the above proposed !PerformOperationalAction.
    567594= Adopted: Change Set G: Credentials are general authorization tokens. =