Changes between Version 23 and Version 24 of GAPI_AM_API_V3


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

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3

    v23 v24  
    5555
    5656== API Overview ==
    57 The 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.
     57The GENI Aggregate Manager API is the control plane interface by which experimenter tools discover and reserve resources at resource providers. It does not include resource specific interactions, application level interactions, or monitoring and management functions.
    5858
    5959=== API Protocols and Data Structures ===
    … …  
    6161GENI specifies that the AM API is provided via [http://www.xmlrpc.com/spec XML-RPC] over an SSL connection. Aggregate Managers shall require client side [wiki:GeniApiCertificates GENI certificates] to authenticate users, accepting only certificates that comply with the adopted [wiki:GeniApiCertificates GENI certificates] standards. The GENI AM API therefore assumes that users have already been authenticated, and that the aggregate manager has available the client certificate to identify the user.
    6262
    63 Clients are authorized to take actions at aggregates using [wiki:GeniApiCredentials GENI credentials]. To that end, all methods that require authorization take an argument {{{credentials}}}. In particular, operations on a single GENI slice require a credential (set) that authorizes the client whose certificate was used to authenticate to operate on the slice named by a {{{urn}}} argument to the method or on the slice containing the slivers named by a {{{urns}}} argument.
     63Clients are authorized to take actions at aggregates using [wiki:GeniApiCredentials GENI credentials]. To that end, all methods that require authorization take an argument {{{credentials}}}. In particular, operations on a single GENI slice require a set of credentials that authorize the client whose certificate was used to authenticate to operate on the slice named by a {{{urn}}} argument to the method or on the slice containing the slivers named by a {{{urns}}} argument.
    6464
    6565The primary data structure used within this API is a resource specification, known as an [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype RSpec]. These XML documents follow a specific set of schemas. They are used by aggregates to list and describe local resources (advertisement RSpecs), by experimenters to describe desired resources (request RSpecs), and then by aggregates to describe reserved resources (manifest RSpecs). For more information on RSpecs, see [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype the RSpecs section on the detail page].
    … …  
    7171`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.
    7272
    73 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 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. 
     73Once 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 at 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. 
    7474
    7575The 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.
    76 Operational 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.
     76Operational 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 fully allocated 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.
    7777
    7878Typical client work flow:
    79  0. <Experimenter gets a [wiki:GeniApiCertificates GENI certificate] and slice [wiki:GeniApiCredentials credential]>
     79 0. <Experimenter gets a [wiki:GeniApiCertificates GENI certificate] and slice [wiki:GeniApiCredentials credential], renewing that slice as needed>
    8080 1. {{{GetVersion()}}}: learn RSpec formats supported at this aggregate
    8181 2. {{{ListResources(<user credential>, options)}}}: get Ad RSpec describing available resources
    … …  
    110110 - Slice name restrictions have been codified and standardized.
    111111   - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): `'^[a-zA-Z0-9][-a-zA-Z0-9]\{0,18\}$'`
     112   - Slice UUIDs are required, along with the slice URN, to fully identify slices
    112113
    113114Tool developers should also be aware:
    … …  
    116117
    117118-----
     119''Method Signatures''
     120Signatures for the aggregate manager API follow. Examples, return codes, and other details are on the [wiki:GAPI_AM_API_V3_DETAILS Details page]. Most data types and the state machines are explained on the [wiki:GAPI_AM_API_V3/CommonConcepts Common Concepts page].
     121
    118122 == `GetVersion` ==
    119123Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.
    … …  
    123127}}}
    124128
    125 The `options` argument may be omitted entirely by clients.
     129The `options` argument may be omitted entirely by clients.
     130Note that this method should be understandable by clients expecting any version of this API.
    126131
    127132The result is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members:
    … …  
    138143        int geni_api;
    139144        struct geni_api_versions {
    140              URL <this API version #>; # value is a URL, name is a number
     145             URL <this API version #>; # value is a URL, name (key) is a number
    141146             [optional: other supported API versions and the URLs where they run]
    142147        }
    … …  
    170175As with all AM API methods, the return is an XML-RPC struct. For `GetVersion`, it includes:
    171176 * The standard AM API {{{code}}}, {{{value}}}, and {{{output}}} entries. For details, see [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct the Common Concepts page]
    172  * {{{geni_api}}}: integer version of this API ('''3'''). Repeated here for backwards compatibility.
     177 * {{{geni_api}}}: integer version of this API ('''3'''). Repeated here for backwards compatibility for older clients.
    173178
    174179`GetVersion` {{{value}}} required return members:
    … …  
    183188
    184189 == `ListResources` ==
    185 Return a listing and description of available resources at this aggregate. The resource listing and description provides sufficient information for clients to select among available resources. These listings are known as RSpecs.
     190Return a listing and description of available resources at this aggregate. The resource listing and description provides sufficient information for clients to select among available resources. These listings are known as advertisement RSpecs.
    186191
    187192{{{
    … …  
    208213Note that this is only part of what `ListResources` did in earlier versions of this API. For the what-is-in-my-slice functionality, see `Describe()`.
    209214
    210 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DiscoverResources DiscoverResources] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !GetResources operation (sec. 6.2.4).
     215This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DiscoverResources `DiscoverResources`] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s `GetResources` operation (sec. 6.2.4).
    211216
    212217For details on the options (which are required), see [wiki:GAPI_AM_API_V3_DETAILS#ListResourcesDetails the Details page].
    213218
    214219 == `Describe` ==
    215 Retrieve a manifest RSpec describing the resources contained by the entities named, e.g. a single slice or a set of the slivers in a slice. This listing and description should be sufficient to allow experimenters to use the resources.
     220Retrieve a manifest RSpec describing the resources contained by the named entities, e.g. a single slice or a set of the slivers in a slice. This listing and description should be sufficient to allow experimenters to use the resources.
    216221
    217222{{{