Changes between Version 53 and Version 54 of AaronHelsinger/GAPI_AM_API_DRAFT


Ignore:
Timestamp:
04/24/12 10:29:19 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • AaronHelsinger/GAPI_AM_API_DRAFT

    v53 v54  
    3838Below, you will see that some change sets have been withdrawn (J). Others have been superseded, meaning that other proposals implement similar concepts in an alternative way (Change Sets F1 and F2). Some sets may be postponed, to be considered for a later version of this API (L). In addition, two change sets are waiting on revised proposals (C and E).
    3939
    40 Given that, readers of this page should focus on Change Sets F, G, I, K, and M.
     40Given that, readers of this page should focus on Change Sets D, F, G, I, K, and M.
    4141
    4242Proposals currently under discusion:
    43  - [#ChangeSetD:Sliver-specificoperations Change Set D: Slivers]: ''Partially superseded.'' Change methods to clarify that there may be multiple slivers per slice at an AM, and to allow operating on individual slivers
     43 - [#ChangeSetD:Sliver-specificoperations Change Set D: Slivers]: Change methods to clarify that there may be multiple slivers per slice at an AM, and to allow operating on individual slivers
    4444 - [#ChangeSetF3:SliverAllocationStatesandmethods Change Set F3]: Sliver Allocation States and methods
    4545 - [#ChangeSetF4:SliverOperationsMethod Change Set F4]: Method to perform Sliver Operational actions
    … …  
    4747 - [#ChangeSetM:NewMethodSignatures Change Set M]: New method signatures, incorporating all previous adopted change sets
    4848
    49 We are awaiting new proposals on !UpdateSlivers, and the semantics of adding multiple sets of resources to a slice at an aggregate.
     49We are awaiting new proposals on !UpdateSlivers.
    5050
    5151Proposals previously adopted:
    … …  
    5454 - '''ADOPTED''' with changes: Change Set I2: !SliversStatus return includes SSH logins/key for nodes that support SSH access
    5555 - '''ADOPTED''': Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration
    56  - '''ADOPTED''': [#Adopted:ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc
     56 - '''ADOPTED''': [#Adopted:ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc.
    5757  - Include a real serial number, holder email, holder uuid, and optionally authority URL in certificates
    5858  - Define slice ID as the UUID plus URN in slice certificates
    … …  
    7373
    7474== Unspecified items ==
    75  - Semantics of adding or removing slivers from the full set of slivers in a slice at an aggregate
    7675 - An acceptable Update proposal
    7776 - RSpec for advertising operational states for a sliver type
    … …  
    8180----
    8281
    83 
    8482= Change Set D: Sliver-specific operations =
    8583A slice may have multiple slivers at a single AM. Experimenters can operate on slivers independently, if the AM supports it. AMs define slivers as groups of resources, and give them locally unique sliver_urns for identifying that group of resources.
    … …  
    10199Given this definition, the current AM API methods in fact operate on a group of slivers.
    102100
    103 This change set would provide a means for experimenters to operate on individual slivers within their slice at a given aggregate.
     101This change set provides a means for experimenters to operate on individual slivers within their slice at a given aggregate.
    104102
    105103== Define sliver ==
    … …  
    122120  - AMs are free to refuse to Renew, Delete, or provide status on an individual sliver, if the local AM or that resource type does not support it.
    123121   - AMs should return an error message if the operation is not supported.
     122   - See below for ways that aggregates advertise their supported behavior.
    124123
    125124 3. Define new returns from !GetVersion, for specifying the semantics of operating on individual slivers.
    126 These returns are only required if the aggregate supports non-standard behavior.
     125These returns are only required if the aggregate supports non-standard behavior. Aggregates that supporte the default behavior may omit these !GetVersion returns.
    127126
    128127  - `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.
    … …  
    146145The proposal originally here elicited concerns (the method !ActOnSlivers is an ioctl, and the states mix allocation and operational states).
    147146
    148 A later alternative proposal, see http://lists.geni.net/pipermail/dev/2012-March/000721.html
     147A later alternative proposal was proposed via email: http://lists.geni.net/pipermail/dev/2012-March/000721.html
    149148
    150149At the GEC13 coding sprint, a variant on the above was approved. It is documented here as [#ChangeSetF3:SliverAllocationStatesandmethods Change Set F3].
    … …  
    161160For meeting minutes, see: [wiki:GEC13Agenda/CodingSprint the GEC13 Coding Sprint agenda page].
    162161
    163  - We agreed to use two kinds of states: allocation states, and operational states. We put off discussion of operational states (ie is the node booted), noting however that this is critical. See Change Set F4.
     162 - We agreed to use two kinds of states: allocation states, and operational states. We put off discussion of operational states (i.e. is the node booted), noting however that this is critical. See Change Set F4.
    164163 - We debated whether the API should specify a limited number of states, or allow for aggregate or resource specific states. We agreed that for allocation states, the API should define a limited set of states, while operational states might be more permissive.
    165164 - We discussed the pros and cons of including a single all-in-one method to change allocation states, or a single method per desired transition. There is at least 1 case where there are 2 paths between the same 2 allocation states with very different meaning. As a result, we agreed to use a separate method per allocation state change.
    … …  
    232231The canonical source for documentation on this proposal is here: https://openflow.stanford.edu/display/FOAM/GENI+-+PerformOperationalAction
    233232
    234 Open questions include:
    235  - Do we need a state discovery mechanism? A method? An RSpec ad extension?
    236  - Should the method default to all or nothing? Or to partial success?
    237  - What are the defined operational states, and GENI standard actions for transitions?
    238  - Does the API specify how operational state of slivers rolls up to the state of the slice at the aggregate?
    239  - Make option names and returns consistent between this change set and [#ChangeSetF3:SliverAllocationStatesandmethods change set F3]
     233See Change Set F5 for a companion proposal for aggregates to advertise legal operational states and actions.
    240234
    241235{{{
    … …  
    260254}}}
    261255
    262 Performs the given action on the given sliver_urn(s) (or slice_urn as a proxy for "all slivers").  Actions are constrained to the set of default GENI actions, as well as resource-specific actions which reasonably perform operational resource tasks as defined by the aggregate manager for the given resource type.  This method is not intended to allow for reconfiguration of options found in the request rspec.  Aggregate Managers SHOULD return an error code of `13` (`UNSUPPORTED`) if they do not support a given action for a given resource. Actions are performed on all slivers, or none - if an action cannot be performed on a sliver given, the entire operation MUST fail. Passing the option `geni_best_effort` allows for partial success.
    263 
    264 An AM SHOULD constrain actions based on the current operational state of the resource, such that attempting to perform the action `geni_stop` on a resource that is `geni_busy` will fail, but SHOULD also be idempotent for all actions which result in a steady state.
    265 
    266 `geni_operational_status` MUST be the current operational status of the sliver after this action (as would be returned by !SliverStatus). An optional `geni_resource_status` field MAY be returned for each sliver which contains a resource-specific status that may be more nuanced than the options for `geni_operational_status`.
     256Performs the given action on the given sliver_urn(s) (or slice_urn as a proxy for "all slivers").  Actions are constrained to the set of default GENI actions, as well as resource-specific actions which reasonably perform operational resource tasks as defined by the aggregate manager for the given resource type.  This method is not intended to allow for reconfiguration of options found in the request rspec.  Aggregate Managers SHOULD return an error code of `13` (`UNSUPPORTED`) if they do not support a given action for a given resource. Actions are performed on all slivers, or none - if an action cannot be performed on a sliver given, the entire operation MUST fail. Passing the option `geni_best_effort` with a value of true allows for partial success (this option defaults to false if not supplied).
     257
     258An AM SHOULD constrain actions based on the current operational state of the resource, such that for example attempting to perform the action `geni_stop` on a resource that is `geni_ready_busy` or `geni_configuring` or `geni_stopping` will fail, but SHOULD also be idempotent for all actions which result in a steady state.
     259
     260`geni_operational_status` MUST be the current operational status of the sliver after this action (as would be returned by !SliverStatus). An optional `geni_resource_status field` MAY be returned for each sliver which contains a resource-specific status that may be more nuanced than the options for `geni_operational_status`.
    267261
    268262Calling this method with a slice_urn functions as if all the child sliver_urn's had been passed in - specifically the action is performed on all slivers and all sliver_urn's and their statuses are returned. No status is returned for the slice as a whole.
    … …  
    273267
    274268== Change Set F5: Sliver Operational States ==
    275 Currently, geni_status in !SliverStatus can have values `configuring`, `ready`, `failed`, `unknown`.
     269Currently, `geni_status` in !SliverStatus can have values `configuring`, `ready`, `failed`, `unknown`.
    276270
    277271This proposal modifies that list, and renames those to use the standard 'geni_' prefix.
    … …  
    550544
    551545== M1: users struct an option ==
    552 Previously, the !CreateSliver method took a `users[]` struct to specify information for logging in to resources. But this struct is not universally applicable. This change moves that struct to be an option within the `options` struct, named `geni_users[]`.
     546Previously, the !CreateSliver method took a `users[]` struct to specify information for logging in to resources. But this struct is not universally applicable. This change moves that struct to be an option within the `options` struct, named `geni_users[]`. All other semantics and syntax for this argument remain the same from AM API version 2.
    553547
    554548== M2: Split !ListResources ==
    555 Currently, !ListResources has two forms: get an advertisement general to the aggregate, and get a manifest specific to a slice. This proposal splits those two modes into two separate methods, !ListResources, and Describe.
     549Currently, !ListResources has two forms: (1) get an advertisement general to the aggregate, and (2) get a manifest specific to a slice. This proposal splits those two modes into two separate methods, !ListResources, and Describe.
    556550
    557551!ListResources would no longer take a `slice_urn` option, and no longer ever return a manifest RSpec.
    558552
    559 Describe would be used to achieve the same functionality.
     553Describe would be used to achieve that same functionality.
    560554{{{
    561555struct Describe(string urns[], struct credentials[], struct options[])
    … …  
    576570{{{
    577571{
    578    geni_rspec: <geni.rspec, Manifest - may be empty though)>
    579    geni_urn: <string slice urn, as requested>
     572   geni_rspec: <geni.rspec, Manifest>
     573   geni_urn: <string slice urn of the containing slice>
    580574   geni_slivers: [
    581575               {