ProtoGeni Component Manager

Overview

Each member of the federation runs a Component Manager XMLRPC server. Since the members are running as Emulab clusters, the CM is closely coupled to existing Emulab infrastructure.

Authentication

The certificates that researchers use to authenticate themselves to the Component Manager are issued by their home Emulab. This certificate is valid for accessing any member of the federation. Please see the Slice Authority documentation for details on how users create their certificates.

See details about Protogeni's authentication implementation.

API Documentation

The following sections describe the Component Manager API. Where appropriate, we have used pythonese to describe arguments and return values.

Resolve

Lookup a UUID and return information about it:

struct Resolve(credential, uuid, type);

where credential is a vaild credential issued by any Slice Authority or the ClearingHouse, uuid is the uuid of the object to be resolved, and type is limited to just Node.

The return value is an XML document representing a structure that describes the node in detail, including all of its interfaces.

Availability: supported in revisions 0 to 1.

DiscoverResources

Return information about available resources.

string DiscoverResources(credential,available,compress);

where credential is a vaild credential issued by any Slice Authority or the ClearingHouse. available is a Boolean parameter, which when true specifies that only resources which are currently free should be returned (i.e. any resource which is temporarily busy will be silently ignored). If the optional compress Boolean parameter is specified and set, then the returned resource list will be compressed according to RFC 1950 (ZLIB Compressed Data Format Specification version 3.3).

The return value is an XML document, in RSpec format (its type will be text if the compress parameter is absent or false, and base64 if compress is present and true).

Availability: supported in revisions 0 to 1.

GetTicket,UpdateTicket

Request a ticket from the Component Manager. A ticket is another form of a credential, which in this case, is an rspec that has been signed, indicating a promise to deliver the resources specified in the rspec when the ticket is redeemed.

string GetTicket(credential, rspec);
string UpdateTicket(credential, ticket, rspec);
string GetTicket(credential, uuid);

In the first form, credential is a valid credential issued by any Slice Authority, and rspec is an XML document conforming to the rspec specification. In the second form, an existing ticket is supplied that is to be modified to conform to the provided rspec. The supplied ticket can be an unredeemed ticket, or it might a ticket for an existing sliver, as returned by SliverTicket() below. Updated tickets are redeemed with UpdateSLiver() below. In the final form, a duplicate ticket is requested using the uuid of the original ticket. See ListTickets() below.

Note that tickets have very short time limits; they expire within a few minutes to avoid locking up resources.

The return value is either a new ticket, or failure.

Availability: supported in revisions 0 to 1. Revisions 0 to 1 require rspec to validate according to schema version 0.1.

RedeemTicket

Redeem a ticket obtained via the GetTicket() call above. A set of SSH keys may be optionally provided, which will be placed on the nodes when they are booted. See the GetKeys routine in the Slice Authority documentation.

(string,string) RedeemTicket(credential, ticket, keys);

where credential is a valid slice credential for the slice, ticket is a ticket issued by GetTicket() above, and keys is an optional list of keys obtained with GetKeys.

If the RedeemTicket operation succeeds, all of the resources specified in the rspec will have been allocated and initialized. Note that nodes will not have been booted yet; see the StartSliver() operation below.

Upon success, the return value is a multivalued list containing the new sliver credential and the sliver manifest. The sliver credential grants the caller permission to manipulate the sliver later.

Availability: supported in revisions 0 to 1.

UpdateSliver

Request a change of resources for an existing sliver. The new set of resources that are desired are specified in the rspec. A set of SSH keys may be optionally provided, which will be placed on the nodes when they are booted. See the GetKeys routine in the Slice Authority documentation.

string UpdateSliver(credential, ticket, keys);

where credential is a sliver credential returned by the RedeemTicket() call above, ticket is an updated ticket returned by UpdateTicket() above, and keys is an optional list of keys obtained with GetKeys.

If the UpdateSliver operation succeeds, all of the resources specified in the ticket will have been allocated and initialized. Note that nodes will not have been booted yet; see the StartSliver() operation below.

The return value is success or failure. Upon success, the new sliver manifest is returned.

Availability: supported in revisions 0 to 1.

ReleaseTicket

Release a ticket obtained via the GetTicket() call above. All of the resources that have been promised are made available to other users.

string ReleaseTicket(ticket);

where ticket is a ticket issued by GetTicket() above.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

StartSliver

Request that all resources associated with a sliver be started. More precisely, all of the nodes allocated to the sliver are rebooted.

int StartSliver(credential);

where credential is a sliver credential returned by the RedeemTicket() call above.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

DeleteSliver

Request that all resources associated with a sliver be released, and the sliver record deleted.

int DeleteSliver(credential);

where credential is a sliver credential returned by the RedeemTicket() call above.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

DeleteSlice

Request that all resources associated with a slice be released, and the slice record deleted. This function is operationally similar to DeleteSliver() above, but allows anyone holding the slice credential to release all of the resources associated with the slice.

