Changes between Version 1 and Version 2 of AaronHelsinger/GAPI_AM_API_DRAFT
- Timestamp:
- 03/22/12 13:33:48 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
AaronHelsinger/GAPI_AM_API_DRAFT
v1 v2 46 46 - ADOPTED: Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration 47 47 - 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 entry49 - Partially Adopted: [#ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc48 - 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 50 50 - Include a real serial number, holder email, holder uuid, and optionally authority URL in certificates 51 - Define slice ID as the UUID in slice certificates52 - ADOPTED:Define slice name, sliver name, and user name restrictions, and similar for URNs51 - 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 53 53 - Publish schemas for credentials and certificates 54 - [#ChangeSetL:ChangeSFAcredentialsprivileges Change Set L]: Standardize slice credential privileges54 - Postponed: [#ChangeSetL:ChangeSFAcredentialsprivileges Change Set L]: Standardize slice credential privileges 55 55 56 56 For a full listing of the proposed API methods after all these changes, see [#Changesummary-methodsignatures below]. … … 81 81 This 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]). 82 82 83 This 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 85 A competing related proposal from Gary Wong is here: http://www.protogeni.net/trac/protogeni/wiki/AM_API_proposals 86 83 87 == !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.88 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. 85 89 86 90 Some points about this change: … … 90 94 - The request is either fully satisfied, or fails (returns an error code). 91 95 - 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.97 96 - Options includes {{{geni_end_time}}}, a RFC3339 requested end time for the reservation. See below for details. 98 97 - If omitted, the AM may reserve the resources for the default sliver duration. … … 100 99 - The request should Fail (return an error code) if the resources cannot be reserved until the requested time. 101 100 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: 101 Aggregates and experimenters should use an RSpec extension for specifying a guarantee on state loss per-resource: 111 102 EG: 112 103 {{{ … … 143 134 string ticket=<ticket> 144 135 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>,146 136 <others that are AM specific> 147 137 } … … 149 139 150 140 See [#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 value172 {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 }}}181 141 182 142 = Change Set D: Sliver-specific operations = … … 184 144 185 145 This 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 147 See http://lists.geni.net/pipermail/dev/2012-March/000593.html as well. 186 148 187 149 == Motivation == … … 219 181 - AMs should return an error message. Clients may often use !UpdateSlivers instead to similar effect. 220 182 183 Open Question: Should the methods take a list of urns, 1 of which may be a slice_urn? 184 221 185 = Change Set E: Tickets = 222 186 AM 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. 223 187 224 This change is actively under discussion. 188 This 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 225 189 226 190 For an alternative proposal, see: http://www.protogeni.net/trac/protogeni/wiki/AM_API_proposals … … 288 252 - RSpec (not specified as request or manifest) 289 253 - 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).291 254 - Including {{{geni_ticket_service_class}}} as defined below, to indicate the firmness of the promise this ticket represents 292 255 - signature including issuing AM's certificate … … 303 266 rspec = <RSpec (not specified as request or manifest)>, 304 267 attributes = { 305 geni_state_guarantee = <string>,306 268 geni_ticket_service_class = <string>, 307 269 <others> … … 310 272 } 311 273 }}} 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.320 274 321 275 Tickets should include the {{{geni_ticket_service_class}}} attribute for advertising the firmness of the promise that a ticket represents (case insensitive string or integer). … … 355 309 string geni_expires=<RFC3339 sliver expiration>, 356 310 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>,358 311 <others that are AM specific> 359 312 } … … 399 352 string ticket=<ticket> 400 353 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>,402 354 <others that are AM specific> 403 355 } … … 411 363 - AMs may, as always, return {{{UNSUPPORTED}}} - EG if they are incapable of determining what changes to apply (computing a diff). 412 364 - 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.417 365 - For further details on the !UpdateSlivers semantics, see [#ChangeSetC:UpdateSlivers Change Set C]. 418 366 … … 447 395 - Specifying {{{geni_start_time}}} means tell me what will be available at that time. Default is now. 448 396 - 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.452 397 453 398 -----