Changes between Version 8 and Version 9 of GAPI_AM_API_V3
- Timestamp:
- 05/04/12 10:00:12 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
GAPI_AM_API_V3
v8 v9 71 71 Once the experimenter has selected the resources they want and how to configure them, they produce a request RSpec, detailing the resources they want and how they should be configured. They separately contact their slice authority to obtain a slice credential (or set of credentials), granting them rights to reserve resources for that slice. The experimenter then calls `Allocate` on this API, passing in both the slice credential and the request RSpec. The aggregate then attempts to satisfy the experimenter's resource request. If the aggregate can satisfy the request, the aggregate reserves the resources for the experimenter. The resources have not been provisioned yet, giving the experimenter a chance to verify the reservation, or check for corresponding resource availability in another aggregate. If it is acceptable, the experimenter calls `Provision` to set up the resources. The aggregate then starts the process of instantiating the resources and configuring them as requested in the request RSpec. Once that process has started, the `Provision` call returns with a manifest RSpec, listing the resources as reserved and initially configured for the experimenter. 72 72 73 The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling `Status`, looking for an operational state other than `geni_pending_allocation . A given aggregate and sliver type may use a different set of states once provisioning is complete, and further operational actions are possible - see the AM's Ad RSpec. In many cases, this indication comes with a `geni_operational_state` value of `geni_notready`. Once the resources are ready for use, the experimenter will typically call `!PerformOperationalAction(geni_start)` to start the resources (e.g. boot a machine). The experimenter will also call `Renew` to request that their reservation lasts as long as they require the resources for. When the experimenter is done using the resources, they call `Delete` to end their reservation. The aggregate then stops and clears the resources, freeing them for use by other clients.73 The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling `Status`, looking for an operational state other than `geni_pending_allocation`. A given aggregate and sliver type may use a different set of states once provisioning is complete, and further operational actions are possible - see the AM's Ad RSpec. In many cases, this indication comes with a `geni_operational_state` value of `geni_notready`. Once the resources are ready for use, the experimenter will typically call `!PerformOperationalAction(geni_start)` to start the resources (e.g. boot a machine). The experimenter will also call `Renew` to request that their reservation lasts as long as they require the resources for. When the experimenter is done using the resources, they call `Delete` to end their reservation. The aggregate then stops and clears the resources, freeing them for use by other clients. 74 74 75 75 Typical client work flow: … … 247 247 geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from SliversStatus>, 248 248 geni_allocation_status: <string sliver state - allocated or ?? >, 249 geni_operational_status: <string sliver operational state> 249 geni_operational_status: <string sliver operational state>, 250 geni_error: <optional string, may be omitted entirely, explaining any failure for a sliver> 250 251 }, 251 252 ... … … 262 263 Allocated slivers are held for an aggregate-determined period. Clients must `Renew` or `Provision` slivers before the expiration time (given in the return struct), or the aggregate will automatically `Delete` them. 263 264 Aggregates should implement `Allocate()` as quick, cheap, and not impacting provisioned resources, such that it can be readily undone. 265 `Allocate` is an all or nothing request: if the aggregate cannot completely satisfy the request RSpec, it should fail the request entirely. 264 266 265 267 This method is part of what was previously known as !CreateSliver. … … 323 325 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. See the Common Concepts page under [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`] and [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers Operations on Individual Slivers]. 324 326 327 When `Renew` is called with `geni_best_effort` false, the entire method will fail if any requested sliver cannot be renewed to the requested time, and all slivers will keep their original expiration time. When `Renew` is called with `geni_best_effort` true, some sliver may fail to be renewed. In this case, the allocation state and expiration times do not change. `geni_error` may optionally be returned by the aggregate to explain this failure. 328 325 329 Arguments: 326 330 {{{expiration_time}}}: The date-time string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format in UTC when the reservation(s) should be extended until. See [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype the Common Concepts page]. 327 331 328 See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns []`] and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials[]`] arguments.332 See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns`] and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials`] arguments. 329 333 330 334 Return value is a list of structs: … … 336 340 geni_operational_status: <string>, 337 341 geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>, 342 geni_error: <optional string, may be omitted entirely, explaining any renewal failure for this sliver> 338 343 }, 339 344 ... … … 341 346 }}} 342 347 343 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns []`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials[]`].348 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials`]. 344 349 345 350 {{{ … … 371 376 geni_sliver_urn: <string sliver urn> 372 377 geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from SliversStatus>, 373 geni_allocation_status: <string sliver state - allocated or ?? > 378 geni_allocation_status: <string sliver state - allocated or ?? >. 379 geni_error: <optional string, may be omitted entirely, explaining any update failure> 374 380 }, 375 381 ... … … 410 416 geni_operational_status: <string>, 411 417 geni_expires <dateTime.rfc3339 when the sliver expires from its current state>, 418 geni_error: <optional string, may be omitted entirely, explaining any failure to Provision this sliver> 412 419 }, 413 420 ... … … 415 422 }}} 416 423 417 The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers. 418 419 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns []`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials[]`], and [wiki:GAPI_AM_API_V3/CommonConcepts#geni_users `geni_users`].424 The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers. When `geni_best_effort` is true, all requested slivers are returned, but some slivers may have failed: `geni_allocation_status` may be `geni_failed` or `geni_unallocated` or remain `geni_allocated`. Check `geni_error` for details. 425 426 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials`], and [wiki:GAPI_AM_API_V3/CommonConcepts#geni_users `geni_users`]. 420 427 421 428 {{{ … … 498 505 Note that aggregates may return other information, such as details on sliver contents, etc. 499 506 500 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns []`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials[]`].507 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials`]. 501 508 502 509 == !PerformOperationalAction == … … 512 519 Aggregate Managers SHOULD return an error code of `13` (`UNSUPPORTED`) if they do not support a given action for a given resource. An AM SHOULD constrain actions based on the current operational state of the resource. This is a fast synchronous operation, and MAY start long-running sliver transitions whose status can be queried using `Status`. This method should only be called, and is only valid, when the sliver is fully allocated (allocation state is not `geni_pending_allocation`). 513 520 514 Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none .521 Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none). 515 522 516 523 Return value is a list of structs: … … 518 525 [ { 519 526 geni_sliver_urn : <string>, 520 geni_allocation_status: <string, eg provisioned> 527 geni_allocation_status: <string, eg provisioned>, 521 528 geni_operational_status : <string>, 522 geni_expires: <dateTime.rfc3339 of individual sliver expiration> 523 [optional: 'geni_resource_status' : string] 529 geni_expires: <dateTime.rfc3339 of individual sliver expiration>, 530 [optional: 'geni_resource_status' : string], 531 [optional: 'geni_error': string explanation of operation failure for this sliver] 524 532 }, 525 533 ... … … 528 536 }}} 529 537 530 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalActions operational methods], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns []`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials[]`].538 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalActions operational methods], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials`]. 531 539 532 540 == Delete == … … 550 558 geni_allocation_status: <string>, 551 559 geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>, 560 [optional: 'geni_error': string indicating any AM failure deleting the sliver.] 552 561 }, 553 562 ... … … 555 564 }}} 556 565 557 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns []`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials[]`].566 See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort `geni_best_effort`], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns`], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials`credentials`]. 558 567 559 568 == Shutdown == … … 570 579 Return: XML-RPC boolean, indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics. 571 580 572 See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials []` argument].581 See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials` argument].