ProtoGeni Component Manager

Overview

Each member wishing to contribute resources to the federation runs a Component Manager XMLRPC server. So far, there are two CM prototypes available: a more sophisticated Emulab-based installation, and a simpler standalone reference implementation.

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 (in conjunction with the standard ProtoGENI XMLRPC interface) describe the Component Manager API. Where appropriate, we have used pythonese to describe arguments and return values.

Please note that the API here described is large, and most of it is optional: it is not expected that all managers will implement the entire interface. A minimal subset (which all managers are expected to provide) has been defined, and consists of the following calls:

• Resolve
• DiscoverResources
• CreateSliver
• DeleteSlice
• GetSliver
• RestartSliver
• RenewSlice
• SliverStatus
• Shutdown
• GetVersion

See GetVersion for a mechanism to determine whether a particular Component Manager implements more than this minimal (level 0) interface.

See the slides attached to the bottom of this page for a presentation given about this "minimal" set at GEC6.

Notes on Version 2

Many of the API calls now take an explicit target to operate on. For example, when redeeming a ticket, the slice to operate on is specified as an explicit parameter to RedeemTicket(). Previously, the slice to be operated on was implicitly specified by virtue of the slice credential that was supplied in the call. In addition, many API calls now take a list of credentials, rather then a single credential.

This change allows for greater flexibility in implementing the Component Manager; an implementation can make use of the credentials however it wants to. However, a typical implementation will require at least one credential, usually the slice credential, in which case the slice parameter must match the slice specified inside the credential.

The Life Cycle of a Sliver

When using the minimal API, the state of a sliver is very simple: it either has been started, or it has not. No facilities are provided for configuring the sliver beyond the parameters available at creation time.

In the full API, however, further possibilities are available, through the use of tickets. (The main benefits to using tickets are that resources can potentially be reserved without performing immediate sliver instantiation, and sliver resources can be modified dynamically without shutting down and recreating the entire sliver.) The following diagram shows a summary of the operations applicable to slivers in various states:

Resolve

Lookup an object (by URN) and return information about it:

struct Resolve(urn, credentials[]);

where credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, issued by a Slice Authority or the ClearingHouse, and urn is the URN of the object to be resolved. The type of the object being resolved is encoded in the URN. A typical implementation will support at least the following types:

1. Node - Describe the physical node in detail, including an advertisement rspec fragment.

   {
    'urn'        : string,
    'hostname'   : string,
    'rspec'      : string, 
   }
   

2. Slice - Describe the slice, including the URN of any outstanding ticket and/or the URN of any outstanding sliver.

   {
    'urn'        : string,
    'sliver_urn' : string,
    'ticket_urn' : string,
   }
   

3. Sliver - Describe the sliver resources. The return value is the sliver manifest.

   {
    'urn'        : string,
    'manifest'   : string,
   }
   

4. Ticket - Return a duplicate copy of the ticket. See the GetTicket() call.

The return value is an XML document representing a structure that describes the object in detail.

Availability: supported in revisions 0 to 2, by both minimal and full implementations.

Implementation Notes:

• Component Managers should endeavor to provide URN resolution for all names it gives out.
• Not all Component Managers will provide the same set of physical resources (such as Node above), but Component Managers should return physical resource information for the resource types it does support.

DiscoverResources

Return information about available resources.

string DiscoverResources(credentials[],available,compress,rspec_version);

where credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, issued by a 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 optional argument rspec_version may be used to control the rspec version that is returned. The current default is to return an advertisement in 0.1 format. Use '2' to get a Version 2 rspec. In the future, Version 2 will be the default.

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 2, by both minimal and full implementations.

CreateSliver

Add a new sliver to an existing slice. A set of requested resources will be allocated to the sliver, and any necessary procedures to make them ready for use (such as rebooting nodes) will be initiated. A set of optional SSH keys may be provided, which will be installed on the nodes. It is an error if a sliver already exists at the CM for the specified slice.

