Changes between Version 79 and Version 80 of GAPI_AM_API_DRAFT

Timestamp:

10/19/12 09:29:10 (12 years ago)

Author:

Aaron Helsinger

Comment:

--

GAPI_AM_API_DRAFT

@@ -52 +52 @@
 = Proposed Changes for GENI Aggregate Manager API version 4 =
 
-A key feature desired by experimenters, but not yet included in the Aggregate Manager API, is the ability to update a reservation in place, without losing the existing reservation. At times, this has been called !UpdateSlivers. There is not currently an acceptable proposal for this feature that has been circulated.
+== Change Set C: `Update()` ==
+Add an ability for experimenters to modify their allocated resources at an aggregate without deleting (and possibly losing) existing resource allocations.
+
+This change was briefly discussed at GEC13, discussed at the GEC14 coding sprint, and is a topic for ongoing discussion.
+
+=== Motivation ===
+A common complaint among experimenters about the current AM API is that there is no way to atomically add/remove and modify resources at an aggregate. AM API v3 allows aggregates to support adding or deleting some resources from the slice at the aggregate, but not all aggregates can support that without the ability to also modify other resources. For example, you cannot add a link without adding an interface to one or more nodes, and there is no way to modify the node without first deleting it. This proposal aims to address that, by introducing a method to update the slice at an aggregate.
+
+The  [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] calls for an !UpdateSlice method, "to request that additional resources—as specified in the RSpec—be allocated to the slice".
+
+In the !PlanetLab implementation of the SFA, !UpdateSliver is in fact a synonym for !CreateSliver - the server will ensure that your allocated resources match your request RSpec, adding, removing and modifying resources as needed. It immediately allocates and boots nodes to match the request RSpec.
+
+The ProtoGENI CMV2 API has [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#UpdateSliver UpdateSliver], which is described as the way to "Request a change of resuorces for an existing sliver. The new set of resources that are desired are specified in the rspec." At ProtoGENI as at !PlanetLab, this method takes the full RSpec description of resources the experimenter wants, and the server computes the difference with what the experimenter already has. At ProtoGENI though, this method returns a ticket. The experimenter must then redeem the ticket to actually acquire the resources. 
+
+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]). 
+
+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.
+
+A competing related proposal from Gary Wong is here: http://www.protogeni.net/trac/protogeni/wiki/AM_API_proposals
+
+Jon Duerig [http://lists.geni.net/pipermail/dev/2012-July/000823.html made a proposal prior to GEC14], which was [http://groups.geni.net/geni/wiki/GEC14Agenda/CodingSprintAndExperimenterTutoring#Update discussed at the coding sprint]. This proposal is a revised version of that proposal.
+
+=== Proposal Summary ===
+This proposal adds an `Update()` method, a `Cancel()` method, and a new `geni_allocation_state`: `geni_updating`. The proposal includes a new state guarantee RSpec extension, a new `geni_cancelled` option to `Describe()`, and calls for some minor changes to GENI v3 RSpecs.
+
+=== `Update()` ===
+
+Begins a transaction to modify resources which are currently in the `geni_allocated` or `geni_provisioned` state. `Update()` itself changes only the internal allocation of slivers, not their operational state. It is therefore fast and synchronous.
+
+{{{
+struct Update(string urns[], struct credentials[], struct geni.rspec rspec, struct options)
+}}}
+
+This call accepts the `geni_best_effort` option; when supplied, the aggregate should attempt to partially satisfy the request.
+
+This 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.
+
+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
+two-step process involving first changing the allocation via `Update()` and then committing those changes with `Provision()`.
+
+The 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.
+
+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
+a modification to the given resource. Resources without a `sliver_id` are to be interpreted as new resource requests.
+
+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
+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
+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.
+
+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
+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.
+
+Any 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.
+
+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.
+
+=== After a successful `Update()` ===
+
+After 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.
+
+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
+freed and the sliver is `geni_unallocated`. The sliver does not return to the `geni_provisioned` state on sliver expiration.
+
+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
+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`.
+
+Any 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.
+
+Any 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()`.
+
+==== Return ====
+On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
+{{{
+{
+ geni_rspec: <geni.rspec manifest of newly allocated slivers>,
+ geni_slivers: [
+        {
+                  geni_sliver_urn: <string sliver urn>
+                  geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from Status>,
+                  geni_allocation_status: <string sliver state - e.g. geni_allocated, geni_updating>,
+                  geni_error: <optional string, may be omitted entirely, explaining any failure for a sliver>
+        },
+        ...
+    ]
+}
+}}}
+
+The list of returned slivers includes even those that will be deleted.
+
+=== State Guarantees ===
+
+The manifest RSpec may include an extension describing what guarantees the AM will make about state preservation. Omitting the extension means the AM provides no guarantees. It is proposed that the extension have the following RNC schema:
+
+{{{
+default namespace = "http://www.geni.net/resources/rspec/ext/preserve/1"
+
+# This is meant to extend a node or link
+Preserved = element preserve {
+  attribute guarantee { "geni_none" | "geni_persistent_state" |
+                        "geni_dynamic_state" | "geni_no_disruption" }
+}
+
+start = Preserved
+}}}
+
+Guarantee levels are defined to mean:
+ * `geni_none` is returned when the AM provides no state preservation guarantees for a sliver.
+ * `geni_persistent_state` is returned when the AM may wipe out dynamic state (i.e. reboot a node) but will preserve persistent state.
+ * `geni_dynamic_state` is returned when the AM retains the dynamic state but there may be other perturbations such as packet loss or service restarts.
+ * `geni_no_disruption` is returned when the AM will not make any changes that can perturb the sliver.
+
+=== `Cancel()` ===
+
+Cancels an `Update()` or an `Allocate()`.
+
+{{{
+struct Cancel(string urns[], string credentials[], struct options)
+}}}
+
+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.
+
+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
+operational state or attributes of the existing slivers.
+
+Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
+{{{
+{
+   geni_rspec: <geni.rspec, a Manifest RSpec>
+   geni_urn: <string slice urn of the containing slice>
+   geni_slivers: [
+               {
+                  geni_sliver_urn: <string sliver urn>
+                  geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from SliversStatus>,
+                  geni_allocation_status: <string sliver state - e.g. geni_allocated or geni_provisioned >,
+                  geni_operational_status: <string sliver operational state>,
+                  geni_error: <optional string, may be omitted entirely, explaining any failure for a sliver>
+               },
+               ...
+         ]
+}
+}}}
+
+=== Changes to `Provision()` ===
+
+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`
+state, provisioning them according to the manifest RSpec returned from that call.
+
+=== Changes to `Describe()` ===
+
+The addition of an `Update()` operation creates an ambiguity on the slivers being described. Should the Aggregate `Describe()` the slivers as they will
+be instantiated on a successful `Provision()` (including all slivers that are `geni_allocated`, `geni_updating`, and `geni_provisioned`)? Or should the AM describe the
+slivers which would remain after a `Cancel()` (including only the slivers that are `geni_allocated` or `geni_provisioned`, plus the updated slivers as they existed before being updated)?
+
+In order to account for this ambiguity, `Describe()` accepts a new option, `geni_cancelled` which defaults to `false`. When `geni_cancelled` is `true`,
+`Describe()` returns the state of all currently `geni_provisioned` slivers, showing the user what their slice will look like if they cancel all `geni_updating` and `geni_allocated` slivers. When `geni_cancelled` is `false`, the manifest and status will reflect the changed slivers in the `geni_updating` and `geni_allocated` states.
+
+=== Changes to `Delete()` ===
+
+A call to `Delete()` can be used to delete slivers in any state.
+
+=== Change to `geni_single_allocation` ===
+
+When an AM reports `geni_single_allocation` as `true` in `GetVersion()`, the following additional restrictions apply to calls:
+
+ * When calling `Update()`, the `urns` list must either contain a slice URN or it must contain the URN of every sliver at this Aggregate Manager in the given slice.
+ * When calling `Provision()`, the `urns` list must contain the sliver URNs of all slivers in either the `geni_allocated` or `geni_updating` states in the given slice.
+ * When calling `Cancel()`, the `urns` list must contain the sliver URNs of all slivers in either the `geni_allocated` or `geni_updating` states in the given slice.
+
+=== Mixed State Calls ===
+
+A `Renew()` call which contains sliver URNs in multiple allocation states will attempt to renew them all to the same requested expiration time.
+
+A `Delete()` call which contains sliver URNs in multiple allocation states will attempt to delete all slivers and put them in the `geni_unallocated` state.
+
+`Provision()` and `Cancel()` will ignore any sliver URNs which are not in the `geni_allocated` or `geni_updating` states.
+
+`Update()` can be called on slivers in any state. It will have no effect on slivers in the `geni_unallocated` state, and otherwise operates as described above.
+
+=== RSpec Change ===
+
+To easily accommodate submitting `Update()` requests, RSpecs will be changed:
+ * `sliver_id` will be allowed in request RSpecs
+ * Manifests will be modified to be re-usable as request RSpecs. In particular, the manifest schema will become a simple extension of the request schema, but this change is not required to support `Update()`.
 
 == Change Set N: Add information to `GetVersion` ==
-This change set adds some additional information to the return from `GetVersion`.
+This change set adds some additional information to the return from `GetVersion`. If adopted, aggregates may implement this as part of their AM API v3 implementation, but will be required to do so as part of AM API v4.
 
 === Change Set N1: Add `geni_am_code_version` ===
@@ -103 +285 @@
 
 == Change Set O: Refine character restrictions ==
+If adopted, aggregates may implement this as part of their AM API v3 implementation, but will be required to do so as part of AM API v4.
 
 === Change Set O1: Allow other characters in sliver names ===