GENI AM API Changes from version 2 to version 3

This page documents changes to the GENI Aggregate Manager API from version 2 to version 3. It consists of the text describing the changes to the API which was used to define and adopt the changes to the API for version 3.

• Version 2 of the GENI Aggregate Manager API
• Version 3 of the GENI Aggregate Manager API
• Draft changes to the GENI Aggregate Manager API for future versions. That is where this text originally was written.

Summary of Changes

This version of the AM API includes multiple changes since version 2 of the AM API. For experimenters, a few things are worth noting:

• The old CreateSliver operation has now been broken into 3 steps:
  • Allocate to reserve the resources
  • Provision to instantiate the resources, which may take time to complete
  • PerformOperationalAction(geni_start) to start (e.g. boot) the resources, which also may take time to complete
• Use the new intermediate geni_allocated state after Allocate to coordinate reservations across aggregates, e.g. to ensure another aggregate can give you nodes to be the other end of a requested link.
• Multiple methods have been renamed, typically by removing the Sliver term from method names.
• Sliver expiration is available in the return from multiple other methods, like Provision
• You no longer use ListResources to see the contents of your slice - use Describe instead. ListResources is only for the AM's Ad RSpec.
• Experimenters can select when to start or stop resources, e.g. when to boot a VM. Consult the operational state machine in the AM's Ad RSpec, and use PerformOperationalAction.
• SSH login names and keys should be available in manifest RSpecs in a standard format.
• Slice name restrictions have been codified and standardized.
  • Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): '^[a-zA-Z0-9][-a-zA-Z0-9]+$'

Tool developers should also be aware:

• The credentials argument to methods is now a struct, including a type and version for each credential. AMs should advertise which credential types they accept. SAs should advertise which type they provide.
• Aggregates may have their own operational states and actions. The Ad RSpec should define these, probably by sliver_type.

Listing of the Change Sets:

• Change Set D: Slivers: Change methods to clarify that there may be multiple slivers per slice at an AM, and to allow operating on individual slivers
• Change Set F3: Sliver Allocation States and methods
• Change Set F4: Method to perform Sliver Operational actions
• Change Set F5: Sliver Operational States
• Change Set G: Generalize the credentials argument, allowing ABAC support
• Change Set I1: SliversStatus return structure includes sliver expiration
• Change Set I2: SliversStatus return includes SSH logins/key for nodes that support SSH access
• Change Set I3: CreateSlivers return becomes a struct, adds sliver expiration
• Change Set K: Standardize certificate contents, etc.
  • Include a real serial number, holder email, holder uuid, and optionally authority URL in certificates
  • Define slice ID as the UUID plus URN in slice certificates
  • Define slice name, sliver name, and user name restrictions, and similar for URNs
  • Publish schemas for credentials and certificates
• Change Set M: New method signatures, incorporating all previous adopted change sets

FIXME: Sub heading for each change set with a summary of the change set?

Adopted Change Details

FIXME: Sub heading for each change set with full text from the DRAFT page