Changes between Version 22 and Version 23 of GAPI_AM_API_V3/CommonConcepts
- Timestamp:
- 07/17/12 11:35:38 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
GAPI_AM_API_V3/CommonConcepts
v22 v23 17 17 18 18 === 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 !GetVersionreturn 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.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. 20 20 21 21 A 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. … … 25 25 The 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. 26 26 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 !ListResourcescall 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 Describecall which supplies a valid slice URN or list of sliver URNs and an `geni_rspec_version` option containing that supported `type`/`version`.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`. 30 30 31 31 In this API, such RSpec fields are labeled as type `geni.rspec`. … … 55 55 At 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]. 56 56 57 Aggregates must advertise the type(s) of credentials they support, using a new entry in !GetVersion:57 Aggregates must advertise the type(s) of credentials they support, using a new entry in `GetVersion`: 58 58 {{{ 59 59 geni_credential_types = <a list of structs>: [ … … 69 69 ABAC credentials as of AM API version 3 will be type=`geni_abac`, version=`1`. 70 70 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: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`: 72 72 73 73 {{{ … … 90 90 91 91 === `options` === 92 An XML-RPC struct. For !GetVersion only, this argument is optional. In all other methods, it is required. Only !ListResources hasrequired 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.92 An 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. 93 93 94 94 === Operations on Individual Slivers === … … 142 142 If the transition from one state to another fails, the sliver shall remain in its original state. 143 143 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 !CreateSliverdid 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`. 146 146 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 !RenewSliverfrom 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 !CreateSliverdid. 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. 149 149 150 150 When `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. … … 189 189 190 190 GENI 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. !PerformOperationalActionmay 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`. 192 192 - `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`. 193 193 - `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. … … 279 279 || 17 || ALREADYEXISTS || "Already Exists (eg the slice}" || 280 280 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 !CreateSlivercall might return a modified request RSpec in the {{{value}}} field.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 `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. 282 282 283 283 Note 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: … … 381 381 === Documenting Aggregate Additions === 382 382 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.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`. 384 384 385 385 ----- … … 390 390 When aggregates start supporting a new version of the API, they should keep running the old version of the API for a suitable transition period. 391 391 392 Aggregates running multiple versions of the API must advertise the URLs and versions of the API supported using the new !GetVersionreturn as part of the {{{value}}} entry: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: 393 393 {{{ 394 394 geni_api_versions: an XML-RPC struct containing 1+ entries of: