wiki:GAPI_AM_API_V3_DETAILS

Version 24 (modified by Aaron Helsinger, 12 years ago) (diff)

--

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, that are not already provided by the main and overview page of this version of the AM API, the API Version 3 overview page. In particular, this page provides sample returns, and expected error codes.

See Also:

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' = <This server's AM API absolute URL>
             '2' = <Prior API version still supported at a slightly different URL - optional but included here>
        }
        geni_request_rspec_versions = [{
             type = "GENI"
             version = "3"
             schema = "http://www.geni.net/resources/rspec/3/request.xsd" # required but may be empty
             namespace = "http://www.geni.net/resources/rspec/3" # required but may be empty
             extensions = ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd", <other URLs here>] # required but may be empty
        }]
        geni_ad_rspec_versions = [{
             type = "GENI"
             version = "3"
             schema = "http://www.geni.net/resources/rspec/3/ad.xsd" # required but may be empty
             namespace = "http://www.geni.net/resources/rspec/3" # required but may be empty
             extensions = ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd", <other URLs here>] # required but may be empty
        }]
        geni_credential_types = [{ # This AM accepts only SFA style credentials for API v3
             geni_type = "geni_sfa"
             geni_version = "3"
       }]
       geni_single_allocation = 0 # false - can operate on individual slivers. This is the default, so could legally be omitted here.
       geni_allocate = "geni_many" # Can do multiple Allocates. This is not the default value, so is required here.
      }
  output = <None>
}

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 3 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 standard return from all AM API methods, which has a specific 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 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 3 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 conform to the guidelines specified on the Common Concepts page.
geni_api_versions: an XML-RPC struct containing 1+ entries of:
  Name: Integer (encoded as a String) - 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 contract for RSpec versions is described with links to further reading on the Common Concepts page. Per that contract, AMs will produce manifest RSpecs with a schema that is based on the given request type and version.
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 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
A 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. As elsewhere, this page provides only details not covered by the main AM API page.

Options

geni_available
Optional. An XML-RPC boolean value indicating whether the caller is interested in all resources or available resources. If this value is true (1), the result should contain only available resources. If this value is false (0) 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 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 RFC 1950. If the value is false (0) or unspecified, the return will be text.
geni_rspec_version
Required. An 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 ('BADARGS') if it is missing. Aggregates should return a geni_code of 4 (BADVERSION) if the requested RSpec version is not one advertised as supported in GetVersion. The contract for RSpec versions is described with links to further reading on the Common Concepts page.

Return

ListResources returns a value containing an RSpec listing and describing resources at this aggregate. Depending on the arguments, these may be all local resources, or only available local resources.

ListResources returns the standard return struct from all AM API methods (output, value, code).

value
ListResources returns an RSpec conforming to the 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 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 the standard AM API struct, with a value that is a struct that always includes a single manifest RSpec, describing the resources in the set of slivers whose URNs were supplied, or describing the entire 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. Valid values for geni_allocation_status and geni_operational_status are described on the Common Concepts page.

For details on options to Describe, see ListResources above, and the Common Concepts page.

Sample Return value:

{
    geni_rspec: "<?xml version="1.0" ?>
<rspec expires="2012-02-01T18:20:39Z" generated="2012-02-01T18:20:39Z" type="manifest" xmlns="http://www.geni.net/resources/rspec/3" xmlns:emulab="http://www.protogeni.net/resources/rspec/ext/emulab/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/manifest.xsd http://www.protogeni.net/resources/rspec/ext/emulab/1 http://www.protogeni.net/resources/rspec/ext/emulab/1/ptop_extension.xsd http://hpn.east.isi.edu/rspec/ext/stitch/0.1/ http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd ">  
  <node component_id="urn:publicid:IDN+emulab.net+node+cisco3" component_manager_id="urn:publicid:IDN+emulab.net+authority+cm" component_name="cisco3" exclusive="true"> 
....   
",
    geni_urn: "urn:publicid:IDN+pgenigpolabbbncom+slice+ahtest",
    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_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123457",
              geni_expires: "2012-06-16T12:00:00Z",
              geni_allocation_status: "geni_provisioned"
              geni_operational_status: "geni_ready",
              geni_error: "" # optional field, included here as an example
          }
    ]
}      

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.

Arguments: Most arguments are described on the main page. Here a few additional details are provided.

rspec
An RSpec matching the GENI standard request RSpec 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 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, experimenter tools 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 (geni_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 value:

    [
          {
              geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123456",
              geni_expires: "2012-06-16T18:00:00Z",
              geni_allocation_status: "geni_provisioned",
              geni_operational_status: "geni_pending_allocation",
              geni_error: "" # Optional, included here for reference
          },
          {
              geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123457",
              geni_expires: "2012-06-16T18:00:00Z",
              geni_allocation_status: "geni_provisioned",
              geni_operational_status: "geni_started"
          }
    ] 

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 allow the operation while ignoring the requested expiration time or granting a different expiration time.

Some resource types allow experimenter access. The geni_users option allows specifying login key material to be installed on the resources (e.g. SSH public keys).

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 value:

{
    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: "" # required but may be empty, consistent with previous versions of this API
          },
          {
              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: "" # required but may be empty
          }
    ]
}      

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), geni_restart (reboot a computer), and geni_stop (power down a computer).

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 (1), unless the resources 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.