Draft GENI Aggregate Manager API Proposals

Here are a list of changes to the GENI AM API we may propose for future adoption.

Change Set PG-A: Transactions

This change set allows experimenters to request atomic and lossless modifications to resources allocated at the AM. It adds a primitive which allows reliable distributed allocations (such as two-phase commits) to be built at higher layers. It can be applied for all updates, including the case of the initial request for resources.

It is intended as an alternative to GENI AM API change sets C and E, replacing proposed tickets for the purpose of transactional updates but not for the purposes of future reservations or brokers (tickets for those are expected to be specialised credentials, and are left for future specification).

Methods

1. BeginTransaction

   struct BeginTransaction( string slice_urn, string credentials[],
                            string rspec, struct users[], struct options )
   

   • Requests a change in the resources allocated to a slice. It can be used even if no slivers exist at all (in that case, in conjunction with CommitTransaction, it behaves like a generalised variant of CreateSliver).
   • The slice must be in the uninitialised or allocated state. If BeginTransaction is invoked from the transaction state, the result is an INPROGRESS error.
   • No changes to the resources are made immediately. Any successful modifications are left pending, and are subject to future negotiation with UpdateTransaction, resolution with CommitTransaction, or lossless rollback with AbortTransaction.
   • All parameters are interpreted as those for the version 2 CreateSliver.
   • AMs choosing to implement transactions must accept full GENI v3 RSpecs in the rspec parameter (in which case the RSpec represents the entire desired state upon commit --- not a diff). AMs may also choose to allow other RSpec formats (possibly native RSpecs and/or diffs).
   • An RSpec extension (to be specified) will allow state retention requests to be made.
   • In future, the credentials array may include one or more tickets to allow the redemption of resource reservations. However, the format of tickets and mechanisms for obtaining them are not yet specified.
   • The return value is identical to that of the CreateSliver --- either an RSpec of some type, or (if GENI Change Set I3 is adopted) a struct containing an RSpec and other data.
     • When the input rspec is a GENI v3 request, the result RSpec is an annotated version of that input. Among other annotations, the AM might choose to add RSpec extensions (to be specified) describing what state retention guarantees are promised. If that extension is missing, no guarantees are made.
     • If the input is some other RSpec format, then the result RSpec should be a full (not a diff) RSpec of a form specified by the AM.
     • If GENI Change Set I3 is adopted, the result struct may contain any member specified for the CreateSlivers result struct, and also an additional member:

       string commit_by=<RFC3339 transaction expiration>
       

       If no subsequent CommitTransaction or AbortTransaction succeeds on slice_urn at the AM before the expiration time, the AM may automatically invoke AbortTransaction. A subsequent UpdateTransaction might modify the commit_by time.
   • Result state: transaction.
2. UpdateTransaction

   struct UpdateTransaction( string slice_urn, string credentials[],
                             string rspec, struct users[], struct options )
   

   • Modifies the state requested by an ongoing transaction. The parameters are interpreted as those for CreateSliver and BeginTransaction.
   • The slice must be in the transaction state. If it is not, UpdateTransaction returns ERROR.
   • The return value is identical to that specified by BeginTransaction.
   • Upon failure, any existing transaction is still open and in the same state as prior to UpdateTransaction invocation.
   • Result state: transaction.
3. CommitTransaction

   struct CommitTransaction( string slice_urn, string credentials[],
                             struct options )
   

   • Applies the resource changes requested in the most recent BeginTransaction or UpdateTransaction.
   • The slice must be in the transaction state. If it is not, CommitTransaction returns ERROR.
   • Following a successful BeginTransaction or UpdateTransaction, the AM should not reject the commit operation simply because the requested resources have been allocated to another slice. It might still be possible for the commit to fail for other reasons.
   • The return value is a manifest, identical to that described for the version 2 CreateSliver (modified by GENI Change Set I3 if approved). (In fact, CreateSliver can be interpreted as an atomic BeginTransaction and CommitTransaction.)
   • Result state: allocated.
4. AbortTransaction

   struct AbortTransaction( string slice_urn, string credentials[],
                             struct options )
   

   • Reverts the slice to its previous state before the transaction was begun.
   • The slice must be in the transaction state. If it is not, AbortTransaction returns ERROR.
   • Returns true on success and false on failure. true means a transaction in progress has been aborted, and false means that no state change has been made.
   • In neither case is the state on any instantiated sliver(s) modified.
   • Result state: the original state before BeginTransaction --- either uninitialised or allocated.