API tutorial

From Grid5000
Revision as of 12:01, 11 January 2021 by Snoir (talk | contribs)
Jump to navigation Jump to search
See also: API | API tutorial | API specification
Note.png Note

This page is actively maintained by the Grid'5000 team. If you encounter problems, please report them (see the Support page). Additionally, as it is a wiki page, you are free to make minor corrections yourself if needed. If you would like to suggest a more fundamental change, please contact the Grid'5000 team.

Introduction

This tutorial will help you learning how to interact with Grid'5000's API, using simple example (with the curl tool to interact with the API, and sometimes jq to parse the JSON result). We target people who want a remote and programmatic access to the Grid'5000 tools in order to monitor nodes, submit jobs, and deploy environments.

Other aspects (how to access, versioning, content negotiating, authentication, …) of the API are mentioned in the general page about the Grid'5000 API.

The goal of this tutorial is not to present all the possibilities of the API, a specification of the API (which is more precise and complete) is available for each variant (stable and sid) here: https://api.grid5000.fr/doc/

Note.png Note

In this tutorial curl will be launched without requiring credentials (as if we were on a Grid'5000 frontend). Credentials are not needed from within Grid'5000, but are required from outside, as described here.

Reference API

The Reference API exposes Grid'5000's reference-repository: the single source of truth about sites, clusters, nodes, and network topology (the platform inventory on steroids).

The resources that can be queried are described in the documentation of each API. Resources are identified by a relative URI, which should be added to the end of the API entry-point to form the URL.

For example, /sites/rennes is a resource exposed by the Reference API. If you would like to get the representation of this resource as it is returned by the 3.0 version of the Grid'5000 API, the URL to enter in your HTTP client would be: 

curl https://api.grid5000.fr/3.0/sites/rennes

As an other example, to get the list of sites, the URL will be: 

curl https://api.grid5000.fr/3.0/sites

For a particular cluster: 

curl https://api.grid5000.fr/3.0/sites/rennes/clusters/paravance/

Versioning

The resources exposed by the Reference API are described in the reference-repository, which is a Git repository. Therefore, the API offers the possibility to list the latest changes in the Grid'5000 infrastructure or to fetch resources description for a specific version or at a specific time.

List versions

Each URL resources can be suffixed with /versions to get a list of versions (Git commit). For example: 

$ curl https://api.grid5000.fr/3.0/sites/rennes/clusters/versions?pretty
 "total": 392,
 "offset": 0,
 "items": [
   {
     "uid": "68fdd053e6767ba2da1edf5105f57ff7b963f91f",
     "date": "Thu, 03 Dec 2020 09:56:38 GMT",
     "message": "[all] upgrade postinstall",
     "author": "Author",
     "type": "version",
     "links": [
       {
         "rel": "self",
         "href": "/3.0/sites/rennes/clusters/versions/68fdd053e6767ba2da1edf5105f57ff7b963f91f",
         "type": "application/vnd.grid5000.item+json"
       },
       {
         "rel": "parent",
         "href": "/3.0/sites/rennes/clusters",
         "type": "application/vnd.grid5000.item+json"
       }
     ]
   },
   {
     "uid": "5d9b32e3f6f0eb63608274d028994e99ea4c0698",
     "date": "Fri, 20 Nov 2020 17:20:33 GMT",
     "message": "[all] Add prometheus metrics to all clusters",
     "author": "Author",
     "type": "version",

And following the logic behind the API, each item can be accessed, like https://api.grid5000.fr/3.0/sites/rennes/clusters/versions/68fdd053e6767ba2da1edf5105f57ff7b963f91f

Get resources for a version

To get a resource description for specific version of the reference-repository, the version *GET* parameter can be added to the request. For example, to get on old description of the node dahu-29 of Grenoble: 

$ curl "https://api.grid5000.fr/3.0/sites/grenoble/clusters/dahu/nodes/dahu-29?pretty&version=0c1396da414cca75faadd7b52fbb4fea11667213"

It is also possible to Get the reference-repository at a specific time, using the date or timestamp *GET* parameters. With a UNIX timestamp: 

$ curl "https://api.grid5000.fr/3.0/sites/grenoble/clusters/dahu/nodes/dahu-29.json?pretty&timestamp=1606400407"

Jobs API

The Jobs API allows to reserve resources of the testbed, using OAR underneath. You can find more about OAR on the Advanced OAR page.

Job submission

This API is a thin wrapper on top of the OAR tool, therefore most of the oarsub options are supported.

For instance, let's submit a job with 2 nodes of the grenoble site, for 2 hours. And let's say we want to launch a useless script that just sleeps forever when the job starts: 

$ curl -i https://api.grid5000.fr/3.0/sites/grenoble/jobs?pretty -X POST -H'Content-Type: application/json' -d '{"resources": "nodes=2,walltime=02:00", "command": "while(true); do sleep 5; echo \"awake\"; done"}'
HTTP/1.1 201 Created
Date: Thu, 03 Dec 2020 14:47:57 GMT
Server: thin
Content-Type: application/json; charset=utf-8
Location: https://api.grid5000.fr/3.0/sites/grenoble/jobs/1965464
Content-Length: 818
ETag: W/"40668ba7ef11e54db1ef39adc09bddcf"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: f705fc66-bfbf-459b-954d-cc722ff1914f
X-Runtime: 0.642098
Via: 1.1 api-server-v3.grenoble.grid5000.fr:4444
X-Api-Auth-Type: IDENT
X-Api-User-CN: auser
X-Remote-Ident: auser
X-Kadeploy-User: auser

{
 "uid": 1965464,
 "user_uid": "auser",
 "user": "auser",
 "walltime": 7200,
 "queue": "default",
 "state": "waiting",
 "project": "g5k-staff",
 "types": [
   "monitor=prom_.*default_metrics"
 ],
 "mode": "PASSIVE",
 "command": "./oarapi.subscript.IEtz0",
 "submitted_at": 1607006878,
 "started_at": 0,
 "message": "R=64,W=2:0:0,J=B,P=g5k-staff,T=monitor=prom_.*default_metrics",
 "properties": "maintenance = 'NO'",
 "directory": "/home/auser",
 "events": [
  
 ],
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/jobs/1965464",
     "type": "application/vnd.grid5000.item+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble",
     "type": "application/vnd.grid5000.item+json"
   }
 ],
 "resources_by_type": {
 },
 "assigned_nodes": [
 
 ]
}

Status code is 201 Created, which means a new job resource has been created. You can find the URI of that new job resource in the Location HTTP header: https://api.grid5000.fr/3.0/sites/grenoble/jobs/1965464 The job is in the waiting state at first, but then will go to the running state. 

{
 "uid": 1965464,
 "user_uid": "auser",
 "user": "auser",
 "walltime": 7200,
 "queue": "default",
 "state": "running",
 "project": "g5k-staff",
 "types": [
   "monitor=prom_.*default_metrics"
 ],
 "mode": "PASSIVE",
 "command": "./oarapi.subscript.IEtz0",
 "submitted_at": 1607006878,
 "scheduled_at": 1607006880,
 "started_at": 1607006880,
 "message": "FIFO scheduling OK",
 "properties": "maintenance = 'NO'",
 "directory": "/home/auser",
 "events": [
 
 ],
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/jobs/1965464",
     "type": "application/vnd.grid5000.item+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble",
     "type": "application/vnd.grid5000.item+json"
   }
 ],
 "resources_by_type": {
   "cores": [
     "dahu-3.grenoble.grid5000.fr/0",
     "dahu-3.grenoble.grid5000.fr/1",
     "dahu-3.grenoble.grid5000.fr/2",
     "dahu-3.grenoble.grid5000.fr/3",
     "dahu-3.grenoble.grid5000.fr/4",
     "dahu-3.grenoble.grid5000.fr/5",
     "dahu-3.grenoble.grid5000.fr/6",
     "dahu-3.grenoble.grid5000.fr/7",
     "dahu-3.grenoble.grid5000.fr/8",
     "dahu-3.grenoble.grid5000.fr/9",
     "dahu-3.grenoble.grid5000.fr/10",
     "dahu-3.grenoble.grid5000.fr/11",
     "dahu-3.grenoble.grid5000.fr/12",
     "dahu-3.grenoble.grid5000.fr/13",
     "dahu-3.grenoble.grid5000.fr/14",
     "dahu-3.grenoble.grid5000.fr/15",
     "dahu-3.grenoble.grid5000.fr/16",
     "dahu-3.grenoble.grid5000.fr/17",
     "dahu-3.grenoble.grid5000.fr/18",
     "dahu-3.grenoble.grid5000.fr/19",
     "dahu-3.grenoble.grid5000.fr/20",
     "dahu-3.grenoble.grid5000.fr/21",
     "dahu-3.grenoble.grid5000.fr/22",
     "dahu-3.grenoble.grid5000.fr/23",
     "dahu-3.grenoble.grid5000.fr/24",
     "dahu-3.grenoble.grid5000.fr/25",
     "dahu-3.grenoble.grid5000.fr/26",
     "dahu-3.grenoble.grid5000.fr/27",
     "dahu-3.grenoble.grid5000.fr/28",
     "dahu-3.grenoble.grid5000.fr/29",
     "dahu-3.grenoble.grid5000.fr/30",
     "dahu-3.grenoble.grid5000.fr/31",
     "dahu-32.grenoble.grid5000.fr/0",
     "dahu-32.grenoble.grid5000.fr/1",
     "dahu-32.grenoble.grid5000.fr/2",
     "dahu-32.grenoble.grid5000.fr/3",
     "dahu-32.grenoble.grid5000.fr/4",
     "dahu-32.grenoble.grid5000.fr/5",
     "dahu-32.grenoble.grid5000.fr/6",
     "dahu-32.grenoble.grid5000.fr/7",
     "dahu-32.grenoble.grid5000.fr/8",
     "dahu-32.grenoble.grid5000.fr/9",
     "dahu-32.grenoble.grid5000.fr/10",
     "dahu-32.grenoble.grid5000.fr/11",
     "dahu-32.grenoble.grid5000.fr/12",
     "dahu-32.grenoble.grid5000.fr/13",
     "dahu-32.grenoble.grid5000.fr/14",
     "dahu-32.grenoble.grid5000.fr/15",
     "dahu-32.grenoble.grid5000.fr/16",
     "dahu-32.grenoble.grid5000.fr/17",
     "dahu-32.grenoble.grid5000.fr/18",
     "dahu-32.grenoble.grid5000.fr/19",
     "dahu-32.grenoble.grid5000.fr/20",
     "dahu-32.grenoble.grid5000.fr/21",
     "dahu-32.grenoble.grid5000.fr/22",
     "dahu-32.grenoble.grid5000.fr/23",
     "dahu-32.grenoble.grid5000.fr/24",
     "dahu-32.grenoble.grid5000.fr/25",
     "dahu-32.grenoble.grid5000.fr/26",
     "dahu-32.grenoble.grid5000.fr/27",
     "dahu-32.grenoble.grid5000.fr/28",
     "dahu-32.grenoble.grid5000.fr/29",
     "dahu-32.grenoble.grid5000.fr/30",
     "dahu-32.grenoble.grid5000.fr/31"
   ]
 },
 "assigned_nodes": [
   "dahu-3.grenoble.grid5000.fr",
   "dahu-32.grenoble.grid5000.fr"
 ]
}

