User Tools

Site Tools


sfa:interfaces

SFA interfaces

On this page we detail the interfaces of the SFA as implemented by PlanetLab.

Registry interface

The registry interface is provided by the registry and it enables not only the mapping between HRN and GIDs, called a record, but it also issues the credentials and certificates for the records it manages.

  • Register(Credential, Record): Registers the given Record.
  • Remove(Credential, Record): Removes the given Record.
  • Update(Credential, Record): Updates the given Record. Records need to be periodically refreshed, otherwise they are automatically removed.
  • Resolve(Credential, HRN, Type): Returns the record of the given Type and with the given HRN.
  • List(Credential, HRN, Type): Retrieves information about the set of objects managed by the named authority.
  • GetCredential(Credential, HRN, Type): Allows a principal to retrieve credentials corresponding to the named object. For example, a user might invoke GetCredential(), giving his or her user credentials as the first argument, to retrieve the credentials associated with the named slice. The Type argument is used to differentiate among multiple records with the same name, so for Type=Slice, the return value is a “slice credential” that can subsequently be passed to the operations defined in the next section. Similarly, a call to GetCredential() with Type=SA returns a “registry credential” that can subsequently be used to operate on records belonging to the named authority.
  • CreateGid(credentials, xrn[ ,cert]): Creates a signed credential for the specified object. The record will be stored both in the SFA database and the PLC one.
  • GetGids(xrns, credentials): Provides a list of record information (HRN, GID and type) for the specified objects.
  • GetSelfCredential(cert, xrn, type): Retrieves the credential of an object.
  • get_key_from_incoming_ip() Generates a new keypair and GID for requesting caller (component/node). This is a MyPLC-specific API call used by the component manager.

All operations are interpreted relative to a credential that specifies the context (authority) in which the operation is applied. For example, invoking Register() with a Credential that specifies planetlab.princeton and Type=Slice registers new slice with the Princeton slice authority.

Slice interface

The slice interface is used to create and control slices. It is provided both by the slice manager as well as by the aggregate manager.

  • GetTicket(xrn, credentials, RSpec, users, options): Provides a ticket for xrn (the HRN or URN of the slice) filled with information from the database, including resources and attributes such as user keys and initscripts. This ticket binds the slice to the right to allocate the requested resources. Whether or not the call succeeds depends on the local resources available, and the resource allocation policy implemeted on behalf of the resource owner. The operations below are grouped according to their functionality.

Operations for the creation of a slice:

  • RedeemTicket(ticket, credentials): Allows the principal to create slivers and bind new resources to existing slivers as defined by the ticket. (Note: The parameter credentials are not the credentials provided to create the ticket, but the ones that allow the caller to redeem a ticket, e.g. they don't need to allow the caller to instantiate the slice, just to redeem the ticket).
  • CreateSliver(slice_xrn, credentials, RSpec, users, options): Allocates resources to a slice. This operation is expected to be asynchronous, so the callers should check the status of the allocation by using SliverStatus().

Operations for the management of an already created slice:

  • UpdateSliver(slice_xrn, credentials, RSpec, users, options): Invoked to request additional resources as specified in the RSpec.
  • RenewSliver(slice_xrn, credentials, expiration_time, options): Renews the resources in a sliver, extending the lifetime of the slice.
  • Shutdown(slice_xrn, credentials): Performs an emergency shutdown of a sliver. This operation is intended for administrative use. The sliver is shutdown but remains available for further forensics.

Operations for the control of a slice:

  • Stop(xrn, credentials): Stops the specified slice.
  • Start(xrn, credentials): Starts the specified slice.
  • reset_slice(credentials, xrn[, origin_hrn]): Resets the specified slice.
  • DeleteSliver(xrn, credentials, options): Removes the slice from all nodes and frees the allocated resources.

Operations for information retrieval:

  • ListSlices(credentials, options): Lists the slices instantiated at this interface.
  • ListResources(credentials, options): Returns information about available resources or resources allocated to this slice. Among the options, it must be included the RSpec version.
  • SliverStatus(slice_xrn, credentials, options): Returns the status of a sliver.
sfa/interfaces.txt · Last modified: 2013/09/10 14:35 by leandro