struct CreateSliver(slice_urn, rspec, keys, credentials[]);

slice_urn is the slice to which the sliver will be added. rspec is an XML document which conforms to one of the schemata accepted by the Component Manager. (Please see GetVersion to see how to determine what formats are permissible.) keys, if provided, is an optional list of SSH keys obtained with GetKeys.

credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the slice credential, in which case the slice_urn parameter must match the slice specified inside the credential.

If successful, the value returned is an array:

{
 'sliver'   : string,
 'manifest' : string,
}

where both strings are XML blobs, one for the sliver credential and the other for the sliver manifest. The sliver credential grants the caller permission to manipulate the sliver later. The _manifest_ will always be in the same format (and version) as the input _rspec_.

An additional note about the keys argument. The format is:

[{'urn'   => 'urn:publicid:IDN+emulab.net+user+dopey'
  'login' => 'dopey',
  'keys'  => [ list of keys ]},
 {'login' => "sleepy",
  'keys'  => [ list of keys ]}];

where the list of keys is:

[ {'type': 'ssh', 'key': 'ssh-dss ....'},
  {'type': 'ssh', 'key': 'ssh-rsa ....'} ]

The urn field is currently optional; the login is always used if it is provided. At this time, only login in traditional unix format are allowed; 8 alphanumeric characters, starting with an alpha.

Availability: supported in revision 2 only, by both minimal and full implementations.

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(slice_urn, rspec, credentials[]);
string UpdateTicket(slice_urn, ticket, rspec, credentials[]);

In the first form, rspec is an XML document conforming to one of the permissible rspec specifications (see GetVersion to learn which versions are accepted). In the second form, an existing ticket is supplied that is to be modified to conform to the provided rspec. The supplied ticket can only be an unredeemed ticket, as returned by GetTicket().

In both forms, slice_urn is the slice to which the operation is applied, and credentials is a list of valid credentials issued by any ProtoGeni Authority.

It is an error to request a new ticket when there is already an unredeemed ticket issued. The original ticket must be released first, with ReleaseTicket().

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. When updating a ticket, the original ticket is effectively destroyed and no longer accessible (if the operation succeeds).

Availability: supported in revision 2, by full implementations only.

Implementation notes:

• While a ticket is defined as another form of credential, the owner of the ticket (within the signed xml document) is ignored by the Component Manager. It is the presence of a slice credential in the credentials argument that grants the caller permission to redeem, update, or release the ticket.
• Tickets behave a little bit like airline e-tickets. They can be a useful record of a reservation, but are not authoritative. Whether a ticket is valid, and who can redeem a ticket can be answered in a strict sense only by asking the component manager, and not merely from inspection of a ticket. And if you lose your ticket, it really makes no difference.
• The above comments make an obvious case for the removal of tickets from the API, but we are unwilling to go that far, yet.

RedeemTicket

Redeem a ticket obtained via the GetTicket() or UpdateSliver(). 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.

struct RedeemTicket(slice_urn, ticket, keys, credentials[]);

where slice_urn is the slice to which the sliver will be added (ticket redeemed), ticket is a ticket issued by GetTicket() above, keys is an optional list of keys obtained with GetKeys, and credentials is a list of valid credentials issued by any ProtoGeni Authority.

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

If successful, the value returned is an array:

{
 'sliver'   : string,
 'manifest' : string,
}

where both strings are XML blobs, one for the sliver credential and the other for the sliver manifest. The sliver credential grants the caller permission to manipulate the sliver later. The manifest is always an rspec of the same version that was supplied to GetTicket.

Note that the ticket is effectively destroyed, and no longer usable or accessible, if the operation succeeds.

Availability: supported in revision 2, by full implementations only.

UpdateSliver

Request a change of resources for an existing sliver. The new set of resources that are desired are specified in the rspec.

string UpdateSliver(sliver_urn, rspec, credentials[]);

where sliver_urn is the sliver to be modified, and rspec is an XML document conforming to the rspec specification.

