Changes between Version 22 and Version 23 of GAPI_AM_API_V3/CommonConcepts


Ignore:
Timestamp:
07/17/12 11:35:38 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3/CommonConcepts

    v22 v23  
    1717
    1818=== RSpec data type ===
    19 Throughout this API, multiple arguments and returns are labeled as an RSpec. These fields shall be understood as XML documents following one of the schemas advertised in the return from !GetVersion. All such RSpecs must pass an XML schema validator, must list all used schemas and namespaces within the document, using schemas that are publicly available. The !GetVersion return advertises schemas for advertisment and request RSpecs; the schemas for manifest RSpecs are assumed to be available at the same base URL, but using a corresponding manifest schema.
     19Throughout this API, multiple arguments and returns are labeled as an RSpec. These fields shall be understood as XML documents following one of the schemas advertised in the return from `GetVersion`. All such RSpecs must pass an XML schema validator, must list all used schemas and namespaces within the document, using schemas that are publicly available. The `GetVersion` return advertises schemas for advertisment and request RSpecs; the schemas for manifest RSpecs are assumed to be available at the same base URL, but using a corresponding manifest schema.
    2020
    2121A fully GENI AM API compliant aggregate will always support the GENI standard schemas for RSpecs, available at http://www.geni.net/resources/rspec. As of 4/2012, the current GENI RSpec version is '''3'''. Aggregates are free to use an alternate format internally, but must accept and produce compliant RSpecs on demand. 
    … …  
    2525The Aggregate Manager API requires this contract: Aggregates advertise the `type` and `version` of RSpec formats that they support. If available, they specify the `schema`, `namespace` and `extensions` combination which is the authoritative definition of that format. Clients of the API should understand that combination in order to know how to understand the resources available at that aggregate.
    2626
    27 If an aggregate advertises a particular `type`/`version` (optionally defined with a combination of `schema`, `namespace` and `extensions`) in the `geni_ad_rspec_versions` attribute of !GetVersion, then it promises to send a correct Advertisement RSpec in response to a !ListResources call which supplies a `geni_rspec_version` option containing that `type`/`version`. (`geni_rspec_version` is a struct with 2 members, `type` and `version`. `type` and `version` are case-insensitive strings, matching those in `geni_ad_rspec_versions`).
    28 
    29 If an Aggregate advertises a particular `type`/`version` (optionally defined with a combination of `schema`, `namespace` and `extensions`) in the `geni_request_rspec_versions` attribute of !GetVersion then it promises to correctly honor an Allocate (was !CreateSliver in API v2) call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (i.e. a GENI format request is answered with a GENI format manifest). The aggregate also promises to send a correctly formatted Manifest RSpec in response to a Describe call which supplies a valid slice URN or list of sliver URNs and an `geni_rspec_version` option containing that supported `type`/`version`.
     27If an aggregate advertises a particular `type`/`version` (optionally defined with a combination of `schema`, `namespace` and `extensions`) in the `geni_ad_rspec_versions` attribute of `GetVersion`, then it promises to send a correct Advertisement RSpec in response to a `ListResources` call which supplies a `geni_rspec_version` option containing that `type`/`version`. (`geni_rspec_version` is a struct with 2 members, `type` and `version`. `type` and `version` are case-insensitive strings, matching those in `geni_ad_rspec_versions`).
     28
     29If an Aggregate advertises a particular `type`/`version` (optionally defined with a combination of `schema`, `namespace` and `extensions`) in the `geni_request_rspec_versions` attribute of `GetVersion` then it promises to correctly honor an `Allocate` (was `CreateSliver` in API v2) call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (i.e. a GENI format request is answered with a GENI format manifest). The aggregate also promises to send a correctly formatted Manifest RSpec in response to a `Describe` call which supplies a valid slice URN or list of sliver URNs and an `geni_rspec_version` option containing that supported `type`/`version`.
    3030
    3131In this API, such RSpec fields are labeled as type `geni.rspec`.
    … …  
    5555At least one subset of the credentials (e.g. a single SFA style slice credential) must authorize operations for the slice specified in `slice_urn` if that is an argument, or for the slice that contains the named slivers, if sliver urns are an argument, or a valid set of administrative credentials with sufficient privileges. When sliver_urns are supplied, all such slivers must belong to the same slice, over which the given credential set provides access. Credentials must be valid (signed by a valid GENI certificate authority either directly or by chain, not expired, and grant privileges to the client identified by the SSL client certificate). Each method requires specific privileges, which must be granted by the provided credentials. Note that the semantics of this argument is not clear: most implementations require a single credential to provide all needed privileges. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. For details on GENI AM API format credentials, see [wiki:GeniApiCredentials the GENI wiki].
    5656
    57 Aggregates must advertise the type(s) of credentials they support, using a new entry in !GetVersion:
     57Aggregates must advertise the type(s) of credentials they support, using a new entry in `GetVersion`:
    5858{{{
    5959geni_credential_types = <a list of structs>: [
    … …  
    6969ABAC credentials as of AM API version 3 will be type=`geni_abac`, version=`1`.
    7070
    71 For example, an aggregate that accepts ABAC credentials, SFA slice credentials that were issued prior to AM API v3, and SFA slice credentials from AM API version 3, would include this in !GetVersion:
     71For example, an aggregate that accepts ABAC credentials, SFA slice credentials that were issued prior to AM API v3, and SFA slice credentials from AM API version 3, would include this in `GetVersion`:
    7272
    7373{{{
    … …  
    9090
    9191=== `options` ===
    92 An XML-RPC struct. For !GetVersion only, this argument is optional. In all other methods, it is required. Only !ListResources has required entries in the options struct. Aggregates are compliant with this API change by accepting this argument. Aggregates may accept entries to this struct. Aggregates should not require any new options to any method - they should always have a reasonable default for any such option. Aggregates should document new `options` arguments. The prefix `geni_` is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts.
     92An XML-RPC struct. For `GetVersion` only, this argument is optional. In all other methods, it is required. Only `ListResources` and `Describe` have required entries in the options struct. Aggregates are compliant with this API change by accepting this argument. Aggregates may accept entries to this struct. Aggregates should not require any new options to any method - they should always have a reasonable default for any such option. Aggregates should document new `options` arguments. The prefix `geni_` is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts.
    9393
    9494=== Operations on Individual Slivers ===
    … …  
    142142If the transition from one state to another fails, the sliver shall remain in its original state.
    143143
    144  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.
    145  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.
     144 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.
     145 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`.
    146146 3. `Renew`, when given allocated slivers, requests an extended timeout for slivers in state 2 (`geni_allocated`).
    147  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.
    148  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.
     147 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.
     148 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.
    149149
    150150When `Provision` fails for only some slivers, and `geni_best_effort` option was supplied, the aggregate will return the status of each requested sliver individually. The `geni_allocation_state` for slivers that failed will remain `geni_allocated`. This typically suggests that the experimenter may retry the call. For some aggregates or resource types, the sliver may be 'dead', and `Provision` may never succeed. Experimenters should check `geni_error` for more information.
    … …  
    189189
    190190GENI defined operational states:
    191  - `geni_pending_allocation`: A wait state. The sliver is still being allocated and provisioned, and other operational states are not yet valid. !PerformOperationalAction may not yet be called on this sliver.  For example, the sliver is in allocation state `geni_provisioned`, but has not been fully provisioned (e.g., the VM has not been fully imaged). Once the sliver has been fully allocated, the AM will transition the sliver to some other valid operational state, as specified by the advertised operational state machine. This state is generally not part of the AM's advertised state machine, as it represents 'operational states not valid yet'. Common next states (and first states of operational state machines) are `geni_notready`, `geni_ready`, and `geni_failed`.
     191 - `geni_pending_allocation`: A wait state. The sliver is still being allocated and provisioned, and other operational states are not yet valid. `PerformOperationalAction` may not yet be called on this sliver.  For example, the sliver is in allocation state `geni_provisioned`, but has not been fully provisioned (e.g., the VM has not been fully imaged). Once the sliver has been fully allocated, the AM will transition the sliver to some other valid operational state, as specified by the advertised operational state machine. This state is generally not part of the AM's advertised state machine, as it represents 'operational states not valid yet'. Common next states (and first states of operational state machines) are `geni_notready`, `geni_ready`, and `geni_failed`.
    192192 - `geni_notready`: A final state. The resource is not usable / accessible by the experimenter, and requires explicit experimenter action before it is usable/accessible by the experimenter. For some resources, `geni_start` will move the resource out of this state and towards `geni_ready`.
    193193 - `geni_configuring`: A wait state. The resource is in process of changing to `geni_ready`, and on success will do so without additional experimenter action. For example, the resource may be powering on.
    … …  
    279279|| 17   || ALREADYEXISTS        || "Already Exists (eg the slice}" ||
    280280
    281 Aggregates are similarly encouraged to provide hints on how to fix bad requests using the {{{value}}} entry to experimenters on error or failures. For example, a failed !RenewSliver call that failed because you are not allowed to renew your sliver that far in the future, might return a new date string in the {{{value}}} field that would be allowed. Similarly, a failed !CreateSliver call might return a modified request RSpec in the {{{value}}} field.
     281Aggregates are similarly encouraged to provide hints on how to fix bad requests using the {{{value}}} entry to experimenters on error or failures. For example, a failed `Renew` call that failed because you are not allowed to renew your sliver that far in the future, might return a new date string in the {{{value}}} field that would be allowed. Similarly, a failed `Allocate` call might return a modified request RSpec in the {{{value}}} field.
    282282
    283283Note that a malformed XML-RPC request should still raise an XML-RPC Fault, and other Faults dictated by the XML-RPC specification should still be raised.  Aggregates should avoid raising an error (XML-RPC Fault) for application layer errors or any other cases where the XML-RPC specification does not require a Fault, but rather should attempt to return this struct, providing any error messages and stack traces in the {{{output}}} field or other additional fields.  Certain XML-RPC errors may be returned using Faults or otherwise by the XML-RPC layer, or may more properly be returned using this struct in the application layer. In such cases, servers should use error codes with negative values. Selected such errors are listed below:
    … …  
    381381=== Documenting Aggregate Additions ===
    382382
    383 Aggregates are free to add additional return values or input {{{options}}} to support aggregate or resource specific functionality, or to innovate within the bounds of the AM API. This includes adding new methods that use the same transport, interface, certificates, and credentials. Aggregates are encouraged to document any such new return values which they return or {{{options}}} arguments, to bootstrap coordination with clients, and provide documentation for human experimenters. One way to provide partial documentation, is to implement [http://xmlrpc-c.sourceforge.net/introspection.html XML-RPC introspection]. Through the use of method help, aggregates can provide human readable text describing return values. Alternatively or additionally, aggregates may document return values as part of their return from !GetVersion. This API does not specify the format for advertising those extra return values in !GetVersion.
     383Aggregates are free to add additional return values or input {{{options}}} to support aggregate or resource specific functionality, or to innovate within the bounds of the AM API. This includes adding new methods that use the same transport, interface, certificates, and credentials. Aggregates are encouraged to document any such new return values which they return or {{{options}}} arguments, to bootstrap coordination with clients, and provide documentation for human experimenters. One way to provide partial documentation, is to implement [http://xmlrpc-c.sourceforge.net/introspection.html XML-RPC introspection]. Through the use of method help, aggregates can provide human readable text describing return values. Alternatively or additionally, aggregates may document return values as part of their return from `GetVersion`. This API does not specify the format for advertising those extra return values in `GetVersion`.
    384384
    385385-----
    … …  
    390390When aggregates start supporting a new version of the API, they should keep running the old version of the API for a suitable transition period.
    391391
    392 Aggregates running multiple versions of the API must advertise the URLs and versions of the API supported using the new !GetVersion return as part of the {{{value}}} entry:
     392Aggregates running multiple versions of the API must advertise the URLs and versions of the API supported using the new `GetVersion` return as part of the {{{value}}} entry:
    393393{{{
    394394geni_api_versions: an XML-RPC struct containing 1+ entries of: