Changes between Version 19 and Version 20 of GAPI_AM_API_V3


Ignore:
Timestamp:
05/16/12 12:50:07 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3

    v19 v20  
    2525 * Latest: 3 - Documented here. [wiki:GAPI_AM_API_V3_DELTAS Changes since version 2] include:
    2626  * All new method names
    27   * Change Set D: Addressable slivers: the ability to add or delete resources from an existing slice reservation at a single aggregate
    28   * Change Set F3: New sliver allocation states & methods.
     27  * Addressable slivers: the ability to add or delete resources from an existing slice reservation at a single aggregate
     28  * New sliver allocation states & methods.
    2929    * Including a cheap 'allocated' state, that tools can use to negotiate resource reservations, and coordinate resource reservations among multiple aggregates (necessary for VLAN stitching)
    30    * Change Sets F4&5: Operational states, and a way for aggregates to advertise resource specific operational states and methods in the Ad RSpec.
    31    * Change Set G: Generalized credential argument, allowing aggregates to accept and tools to supply credentials of alternate types
    32    * Change Set I: Return sliver expiration in most method returns
    33    * Change Set I: Specify SSH node login information in a standard RSpec extension
    34    * Change Set K: Standardize certificate contents, specifically including a UUID and email address with particular semantics
    35    * Change Set K: Standardize slice and user name character and length restrictions
    36    * Change Set M: Split !ListResources in two: !ListResources for Ad RSpecs, and Describe for a slice' manifest RSpec
     30   * Operational states, and a way for aggregates to advertise resource specific operational states and methods in the Ad RSpec.
     31   * Generalized credential argument, allowing aggregates to accept and tools to supply credentials of alternate types
     32   * Return sliver expiration in most method returns
     33   * Specify SSH node login information in a standard RSpec extension
     34   * Standardize certificate contents, specifically including a UUID and email address with particular semantics
     35   * Standardize slice and user name character and length restrictions
     36   * Split !ListResources in two: !ListResources for Ad RSpecs, and Describe for a slice' manifest RSpec
    3737
    3838 * Previous: 2 - Documented on [wiki:GAPI_AM_API_V2 the v2 page]. Changes since v1 include:
    … …  
    5252
    5353== API Overview ==
    54 The GENI Aggregate Manager API is the control plane interface by which experimenters discover, reserve and control resources at resource providers. It does not include resource specific interactions, application level interactions, or monitoring and management functions.
     54The GENI Aggregate Manager API is the control plane interface by which experimenter tools discover, reserve and control resources at resource providers. It does not include resource specific interactions, application level interactions, or monitoring and management functions.
    5555
    5656=== API Protocols and Data Structures ===
    … …  
    6464=== Using the GENI AM API ===
    6565
    66 Clients (experimenters) use the AM API to discover resources (`ListResources`), request resources (`Allocate`), provision reserved resources (`Provision`), start resources (`PerformOperationalAction`), check the status of resources as they are started (`Status`), extend their reservation (`Renew`), and then return the resources when done (`Delete`). Client tools may use `GetVersion` to ensure aggregates speak a compatible version of the AM API and known formats for RSpecs. Administrators may call `Shutdown` to stop the resources of a slice at this aggregate, perhaps if that slice is misbehaving.
     66Clients (experimenters via their tools) use the AM API to discover resources (`ListResources`), request resources (`Allocate`), provision reserved resources (`Provision`), start resources (`PerformOperationalAction`), check the status of resources as they are started (`Status`), extend their reservation (`Renew`), and then return the resources when done (`Delete`). Client tools may use `GetVersion` to ensure aggregates speak a compatible version of the AM API and known formats for RSpecs. Administrators may call `Shutdown` to stop the resources of a slice at this aggregate, perhaps if that slice is misbehaving.
    6767
    6868`ListResources` returns to the client an advertisement RSpec - a detailed listing of the resources available at that aggregate. From this information, the experimenter may determine which resources to reserve for their use. The RSpec should also have enough information to help the experimenter set the initial configuration for their resources.
    6969
    70 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. 
    71 
    72 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.
     70Once 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 uses their tool and 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 (via their tool) 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. 
     71
     72The experimenter tool 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`. The actual operational state that the sliver will change to depends on the sliver and aggregate type.
     73Operational states are sliver type and aggregate specific, and defined in the aggregate's advertisement RSpec. In many cases, the aggregate indicates that the sliver is ready with a `geni_operational_state` value of `geni_notready`.  Once the resources are ready for use, the experimenter tool will typically call `PerformOperationalAction(geni_start)` to start the resources (e.g. boot a machine). The experimenter (or their tool) 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.
    7374
    7475Typical client work flow:
    … …  
    8586  * Return is a manifest RSpec describing the reserved resources, plus any instantiation-specific configuration information
    8687 6. {{{Status(<slice URN or sliver URNs>, <slice credential>, {})}}} to check that resources are provisioned (e.g. look for operational state `geni_notready`.
    87  7. {{{PerformOperationalAction(<slice URN>, <slice credential>, geni_start, {})}}}:
     88 7. {{{PerformOperationalAction(<slice URN>, <slice credential>, "geni_start", {})}}}:
    8889  * Aggregate starts resources
    8990 8. {{{Status(<slice URN or sliver URNs>, <slice credential>, {})}}} to check that resources have started
    90  9. {{{Renew(<slice URN or sliver URNs>, <slice credential>, newtime, {})}}} to extend reservation
     91 9. {{{Renew(<slice URN or sliver URNs>, <slice credential>, <newtime>, {})}}} to extend reservation
    9192 10. <Experimenter uses resources>
    9293 11. {{{Delete(<slice URN or sliver URNs>, <slice credential>, {})}}} when done
    9394
    9495=== Changes from AM API v2 ===
    95 This version of the AM API includes multiple changes since version 2 of the AM API. For experimenters, a few things are worth noting:
     96This version of the AM API includes substantial changes since version 2 of the AM API. For experimenters, a few things are worth noting:
    9697 - The old `CreateSliver` operation has now been broken into 3 steps:
    9798  - `Allocate` to reserve the resources
    … …  
    105106 - SSH login names and keys should be available in manifest RSpecs in a standard format.
    106107 - Slice name restrictions have been codified and standardized.
    107    - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): `'^[a-zA-Z0-9][-a-zA-Z0-9]+$'`
     108   - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): `'^[a-zA-Z0-9][-a-zA-Z0-9]\{0,18\}$'`
    108109
    109110Tool developers should also be aware:
    110111 - The `credentials` argument to methods is now a struct, including a type and version for each credential. AMs should advertise which credential types they accept. SAs should advertise which type they provide.
    111  - Aggregates may have their own operational states and actions. The Ad RSpec should define these, probably by `sliver_type`.
     112 - Aggregates may have their own operational states and actions. The advertisement RSpec should define these, probably by `sliver_type`.
    112113
    113114-----
    114115 == !GetVersion ==
    115116Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.
    116 
    117 The !GetVersion operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetVersion GetVersion] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
    118117
    119118{{{
    … …  
    201200Note that all options may be omitted by the client, except `geni_rspec_version` which is required.
    202201
    203 Return:
     202Return: On success, the value field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain:
    204203A `geni.rspec` advertisment RSpec. For details on RSpecs, see [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecs the Common Concepts page].
    205204
    … …  
    236235This method is part of what !ListResources used to do, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve Resolve].
    237236
    238 Return struct:
     237Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain at struct:
    239238{{{
    240239{
    … …  
    268267`Allocate` is an all or nothing request: if the aggregate cannot completely satisfy the request RSpec, it should fail the request entirely.
    269268
    270 This method is part of what was previously known as !CreateSliver.
     269This method is the first part of what was previously known as !CreateSliver.
    271270
    272271{{{
    … …  
    277276}}}
    278277
    279 This is the first part of what !CreateSliver used to do. The next part is now done by `Provision`.
     278This is the first part of what !CreateSliver used to do. The second part is now done by `Provision`, and the final part is done by `PerformOperationalAction`.
    280279
    281280This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetTicket GetTicket] operation.
    282281
    283 Return struct:
     282Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
    284283{{{
    285284{
    … …  
    324323This operation used to be called !RenewSliver. Use `Renew(<slice_urn>)` to get the equivalent functionality.
    325324
    326 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RenewSlice RenewSlice] operation.
    327 
    328325Options 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].
    329326
    330 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.
     327When `Renew` is called with `geni_best_effort` false, the entire method will fail (return non-zero code) 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.
    331328
    332329Arguments:
    … …  
    335332See 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.
    336333
    337 Return value is a list of structs:
     334Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a list of structs:
    338335{{{
    339336[
    … …  
    349346}}}
    350347
    351 Attempting to Renew an unknown sliver will result in an error. Attempting to Renew a previously deleted or expired sliver may result in an error - the aggregate may have forgotten about it entirely. Attempting to Renew a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted.
     348Attempting to `Renew` an unknown sliver will result in an error (non zero `geni_code`). Attempting to `Renew` a previously deleted or expired sliver may result in an error - the aggregate may have forgotten about it entirely. Attempting to `Renew` a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted.
    352349
    353350It is legal to attempt to renew a sliver to a sooner expiration time than the sliver was previously due to expire. Not all aggregates will support this however.
    … …  
    375372 - {{{geni_best_effort}}}
    376373
    377 Return struct:
     374Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
    378375{{{
    379376{
    … …  
    413410 - `struct geni_users[]`: Resource login information. See [wiki:GAPI_AM_API_V3/CommonConcepts#geni_users the Common Concepts page].
    414411
    415 Return struct:
     412Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
    416413{{{
    417414  geni_rspec: <geni.rspec, RSpec manifest>,
    … …  
    460457 - `struct geni_users[]`: Resource login information. See [wiki:GAPI_AM_API_V3/CommonConcepts#geni_users the Common Concepts page].
    461458
    462 Return struct:
     459Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
    463460{{{
    464461{
    … …  
    491488This 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`.
    492489
    493 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.
    494 
    495490This method has no required options.
    496491
    497 Return `value` is a struct:
     492Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
    498493{{{
    499494{
    … …  
    532527This operation is similar to ProtoGENI functions like `StartSliver`, `StopSliver`, and `RestartSliver` in the [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 PG CMv2 API].
    533528
    534 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`).
     529Aggregate 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`).
     530
     531While the `action` argument may be aggregate and sliver type specific (none are required for all aggregates and sliver types), this API does define three common actions that AMs should support if possible: `geni_start`, `geni_stop`, and `geni_restart`. Calling `PerformOperationalAction` with the action`geni_start` corresponds to the final part of what !CreateSliver did in AM API v2. For more information, see the Common Concepts page section on  wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalActions operational actions].
    535532
    536533Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none).
    537534
    538 Return value is a list of structs:
     535Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a list of structs:
    539536{{{
    540537[ {
    … …  
    566563Options include: {{{geni_best_effort}}}
    567564
    568 Return `value` is a list of structs:
     565Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a list of structs:
    569566{{{
    570567[
    … …  
    596593No options are required.
    597594
    598 Return: XML-RPC boolean, indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics. Return should be true, or else an error should be returned.
     595Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain: XML-RPC boolean, indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics. Return should be true, or else an error should be returned.
    599596
    600597If the given slice has no resources locally, or was previously `Shutdown`, return shall be true, indicating the slice is shut down.