If the UpdateSliver operation succeeds, a new ticket is issued that represents the new set of resources as specified in the rspec. The sliver itself has not been changed in any way; all of the original resources still belong to the sliver. The sliver is not modified until you redeem the new ticket with RedeemTicket(). You may also release the new ticket with ReleaseTicket(), effectively putting the sliver in the same state it was before UpdateSliver() was called.

The state after a successful update are unusual in that there is both a valid sliver and a valid ticket. This is the only time this can happen.

Note that you may not update this ticket with UpdateTicket(); you must first release the new ticket with ReleaseTicket() and then call UpdateSliver() again, with a different rspec. A future version of the API will support this capability.

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

Availability: supported in revision 2, by full implementations only.

Implementation notes:

• Still to be worked out in the API, is what happens after an UpdateSliver()/RedeemTicket() operation, wrt the state of the slice (is it stopped or still started) and what operation is required to initialize newly added physical resources (call restart or call start).

RenewSlice

Request a change of expiration time for an existing sliver.

int RenewSlice(slice_urn, expiration, credentials[]);

where slice_urn is the slice to which the sliver belongs, and expiration is a string in valid RFC 3339 format.

The supplied expiration time cannot be later then the expiration time of the credential. If no expiration is provided, the expiration of the credential is used instead. In order to extend a slice, you must first call RenewSlice() at the Slice Authority, request a new slice credential that reflects the new expiration, and then call RenewSlice() at each of the Component Managers where you have slivers.

If the RenewSlice operation succeeds, the expiration time of the slice (sliver) is immediately updated. No other slivers (on other CMs) or tickets that might belong to the slice are affected.

The return value is either success or failure: upon success, the expiration time has been set to the value specified; upon failure, no change has been made.

Availability: supported in revision 2, by both minimal and full implementations.

ReleaseTicket

Release a ticket obtained via the GetTicket() or UpdateSliver(). All of the resources that have been promised are made available to other users. If the ticket was the result of an UpdateSliver() on an existing sliver, only those resources that were added to the new ticket are released; the original resources held by the sliver are retained.

struct ReleasTicket(slice_urn, ticket, credentials[]);

where slice_urn is the slice to which the ticket belongs, ticket is a ticket issued by GetTicket() or UpdateSliver(), and credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the slice credential, in which case the slice_urn parameter must match the slice specified inside the credential.

The return value is success or failure.

Availability: supported in revisions 0 to 2, by full implementations only.

StartSliver

Request that resources associated with a sliver be started. More precisely, some or all of the nodes allocated to the sliver are booted, and network links are created (or modified) to match the request rspec. This call returns immediately; use SliverStatus() and/or WaitForStatus() to determine when the sliver is ready to use.

int StartSliver(slice_urn, credentials[]);
int StartSliver(sliver_urns[], credentials[]);

In the first form, slice_urn is the slice to which the sliver belongs, and indicates that all sliverss in the sliver should be started. In the second form, sliver_urns is a list of specific slivers in the slice to start. credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the sliver credential or the slice credential.

Note that after a ticket is redeemed with RedeemTicket() or UpdateSliver(), it would be most appropriate to use the first form to ensure that all nodes and links are initialized properly. In the case of UpdateSliver(), only new resources are initialized; nothing is done to existing or unmodified resources.

Calling StartSliver() on a sliver that is already in the started state results in no changes to the sliver.

Calling StartSliver() on a sliver that is currently in transition because of an previous call to any of StartSliver(), RestartSliver(), or StopSliver(), is an error.

The return value is success or failure.

Availability: supported in revision 2, by full implementations only.

Implementation notes:

• The notion of "in transition" is not well defined yet. The intent is to make it possible for the CM to prevent a component from being restarted or stopped again before the previous start is done, so as not to damage or corrupt the physical resources. For example, rebooting a node while it is in the middle of booting up.

StopSliver

