Changes between Version 23 and Version 24 of GAPI_AM_API_V3/CommonConcepts


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

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3/CommonConcepts

    v23 v24  
    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.
    20 
    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. 
     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 advertisement 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
     21A 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''' (type is `GENI`). Aggregates are free to use an alternate format internally, but must accept and produce compliant RSpecs on demand. 
    2222
    2323More information on GENI RSpecs is available [http://www.protogeni.net/trac/protogeni/wiki/RSpec on the ProtoGENI wiki].
    2424
    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.
     25The Aggregate Manager (AM) 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
    2727If 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`).
    … …  
    3232
    3333=== `credentials` ===
    34 Many methods take an array of credentials. This is an array of credential type, version, and string value.
     34Many methods take an array of `credentials`. This is actually an array of structures specifying the credential type and version, as well as the actual string credential.
    3535{{{
    3636credentials = [
    … …  
    4747
    4848 - An AM must pick credentials out of the list that it understands and be robust to receiving credentials it does not understand.
    49  - Current slice and user credentials will be recognizable for following the schema defined in GeniApiCredentials.
    50  - AMs are required to continue to accept current-format credentials.
     49 - Aggregates can identify and use valid slice and user credentials by matching against the schema defined in GeniApiCredentials.
     50 - AMs are required to continue to accept current-format credentials as specified in GeniApiCredentials.
    5151  - In particular, a single standard slice credential remains sufficient for most authorization policies.
    52  - Other credential formats acceptable by some aggregates might include ABAC x509 Attribute certificates, eg.
     52 - Other credential formats acceptable by some aggregates might include [http://abac.deterlab.net/ ABAC] x509 Attribute certificates, eg.
    5353 - AMs may get other authorization material from other sources: EG a future Credential Store service.
    5454
    … …  
    6666}}}
    6767
    68 "sfa" slice credentials as defined pre-AM API version 3 will have type=`geni_sfa` and version=`2`. "sfa" slice credentials as of AM API version 3 will be type=`geni_sfa`, version=`3`.
    69 ABAC credentials as of AM API version 3 will be type=`geni_abac`, version=`1`.
     68"sfa" slice credentials as defined before AM API version 3 will have type=`geni_sfa` and version=`2`. "sfa" slice credentials as of AM API version 3 will be type=`geni_sfa`, version=`3`.
     69[http://abac.deterlab.net/ ABAC] credentials as of AM API version 3 will be type=`geni_abac`, version=`1`.
    7070
    7171For 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`:
    … …  
    9090
    9191=== `options` ===
    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.
     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 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 ===
    … …  
    9797One or more slivers are created by an aggregate when the experimenter tool calls `Allocate()`. This API encourages aggregates to independently manage each sliver, allowing experimenters to selectively `Delete`, `Renew`, or `Provision` each sliver. As such, these methods take a list of sliver urns (or a slice urn), and return a struct reporting results for each sliver URN independently. However, slivers at an aggregate may have interdependencies, and an individual aggregate may not be able to independently manage each sliver, without also modifying other related slivers. This API defines a number of aggregate configuration options returned by `GetVersion`, and an option to many methods, allowing aggregates to advertise their behavior, and experimenters to request particular behavior.
    9898
    99  1. `geni_single_allocation: <XML-RPC boolean 1/0, default 0>`: When true (not default), when performing one of (`Describe`, `Allocate`, `Renew`, `Provision`, `Delete`), such an AM requires you to include either the slice urn or the urn of all the slivers in the same state. If you attempt to run one of those operations on just some slivers in a given state, such an AM will return an error.
     99 1. `geni_single_allocation: <XML-RPC boolean 1/0, default 0>`: When true (not default), and performing one of (`Describe`, `Allocate`, `Renew`, `Provision`, `Delete`), such an AM requires you to include either the slice urn or the urn of all the slivers in the same state. If you attempt to run one of those operations on just some slivers in a given state, such an AM will return an error.
    100100For example, at an AM where `geni_single_allocation` is true you must `Provision` all `geni_allocated` slivers at once. If you supply a list of sliver URNs to `Provision` that is only 'some' of the `geni_allocated` slivers for this slice at this AM, then the AM will return an error. Similarly, such an aggregate would return an error from `Describe` if you request a set of sliver URNs that is only some of the `geni_provisioned` slivers.
    101101
    … …  
    109109   geni_best_effort: <XML-RPC boolean 1/0, default 0>
    110110}}}
    111 If false, the client is requesting that the aggregate either fully satisfy the request, moving all listed slivers to the desired state, or fully fail the request, leaving all slivers in their original state. If the aggregate cannot guarantee all or nothing success or failure given the included slivers and resource types, the aggregate shall fail the request, returning an appropriate error code. If this option is true, then some slivers may transition to the new state, and some not. Experimenters must examine the return closely to know the state of their slivers - such methods will return data about all requested slivers. Aggregates may optionally return `geni_error` for each sliver for which the operation failed, to indicate further details.  Note that `Allocate` is always all-or-nothing.
     111If false, the client is requesting that the aggregate either fully satisfy the request, moving all listed slivers to the desired state, or fully fail the request, leaving all slivers in their original state. If the aggregate cannot guarantee all or nothing success or failure given the included slivers and resource types, the aggregate shall fail the request, returning an appropriate error code (`UNSUPPORTED`). If this option is true, then some slivers may transition to the new state, and some not. Experimenters must examine the return closely to know the state of their slivers - such methods will return data about all requested slivers. Aggregates may optionally return `geni_error` for each sliver for which the operation failed, to indicate further details.  Note that `Allocate` is always all-or-nothing.
    112112
    113113It is expected that many aggregates will implement one of the following combinations of options:
    … …  
    116116
    117117=== `urns[]` ===
    118 Several methods take some URNs to identify what to operate on. These methods are defined as accepting a list of arbitrary strings we call URNs.
     118Several methods take some URNs to identify what to operate on. These methods are defined as accepting a list of arbitrary strings called URNs.
    119119This API defines two kinds of URNs that may be supplied here, slice URNs and sliver URNs (see [wiki:GeniApiIdentifiers the GENI identifiers page]). Some aggregates may understand other URNs, but these are not defined or required here. Aggregates that accept only URNs defined by this API will return an error when given URNs not in one of those forms.
    120 This API requires that aggregates accept either a single slice URN, or 1+ sliver URNs that all belong to the same slice. Aggregates are not required to accept both a slice URN and sliver URNs, 2+ slice URNs, or a set of sliver URNs that crosses multiple slices. Some aggregates may choose to accept other such combinations of URNs. Aggregates that accept only arguments defined by this API will return an error when given more than 1 slice URN, a combination of both slice and sliver URNs, or a set of sliver URNs that belong to more than 1 slice.
     120This API requires that aggregates accept either a single slice URN, or 1 or more sliver URNs that all belong to the same slice. Aggregates are not required to accept both a slice URN and sliver URNs, 2 or more slice URNs, or a set of sliver URNs that crosses multiple slices. Some aggregates may choose to accept other such combinations of URNs. Aggregates that accept only arguments defined by this API will return an error when given more than 1 slice URN, a combination of both slice and sliver URNs, or a set of sliver URNs that belong to more than 1 slice.
    121121
    122122=== Sliver Allocation States ===