int DeleteSlice(credential);

where credential is a valid slice credential issued by any Slice Authority.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

GetSliver

Request a sliver credential for any resources that are currently allocated to a slice. Put another way, this call allows a user to get a duplicate sliver credential, if they have a valid slice credential.

string GetSliver(credential);

where credential is a valid slice credential issued by any Slice Authority.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

BindToSlice

Bind to a slice so that the caller may manipulate the slice. This call can be invoked by any user with a valid slice credential issued by the Slice Authority for that slice. Once a user has bound herself to the slice, she may use any of the slice oriented API calls in this document. A set of SSH keys may be optionally provided, which will be placed on the nodes when they are booted. See the GetKeys routine in the Slice Authority documentation.

Note that this call is provided in lieu of credential delegation, which has not been implemented yet.

int BindToSlice(credential, keys);

where credential is a valid slice credential issued by any Slice Authority, and keys is an optional list of keys obtained with GetKeys.

The return value is success or failure.

Availability: supported in revisions 0 to 1.

SliverStatus,SliceStatus

Return a status for all of the resources that have been allocated to the slice on the component. The two forms of this call allow for using a sliver credential or a slice credential, but the information returned is the same.

list SliceStatus(credential);
list SliverStatus(credential);

In the first form, credential is a valid slice credential issued by any Slice Authority. In the second form, credential is a valid sliver credential returned by the RedeemTicket() call above.

Returns failure, or an array:

{'status'  : 'ready',
 'details' : {'de990279-773e-102b-8eb4-001143e453fe': 'ready'},
 'detailsNew' : {'urn:publicid:IDN+example.net+sliver+pc123': 'ready'},
}

where status is a summary indicator for all of the resources (for example, all nodes have booted and are running okay), and details and detailsNew are arrays that provides the status for each individual resource. Currently three status indicators are returned:

1. notready : some nodes have not yet booted properly.
2. ready : all nodes have booted properly.
3. failed : some nodes were unable to boot properly and have given up trying.

Availability: supported in revisions 0 to 1. detailsNew is not provided by all implementations.

SliverTicket

Request a ticket representing the current resources being used by a sliver. This ticket can be used to modify the resources being used, by doing an UpdateTicket() and then an UpdateSliver() with the new ticket returned by UpdateTicket().

The rspec contained within the returned ticket is the sliver "manifest", to be described soon ...

string SliverTicket(credential);

where credential is a valid sliver credential returned by the RedeemTicket() call above.

The return value is either a new ticket, or failure. The returned ticket cannot be "redeemed" since in effect, it already was redeemed. It can only be used in the UpdateTicket() method mentioned above.

Availability: supported in revisions 0 to 1.

ListTickets

Return a summary list of unredeemed tickets belong to a user. This allows a user to recover tickets she has lost. Only unredeemed tickets are listed; to get a ticket for an existing sliver, use the SliverTicket method above.

struct ListTickets(credential);

where credential is a valid credential issued by any Slice Authority, or a credential returned by the RedeemTicket() call above.

Returns failure, or an array of hashes:

{'redeem_before  : '2009-05-17T15:53:03',
 'expires'       : '2009-05-17T15:53:03',
 'uuid'          : 'de990279-773e-102b-8eb4-001143e453fe',
}

where uuid is the UUID of the ticket, which can be used to request a duplicate of the original ticket using the GetTicket() method above.

Availability: supported in revisions 0 to 1.

ListUsage

Return a list of all resources in use. This is used by the ClearingHouse to get a global sense of usage. Currently, only the ClearingHouse will be allowed to make this call, but might perhaps be made available to other principles.

struct ListUsage(credential);

where credential is a valid credential issued by the ClearingHouse. Since no one can actually request one of these credentials, the only place it can be invoked is on the ClearingHouse itself, by someone with administrator privileges.

The return value is a list of resources in use.

Availability: supported in revisions 0 to 1.

SplitSliver

credential[] SplitSliver( credential, impotent );

Splits an aggregated sliver into its separate parts, and returns a list. The credential parameter must be a valid sliver credential corresponding to a slice instantiated on this component manager, and the value returned is an array of sliver credentials, one per sliver in the aggregate.

Availability: supported in revisions 0 to 1.

Shutdown

void Shutdown( credential, clear );

Shuts down a slice completely. The credential parameter must be a valid slice credential, for which the owner has pi, instantiate or control privileges. If clear is set, then the slice shutdown time is cleared; otherwise, it is set to the current time.

Availability: supported in revisions 0 to 1.

ListHistory

struct[] ListHistory( credential, type );

This operation is reserved for the clearing house (which authenticates itself with the credential parameter); other principals may not use it. It currently returns a list of structures describing ticket history (the type parameter is ignored).

Availability: supported in revisions 0 to 1.

GetVersion

int GetVersion();

Returns an integer corresponding to the revision of this API supported by the component manager.

Availability: supported in revision 1 only.