Now the job is now in the running state, and you can find the list of nodes (independently of how many cores you reserved on each node) assigned to your job in the assigned_nodes property. Also note the resources_by_type property, which lists all the resources by type (nodes, vlans, subnets, disks). For nodes type, there is an entry per core reserved on the node.

Note.png Note

API resources (i.e. objects managed by the API) are not to be confused with OAR resources (i.e. compute nodes, CPUs, cores, GPUs, disks, or VLANs, or subnets).

You should now be able to connect to your nodes using the job uid and the oarsub tool (see the Advanced OAR page).

Job deletion

Since the previous job is doing nothing, we can delete it to free the nodes for other users. To do this, just send a http request with the DELETE method on the job URI: 

$ curl  -i -X DELETE https://api.grid5000.fr/3.0/sites/grenoble/jobs/1965464
HTTP/1.1 202 Accepted
Date: Thu, 03 Dec 2020 15:17:18 GMT
Server: thin
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
X-Oar-Info: Deleting the job = 1965464 ...REGISTERED. The job(s) [ 1965464 ] will be deleted in the near future.
Location: https://api.grid5000.fr/3.0/sites/grenoble/jobs/1965464
Content-Type: text/plain; charset=utf-8
Cache-Control: no-cache
X-Request-Id: 2c256e0f-c623-4522-9df2-c11ea200a32f
X-Runtime: 0.230989
Via: 1.1 api-server-v3.grenoble.grid5000.fr:4444
X-Api-Auth-Type: IDENT
X-Api-User-CN: auser
X-Remote-Ident: auser
X-Kadeploy-User: auser
Transfer-Encoding: chunked

