Changes between Version 13 and Version 14 of AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures
- Timestamp:
- 04/18/12 15:40:07 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures
v13 v14 99 99 }}} 100 100 101 102 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. 101 Note that all options may be omitted by the client, except `geni_rspec_version` which is required. 103 102 104 103 Return: 105 104 A `geni.rspec` advertisment RSpec. 105 106 Note that this is only part of what !ListResources did in earlier versions of this API. For the what-is-in-my-slice functionality, see `Describe()`. 106 107 107 108 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DiscoverResources DiscoverResources] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !GetResources operation (sec. 6.2.4). … … 128 129 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. 129 130 130 Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers.131 This method is part of what !ListResources used to do, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve Resolve]. 131 132 132 133 Return struct: … … 147 148 }}} 148 149 149 Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec. Note that a manifest returned here for only some of the slivers in a slice at this aggregate, may contain references to resources not described in this manifest (they are in other slivers). As a result, such manifests may not be directly usable as a subsequent request.150 Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers. Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec. Note that a manifest returned here for only some of the slivers in a slice at this aggregate, may contain references to resources not described in this manifest (they are in other slivers). As a result, such manifests may not be directly usable as a subsequent request. 150 151 151 152 == Allocate == … … 163 164 }}} 164 165 165 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#CreateSliver CreateSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !CreateSlice operation (sec. 6.2.1). 166 This is the first part of what !CreateSliver used to do. The next part is now done by Provision. 167 168 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetTicket GetTicket] operation. 166 169 167 170 * {{{slice_urn}}}: The URN of the slice to which the resources specified in {{{rspec}}} will be allocated. For details on GENI AM API URN identifiers, see the [wiki:GeniApiIdentifiers GENI wiki page]. … … 172 175 {{{ 173 176 { 174 [optional geni_end_time: <dateTime.rfc3339 >]177 [optional geni_end_time: <dateTime.rfc3339: requested expiration of all new slivers, may be ignored by aggregates>] 175 178 } 176 179 }}} … … 203 206 struct options) 204 207 }}} 208 209 This operation used to be called !RenewSliver. Use Renew(<slice_urn>) to get the equivalent functionality. 210 211 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RenewSlice RenewSlice] operation. 205 212 206 213 Options include {{{geni_best_effort}}}, specifying whether the client prefers all included slivers to be renewed or none, or wants a partial success if possible. … … 262 269 == Provision == 263 270 AKA !ProvisionSlivers() 264 Request that the named `geni_allocated` slivers be made `geni_provisioned`, instantiating or otherwise realizing the resources, such that they have a valid `geni_operational_status` and may possibly be made `geni_ready` for experimenter use. 271 Request that the named `geni_allocated` slivers be made `geni_provisioned`, instantiating or otherwise realizing the resources, such that they have a valid `geni_operational_status` and may possibly be made `geni_ready` for experimenter use. This operation is synchronous, but may start a longer process, such as creating and imaging a virtual machine. 265 272 266 273 {{{ … … 269 276 }}} 270 277 271 `credentials` is the standard argument defined above. 278 This operation is part of what !CreateSliver used to do. The first part of what !CreateSliver did is now in `Allocate()`. Note that resources are not necessarily ready for experimenter use after the work that this function initiates finally completes. Consult the `geni_operational_status`, and the advertised operational state machine. Consider calling `PerformOperationalAction`, e.g. with the command name `geni_start`. 279 280 The operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RedeemTicket RedeemTicket] method. 272 281 273 282 Options include: … … 291 300 }}} 292 301 293 FIXME: Is the returned manifest only for newly provisioned slivers? Or all slivers at this AM for this slice? 302 The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers. 294 303 295 304 == !UpdateSlivers == … … 337 346 == Status == 338 347 AKA !SliverStatus 339 Retrieve status information about the named slivers. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec. 340 348 349 Get the status of a sliver or slivers belonging to a single slice at the given aggregate. Status may include other dynamic reservation or instantiation information as required by the resource type and aggregate. This method is used to provide updates on the state of the resources after the completion of Provision, which began to asynchronously provision the resources. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec. 341 350 342 351 {{{ … … 344 353 }}} 345 354 346 `credentials` is the standard argument defined above. 347 348 Return: 355 This operation used to be called !SliverStatus in earlier versions of the AM API. `geni_slivers` has replaced `geni_resources` and `geni_sliver_urn` replaces `geni_urn`. `geni_status` is replaced with 2 fields, `geni_allocation_status` and `geni_operational_status`. 356 357 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#SliverStatus,WaitForStatus SliverStatus] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation. 358 359 Return `value` is a struct: 349 360 {{{ 350 361 { … … 368 379 369 380 == !PerformOperationalAction == 370 Perform the named operational action on the named slivers, possibly changing the `geni_operational_status` of the named slivers. 381 Perform the named operational action on the named slivers, possibly changing the `geni_operational_status` of the named slivers. E.G. 'start' a VM. For valid operations and expected states, consult the state diagram advertised in the Aggregate's Ad RSpec. 371 382 372 383 {{{ … … 375 386 }}} 376 387 377 `credentials` is the standard argument defined above.388 This operation is similar to ProtoGENI functions like `StartSliver`, `StopSliver`, `RestartSliver` in the [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 PG CMv2 API]. 378 389 379 390 Options include: {{{geni_best_effort}}} 380 391 381 Return list of structs:392 Return value is a list of structs: 382 393 {{{ 383 394 [ { … … 394 405 == Delete == 395 406 AKA !DeleteSliver 396 Delete the named slivers, making them `geni_unallocated`. Resources are de-provisioned. No further AM API operations may be performed on slivers that have been deleted.407 Delete the named slivers, making them `geni_unallocated`. Resources are stopped in necessary, and both de-provisioned and de-allocated. No further AM API operations may be performed on slivers that have been deleted. 397 408 398 409 {{{ … … 400 411 }}} 401 412 402 `credentials` is the standard argument defined above. 413 This operation used to be called !DeleteSliver in earlier versions of this API. To get the functionality of !DeleteSliver, call Delete with the slice URN. 414 415 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DeleteSliver DeleteSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !DeleteSlice operation (sec. 6.2.3). 403 416 404 417 Options include: {{{geni_best_effort}}} … … 417 430 418 431 == Shutdown == 419 Perform an emergency shutdown on the slice at this aggregate. Resources should be taken offline, such that experimenter access (on both the control and data plane) is cut off. No further actions on the slice should be possible at this aggregate, until an un-specified operator action restores the slice. 432 Perform an emergency shutdown on the slice at this aggregate. Resources should be taken offline, such that experimenter access (on both the control and data plane) is cut off. No further actions on the slice should be possible at this aggregate, until an un-specified operator action restores the slice. This operation is intended for operator use. The sliver is shut down but remains available for further forensics. 420 433 {{{ 421 434 struct Shutdown(string slice_urn, struct credentials[], struct options) 422 435 }}} 423 436 424 `credentials` is the standard argument defined above.425 426 Return: XML-RPC boolean 437 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Shutdown Shutdown] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation. 438 439 Return: XML-RPC boolean, indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics.