| 466 | | The key change is the addition of state 2, representing resources that have been allocated to a slice without provisioning the resources. This represents a cheap and un-doable resource allocation, such as we previously discussed in the context of tickets. This compares reasonably well to the 'transaction' proposal written up by Gary Wong (http://www.protogeni.net/trac/protogeni/wiki/AM_API_proposals). When a sliver is created and moved into state 2 (`geni_allocated`), the aggregate produces a manifest RSpec identifying which resources are included in the sliver. This is something like the current !CreateSlivers, except that it does not provision nor start the resources. These resources are exclusively available to the containing sliver, but are not ready for use. In particular, allocating a sliver should be a cheap and quick operation, which the aggregate can readily un-do without impacting the state of slivers which are fully provisioned. For some aggregates, transitioning to this state may be a no-op. |
| | 466 | The key change is the addition of state 2, representing resources that have been allocated to a slice without provisioning the resources. This represents a cheap and un-doable resource allocation, such as we previously discussed in the context of tickets. This compares reasonably well to the 'transaction' proposal written up by Gary Wong (http://www.protogeni.net/trac/protogeni/wiki/AM_API_proposals). When a sliver is created and moved into state 2 (`geni_allocated`), the aggregate produces a manifest RSpec identifying which resources are included in the sliver. This is something like the current !CreateSliver, except that it does not provision nor start the resources. These resources are exclusively available to the containing sliver, but are not ready for use. In particular, allocating a sliver should be a cheap and quick operation, which the aggregate can readily un-do without impacting the state of slivers which are fully provisioned. For some aggregates, transitioning to this state may be a no-op. |
| 475 | | 1. !CreateSlivers moves 1+ slivers from `geni_unallocated` (state 1) to `geni_allocated` (state 2). This method can be described as creating an instance of the state machine for each sliver. If the aggregate cannot fully satisfy the request, the whole request fails. This is a change from the version 2 !CreateSliver, which also provisioned the resources, and 'started' them. That is !CreateSlivers does 1 of the 3 things that it did previously. Note the method name change, consistent with change set D. |
| 476 | | 2. !DeleteSlivers moves 1+ slivers from either state 2 or 3 (`geni_allocated` or `geni_provisioned`), back to state 1 (`geni_unallocated`). This is similar to the AM API version 2 !DeleteSliver. Note the method name change, consistent with change set D. |
| 477 | | 3. !RenewAllocations requests an extended timeout for slivers in state 2 (`geni_allocated`). |
| 478 | | 4. !RenewSlivers requests an extended timeout for slivers in state 3 - the `geni_provisioned` state. That is, this method's semantics does not change. Note the method name change, consistent with change set D. |
| 479 | | 5. !ProvisionSlivers moves 1+ slivers from state 2 (`geni_allocated`) to state 3 (`geni_provisioned`). This is some of what version 2 !CreateSliver did. Note however that this does not 'start' the resources, or otherwise change their operational state. This method only fully instantiates the resources in the slice. This may be a no-op for some aggregates or resources. |
| 480 | | |
| 481 | | '''Update''': Combine the 2 !RenewFoo methods into a single Renew() method which does different things for different sliver types. |
| | 475 | 1. Allocate moves 1+ slivers from `geni_unallocated` (state 1) to `geni_allocated` (state 2). This method can be described as creating an instance of the state machine for each sliver. If the aggregate cannot fully satisfy the request, the whole request fails. This is a change from the version 2 !CreateSliver, which also provisioned the resources, and 'started' them. That is Allocate does 1 of the 3 things that !CreateSliver did previously. |
| | 476 | 2. Delete moves 1+ slivers from either state 2 or 3 (`geni_allocated` or `geni_provisioned`), back to state 1 (`geni_unallocated`). This is similar to the AM API version 2 !DeleteSliver. |
| | 477 | 3. Renew, when given allocated slivers, requests an extended timeout for slivers in state 2 (`geni_allocated`). |
| | 478 | 4. Renew can also be used to request an extended timeout for slivers in state 3 - the `geni_provisioned` state. That is, this method's semantics can be the same as !RenewSliver from AM API v2. |
| | 479 | 5. Provision moves 1+ slivers from state 2 (`geni_allocated`) to state 3 (`geni_provisioned`). This is some of what version 2 !CreateSliver did. Note however that this does not 'start' the resources, or otherwise change their operational state. This method only fully instantiates the resources in the slice. This may be a no-op for some aggregates or resources. |
| | 888 | == M2: Split !ListResources == |
| | 889 | 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. |
| | 890 | |
| | 891 | !ListResources would no longer take a `slice_urn` option, and no longer ever return a manifest RSpec. Describe would be used to achieve the same functionality. |
| | 892 | |
| | 893 | {{{ |
| | 894 | struct Describe(string urns[], struct credentials[], struct options[]) |
| | 895 | }}} |
| | 896 | |
| | 897 | Where options include: |
| | 898 | {{{ |
| | 899 | { |
| | 900 | boolean geni_compressed <optional>; |
| | 901 | struct geni_rspec_version { |
| | 902 | string type; |
| | 903 | string version; |
| | 904 | }; |
| | 905 | } |
| | 906 | }}} |
| | 907 | |
| | 908 | Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. The aggregate must honor all supplied options. |
| | 909 | |
| | 910 | `credentials` is the standard argument defined elsewhere. |
| | 911 | |
| | 912 | Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers. |
| | 913 | |
| | 914 | Return struct: |
| | 915 | {{{ |
| | 916 | { |
| | 917 | geni_rspec: <geni.rspec, Manifest - may be empty though)> |
| | 918 | geni_urn: <string slice urn, as requested> |
| | 919 | geni_slivers: [ |
| | 920 | { |
| | 921 | geni_sliver_urn: <string sliver urn> |
| | 922 | geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from SliversStatus>, |
| | 923 | geni_allocation_status: <string sliver state - allocated or ?? >, |
| | 924 | geni_operational_status: <string sliver operational state> |
| | 925 | }, |
| | 926 | ... |
| | 927 | ] |
| | 928 | } |
| | 929 | }}} |
| | 930 | |
| 994 | | === `sliver_urns[]` === |
| 995 | | Several methods exist in two variants. Variant one takes a slice URN. In this mode, it is interpreted to operate on all slivers contained in that slice at this aggregate. Variant two takes a list of sliver URNs. Typically, all such slivers belong to the same slice. Some aggregates may refuse calls to operate on slivers in more than one slice. All aggregates shall refuse to authorize calls which operate on more than one implicitly referenced slice but do not provide credentials that authorize operating on all such referenced slices. |
| | 1035 | === `urns[]` === |
| | 1036 | Several methods take some URNs to identify what to operate on. These methods are defined as accepting a list of arbitrary strings we call URNs. |
| | 1037 | This API defines two kinds of URNs that may be supplied here, slice URNs and sliver URNs (see [wiki:GeniApiIdentifiers the GENI identifiers page], and [#Adopted:ChangeSetK:Standardizecertificatesandcredentials Change Set K]). Some aggregates may understand other URNs, but these are not defined or required here. Aggregates that accept only URNs defined by this API will return an error when given URNs not in one of those forms. |
| | 1038 | This API requires that aggregates accept either a single slice URN, or 1+ sliver URNs that all belong to the same slice. Aggregates are not required to accept both a slice URN and sliver URNs, 2+ slice URNs, or a set of sliver URNs that crosses multiple slices. Some aggregates may choose to accept other such combinations of URNs. Aggregates that accept only arguments defined by this API will return an error when given more than 1 slice URN, a combination of both slice and sliver URNs, or a set of sliver URNs that belong to more than 1 slice. |
| 1124 | | This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical. |
| 1125 | | |
| 1126 | | Form 1: |
| 1127 | | {{{ |
| 1128 | | struct Renew(string slice_urn, |
| 1129 | | struct credentials[], |
| 1130 | | dateTime.rfc3339 expiration_time, |
| 1131 | | struct options) |
| 1132 | | }}} |
| 1133 | | |
| 1134 | | Form 2: |
| 1135 | | {{{ |
| 1136 | | struct Renew(string sliver_urns[], |
| | 1167 | {{{ |
| | 1168 | struct Renew(string urns[], |
| 1167 | | This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical. |
| 1168 | | |
| 1169 | | Form 1: |
| 1170 | | {{{ |
| 1171 | | struct UpdateAllocations(string slice_urn, struct credentials[], geni.rspec rspec, |
| 1172 | | struct options) |
| 1173 | | }}} |
| 1174 | | |
| 1175 | | Form 2: |
| 1176 | | {{{ |
| 1177 | | struct UpdateAllocations(string sliver_urns[], struct credentials[], geni.rspec rspec, |
| | 1199 | {{{ |
| | 1200 | struct UpdateAllocations(string urns[], struct credentials[], geni.rspec rspec, |
| 1211 | | This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical. |
| 1212 | | |
| 1213 | | Form 1: |
| 1214 | | {{{ |
| 1215 | | struct ProvisionSlivers(string slice_urn, struct credentials[], |
| 1216 | | struct options) |
| 1217 | | }}} |
| 1218 | | |
| 1219 | | Form 2: |
| 1220 | | {{{ |
| 1221 | | struct ProvisionSlivers(string sliver_urns[], struct credentials[], |
| | 1234 | {{{ |
| | 1235 | struct Provision(string urns[], struct credentials[], |
| 1257 | | This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical. |
| 1258 | | |
| 1259 | | Form 1: |
| 1260 | | {{{ |
| 1261 | | struct UpdateSlivers(string slice_urn, struct credentials[], geni.rspec rspec, |
| 1262 | | struct options) |
| 1263 | | }}} |
| 1264 | | |
| 1265 | | Form 2: |
| 1266 | | {{{ |
| 1267 | | struct UpdateSlivers(string sliver_urns[], struct credentials[], geni.rspec rspec, |
| | 1271 | {{{ |
| | 1272 | struct UpdateSlivers(string urns[], struct credentials[], geni.rspec rspec, |
| 1300 | | == !SliversStatus == |
| 1301 | | Retrieve status information about the named slivers. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec by !ListResources. |
| 1302 | | |
| 1303 | | This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical. |
| 1304 | | |
| 1305 | | Form 1: |
| 1306 | | {{{ |
| 1307 | | struct SliversStatus(string slice_urn, struct credentials[], struct options) |
| 1308 | | }}} |
| 1309 | | |
| 1310 | | Form 2: |
| 1311 | | {{{ |
| 1312 | | struct SliversStatus(string sliver_urns[], struct credentials[], struct options) |
| | 1305 | == Status == |
| | 1306 | AKA !SliverStatus |
| | 1307 | Retrieve status information about the named slivers. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec. |
| | 1308 | |
| | 1309 | |
| | 1310 | {{{ |
| | 1311 | struct Status(string urns[], struct credentials[], struct options) |
| 1341 | | This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical. |
| 1342 | | |
| 1343 | | Form 1: |
| 1344 | | {{{ |
| 1345 | | struct PerformOperationalAction (string slice_urn, struct credentials[], string action, |
| 1346 | | struct options={}) |
| 1347 | | }}} |
| 1348 | | |
| 1349 | | Form 2: |
| 1350 | | {{{ |
| 1351 | | struct PerformOperationalAction (string sliver_urns[], struct credentials[], string action, |
| | 1340 | {{{ |
| | 1341 | struct PerformOperationalAction (string urns[], struct credentials[], string action, |
| 1375 | | This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical. |
| 1376 | | |
| 1377 | | Form 1: |
| 1378 | | {{{ |
| 1379 | | struct DeleteSlivers(string slice_urn, struct credentials[], struct options) |
| 1380 | | }}} |
| 1381 | | |
| 1382 | | Form 2: |
| 1383 | | {{{ |
| 1384 | | struct DeleteSlivers(string sliver_urns[], struct credentials[], struct options) |
| | 1366 | {{{ |
| | 1367 | struct Delete(string urns, struct credentials[], struct options) |