Deletion is not immediate, that's why you receive a 202 Accepted status code, which means that the request will be handled shortly thereafter.

Deployments API

Deployments API allows deploying an environment on nodes, using Kadeploy. You can find more about Kadeploy on the Advanced Kadeploy page.

Reserve nodes

An OAR job of type deploy is required to perform a deployment. The following creates the job: 

$ curl https://api.grid5000.fr/3.0/sites/grenoble/jobs -X POST -H 'Content-Type: application/json' -d '{"resources": "nodes=2", "types": ["deploy"], "command": "sleep 3600"}'

If everything goes well, you’ll receive a 201 created: 

HTTP/1.1 201 Created
Date: Thu, 03 Dec 2020 13:34:22 GMT
Server: thin
Content-Type: application/json; charset=utf-8
Location: https://api.grid5000.fr/3.0/sites/grenoble/jobs/1965452
Content-Length: 625
X-Info: Use `?pretty=yes` or add the HTTP header `X-Rack-PrettyJSON: yes` if you want pretty output.
ETag: W/"bca9a34873d997ae8e0da4a829daae9d"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 64bc2472-459d-4e29-a46d-50d893f75e47
X-Runtime: 0.648162
X-Api-Auth-Type: IDENT
X-Api-User-CN: auser
X-Remote-Ident: auser
X-Kadeploy-User: auser

 {
 "uid": 1965460,
 "user_uid": "auser",
 "user": "auser",
 "walltime": 3600,
 "queue": "default",
 "state": "waiting",
 "project": "g5k-staff",
 "types": [
   "deploy"
 ],
 "mode": "PASSIVE",
 "command": "./oarapi.subscript._o1nf",
 "submitted_at": 1607005232,
 "started_at": 0,
 "message": "R=64,W=1:0:0,J=B,P=g5k-staff,T=deploy",
 "properties": "(deploy = 'YES') AND maintenance = 'NO'",
 "directory": "/home/auser",
 "events": [],
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/jobs/1965460",
     "type": "application/vnd.grid5000.item+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble",
     "type": "application/vnd.grid5000.item+json"
   }
 ],
 "resources_by_type": {},
 "assigned_nodes": []
}