Request that resources associated with a sliver be stopped. In the first form, all of the nodes in the sliver are powered down, and all networks are destroyed. In the second form, only those nodes matching the provided list are powered down; networks are left intact. This call returns immediately; use SliverStatus() and/or WaitForStatus() to determine when the sliver has completed stopping.

int StopSliver(slice_urn, credentials[]);
int StopSliver(sliver_urns[], credentials[]);

In the first form, slice_urn is the slice to which the sliver belongs, and indicates that all slivers in the slice should be stopped. In the second form, sliver_urns is a list of specific slivers to stop. credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the sliver credential or the slice credential.

Calling StopSliver() on a sliver that is already in the stopped state results in no changes to the sliver.

Calling StopSliver() on a sliver that is currently in transition because of an previous call to any of StartSliver(), RestartSliver(), or StopSliver(), is an error.

The return value is success or failure.

Availability: supported in revision 2, by full implementations only.

Implementation notes:

• The notion of "in transition" is not well defined yet. The intent is to make it possible for the CM to prevent a component from being restarted or stopped again before the previous start is done, so as not to damage or corrupt the physical resources. For example, rebooting a node while it is in the middle of booting up.

RestartSliver

Request that resources associated with a sliver be restarted. More precisely, some or all of the nodes allocated to the sliver are rebooted. No action is taken on network links. This call returns immediately; use SliverStatus() and/or WaitForStatus() to determine when the sliver is ready to use again.

int RestartSliver(slice_urn, credentials[]);
int RestartSliver(sliver_urns[], credentials[]);

In the first form, slice_urn is the slice to which the sliver belongs, and indicates that all slivers in the slice should be restarted. In the second form, sliver_urns is a list of specific slivers to restart. credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the sliver credential or the slice credential.

Calling RestartSliver() on a sliver that is currently in transition because of an previous call to any of StartSliver(), RestartSliver(), or StopSliver(), is an error.

The return value is success or failure.

Availability: supported in revision 2, by both minimal and full implementations.

Implementation notes:

• Managers that implement only the minimal interface may return an error unless a slice_urn is provided.
• The notion of "in transition" is not well defined yet. The intent is to make it possible for the CM to prevent a component from being restarted or stopped again before the previous start is done, so as not to damage or corrupt the physical resources. For example, rebooting a node while it is in the middle of booting up.

DeleteSliver

Request that a sliver be shutdown, returning a ticket for whatever remains of the original promise of resources.

int DeleteSliver(sliver_urn, credentials[]);

where sliver_urn is the sliver to be deleted, and credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the sliver credential or the slice credential.

Upon success, a new ticket is returned for whatever remains of the original promise of resources. This is a new ticket, not merely a copy of the original ticket (which became invalid when it was redeemed). Although the resources promised by the ticket will typically be identical to the resources in the original ticket, the user should expect certain contents of the ticket to have changed from those in the original.

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

Availability: supported in revision 2, by full implementations only.

DeleteSlice

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

int DeleteSlice(slice_urn, credentials[]);

where slice_urn is the slice containing the sliver to be deleted, and credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the sliver credential or the slice credential.

The return value is success or failure.

Availability: supported in revision 2, by both minimal and full implementations.

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(slice_urn, credentials[]);

where slice_urn is the slice containing the sliver, and credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the sliver credential or the slice credential.

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

Availability: supported in revision 2, by both minimal and full implementations.

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(slice_urn, keys[], credentials[]);

where slice_urn is the slice to bind the keys to, keys is an optional list of keys obtained with GetKeys, and credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the sliver credential or the slice credential.

The return value is success or failure.

Availability: supported in revision 2, by full implementations only.

SliverStatus,WaitForStatus

Return a description of the status for all of the resources that have been allocated to the slice on the component. SliverStatus() returns immediately; it is a polling operation. WaitForStatus() is a blocking operation, returning when the timeout has been reached, or if the status changes and should reported back to the caller.

