[[PageOutline]] = GENI Aggregate Manager API Version 3 Details = The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers. This page provides details on GENI AM API Version '''3'''. For an overview of this version of the AM API, see the [wiki:GAPI_AM_API_V3 API Version 3 overview page]. See Also: * [wiki:GAPI_AM_API_V3 API Version 3 overview page] * [wiki:GAPI_AM_API_V3/CommonConcepts API Version 3 common concepts, arguments, and returns page] * [wiki:GeniApi GENI API] implementation status * [wiki:GeniApiCredentials GENI credentials] for authorization * [wiki:GeniApiCertificates GENI certificates] for authentication. The GENI AM API uses XML-RPC over SSL with client authentication using certificates. * [wiki:GAPI_AM_API_ISSUES Open issues with this API] * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for future versions of this API ''' This page is a work in progress! ''' == !GetVersion Details == !GetVersion is intended to provide information about the configuration of this aggregate, helping experimenter tools determine how to communicate with this aggregate. Sample output: {{{ { geni_api = 3 # This is AM API v3 code = { geni_code = 0 # Success # am_type and am_code are optional. Leaving them out. } value = { geni_api = 3 # Match above geni_api_versions = { 3 = 2 = } geni_request_rspec_versions = [{ type = "GENI" version = "3" schema = "http://www.geni.net/resources/rspec/3/request.xsd" namespace = "http://www.geni.net/resources/rspec/3" extensions = ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd", ] }] geni_ad_rspec_versions = [{ type = "GENI" version = "3" schema = "http://www.geni.net/resources/rspec/3/ad.xsd" namespace = "http://www.geni.net/resources/rspec/3" extensions = ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd", ] }] geni_credential_types = [{ # Accept only SFA style credentials for API v3 geni_type = "geni_sfa" geni_version = "3" }] geni_single_allocation = 0 # false - can operate on individual slivers geni_allocate = "geni_many" # Can do multiple Allocates } output = } }}} === Return === !GetVersion returns the version of the Aggregate Manager API running locally, the RSpec schemas supported, and the URLs where versions of the AM API are running. The return is an XML-RPC struct whose members are described below. `geni_api`:: An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 2 of the API. This value is duplicated here and within the {{{value}}} return struct for backwards compatibility with AM API v1 clients. {{{code}}}, {{{value}}}, and {{{output}}} together provide the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct standard return from all AM API methods], which has a specific [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct structure and semantics described on the Common Concepts page], including specifics of the {{{code}}} and {{{output}}} members. `value`:: For !GetVersion, {{{value}}} is an XML-RPC struct containing the actual return for the method. On success, this is required. Optional (and not defined) on failure or error. ==== !GetVersion return codes ==== Aggregates shall return consistent values for {{{geni_code}}} as described here. Success is always indicated using a {{{geni_code}}} value of {{{0}}}. On error, return the appropriate GENI error code in {{{geni_code}}}, as listed in this table. These error codes are part of a [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct larger set of codes with specific meanings required by this API, described on the Common Concepts page]. || '''''Error''''' || '''''Condition''''' || || `ERROR` || Internal error || || `SERVERERROR` || Server error || `geni_api`:: An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 2 of the API. `geni_api_versions`:: An XML-RPC struct indicating the versions of the Aggregate Manager API supported at this aggregate, and the URLs at which those API versions can be contacted. This element is required, and shall include at least 1 entry indicating the local aggregate manager URL and the version of the API supported at that URL. Aggregates supporting multiple versions of the Aggregate Manager API should [wiki:GAPI_AM_API_V3/CommonConcepts#SupportingMultipleAPIVersions conform to the guidelines specified on the Common Concepts page]. {{{ geni_api_versions: an XML-RPC struct containing 1+ entries of: Name: Integer - supported GENI AM API version Value: String - Absolute URL to the XML-RPC server implementing that version of the GENI AM API }}} `geni_request_rspec_versions`:: An array of data structures indicating the RSpec types accepted by this AM in a request. The [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype contract for RSpec versions is described with links to further reading on the Common Concepts page]. `geni_ad_rspec_versions`:: An array of data structures indicating what types of RSpec advertisements may be produced by this AM in !ListResources. {{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}} refer to the RSpec formats supported at this aggregate. The [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype contract for RSpec versions is described with links to further reading on the Common Concepts page]. Elements used within {{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}}: `type`, `version`:: Two ''case-insensitive'' strings which together comprise the type of RSpec. The RSpec `type` should be one of "geni", "protogeni", "sfa", or "orbit". `version` should be a type-specific version identifier as specified by the appropriate control framework. The "geni" type is reserved for GENI standard format RSpecs, following the schemas hosted at http://www.geni.net/resources/rspec. `schema`:: An URL pointing to a schema which can be used to verify the given type of RSpec. May be empty. `namespace`:: An XML namespace which the RSpec of the given type belongs to. May be empty. `extensions`:: An array of aggregate-specific strings denoting which extensions are supported. In the case of GENI standard RSpecs, these are XML namespaces which denote the extension as a whole. May be empty. ----- == !ListResources Details == !ListResources returns the advertised or available resources that can be reserved at this aggregate. `geni_available`:: Optional. An [http://www.xmlrpc.com/spec XML-RPC] boolean value indicating whether the caller is interested in all resources or available resources. If this value is {{{true}}}, the result should contain only available resources. If this value is {{{false}}} or unspecified, both available and allocated resources should be returned. The Aggregate Manager is free to limit visibility of certain resources based on the {{{credentials}}} parameter. `geni_compressed`:: Optional. An [http://www.xmlrpc.com/spec XML-RPC] boolean value indicating whether the caller would like the result to be compressed. If the value is true (1), the returned resource list will be compressed according to [http://www.ietf.org/rfc/rfc1950.txt RFC 1950]. If the value is false (0) or unspecified, the return will be text. `geni_rspec_version`:: Required. An [http://www.xmlrpc.com/spec XML-RPC] struct indicating the type and version of Advertisement RSpec to return. The struct contains 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{geni_ad_rspec_versions}}} as returned by !GetVersion at this aggregate. This option is ''required'', and aggregates are expected to return a {{{geni_code}}} of {{{1}}} ('Bad Arguments') if it is missing. Aggregates should return a {{{geni_code}}} of {{{4}}} ({{{BADVERSION}}}) if the requested RSpec version is not one advertised in !GetVersion as supported. The [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype contract for RSpec versions is described with links to further reading on the Common Concepts page]. === Return === !ListResources returns an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be all local resources, only available local resources. !ListResources returns the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct standard return from all AM API methods], which has a specific [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct structure and semantics described on the Common Concepts page], including specific requirements for the {{{code}}} and {{{output}}} members. `value`:: !ListResources returns an RSpec in GENI standard schema. If the aggregate cannot support the requested {{{type}}}/{{{version}}} (that pair is not listed in {{{geni_ad_rspec_versions}}}), then the aggregate returns an error ({{{geni_code}}}) of {{{4}}} ({{{BADVERSION}}}), and the {{{value}}} is not defined. ==== !ListResources return codes ==== On error, return the appropriate GENI error code in {{{geni_code}}}, as listed in this table. These error codes are part of a [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct larger set of codes with specific meanings required by this API, described on the Common Concepts page]. || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is badly formed or missing || || `FORBIDDEN` || Credential does not grant permission to aggregate || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `UNAVAILABLE` || Unavailable (eg server in lockdown) || || `BADVERSION` || Bad Version of RSpec requested || ----- == Describe Details == `Describe` is used to list the resources belonging to a particular reservation. The return is always a single manifest RSpec, whose contents cover the set of slivers whose URNs were supplied, or which are contained in the single slice whose URN was supplied as an argument. The manifest RSpec should contain all necessary details about resource identity, configuration, and access information necessary for experimenters to use the resources. As that configuration information may change as the resource becomes operationally `geni_ready`, this information may change. Otherwise, the manifest is mostly static. Additionally, `Describe` returns basic state and expiration information for all queried slivers. For details on options to `Describe`, see !ListResources above, and the Common Concepts page. Sample Return: {{{ { geni_rspec: " .... ", geni_slivers: [ { geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123456", geni_expires: "2012-06-06T12:00:00Z", geni_allocation_status: "geni_allocated" }, { geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123457", geni_expires: "2012-06-16T12:00:00Z", geni_allocation_status: "geni_provisioned" } ] } }}} Error codes: || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is badly formed or missing || || `FORBIDDEN` || Credential does not grant permission to the slice || || `FORBIDDEN` || Slice has been shutdown by the Clearinghouse || || `BUSY` || Slice or sliver is temporarily locked, try again later || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `UNAVAILABLE` || Unavailable (eg server in lockdown) || || `EXPIRED` || Slice or sliver expired || || `BADVERSION` || Bad Version of RSpec requested || == Allocate Details == `Allocate` is used to request a reservation of resources. If the request can be completely satisfied, the manifest RSpec is returned. Otherwise, an error is returned. `rspec`:: An RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard] request RSpec [http://www.geni.net/resources/rspec/3/request.xsd schema] containing the resources that the caller is requesting for allocation to the slice specified in {{{slice_urn}}}. These are expected to be consistent with the resources returned by a previous invocation of [wiki:GAPI_AM_API_V3#ListResources ListResources]. If this RSpec is in a format not listed as supported by !GetVersion, then the aggregate will return an error of {{{BADVERSION}}} ({{{4}}}). If `geni_end_time` is supplied, the experimenter is requesting a particular sliver reservation expiration date. Local policy may however dictate the expiration date. The AM therefore may ignore this argument; the `Allocate` call should still succeed, even if the date argument cannot be satisfied. At some aggregates, experimenters may call `Allocate` multiple times, to add resources to the existing reservation for the same slice. Other aggregates may limit such requests or forbid them entirely. See the Common Concepts page for details on Operations on Individual Slivers. Error codes: || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is missing or badly formed || || `FORBIDDEN` || Credential does not grant permission to the slice || || `FORBIDDEN` || Slice has been shutdown by the Clearinghouse || || `UNAVAILABLE` || AM is temporarily not allowing external users to create slivers || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `TOOBIG` || Request is too big to be satisfied || || `BADVERSION` || Bad Version of RSpec requested || || `UNSUPPORTED` || The aggregate does not permit multiple allocations to the same slice of this form || == Renew Details == `Renew` requests a changed expiration for one or more slivers in a slice. At some aggregates, this expiration may be shorter. This method applies both to slivers that are `geni_allocated` and to those that are already `geni_provisioned`. Depending on local aggregate configuration, the aggregate may only support `Renew` on all current slivers in the slice, or may permit renewing only some slivers. Local policy will dictate maximum expiration times. These times are typically quite short (~ 10 minutes initially, ~120 minutes maximum) for reservations (`geni_allocated`), and longer for provisioned slivers (~ 5-8 days initially). Since these expiration times are different, typically `Renew` is used only for slivers in the same allocation state. Sample Return: {{{ [ { geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123456", geni_expires: "2012-06-06T12:00:00Z", geni_allocation_status: "geni_allocated", geni_operational_status: "geni_pending_allocation" }, { geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123457", geni_expires: "2012-06-16T12:00:00Z", geni_allocation_status: "geni_provisioned", geni_operational_status: "geni_pending_allocation" } ] }}} Error codes: || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is badly formed or missing || || `SEARCHFAILED` || Slice or sliver does not exist at this AM || || `FORBIDDEN` || Credential does not grant permission to the slice or sliver || || `FORBIDDEN` || Slice has been shutdown by the Clearinghouse || || `BUSY` || Slice or sliver is temporarily locked, try again later || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `EXPIRED` || Resources already expired || || `UNSUPPORTED` || This aggregate does not support partial renewals of this form || == Provision Details == Redeem a reservation, requesting that the listed slivers move from `geni_allocated` to `geni_provisioned`. Only when slivers are provisioned are the resources 'instantiated' and made ready for operational use. Note that at some aggregates and for some resource types, this operation may be a no-op. At other aggregates, this operation starts a long running process (e.g. loading an image on a machine and booting it). Tools should monitor the sliver status (by calling `Status`), looking for an operational state other than `geni_pending_allocation`. Depending on the resource type, that next state may differ. See the advertisement RSpec for the resource type specific operational states and actions. As with the `Allocate` method, some aggregates may not support provisioning only some reserved resources. Also as with the `Allocate` method, experimenters may request a sliver expiration time; aggregates may succeed the operation while ignoring the requested expiration time or granting a different expiration time. Some resources types allow experimenter access. The `geni_users` option allows specifying login key material to be installed on the resources (e.g. SSH public keys). `geni_error`:: A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the sliver if this operation fails for a given sliver. Error codes: || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is badly formed or missing || || `SEARCHFAILED` || Slice or sliver does not exist at this AM || || `FORBIDDEN` || Credential does not grant permission to the slice or sliver || || `BUSY` || Slice or sliver is temporarily locked, try again later || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `UNAVAILABLE` || Unavailable (eg server in lockdown) || || `EXPIRED` || Slivers expired || || `UNSUPPORTED` || The aggregate does not permit operations on individual slivers in the same slice of this form || == Status Details == Get dynamic status about one or more slivers in a given slice. In contrast to `Describe`, `Status` is used to query dynamic state information about slivers. Aggregates may include detailed configuration information at their own discretion. Sample Return: {{{ { geni_urn: "urn:publicid:IDN+geni:gpo:portal+slice+myTestSlice", geni_slivers: [ { geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123456", geni_expires: "2012-06-06T12:00:00Z", geni_allocation_status: "geni_allocated". geni_operational_status: "geni_pending_allocation". geni_error: }, { geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123457", geni_expires: "2012-06-16T12:00:00Z", geni_allocation_status: "geni_provisioned", geni_operational_status: "geni_pending_allocation", geni_error: } ] } }}} Error codes: || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is badly formed or missing || || `SEARCHFAILED` || Slice or sliver does not exist at this AM || || `FORBIDDEN` || Credential does not grant permission to the slice or sliver || || `BUSY` || Slice or sliver is temporarily locked, try again later || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `UNAVAILABLE` || Unavailable (eg server in lockdown) || || `EXPIRED` || Slivers expired || || `UNSUPPORTED` || The aggregate does not permit operations on individual slivers in the same slice of this form || == !PerformOperationalAction Details == Perform an operational action on one or more named slivers. Operational actions modify the running state of the resource, not the nature of the resources in the reservation. To add or remove resources from the reservation, use `Delete` and `Allocate`. Operational actions, and the states that result, are resource type and aggregate specific. Aggregates advertise these in the advertisement RSpec. Example actions include `geni_start` (boot a computer) and `geni_stop` (power down a computer). `geni_error`:: A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the sliver if this operation fails for a given sliver. Error codes: || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is badly formed or missing (e.g. unknown operation) || || `SEARCHFAILED` || Slice or sliver does not exist at this AM || || `FORBIDDEN` || Credential does not grant permission to the slice or sliver || || `BUSY` || Slice or sliver is temporarily locked, try again later || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `UNAVAILABLE` || Unavailable (eg server in lockdown) || || `EXPIRED` || Slivers expired || || `UNSUPPORTED` || The aggregate does not support the given operation for the given resource(s) in their current state || || `INPROGRESS` || Requested operation is already in progress || == Delete Details == `Delete` the given slivers, stopping any running resources and freeing the reservation. This method applies to slivers in any state. As with the `Allocate` method, some aggregates may not support deleting only some slivers. Attempting to delete a previously deleted sliver may result in an error - the aggregate may have forgotten about it entirely. Attempting to delete a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted. Details are aggregate specific. This operation should generally succeed for a valid sliver, despite the `geni_best_effort` option. However, when `geni_best_effort` is supplied and is false, and an aggregate cannot delete all the named slivers, no slivers are deleted. Error codes: || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is badly formed or missing || || `SEARCHFAILED` || Slice or sliver does not exist at this AM || || `FORBIDDEN` || Credential does not grant permission to the slice or slivers || || `BUSY` || Slice or sliver is temporarily locked, try again later || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `EXPIRED` || Sliver(s) already expired and gone || == Shutdown Details == This operation is for operator use, to stop a misbehaving resource. Once shut down, the slivers are not available for experimenter use. The underlying resources may be returned to the pool of available resources, depending on resource type and aggregate implementation. This method returns true, unless resource remain running in the slice after this operation. Error codes: || '''''Error''''' || '''''Condition''''' || || `BADARGS` || One of the required arguments is badly formed or missing || || `SEARCHFAILED` || Slice does not exist at this AM || || `FORBIDDEN` || Credential does not grant permission to the slice || || `ERROR` || Internal error || || `SERVERERROR` || Server error || || `EXPIRED` || Slice expired || || `INPROGRESS` || Shutdown in progress || Note: Aggregates should not return {{{BUSY}}}: this is a time critical operation that should succeed if possible.