Using the job URI given in the Location header. We have to wait for the job to be running: It is possible to poll the Jobs API until the job is in running state: 

$ curl -s https://api.grid5000.fr/3.0/sites/grenoble/jobs/1965460 | jq '.assigned_nodes,.state'
[
  "dahu-13.grenoble.grid5000.fr",
  "dahu-17.grenoble.grid5000.fr"
]
"running"

We also extract the assigned_nodes to use them later.

Deploy

Now, we use the nodes list provided by our OAR reservation, and launch a deployment: 

$ export SSH_PUBLIC_KEY=`cat ~/.ssh/id_rsa.pub` # replace with your Grid'5000 public key.
$ curl -i https://api.grid5000.fr/3.0/sites/grenoble/deployments -H'Content-Type: application/json' -d \
'{"nodes": ["dahu-13.grenoble.grid5000.fr", "dahu-17.grenoble.grid5000.fr"], "environment": "debian10-x64-min", "key": "$SSH_PUBLIC_KEY"}'

A 201 created response should be returned: 

HTTP/1.1 201 Created
Date: Thu, 03 Dec 2020 14:25:05 GMT
Server: thin
Content-Type: application/json; charset=utf-8
Location: https://api.grid5000.fr/3.0/sites/grenoble/deployments/D-d54fca72-ef30-47cc-bf6a-54b6223fd7e4
Content-Length: 612
X-Info: Use `?pretty=yes` or add the HTTP header `X-Rack-PrettyJSON: yes` if you want pretty output.
ETag: W/"6ab81705feaa1155d086378912a20230"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 9b052b75-a444-4641-8cd5-bc6c187dbb09
X-Runtime: 0.092125
Via: 1.1 api-server-v3.grenoble.grid5000.fr:4444
X-Api-Auth-Type: IDENT
X-Api-User-CN: auser
X-Remote-Ident: auser
X-Kadeploy-User: auser

