Reference Documentation to access Grid‘5000 through the SFA AMv3 API

This documentation is aimed a client tool developpers. Users should rarely need to directly call the low-level APIs of Grid‘5000’s Aggregate Manager (AM), implementing the SFA AMv3 API, as client tools should be hidding these details from them, except maybe to build rspec documents that can be understood by Grid‘5000.

Access to the Grid‘5000 Aggregate Manager (Grid‘5000 AM)

The Grid‘5000 AM is located at https://am.grid5000.fr/. It is a version 3 aggregate manager.

A development version is reachable as https://am.grid5000.fr:8001/.

Getting Fed4FIRE+ credentials to interact with the Grid‘5000 AM

In the SFA world, servers only interact with clients that are identified with (SSL) certificates. Moreover, they will only authenticate clients with certificates signed by an authority they trust. To successfully interact with the Grid‘5000 AM, you will therefore need to get credentials that it will authenticate. For example, the Grid‘5000 AM should trust any certificate signed by a slice authority federated with Fed4FIRE+ (you can see those at https://portal.fed4fire.eu/certificates/).

If you don’t have such a certificate, please refer to the fed4fire website for instructions on how to request one.

Notes on the AMv3 Implementation for Grid‘5000

General comments

The Grid‘5000 Aggregate Manager is implementated as a plugin to the geni-tools reference implementation made available on github. It is limited to information publishing, so Grid‘5000 can be discovered and browsed using SFA clients. Neverthless, many Grid‘5000 features are not visible using this API.

GetVersion

Grid‘5000’s GetVersion call publish links to sources where the status of Grid‘5000 can be queried, in particular current and planned maintenance events, as well as any acknowledged incident. It is published in many machine readable formats, as well as a Grid‘5000 status page. Details of the information available is in the rspec documents page.

ListResources

The output of ListResources can safely be shared between different callers. Any resource that is specific to a caller is only published by Describe. In particular, any privately-shared disk image applicable to nodes is no visible in ListResources.

The AM implements for the experimental informational hwinfo namespace, meaning that clients can get additional information about the hardware_types advertised in the classic advertisment rspec.

ListResources supports the following options

  • available: only list available nodes in the advertisement rspec. Set to false by default.
  • besteffort_as_available: show resources running low priority jobs as available. Set to true by default, but this can be overridden in the AM’s config file, so real deployments could have a different default.
  • geni_compressed: send the result compressed. Set to false by default.
  • pretty_output: pretty format the advertisement rspec. This is used in unit testing to as to ease comparaison between real output and expected output and in debugging sessions. Set to false by default.

The AM implements link stitching with other testbed. The available stitching are exposed in the advertisment rspec in two ways:

  1. The advertisment manifest contains fake nodes representing possible external stitchings to vlans in other testbeds. Such nodes are identified by their sliver_type set to fake and their hardware_type set to edge-vlan.
  2. The AM implements the protogeni stitchin extention namesapce, providing stitching informations for stitching computation server.

Allocate

Allocate will start resources for immediate use. If a resources is not immediately available the request with fail. No advance reservation mechanism is available at this time.

Allocation can happen only once per slice. The allocation with last as long as the provided slice credential or to the time specified using the endTime option.

Using the request RSpec, the user can request :

  • A specific node, by specifying the node’s component_id.
  • A random node on a specific cluster, by specifying a single hardware_type element.
  • A random node on a specific site, by using component_manager_id of a specific site.
  • A specific environment by specifying the disk_image of an environment .
  • A link between two or more nodes.
  • A link stitched to another testbeds link.

If multiple contradictory information are provided for a node, the AM will only consider the most specific request.

All node can connect to internet.

The number of available link on the whole testbed is limited.

Allocations expire after 10min if not provisioned.

Provision

The AM does not support adding users and ssh keys, using the users option at this time.

Node for which specific images have not been requested should become available almost immediately.

Nodes involved in a link will require a deployment. If no image is provided Grid‘5000 default environement will be deployed.

Describe

As described in the manifest RSpec SSH connections require user to first connect to access.grid5000.fr. Connection are done using your Grid‘5000 account, given in the manifest Rspec, and your certificate key.

Connections to the nodes are done to the root account for nodes where an image has been deployed and to your Grid‘5000 account for nodes without any deployments.

Renew

This AM does not allow renewing allocated or provisioned slivers, at this time.