| | 1 | |
| | 2 | [[PageOutline]] |
| | 3 | |
| | 4 | = GENI AM API Changes from version 2 to version 3 = |
| | 5 | |
| | 6 | This page documents changes to the GENI Aggregate Manager API from [wiki:GAPI_AM_API_V2 version 2] to [wiki:GAPI_AM_API_V3 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. |
| | 7 | * [wiki:GAPI_AM_API_V2 Version 2 of the GENI Aggregate Manager API] |
| | 8 | * [wiki:GAPI_AM_API_V3 Version 3 of the GENI Aggregate Manager API] |
| | 9 | * [wiki:GAPI_AM_API_DRAFT Draft changes to the GENI Aggregate Manager API] for future versions. That is where this text originally was written. |
| | 10 | |
| | 11 | == Summary of Changes == |
| | 12 | |
| | 13 | This version of the AM API includes multiple changes since version 2 of the AM API. For experimenters, a few things are worth noting: |
| | 14 | - The old `CreateSliver` operation has now been broken into 3 steps: |
| | 15 | - `Allocate` to reserve the resources |
| | 16 | - `Provision` to instantiate the resources, which may take time to complete |
| | 17 | - `PerformOperationalAction(geni_start)` to start (e.g. boot) the resources, which also may take time to complete |
| | 18 | - 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. |
| | 19 | - Multiple methods have been renamed, typically by removing the `Sliver` term from method names. |
| | 20 | - Sliver expiration is available in the return from multiple other methods, like `Provision` |
| | 21 | - You no longer use `ListResources` to see the contents of your slice - use `Describe` instead. `ListResources` is only for the AM's Ad RSpec. |
| | 22 | - 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`. |
| | 23 | - SSH login names and keys should be available in manifest RSpecs in a standard format. |
| | 24 | - Slice name restrictions have been codified and standardized. |
| | 25 | - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): `'^[a-zA-Z0-9][-a-zA-Z0-9]+$'` |
| | 26 | |
| | 27 | Tool developers should also be aware: |
| | 28 | - 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. |
| | 29 | - Aggregates may have their own operational states and actions. The Ad RSpec should define these, probably by `sliver_type`. |
| | 30 | |
| | 31 | Listing of the Change Sets: |
| | 32 | - [#ChangeSetD:Sliver-specificoperations 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 |
| | 33 | - [#ChangeSetF3:SliverAllocationStatesandmethods Change Set F3]: Sliver Allocation States and methods |
| | 34 | - [#ChangeSetF4:SliverOperationsMethod Change Set F4]: Method to perform Sliver Operational actions |
| | 35 | - [#ChangeSetF5:SliverOperationalStates Change Set F5]: Sliver Operational States |
| | 36 | - [#Adopted:ChangeSetG:Credentialsaregeneralauthorizationtokens. Change Set G]: Generalize the credentials argument, allowing ABAC support |
| | 37 | - Change Set I1: !SliversStatus return structure includes sliver expiration |
| | 38 | - Change Set I2: !SliversStatus return includes SSH logins/key for nodes that support SSH access |
| | 39 | - Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration |
| | 40 | - [#Adopted:ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc. |
| | 41 | - Include a real serial number, holder email, holder uuid, and optionally authority URL in certificates |
| | 42 | - Define slice ID as the UUID plus URN in slice certificates |
| | 43 | - Define slice name, sliver name, and user name restrictions, and similar for URNs |
| | 44 | - Publish schemas for credentials and certificates |
| | 45 | - [#ChangeSetM:NewMethodSignatures Change Set M]: New method signatures, incorporating all previous adopted change sets |
| | 46 | |
| | 47 | '''FIXME''': Sub heading for each change set with a summary of the change set? |
| | 48 | |
| | 49 | == Adopted Change Details == |
| | 50 | |
| | 51 | '''FIXME''': Sub heading for each change set with full text from the DRAFT page |