{
 "uid": "D-9bd9e783-41fb-4b09-87e0-38522df086d8",
 "site_uid": "grenoble",
 "user_uid": "auser",
 "environment": "debian10-x64-min",
 "status": "processing",
 "key": "https://api.grid5000.fr/3.0/sites/grenoble/files/auser-key-c213083a4ce7e58bc2052f03c144a06afdf6cc4a",
 "nodes": [
   "dahu-13.grenoble.grid5000.fr",
   "dahu-17.grenoble.grid5000.fr"
 ],
 "created_at": 1607005453,
 "updated_at": 1607005453,
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/deployments/D-9bd9e783-41fb-4b09-87e0-38522df086d8",
     "type": "application/vnd.grid5000.item+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble",
     "type": "application/vnd.grid5000.item+json"
   }
 ]
}

Again, we can use the URI given in the Location header to poll the deployment status : 

$ curl -s https://api.grid5000.fr/3.0/sites/grenoble/deployments/D-9bd9e783-41fb-4b09-87e0-38522df086d8 | jq .status
"processing"

Later: 

$ curl -s https://api.grid5000.fr/3.0/sites/grenoble/deployments/D-9bd9e783-41fb-4b09-87e0-38522df086d8 | jq .status
"processing"

Once the deployment is over, the nodes are available and running the deployed environment as OS.

Vlans API

The Vlans API allows to manage or to get information about resources bounded to VLAN management: like Grid'5000 different types of VLANs, nodes interfaces or allowed users on a particular VLAN. This API interacts with the KaVLAN tool. More information about KaVLAN can be found on the Advanced_KaVLAN page.

Reserve VLAN and nodes

We start by reserving two nodes and a local kavlan (VLAN of type local) on the Grenoble site, using the Jobs API: 

$ curl -i https://api.grid5000.fr/3.0/sites/grenoble/jobs?pretty -X POST -H 'Content-Type: application/json' -d "{\"resources\":\"{type='kavlan-local'}/vlan=1,nodes=2\", \"types\": [\"deploy\"], \"command\": \"sleep 3600\"}"