struct SliverStatus(slice_urn, credentials[]);
struct WaitForStatus(slice_urn, status, timeout, credentials[]);

In the first form slice_urn is the slice containing the sliver, and credentials is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the sliver credential or the slice credential.

In the second form, status is the sliver status to wait for, and timeout is the number of milliseconds to block. If the timeout is zero, the Component Manager is free to implement the wait as it likes, but it shall not block infinitely, nor will it return immediately (not a poll).

Returns failure, or a structure:

{'state'   : 'started',
 'status   : 'failed',
 'details' : {'urn:publicid:IDN+emulab.net+sliver+456' :
                   {'state'  : 'started',
                    'status' : 'ready',
                    'error'  : ''},
              'urn:publicid:IDN+emulab.net+sliver+457'' :
                   {'state'  : 'started',
                    'status' : 'failed',
                    'error'  : 'lost power'},
             }
}

where state is the current state of the sliver(s), and is one of started, stopped, or mixed (see below). state is changed by the StartSliver() and StopSliver() operations. RestartSliver() simply combines the two operations into one, so the resulting state is started as well.

status on the other hand, is the operational status of the sliver(s) and is one of the following:

1. changing : In transition, either to being shutdown or booted.
2. ready : the sliver has booted properly.
3. notready : the sliver is halted.
4. failed : the sliver has failed to boot.
5. unknown : the component manager does not provide information about the status of this node; continuing to poll for changes will not help the caller determine anything useful.

For example, when referring to the operational status of a node, ready means it has booted properly and is running, while failed indicates the node failed to boot. changing simply means that the node is in transition, either rebooting or shutting down.

error is an optional and hopefully moderately useful indication of what happened when a sliver fails to start properly. The Component Manager should do its best to make this field useful.

Since the Component Manager might be an aggregate, a sliver can actually be composed of multiple child slivers (nodes, links, etc). The details array holds the state and status for each of the child slivers. For consistency, details is included even when the Component Manager is not an aggregate, in which case details is always of length one.

The top level status and state are therefore a summary of the child slivers. state is started when all of the child slivers are in the started state, and stopped when all of the children are in the stopped state. Otherwise the state will be set to mixed to tell the caller to look inside the details array.

Similarly, status is also a reflection of the status of all of the children, according to the following rules:

1. If any child has failed status, then the parent has failed status.
2. Otherwise, if all children have unknown status, then the parent has unknown status.
3. Otherwise, if all children which are not unknown have the same status as each other, then the parent has the same status as the non-unknown children.
4. Otherwise, the parent has mixed status.

In each case, the caller can inspect the status of the individual slivers in the details array.

Availability: supported in revision 2. SliverStatus() is supported by both minimal and full implementations.

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 2, by full implementations only.

Shutdown

void Shutdown(slice_urn, clear, credentials[]);

Shuts down a slice completely. If clear is set, then the slice shutdown time is cleared; otherwise, it is set to the current time. The credentials parameter is a list of valid credentials issued by any ProtoGeni Authority. A typical implementation will require at least one credential, usually the slice credential.

Availability: supported in revision 2, by both minimal and full implementations.

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 2, by full implementations only.

GetVersion

struct GetVersion();

Returns an XMLRPC struct describing the revision of this API supported by the component manager.

The following members in the result are currently defined:

int api;
int level;
string input_rspec[];
string output_rspec;

where api is an integer corresponding to the revision of this component manager specification and level is 0 for a component manager implementing the minimal subset or 1 for a component manager which implements the full specification.

input_rspec[] is a list of one or more RSpec schema version identifiers, and an RSpec which validates according to any of the listed schemata will be accepted as request inputs by the component manager. Any RSpec supplied as advertisement output will conform to version output_rspec of the schema. (Please note that manifest rspec output will instead match the supplied request version.)

Other members may be added in future revisions of this specification.

Availability: supported in revision 2 only, by both minimal and full implementations. (Revision 1 specified an incompatible interface, and should be considered obsolete.)