Changes between Version 14 and Version 15 of AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures

04/18/12 15:50:29 (8 years ago)
Aaron Helsinger



  • AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures

    v14 v15  
    33= GENI Aggregate Manager API Draft Revisions Method Signatures Summary =
    5 This page documents the DRAFT GENI Aggregate Manager API full method signatures, if all proposed revisions are adopted. This includes proposals that have already been adopted, and others still under discussion.
     5This page documents the DRAFT GENI Aggregate Manager API, if all proposed revisions are adopted. This includes proposals that have already been adopted, and others still under discussion.
    77The current officially adopted version of the API is '''2''' and is documented on [wiki:GAPI_AM_API the main API page].
    99The current adopted or proposed changes for the AM API, whose impacts are reflected here, are documented on [wiki:AaronHelsinger/GAPI_AM_API_DRAFT the AM API Draft wiki page].
    11 For a summary of the Aggregate Manager API, typical workflow, common concepts, arguments, and returns, see [wiki:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/CommonConcepts this sub page].
    13 If the generally agreed-upon change sets listed here are adopted, the final method signatures will be as follows:
     11For a summary of the Aggregate Manager API common concepts, arguments, and returns, see [wiki:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/CommonConcepts this sub page].
     13== API Overview ==
     14The 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.
     16=== API Protocols and Data Structures ===
     18GENI specifies that the AM API is provided via [ 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.
     20Clients 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 {{{urn}}} argument to the method or on the slice containing the slivers named by a {{{urns}}} argument.
     22The primary data structure used within this API is a resource specification, known as an [wiki:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/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:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/CommonConcepts#RSpecdatatype the RSpecs section on the detail page].
     24=== Using the GENI AM API ===
     26Clients (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.
     28`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.
     30Once 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 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 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. 
     32The experimenter 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. A given aggregate and sliver type may use a different set of states once provisioning is complete, and further operational actions are possible - see the AM's Ad RSpec. In many cases, this indication comes with a `geni_operational_state` value of `geni_notready`.  Once the resources are ready for use, the experimenter will typically 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.
     34Typical client work flow:
     35 0. <Experimenter gets a [wiki:GeniApiCertificates GENI certificate] and slice [wiki:GeniApiCredentials credential]>
     36 1. {{{GetVersion()}}}: learn RSpec formats supported at this aggregate
     37 2. {{{ListResources(<user credential>, options)}}}: get Ad RSpec describing available resources
     38 3. <Experimenter constructs a request RSpec>
     39 4. {{{Allocate(<slice URN>, <slice credential>, <request RSpec>, {})}}}:
     40  * Aggregate reserves resources
     41  * Return is a manifest RSpec describing the reserved resources
     42  * Optionally {{{Delete}}} some slivers, if you made a mistake, or don't like what the aggregate picked for you.
     43 5. {{{Provision(<slice URN or sliver URNs>, <slice credential>, <request RSpec>, <users struct>, {})}}}:
     44  * Aggregate instantiates resources
     45  * Return is a manifest RSpec describing the reserved resources, plus any instantiation-specific configuration information
     46 6. {{{Status(<slice URN or sliver URNs>, <slice credential>, {})}}} to check that resources are provisioned (e.g. look for operational state `geni_notready`.
     47 7. {{{PerformOperationalAction(<slice URN>, <slice credential>, geni_start, {})}}}:
     48  * Aggregate starts resources
     49 8. {{{Status(<slice URN or sliver URNs>, <slice credential>, {})}}} to check that resources have started
     50 9. {{{Renew(<slice URN or sliver URNs>, <slice credential>, newtime, {})}}} to extend reservation
     51 10. <Experimenter uses resources>
     52 11. {{{Delete(<slice URN or sliver URNs>, <slice credential>, {})}}} when done
     54=== Changes from AM API v2 ===
     55This version of the AM API includes multiple changes since version 2 of the AM API. For experimenters, a few things are worth noting:
     56 - The old `CreateSliver` operation has now been broken into 3 steps:
     57  - `Allocate` to reserve the resources
     58  - `Provision` to instantiate the resources, which may take time to complete
     59  - `PerformOperationalAction(geni_start)` to start (e.g. boot) the resources, which also may take time to complete
     60 - Use the new intermediate `geni_allocated` state after `Allocate` to coordinate reservations across aggregates, e.g. to ensure another aggregate can give you nodes to be the other end of a requested link.
     61 - Multiple methods have been renamed, typically by removing the `Sliver` term from method names.
     62 - Sliver expiration is available in the return from multiple other methods, like `Provision`
     63 - You no longer use `ListResources` to see the contents of your slice - use `Describe` instead. `ListResources` is only for the AM's Ad RSpec.
     64 - Experimenters can select when to start or stop resources, e.g. when to boot a VM. Consult the operational state machine in the AM's Ad RSpec, and use `PerformOperationalAction`.
     65 - SSH login names and keys should be available in manifest RSpecs in a standard format.
     66 - Slice name restrictions have been codified and standardized.
     67   - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): `'^[a-zA-Z0-9][-a-zA-Z0-9]+$'`
     69Tool developers should also be aware:
     70 - The `credentials` argument to methods is now a struct, including a type and version for each credential. AMs should advertise which credential types they accept. SAs should advertise which type they provide.
     71 - Aggregates may have their own operational states and actions. The Ad RSpec should define these, probably by `sliver_type`.
    1574 == !GetVersion ==
    1675Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.