Changes between Version 1 and Version 2 of AaronHelsinger/GAPI_AM_API_DRAFT


Ignore:
Timestamp:
03/22/12 13:33:48 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • AaronHelsinger/GAPI_AM_API_DRAFT

    v1 v2  
    4646 - ADOPTED: Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration
    4747 - Change Set I4: !CreateSlivers optionally does not start resources.
    48  - [#ChangeSetJ:Proxyaggregatemanagersaresupported Change Set J]: Support proxy aggregates with 1 new option and 1 new !GetVersion entry
    49  - Partially Adopted: [#ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc
     48 - Withdrawn: [#ChangeSetJ:Proxyaggregatemanagersaresupported Change Set J]: Support proxy aggregates with 1 new option and 1 new !GetVersion entry
     49 - ADOPTED: [#ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc
    5050  - Include a real serial number, holder email, holder uuid, and optionally authority URL in certificates
    51   - Define slice ID as the UUID in slice certificates
    52   - ADOPTED: Define slice name, sliver name, and user name restrictions, and similar for URNs
     51  - Define slice ID as the UUID plus URN in slice certificates
     52  - Define slice name, sliver name, and user name restrictions, and similar for URNs
    5353  - Publish schemas for credentials and certificates
    54  - [#ChangeSetL:ChangeSFAcredentialsprivileges Change Set L]: Standardize slice credential privileges
     54 - Postponed: [#ChangeSetL:ChangeSFAcredentialsprivileges Change Set L]: Standardize slice credential privileges
    5555
    5656For a  full listing of the proposed API methods after all these changes, see [#Changesummary-methodsignatures below].
    … …  
    8181This topic was discussed at the [http://groups.geni.net/geni/wiki/GEC12GeniAmAPI GEC12 AM API session] and on the GENI dev mailing list (in [http://lists.geni.net/pipermail/dev/2011-October/000433.html October] and [http://lists.geni.net/pipermail/dev/2011-November/000531.html November]).
    8282
     83This topic was also discussed on the geni-dev mailing list here: http://lists.geni.net/pipermail/dev/2012-March/000588.html and here: http://lists.geni.net/pipermail/dev/2012-March/000643.html and elsewhere in March 2012.
     84
     85A competing related proposal from Gary Wong is here: http://www.protogeni.net/trac/protogeni/wiki/AM_API_proposals
     86
    8387== !UpdateSlivers ==
    84 This change would add a new method !UpdateSlivers, which takes a full request RSpec of the desired final state of the slice at this aggregate. This proposal calls for adding this functionality in the context of tickets: the !UpdateSlivers method returns a ticket. See [#ChangeSetE:Tickets Change Set E: Tickets] for details. If tickets are not adopted, consider the alternative proposal below, where !UpdateSlivers immediately allocates and starts the requested resources, as in !CreateSlivers.
     88This change would add a new method !UpdateSlivers, which takes a full request RSpec of the desired final state of the slice at this aggregate. This proposal calls for adding this functionality in the context of tickets: the !UpdateSlivers method returns a ticket. See [#ChangeSetE:Tickets Change Set E: Tickets] for details.
    8589
    8690Some points about this change:
    … …  
    9094 - The request is either fully satisfied, or fails (returns an error code).
    9195 - AMs must document the level of service they provide: will any state be lost on existing resources?
    92   - Typically this would be a per node or resource-type specification.
    93   - Use the levels of guarantee in {{{geni_state_guarantee}}} below.
    94   - Default is to provide no guarantee.
    95   - This API does not define where AMs provide detailed documentation, but AMs must return this value for the entire change as part of the return struct.
    96  - Experimenters may specify what level of disruption they can tolerate, using the {{{geni_state_guarantee}}} below. AMs are expected to fail a request with a specified service guarantee that they cannot satisfy. Default is to request no guarantee.
    9796 - Options includes {{{geni_end_time}}}, a RFC3339 requested end time for the reservation. See below for details.
    9897  - If omitted, the AM may reserve the resources for the default sliver duration.
    … …  
    10099  - The request should Fail (return an error code) if the resources cannot be reserved until the requested time.
    101100
    102 This change adds a new option {{{geni_state_guarantee}}} with these possible values (case insensitive string or integer):
    103  - 0=NO_GUARANTEE (default: all state ''may'' be lost)
    104  - 1=SAVE_DISK (disk state will be preserved but running processes will be lost)
    105  - 2=SAVE_DISK_AND_PROCESSES (both disk state and running processes will be preserved, like migrating a VM)
    106  - 3=NO_DISRUPTION (no noticeable service disruption)
    107 
    108 AMs which cannot meet the implied limit to service disruption should fail the request (return an error code).
    109 
    110 ''However'' there is an alternative more widely accepted proposal, to use an RSpec extension allowing this guarantee to be per-resource:
     101Aggregates and experimenters should use an RSpec extension for specifying a guarantee on state loss per-resource:
    111102EG:
    112103{{{
    … …  
    143134  string ticket=<ticket>
    144135  string geni_status=<sliver state - ticketed>,
    145   string geni_state_guarantee=<promise from AM of what experimenter state will be lost on trying to 'start' this allocation>,
    146136 <others that are AM specific>
    147137}
    … …  
    149139
    150140See [#ChangeSetE:Tickets Change Set E: Tickets] for details on the ticket returned and ticket semantics.
    151 
    152 == Alternative proposal: !UpdateSlivers with immediate allocation ==
    153 An alternative proposal would add two versions of !UpdateSlivers. Method 1 would return a ticket as above. Method 2 would immediately allocate the resources, as with !CreateSlivers.
    154 
    155 This proposed version of !UpdateSlivers is substantially the same as the main proposal above, with a few differences:
    156 
    157  - Under this alternative proposal, on success the new resources are allocated to the slice. As with !CreateSlivers, by default those new resources are initialized or booted or started, such that they will shortly become available for experimenter use.
    158  - As with !CreateSlivers, the AM should start/restart resources immediately, as necessary.
    159   - This change introduces a new option {{{geni_donotstart}}}. When supplied and true (boolean: 0 or 1 in XML-RPC), aggregates should allocate the resources but not start them. Experimenters will have to explicitly use !ActOnSlivers to start or restart resources as necessary. Note that there may be no such distinction for some resources.
    160    - Removed resources are stopped by the aggregate automatically.
    161  - Note that the tickets proposal includes a method that updates the resource reservation without allocating them.
    162  - This method moves the overall sliver state to {{{allocated}}}, and then (if the experimenter did not specify {{{geni_donotstart}}}) {{{configuring}}} and then {{{ready}}} if it succeeds.
    163 
    164 Proposed method signature:
    165 {{{
    166 struct UpdateSlivers(string slice_urn,
    167                     string credentials[],
    168                     <GENI request RSpec schema compliant XML string> rspec,
    169                     struct users[],
    170                     struct options)
    171 Return value
    172 {
    173  string rspec=<manifest>,
    174  string geni_start_time=<optional (may be omitted altogether) RFC3339 start time for the allocation: now if not specified>,
    175  string geni_expires=<RFC3339 sliver expiration>,
    176  string geni_status=<sliver state - allocated or changing or ready>,
    177  string geni_state_guarantee=<promise from AM of what experimenter state will be lost on trying to 'start' this allocation>,
    178  <others that are AM specific>
    179 }
    180 }}}
    181141
    182142= Change Set D: Sliver-specific operations =
    … …  
    184144
    185145This change was briefly discussed at GEC13, and remains open for discussion. Concerns include whether aggregates can support individually operating on slivers, and whether we should make this change without that functionality.
     146
     147See http://lists.geni.net/pipermail/dev/2012-March/000593.html as well.
    186148
    187149== Motivation ==
    … …  
    219181   - AMs should return an error message. Clients may often use !UpdateSlivers instead to similar effect.
    220182
     183Open Question: Should the methods take a list of urns, 1 of which may be a slice_urn?
     184
    221185= Change Set E: Tickets =
    222186AM APIv3 adds support for negotiated reservations or two-phase commit, by '''add'''ing methods that allow an experimenter to reserve resources for a slice without committing to using them, or forcing the AM to incur the cost of instantiating them.
    223187
    224 This change is actively under discussion.
     188This change is actively under discussion. See for example http://lists.geni.net/pipermail/dev/2012-March/000616.html and http://lists.geni.net/pipermail/dev/2012-March/000648.html
    225189
    226190For an alternative proposal, see: http://www.protogeni.net/trac/protogeni/wiki/AM_API_proposals
    … …  
    288252 - RSpec (not specified as request or manifest)
    289253 - Attributes (AM/resource-type specific name/value pairs)
    290   - Including optionally {{{geni_state_guarantee}}} as defined below, to indicate if existing slivers will be disrupted (default is no guarantee).
    291254  - Including {{{geni_ticket_service_class}}} as defined below, to indicate the firmness of the promise this ticket represents
    292255 - signature including issuing AM's certificate
    … …  
    303266 rspec = <RSpec (not specified as request or manifest)>,
    304267 attributes = {
    305     geni_state_guarantee = <string>,
    306268    geni_ticket_service_class = <string>,
    307269    <others>
    … …  
    310272}
    311273}}}
    312 
    313 Tickets may include in the {{{attributes}}} element the attribute {{{geni_state_guarantee}}}, indicating whether the AM will preserve the state of any existing resources (case insensitive string or integer).
    314  - 0=NO_GUARANTEE (Default: all state ''may'' be lost)
    315  - 1=SAVE_DISK (disk state will be preserved but running processes will be lost)
    316  - 2=SAVE_DISK_AND_PROCESSES (both disk state and running processes will be preserved, like migrating a VM)
    317  - 3=NO_DISRUPTION (no noticeable service disruption)
    318 
    319 ''However'', see above for a proposed RSpec extension to instead make the state guarantee per resource.
    320274
    321275Tickets should include the {{{geni_ticket_service_class}}} attribute for advertising the firmness of the promise that a ticket represents (case insensitive string or integer).
    … …  
    355309 string geni_expires=<RFC3339 sliver expiration>,
    356310 string geni_status=<sliver state - allocated (or optionally changing or ready)>,
    357  string geni_state_guarantee=<promise from AM of what experimenter state will be lost on trying to 'start' this allocation>,
    358311 <others that are AM specific>
    359312}
    … …  
    399352  string ticket=<ticket>
    400353  string geni_status=<sliver state - ticketed>,
    401   string geni_state_guarantee=<promise from AM of what experimenter state will be lost on trying to 'start' this allocation>,
    402354 <others that are AM specific>
    403355}
    … …  
    411363  - AMs may, as always, return {{{UNSUPPORTED}}} - EG if they are incapable of determining what changes to apply (computing a diff).
    412364 - The request is either fully satisfied, or fails (returns an error code).
    413  - AMs must document the level of service they provide using levels from {{{geni_state_guarantee}}}: will any state be lost on existing resources?
    414   - Default is to provide no guarantee.
    415  - Experimenters may specify what level of disruption they can tolerate, using the {{{geni_state_guarantee}}} option.
    416   - AMs are expected to fail a request with a specified service guarantee that they cannot satisfy. Default is to request no guarantee.
    417365 - For further details on the !UpdateSlivers semantics, see [#ChangeSetC:UpdateSlivers Change Set C].
    418366
    … …  
    447395  - Specifying {{{geni_start_time}}} means tell me what will be available at that time. Default is now.
    448396  - Specifying both {{{geni_end_time}}} and {{{geni_start_time}}} means show me only things available for that entire duration.
    449 
    450 == An Alternative: Provide two !UpdateSlivers methods ==
    451 One alternative would be to define two versions of !UpdateSlivers, with and without an intermediate ticket. The no-ticket version of this method would behave like !CreateSlivers, immediately allocating requested resources. For details on this proposal, see above.
    452397
    453398-----