HTTP/1.1 201 Created
Date: Thu, 10 Dec 2020 09:29:24 GMT
Server: thin
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
Location: https://api.grid5000.fr/3.0/sites/grenoble/jobs/1967224
Content-Length: 791
ETag: W/"eda5d6c6671165250f54b1d3aa933601"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 5888554a-e244-4825-b0e7-93fa468a3123
X-Runtime: 0.602346
Via: 1.1 api-server-v3.grenoble.grid5000.fr:4444
X-Api-Auth-Type: IDENT
X-Api-User-CN: auser
X-Remote-Ident: auser
X-Kadeploy-User: auser
  
{
 "uid": 1967227,
 "user_uid": "auser",
 "user": "auser",
 "walltime": 3600,
 "queue": "default",
 "state": "waiting",
 "project": "g5k-staff",
 "types": [
   "deploy"
 ],
 "mode": "PASSIVE",
 "command": "./oarapi.subscript.NZnb2",
 "submitted_at": 1607592564,
 "started_at": 0,
 "message": "R=65,W=1:0:0,J=B,P=g5k-staff,T=deploy",
 "properties": "(deploy = 'YES') AND maintenance = 'NO'",
 "directory": "/home/auser",
 "events": [
   
 ],
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/jobs/1967227",
     "type": "application/vnd.grid5000.item+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble",
     "type": "application/vnd.grid5000.item+json"
   }
 ],
 "resources_by_type": {
 },
 "assigned_nodes": [
  
 ]

We can then look at the job state (is it running?), the assigned nodes, and VLAN number: 

$ curl -s https://api.grid5000.fr/3.0/sites/grenoble/jobs/1967224 | jq '.state,.assigned_nodes,.resources_by_type.vlans'
"running"
[
 "dahu-6.grenoble.grid5000.fr",
 "dahu-7.grenoble.grid5000.fr"
]
[
 "2"
]

In a normal workflow, an image should be deployed on the nodes. We will skip this part to go directly to the VLAN management.

The VLAN we reserved can also be found using the Vlans API (in addition to with the Jobs API): 

$ curl https://api.grid5000.fr/3.0/sites/grenoble/vlans/users/auser?pretty
{
 "uid": "auser",
 "vlans": [
   "2",
   "1"
 ],
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/vlans/users/auser",
     "type": "application/vnd.grid5000.item+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble/vlans/users",
     "type": "application/vnd.grid5000.collection+json"
   }
 ]
}

In this response, we also have the VLAN number 1, which is part of another reservation we made.

The status of a given user for a specific VLAN can be found with this query:

$ curl https://api.grid5000.fr/3.0/sites/grenoble/vlans/2/users/auser?pretty 

{
 "uid": "auser",
 "status": "authorized",
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/vlans/2/users/auser",
     "type": "application/vnd.grid5000.item+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble/vlans/2/users",
     "type": "application/vnd.grid5000.collection+json"
   }
 ]
}

And a list of users with rights on a VLAN is given by the following query: 

curl https://api.grid5000.fr/3.0/sites/grenoble/vlans/2/users

