Changes between Version 85 and Version 86 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
01/28/13 09:04:36 (11 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_DRAFT

    v85 v86  
    9393This call accepts the `geni_end_time` option; when supplied, the aggregate may attempt to renew the slivers being created or modified to the requested time, according to aggregate-local policy.
    9494
    95 This change adds a new `geni_updating state, for slivers that were `geni_provisioned` but have been updated. Here is a state diagram:
     95This change adds a new `geni_updating` state, for slivers that were `geni_provisioned` but have been updated. Here is a state diagram:
    9696
    9797[[Image(update-state.png)]]
    9898
    99 Since `Update()` changes the allocation state only, it has an immediate effect on slivers currently in the `geni_allocated` or `geni_updating` states. However, updating slivers in the `geni_provisioned` state is a
    100 two-step process involving first changing the allocation via `Update()` and then committing those changes with `Provision()`.
     99Since `Update()` changes the allocation state only, it has an immediate effect on slivers currently in the `geni_allocated` or `geni_updating` states. However, updating slivers in the `geni_provisioned` state is a two-step process involving first changing the allocation via `Update()` and then committing those changes with `Provision()`.
    101100
    102101The input RSpec is a complete request specification for all slivers included in the `urns` list, as you would like the slivers to exist when the call is fully committed. Any difference in the update RSpec from the current slivers shall be interpreted as a modification request, including removing interfaces or links, or deleting entire slivers.
    103102
    104 The RSpec argument to `Update()` should be a request RSpec, but RSpecs passing the manifest schema are allowed. Resources in the RSpec should include the `sliver_id` tag when the experimenter is requesting
    105 a modification to the given resource. Resources without a `sliver_id` are to be interpreted as new resource requests.
    106 
    107 If a sliver is defined in the RSpec ''and'' contained in the `urns` list, (either by URN or by indirect inclusion because the slice URN is in the `urns` list), then the user is requesting that the sliver be modified. If the sliver was
    108 in the `geni_allocated` state, the allocation of that sliver is changed immediately and the sliver remains in a `geni_allocated` state. If the sliver was in the `geni_provisioned` state, the operational state of
    109 that sliver is preserved and it is placed in the `geni_updating` state where it can be `Provision()`ed to implement the modification or `Cancel()`led.
    110 
    111 If the RSpec does not define one or more slivers which are specified in the `urns` list (that is, does not include resources containing the given `sliver_id` tag), then the user is requesting that the given sliver(s) should be
    112 deleted. If the sliver was in the `geni_allocated` state, the allocated sliver is deleted and the sliver ceases to exist (becomes `geni_unallocated`). If the sliver was in the `geni_provisioned` state, then the operational state of that sliver is preserved and it is placed in the `geni_updating` allocation state where it can be `Provision()`ed to delete the sliver or `Cancel()`led to preserve it.
     103The RSpec argument to `Update()` should be a request RSpec, but RSpecs passing the manifest schema are allowed. Resources in the RSpec should include the `sliver_id` tag when the experimenter is requesting a modification to the given resource. Resources without a `sliver_id` are to be interpreted as new resource requests.
     104
     105If a sliver is defined in the RSpec ''and'' contained in the `urns` list, (either by URN or by indirect inclusion because the slice URN is in the `urns` list), then the user is requesting that the sliver be modified. If the sliver was in the `geni_allocated` state, then the allocation of that sliver is changed immediately and the sliver remains in a `geni_allocated` state. If the sliver was in the `geni_provisioned` state, then the operational state of that sliver is preserved and it is placed in the `geni_updating` state where it can be `Provision()`ed to implement the modification or `Cancel()`led.
     106
     107If the RSpec does not define one or more slivers which are specified in the `urns` list (that is, does not include resources containing the given `sliver_id` tag), then the user is requesting that the given sliver(s) should be deleted. If the sliver was in the `geni_allocated` state, the allocated sliver is deleted and the sliver ceases to exist (becomes `geni_unallocated`). If the sliver was in the `geni_provisioned` state, then the operational state of that sliver is preserved and it is placed in the `geni_updating` allocation state where it can be `Provision()`ed to delete the sliver or `Cancel()`led to preserve it.
    113108
    114109Any slivers which are not defined in the RSpec ''and'' do not appear in the `urns` list will remain unchanged. They remain in their current allocation state.
    115110
    116 Any resources requested in the RSpec that are not specified in the `urns` list will be instantiated and be in the `geni_allocated` state, if the aggregate has the resources available.
     111Any resources requested in the RSpec that are not specified in the `urns` list will be instantiated and be in the `geni_allocated` state, if the aggregate has the resources available and otherwise can provide the resources following the aggregate's policy for `Allocate`.
     112
     113Note that at least one urn must be provided in the `urns` argument (slice or sliver). If a sliver urn is supplied and that sliver is unknown or expired, then `Update` shall result in an error (e.g. `SEARCHFAILED`, `EXPIRED` or `ERROR` `geni_code`) (unless `geni_best_effort` is `true`, in which case the method may succeed, but return a `geni_error` for each sliver that failed).  If `Update` is called with a slice urn which identifies a slice with no existing reservation at this aggregate, then `Update` behaves like `Allocate`. Not however that if the supplied RSpec identifies any specific slivers (via inclusion of a `sliver_id`), then those sections are treated as new resource requests.
    117114
    118115=== After a successful `Update()` ===
     
    120117After a successful call to `Update()`, all slivers in the `urns` list which began in the `geni_provisioned` state will be in the `geni_updating` state (and their configuration will revert in the case of a `Cancel()` call described below). This ''includes'' those slivers which are marked for deletion as described above. These slivers will not actually be deleted until the `Provision()` call.
    121118
    122 Slivers which were `geni_provisioned` and are now `geni_updating` will retain their prior existing expiration time. If the expiration time is reached before the sliver is `Provision()`ed, then the resources are
    123 freed and the sliver is `geni_unallocated`. The sliver does not return to the `geni_provisioned` state on sliver expiration.
    124 
    125 All slivers which began in the `geni_allocated` state will remain in the `geni_allocated` state, or will have been deleted and there will be no way (except for attempting another `Update()`) to revert their
    126 configuration. Slivers that are updated and remain in the `geni_allocated` state will have a new expiration time, as determined by the aggregate, but typically set just as for new slivers returned by `Allocate()`. As with other `geni_allocated` slivers, if the sliver expires before it is `Provision()`ed, then the resources are freed and the sliver is `geni_unallocated`.
     119Slivers which were `geni_provisioned` and are now `geni_updating` will retain their prior existing expiration time. If the expiration time is reached before the sliver is `Provision()`ed, then the resources are freed and the sliver is `geni_unallocated`. The sliver does not return to the `geni_provisioned` state on sliver expiration.
     120
     121All slivers which began in the `geni_allocated` state will remain in the `geni_allocated` state, or will have been deleted and there will be no way (except for attempting another `Update()`) to revert their configuration. Slivers that are updated and remain in the `geni_allocated` state will have a new expiration time, as determined by the aggregate, but typically set just as for new slivers returned by `Allocate()`. As with other `geni_allocated` slivers, if the sliver expires before it is `Provision()`ed, then the resources are freed and the sliver is `geni_unallocated`.
    127122
    128123Any slivers which began in the `geni_updating` state will remain in the `geni_updating` state, with their prior existing expiration time. If the expiration time is reached before the sliver is `Provision()`ed, then the resources are freed and the sliver is `geni_unallocated`. The sliver does not return to the `geni_provisioned` state on sliver expiration.
     
    130125Any new resources requested in the RSpec not associated with a current sliver will be in the `geni_allocated` state and will be added to slivers, just as after a call to `Allocate()`.
    131126
    132 While slivers are `geni_updating`, operational actions are not permitted (`PerformOperationalAction()` should return an error code).
     127While slivers are `geni_updating`, operational actions are not permitted (`PerformOperationalAction()` should return an error code - `2`, `14`, or `16`).
    133128
    134129==== Return ====
     
    182177}}}
    183178
    184 This call accepts the `geni_best_effort` option; as with `Delete()`, then this option is supplied the aggregate should attempt to de-allocate individual slivers.
    185 
    186 When applied to slivers in the `geni_allocated` state, `Cancel()` acts just like `Delete()`. When applied to slivers in the `geni_updating` state, those slivers are returned to the `geni_provisioned` state with no change to the
    187 operational state or attributes of the existing slivers.
     179This call accepts the `geni_best_effort` option; as with `Delete()`, when this option is supplied the aggregate should attempt to de-allocate individual slivers.
     180
     181When applied to slivers in the `geni_allocated` state, `Cancel()` acts just like `Delete()`. When applied to slivers in the `geni_updating` state, those slivers are returned to the `geni_provisioned` state with no change to the operational state or attributes of the existing slivers.
    188182
    189183Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
     
    207201=== Changes to `Provision()` ===
    208202
    209 When applied to slivers in the `geni_updating` state, this call will either remove those slivers (if they were marked for deletion as described in the `Update()` call) or move them to the `geni_provisioned`
    210 state, provisioning them according to the manifest RSpec returned from that call.
     203When applied to slivers in the `geni_updating` state, this call will either remove those slivers (if they were marked for deletion as described in the `Update()` call) or move them to the `geni_provisioned` state, provisioning them according to the manifest RSpec returned from that call.
    211204
    212205=== Changes to `Describe()` ===
     
    224217}}}
    225218
    226 This attribute is an empty string when the current allocation state is not `geni_allocated` or `geni_updating`.
     219This attribute is an empty string (not `None` or `null`) when the current allocation state is not `geni_allocated` or `geni_updating`.
    227220
    228221=== Changes to `Delete()` ===
     
    232225=== Changes to `PerformOperationalAction()` ===
    233226
    234 While slivers are `geni_updating`, operational actions are not permitted (`PerformOperationalAction()` should return an error code).
     227While slivers are `geni_updating`, operational actions are not permitted (`PerformOperationalAction()` should return an error code - `2`, `14`, or `16`).
    235228
    236229=== Changes to `Status()` ===
     
    242235}}}
    243236
    244 This attribute is an empty string when the current allocation state is not `geni_allocated` or `geni_updating`.
     237This attribute is an empty string (not `None` or `null`) when the current allocation state is not `geni_allocated` or `geni_updating`.
    245238
    246239===  Changes to `Renew()` ===
     
    252245}}}
    253246
    254 This attribute is an empty string when the current allocation state is not `geni_allocated` or `geni_updating`.
     247This attribute is an empty string (not `None` or `null`) when the current allocation state is not `geni_allocated` or `geni_updating`.
    255248
    256249=== Change to `geni_single_allocation` ===