| | 13 | |
| | 14 | ----- |
| | 15 | == API Overview == |
| | 16 | 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. |
| | 17 | |
| | 18 | === API Protocols and Data Structures === |
| | 19 | |
| | 20 | GENI 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. |
| | 21 | |
| | 22 | 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 will require a credential (set) that authorizes the client whose certificate was used to authenticate to operate on the slice named by a {{{slice_urn}}} argument to the method or on the slice containing the slivers named by a {{{urns}}} argument. |
| | 23 | |
| | 24 | The primary data structure used within this API is a resource specification, known as an 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_V2_DETAILS#RSpecs the details page]. |
| | 25 | |
| | 26 | === Using the GENI AM API === |
| | 27 | |
| | 28 | 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. |
| | 29 | |
| | 30 | !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. |
| | 31 | |
| | 32 | 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, 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. 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 !CreateSliver call returns with a manifest RSpec, listing the resources as reserved and initially configured for the experimenter. |
| | 33 | |
| | 34 | The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling Status. Once the resources are ready for use, the experimenter will 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. |
| | 35 | |
| | 36 | Client work flow: |
| | 37 | 0. <Experimenter gets a [wiki:GeniApiCertificates GENI certificate] and slice [wiki:GeniApiCredentials credential]> |
| | 38 | 1. {{{GetVersion()}}}: learn RSpec formats supported at this aggregate |
| | 39 | 2. {{{ListResources(<user credential>, options)}}}: get Ad RSpec describing available resources |
| | 40 | 3. <Experimenter constructs a request RSpec> |
| | 41 | 4. {{{Allocate(<slice URN>, <slice credential>, <request RSpec>, {})}}}: |
| | 42 | * Aggregate reserves resources |
| | 43 | * Return is a manifest RSpec describing the reserved resources |
| | 44 | 5. {{{Provision(<slice URN or sliver URNs>, <slice credential>, <request RSpec>, <users struct>, {})}}}: |
| | 45 | * Aggregate instantiates resources |
| | 46 | 6. {{{Status(<slice URN or sliver URNs>, <slice credential>, <new time>, {})}}} to check that resources are provisioned |
| | 47 | 7. {{{PerformOperationalAction(<slice URN>, <slice credential>, geni_start, {})}}}: |
| | 48 | * Aggregate starts resources |
| | 49 | 8. {{{Status(<slice URN or sliver URNs>, <slice credential>, <new time>, {})}}} to check that resources have started |
| | 50 | 9. {{{Renew(<slice URN or sliver URNs>, <slice credential>, {})}}} to extend reservation |
| | 51 | 10. <Experimenter uses resources> |
| | 52 | 11. {{{Delete(<slice URN or sliver URNs>, <slice credential>, {})}}} when done |
| | 53 | |
| | 54 | === Changes from AM API v2 === |
| | 55 | '''FIXME: Highlight changes in usage, etc ''' |
| | 56 | |
| | 57 | ----- |