(in fact with the current configuration on Grid'5000 only one user can have rights on a VLAN).

Manage nodes

To add our nodes to the reserved VLAN, we have to make a POST request to the API: 

$ curl -X POST https://api.grid5000.fr/3.0/sites/grenoble/vlans/2/nodes?pretty -H "Content-Type: application/json" -d '["dahu-5.grenoble.grid5000.fr","dahu-6.grenoble.grid5000.fr"]'
{
 "dahu-5.grenoble.grid5000.fr": {
   "status": "success",
   "message": "Successfully added to vlan"
 },
 "dahu-6.grenoble.grid5000.fr": {
   "status": "success",
   "message": "Successfully added to vlan"
 }
}

We can see them by listing nodes in the VLAN: 

$ curl https://api.grid5000.fr/3.0/sites/grenoble/vlans/2/nodes?pretty
{
 "total": 2,
 "offset": 0,
 "items": [
   {
     "uid": "dahu-5.grenoble.grid5000.fr",
     "vlan": "2",
     "links": [
       {
         "rel": "self",
         "href": "/3.0/sites/grenoble/vlans/nodes/dahu-5.grenoble.grid5000.fr",
         "type": "application/vnd.grid5000.item+json"
       },
       {
         "rel": "parent",
         "href": "/3.0/sites/grenoble/vlans/nodes",
         "type": "application/vnd.grid5000.collection+json"
       }
     ]
   },
   {
     "uid": "dahu-6.grenoble.grid5000.fr",
     "vlan": "2",
     "links": [
       {
         "rel": "self",
         "href": "/3.0/sites/grenoble/vlans/nodes/dahu-6.grenoble.grid5000.fr",
         "type": "application/vnd.grid5000.item+json"
       },
       {
         "rel": "parent",
         "href": "/3.0/sites/grenoble/vlans/nodes",
         "type": "application/vnd.grid5000.collection+json"
       }
     ]
   }
 ],
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/vlans/2/nodes",
     "type": "application/vnd.grid5000.collection+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble/vlans/2",
     "type": "application/vnd.grid5000.item+json"
   }
 ]
}

A list of all the known nodes in Kavlan and their current VLAN assignation is also available, with the following query: 

$ curl https://api.grid5000.fr/3.0/sites/grenoble/vlans/nodes?pretty
{
 "total": 52,
 "offset": 0,
 "items": [
   {
     "uid": "dahu-1.grenoble.grid5000.fr",
     "vlan": "DEFAULT",
     "links": [
       {
         "rel": "self",
         "href": "/3.0/sites/grenoble/vlans/nodes/dahu-1.grenoble.grid5000.fr",
         "type": "application/vnd.grid5000.item+json"
       },
       {
         "rel": "parent",
         "href": "/3.0/sites/grenoble/vlans/nodes",
         "type": "application/vnd.grid5000.collection+json"
       }
     ]
   },
   {
     "uid": "dahu-10.grenoble.grid5000.fr",
     "vlan": "DEFAULT",
     "links": [
       {
         "rel": "self",
         "href": "/3.0/sites/grenoble/vlans/nodes/dahu-10.grenoble.grid5000.fr",
         "type": "application/vnd.grid5000.item+json"
       },
       {
         "rel": "parent",
         "href": "/3.0/sites/grenoble/vlans/nodes",
         "type": "application/vnd.grid5000.collection+json"
       }
     ]
   },
  …

Manage dhcp server

Kavlan offers the possibility to have a dhcpd service running for a particular vlan.

If we don't want to use it, we can stop it with a simple PUT query: 

curl -X PUT https://api.grid5000.fr/3.0/sites/grenoble/vlans/2/dhcpd -H "Content-Type: application/json" -d '{"action":"stop"}'

Metrics APIs

At the moment, two metrics API are available, kwapi + ganglia (the first one for power consumption at the outlet, second for metrics collected on nodes) in the stable API, and kwollect for the sid one.

stable

The metrics are available on (here on Grenoble site) here: https://api.grid5000.fr/3.0/sites/grenoble/metrics

We can get discover the first metric with curl and jq: 

$ curl -s https://api.grid5000.fr/3.0/sites/grenoble/metrics | jq .items[0]
{
 "uid": "gpu1_temp",
 "available_on": [
   "drac-3.grenoble.grid5000.fr",
   "drac-4.grenoble.grid5000.fr",
   "drac-9.grenoble.grid5000.fr",
   "drac-5.grenoble.grid5000.fr",
   "drac-2.grenoble.grid5000.fr",
   "drac-12.grenoble.grid5000.fr",
   "drac-7.grenoble.grid5000.fr",
   "drac-11.grenoble.grid5000.fr",
   "drac-8.grenoble.grid5000.fr",
   "drac-6.grenoble.grid5000.fr",
   "drac-10.grenoble.grid5000.fr",
   "drac-1.grenoble.grid5000.fr"
 ],
 "timeseries": [
   {
     "cf": "AVERAGE",
     "xff": 0.5,
     "pdp_per_row": 1,
     "rows": 244
   },
   {
     "cf": "AVERAGE",
     "xff": 0.5,
     "pdp_per_row": 24,
     "rows": 244
   },
   {
     "cf": "AVERAGE",
     "xff": 0.5,
     "pdp_per_row": 168,
     "rows": 244
   },
   {
     "cf": "AVERAGE",
     "xff": 0.5,
     "pdp_per_row": 672,
     "rows": 244
   },
   {
     "cf": "AVERAGE",
     "xff": 0.5,
     "pdp_per_row": 5760,
     "rows": 374
   }
 ],
 "step": 15,
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/metrics/gpu1_temp",
     "type": "application/vnd.fr.grid5000.api.Metric+json;level=1"
   },
   {
     "rel": "collection",
     "href": "/3.0/sites/grenoble/metrics/gpu1_temp/timeseries",
     "title": "timeseries",
     "type": "application/vnd.fr.grid5000.api.Collection+json;level=1"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble",
     "type": "application/vnd.fr.grid5000.api.Site+json;level=1"
   }
 ],
 "type": "metric"
}

