Skip to content. | Skip to navigation

Personal tools

Navigation

You are here: Home / Wiki / Geniaggregatemanager

Geniaggregatemanager

Implementation Notes

ProtoGENI versions after stable-20100714 include the GENI Aggregate Manager API. The GENI Aggregate Manager API in ProtoGENI is an additional API; it does not replace any of the ProtoGENI APIs.

Implementation Notes

The GENI Aggregate Manager API is very similar to the minimal ProtoGENI Component Manager API Version 2. The implementation of the GENI AM API follows the adapter pattern, translating AM calls into CMV2 calls. Here is the method mapping:

AM Operation CM V2 Operation Notes
GetVersion None Handled directly in the AM.
ListResources DiscoverResources Under most circumstances.
ListResources Resolve If a slice_urn is specified in the options.
CreateSliver CreateSliver
SliverStatus SliverStatus
RenewSliver RenewSlice
DeleteSliver DeleteSlice
Shutdown Shutdown

The implementation can be found in the file protogeni/lib/GeniAM.pm in the source distribution.

Limitations

Current

There are no known limitations in the current version of ProtoGENI (stable-20110420)

Prior to stable-20110420

Note: This limitation only applies to ProtoGENI sites running versions older than stable-20110420

The ProtoGENI implementation of the GENI AM API creates a single user on a compute node. The ProtoGENI implementation only accepts a user with a URN that matches the URN of the user invoking the CreateSliver operation. If no matching URN is found, no SSH keys are installed in the compute node.

For example, assume CreateSliver is invoked with the following users array:

[
  {
    urn: urn:publicid:IDN+emulab.net+user+alice
    keys: [<ssh key A>, <ssh key B>]
  },
  {
    urn: urn:publicid:IDN+emulab.net+user+bob
    keys: [<ssh key C>]
  }
]

If CreateSliver is invoked by Alice (whose URN is "urn:publicid:IDN+emulab.net+user+alice"), ssh key A and ssh key B will be installed on the compute nodes and ssh key C will be ignored.

If CreateSliver is invoked by Bob (whose URN is "urn:publicid:IDN+emulab.net+user+bob"), ssh key C will be installed on the compute nodes and ssh keys A and B will be ignored.

If CreateSliver is invoked by Carol (whose URN is "urn:publicid:IDN+emulab.net+user+carol"), all three ssh keys (A, B, and C) will be ignored and no keys will be installed on the compute nodes.

Differences from ProtoGENI APIs

Arguments

ProtoGENI XML-RPC interface methods all take a single argument which is a hash (Perl terminology). Python calls it a dict, Java calls it a Map, XML-RPC calls it a struct. Whatever you call it, it is a set of key-value pairs.

The GENI AM API uses positional arguments instead.

So to put things in pure Python terms, the ProtoGENI call would go something like this:

pg_args = {'credentials' : [ <cred1>, <cred2>], 'available' : True, 'compress' : True}
result = DiscoverResources(pg_args)

The GENI AM API equivalent is:

result = ListResources([<cred1>, <cred2>], {'geni_available' : True, 'geni_compress' : True})

Return Values

The result of the above invocations is different as well. ProtoGENI returns a hash (dict, Map, struct) no matter what. There are always three keys in the result map: code, value, output. If all goes well, the code key will have a zero value, and the value key holds the real result, and it should be the type documented on the ProtoGENI API wiki page. If all does not go well, code will be non-zero and output will have a useful string. More detailed information is available at wiki:XMLRPCInterface.

The GENI AM API returns the type as documented - a simple return value. In the case of an error an XML-RPC Fault is thrown (a standard XML-RPC error mechanism).

Enabling the API

Version stable-20100914 and later

The GENI AM API is automatically enabled in ProtoGENI in version stable-20100914 and later versions.

Version stable-20100714

Before following these steps, consider updating to a more recent version of ProtoGENI. This version is quite out of date.

  1. The first step is to install ProtoGENI.
  2. Next, edit /etc/rc.conf and add an additional flag to the apache_flags. Find the line that looks like this:
    apache_flags="-DSSL -DPGENI"
    
    Add the -DGENI_AM flag so it looks like this:
    apache_flags="-DSSL -DPGENI -DGENI_AM"
    
  3. Restart apache:
    sudo /usr/local/etc/rc.d/apache.sh restart 
    
  4. Test it by running one of the AM test scripts
    cd protogeni/test
    am/getversion.py
    
    You should see the following result (or similar):
    {'geni_api': 1}
    

Test scripts

Test scripts for the GENI AM API are included with the ProtoGENI test scripts. See the test scripts page for download and setup information.

There is no test script for the Shutdown operation. This is intended as an administrative function and requires recovery procedures to undo its effects.

Note: These scripts must be run from the .../protogeni/test directory.

getversion.py

Gets the version info for the aggregate manager. See GetVersion. This is analogous to CMV2 GetVersion.

Example invocation

$ am/getversion.py
{'geni_api': 1}

listresources.py

Lists the resources available at the aggregate manager. The output is a ProtoGENI RSpec. See ListResources. This is analogous to CMV2 DiscoverResources.

Note: The output can be voluminous so it is best to redirect it to a file.

Example invocation

$ am/listresources.py > /tmp/advertisement.rspec

createsliver.py

Creates a sliver at the aggregate. See CreateSliver. This is analogous to CMV2 CreateSliver.

Example invocation

$ am/createsliver.py -n am-test
Got my SA credential
No such slice registered here:Creating new slice called am-test
New slice created
Creating the Sliver ...
Created the sliver
<rspec...

The manifest RSpec is printed by createsliver.py, but has been removed from the sample output.

sliverstatus.py

Gets the status of the sliver. See SliverStatus. This is analogous to CMV2 SliverStatus.

Example invocation

$ am/sliverstatus.py -n am-test
Got my SA credential. Looking for slice ...
Found the slice, asking for a credential ...
Got the slice credential, asking for a sliver credential ...
{ 'geni_resources': [ { 'geni_error': '',
                        'geni_status': 'ready',
                        'geni_urn': 'urn:publicid:IDN+emulab.net+sliver+311'}],
  'geni_status': 'ready',
  'geni_urn': 'Unknown'}

renewsliver.py

Renews the sliver. See RenewSliver. This is analogous to CMV2 RenewSlice.

Note: The numeric argument is the number of minutes. This matches the arguments to test/renewsliver.py.

Example invocation

$ am/renewsliver.py -n am-test 480
Got my SA credential
Found the slice, asking for a credential ...
Got the slice credential, renewing the slice at the SA ...
Renewed the slice, asking for slice credential again
Got the slice credential, renewing the sliver
Sliver has been renewed until 20101012T01:08:17

deletesliver.py

Deletes the sliver. See DeleteSliver. This is analogous to CMV2 DeleteSliver.

Example invocation

$ am/deletesliver.py -n am-test
Got my SA credential. Looking for slice am-test...
Found the slice, asking for a credential ...
Got the slice credential, deleting the sliver...
Sliver am-test has been deleted.