We can also directly call the right URI to get the metric: 

$ curl https://api.grid5000.fr/3.0/sites/grenoble/metrics/gpu1_temp/

For each metrics, a list a timeseries (the collected values) can be fetch: 

$ curl https://api.grid5000.fr/3.0/sites/grenoble/metrics/gpu1_temp/timeseries

This will output for each nodes with the timeseries available, with a default time range. It is possible with some parameters to limit to a list of nodes, and to give a specific time range. For example to limit to one node: 

 $ curl https://api.grid5000.fr/3.0/sites/grenoble/metrics/gpu1_temp/timeseries?only=drac-1.grenoble.grid5000.fr

Those parameters are documented in the API specification.

sid

See here for the Kwollect API tutorial.

Status API

The Status API allows getting OAR resources status and reservation (associated job), for a site or a cluster.

Cluster status

$ curl https://api.grid5000.fr/3.0/sites/grenoble/clusters/yeti/status?pretty
 "uid": 1607009770,
 "links": [
   {
     "rel": "self",
     "href": "/3.0/sites/grenoble/clusters/yeti/status",
     "type": "application/vnd.grid5000.item+json"
   },
   {
     "rel": "parent",
     "href": "/3.0/sites/grenoble/clusters/yeti",
     "type": "application/vnd.grid5000.item+json"
   }
 ],
 "disks": {
   "sdd.yeti-1.grenoble.grid5000.fr": {
     "hard": "alive",
     "soft": "free",
     "diskpath": "/dev/disk/by-path/pci-0000:18:00.0-scsi-0:0:3:0",
     "reservations": [
      
     ]
   },
   "sdd.yeti-2.grenoble.grid5000.fr": {
     "hard": "alive",
     "soft": "free",
     "diskpath": "/dev/disk/by-path/pci-0000:18:00.0-scsi-0:0:3:0",
     "reservations": [
      
     ]
   },
  …
 "nodes": {
   "yeti-1.grenoble.grid5000.fr": {
     "hard": "standby",
     "soft": "free",
     "comment": "OK",
     "reservations": [
        
     ],
     "free_slots": 64,
     "freeable_slots": 0,
     "busy_slots": 0
   },
   …

The status of a cluster contains the status of nodes and disks (if the cluster has reservable disks).

Site status

$ curl https://api.grid5000.fr/3.0/sites/grenoble/clusters/status?pretty

On the site level, the Status API gives the status of the nodes, disks, vlans, and subnets OAR resources.

Stitching API

See here for a stitching example.

Storage API

See here for examples on how to use the storage API.

Retrieved from "https://www.grid5000.fr/mediawiki/index.php?title=API_tutorial&oldid=89910"