Storage Manager: Difference between revisions

From Grid5000
Jump to navigation Jump to search
m (Passage à debian10.)
(29 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The '''Storage''' API is used to allow NFS access across machines on Grid'5000. This page focus on accessing user '''home''' directories.
{{Portal|Tutorial}}
{{Portal|User}}
{{StorageHeader}}
{{TutorialHeader}}
 
The Storage Manager manages access to NFS shares (in particular, users' '''home''' directories) on Grid'5000.
 
This page describes its API, and focuses on accessing user's '''home''' directories.


== How it works ==
== How it works ==
The storage API works with '''access''' object. An access specify a list of addresses and a termination condition for a specific location on a NFS Server. Each user home directory is located on <code>/export/home/</code><code class="replace">username</code> on the NFS server of each site : <code>nfs.</code><code class="replace">site</code><code>.grid5000.fr</code>
The storage API works with '''access''' object. An access is defined by a list of addresses and a termination condition for a specific location on an NFS Server. Each user's home directory is located on <code>/export/home/</code><code class="replace">username</code> on the NFS server of each site: <code>nfs.</code><code class="replace">site</code><code>.grid5000.fr</code>


Each time you start a job, an access to your home of the local NFS server is automatically created for all the assigned nodes. You may want to use this page if you want to allow additional addresses to access your home or if you want to access your home over-site.
'''Each time you start a job, an access to your local home directory is automatically created for all the assigned nodes. You may want to use this page if you want to allow additional addresses to access your home (like when you are using VLAN) or if you want to access your home over-site.'''
You will need to use the [[API|Grid'5000 API]], the entry-point for the home of a '''user''' on a specific '''site''' is :
You will need to use the [[API|Grid'5000 API]], the entry-point for the home of a '''user''' on a specific '''site''' is:
  <nowiki>https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">site</code>/storage/home/<code class="replace">username</code>/access
  <nowiki>https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">site</code>/storage/home/<code class="replace">username</code>/access
{{Note|text=Only the home owner can interact with his or her accesses, so you need to be authenticated. It's done automatically on the frontend. With curl, you can also use the <code>-u </code><code class="replace">username</code> option and you will be prompt for your password before the request is sent.}}
For [[Group Storage]], the entry-point of a '''storage''' on a server '''server''' of a '''site''' is:
  <nowiki>https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">site</code>/storage/<code class="replace">server</code>/<code class="replace">storage</code>/access
For example, <code><nowiki>https://api.grid5000.fr/stable/sites/lille/storage/storage1/my-team-storage/access</nowiki></code>
{{Note|text=Only the home owner can interact with his or her accesses, so you need to be authenticated. It's done automatically on the frontend. With curl, you can also use the <code>-u </code><code class="replace">username</code> option and you will be prompted for your password before the request is sent.}}


== Usage ==
== Usage ==
Line 13: Line 23:
   <nowiki> https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">nancy</code>/storage/home/<code class="replace">jpicard</code>/access
   <nowiki> https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">nancy</code>/storage/home/<code class="replace">jpicard</code>/access
=== Create access ===
=== Create access ===
Accesses creation is done by sending POST to the API with a JSON payload.
Accesses creation is done by sending a POST request to the API with a JSON payload.
We must provide a list of hosts to whom we want to give access to, for instance <code class="replace">dahu-1.grenoble.grid5000.fr</code> and <code class="replace">dahu-2.grenoble.grid5000.fr</code>. We also need a termination condition, it can be a specific date or a job termination.
We must provide a list of '''hosts''' to whom we want to give access to, for instance <code class="replace">dahu-1.grenoble.grid5000.fr</code> and <code class="replace">dahu-2.grenoble.grid5000.fr</code>. We also need a termination condition, it can be a specific date or a job termination.
 
{{Note|text=To give access to a home from a specific VLAN, you can use its domain name, for example for dahu-1 on VLAN 2, you can add <code class="replace">dahu-1-kavlan-2.grenoble.grid5000.fr</code>.}}
==== Until termination ====
==== Until termination ====
If we want to use a specific time (for example <code class="replace">2018-12-25 19:38</code>), we send the following request to the Storage API:
If we want to use a specific time (for example <code class="replace">2018-12-25 19:38</code>), we send the following request to the Storage API:
Line 28: Line 38:
   -H "Content-Type: application/json"  
   -H "Content-Type: application/json"  
   -d '{"hosts": [<code class="replace">"dahu-1.grenoble.grid5000.fr", "dahu-2.grenoble.grid5000.fr"</code>],  
   -d '{"hosts": [<code class="replace">"dahu-1.grenoble.grid5000.fr", "dahu-2.grenoble.grid5000.fr"</code>],  
       "termination" : {"job": <code class="replace">4548</code>, "site": <code class="replace">"grenoble"</code>}}
       "termination" : {"job": <code class="replace">4548</code>, "site": <code class="replace">"grenoble"</code>}}'
If we want to give access to all the assigned nodes of a job, we don't need to give any hosts, the API will fill them for us:
If we want to give access to all the assigned nodes of a job, we don't need to give any hosts, the API will fill them for us:
   curl -X POST <nowiki>'https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">nancy</code>/storage/home/<code class="replace">jpicard</code>/access'
   curl -X POST <nowiki>'https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">nancy</code>/storage/home/<code class="replace">jpicard</code>/access'
   -H "Content-Type: application/json"
   -H "Content-Type: application/json"
   -d '{"termination" : {"job": <code class="replace">4548</code>, "site": <code class="replace">"grenoble"</code>}}
   -d '{"termination" : {"job": <code class="replace">4548</code>, "site": <code class="replace">"grenoble"</code>}}'


{{Warning|text= The access is create immediately and and valid until the termination of the job, even if the job has not started yet.}}
{{Warning|text= The access is created immediately and is valid until the termination of the job, even if the job has not started yet.}}


After that, you should be able to mount the home where you want:
The '''nfs_address''' field will contain the address used to manually mount the home:
{{Term|location=node|cmd=mount nfs.<code class="replace">nancy</code>.grid5000.fr:/home/<code class="replace">jpicard</code> <code class="replace">/mnt/</code>}}
{{Term|location=node|cmd=mount srv-data.nancy.grid5000.fr:/export/home/<code class="replace">jpicard</code> <code class="replace">/mnt/</code>}}




{{Note|text=<code class="env">debian9-x64-std</code>,<code class="env">debian9-x64-big</code> and <code class="env">debian9-x64-nfs</code> use autofs for the home directories of the local NFS server. So doing <code>cd /home/jpicard/</code> will automount the home of jpicard if you have the rights.}}  
{{Note|text=<code class="env">debian10-x64-std</code>,<code class="env">debian10-x64-big</code> and <code class="env">debian10-x64-nfs</code> use autofs for the home directories of the local NFS server. So doing <code>cd /home/jpicard/</code> will automount the home of jpicard if you have the rights.}}


=== List access ===
=== List access ===
Line 54: Line 64:
         "job": 1666466,
         "job": 1666466,
         "site": "nancy"
         "site": "nancy"
       }
       },
      "nfs_address": "srv-data.nancy.grid5000.fr:/export/home/jpicard"
     },
     },
     "G5k-home_jpicard_u_1535456240_1": {
     "G5k-home_jpicard_u_1535456240_1": {
Line 62: Line 73:
       "termination": {
       "termination": {
         "until": 1535456240,
         "until": 1535456240,
       }
       },
      "nfs_address": "srv-data.nancy.grid5000.fr:/export/home/jpicard"
     }
     }
   }
   }
You can also ask for a specific access by providing its identifier, for instance :
You can also ask for a specific access by providing its identifier, for instance:
   curl <nowiki>https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">nancy</code>/storage/home/<code class="replace">jpicard</code>/access/<code class="replace">G5k-home_jpicard_u_1535456240_1</code>
   curl <nowiki>https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">nancy</code>/storage/home/<code class="replace">jpicard</code>/access/<code class="replace">G5k-home_jpicard_u_1535456240_1</code>


=== Delete an access ===
=== Delete an access ===
Access deletion is done by sending DELETE to the API with it's identifier.
Access deletion is done by sending a DELETE request to the API with the access identifier.
  curl -X DELETE <nowiki>https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">nancy</code>/storage/home/<code class="replace">jpicard</code>/access/<code class="replace">G5k-home_jpicard_u_1535456240_1</code>
  curl -X DELETE <nowiki>https://api.grid5000.fr/stable/sites/</nowiki><code class="replace">nancy</code>/storage/home/<code class="replace">jpicard</code>/access/<code class="replace">G5k-home_jpicard_u_1535456240_1</code>


Line 75: Line 87:
The Storage API uses the same status codes as the rest of [[API#Status_Codes|the Grid'5000 API]].
The Storage API uses the same status codes as the rest of [[API#Status_Codes|the Grid'5000 API]].
=== GET /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access ===
=== GET /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access ===
fetch a list of access.
Fetch a list of access.


=== GET /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access/<code class="replace">access_id</code> ===
=== GET /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access/<code class="replace">access_id</code> ===
fetch information of a specific access
Fetch information of a specific access.


=== DELETE /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access/<code class="replace">access_id</code> ===
=== DELETE /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access/<code class="replace">access_id</code> ===
delete a specific access
Delete a specific access.


=== DELETE /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access/?job=<code class="replace">job_id</code>&site=<code class="replace">job_site</code> ===
=== DELETE /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access/?job=<code class="replace">job_id</code>&site=<code class="replace">job_site</code> ===
delete all access with a job termination '''job_id''' of site '''job_site'''
Delete all access with a job termination '''job_id''' of site '''job_site'''.


=== POST /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access ===
=== POST /stable/sites/<code class="replace">site</code>/storage/home/<code class="replace">username</code>/access ===
Line 101: Line 113:
|-
|-
| termination || Mandatory || Termination condition can be of two types "Until" or "Job". The form is a structure/hash.
| termination || Mandatory || Termination condition can be of two types "Until" or "Job". The form is a structure/hash.
Until termination takes a date as an '''until''' parameter. The access will be deleted after the specify date. eg:
Until termination takes a date as an '''until''' parameter. The access will be deleted after the specify date. Eg:
   {"until" : "2018-12-25 19:38"}
   {"until" : "2018-12-25 19:38"}
Job terminations takes two parameters, '''job''' and '''site''', which are respectively the id and the site of a Grid'5000 job. When the job end, the export is deleted. eg:
Job terminations takes two parameters, '''job''' and '''site''', which are respectively the id and the site of a Grid'5000 job. When the job ends, the export is deleted. eg:
   {"job": "4548, "site":"nancy"}
   {"job": "4548, "site": "nancy"}
If no hosts and no ipv4 are provided, the API will use the assigned nodes from the job.
|-
|-

Revision as of 15:40, 18 October 2019

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.

The Storage Manager manages access to NFS shares (in particular, users' home directories) on Grid'5000.

This page describes its API, and focuses on accessing user's home directories.

How it works

The storage API works with access object. An access is defined by a list of addresses and a termination condition for a specific location on an NFS Server. Each user's home directory is located on /export/home/username on the NFS server of each site: nfs.site.grid5000.fr

Each time you start a job, an access to your local home directory is automatically created for all the assigned nodes. You may want to use this page if you want to allow additional addresses to access your home (like when you are using VLAN) or if you want to access your home over-site. You will need to use the Grid'5000 API, the entry-point for the home of a user on a specific site is:

https://api.grid5000.fr/stable/sites/site/storage/home/username/access

For Group Storage, the entry-point of a storage on a server server of a site is:

 https://api.grid5000.fr/stable/sites/site/storage/server/storage/access

For example, https://api.grid5000.fr/stable/sites/lille/storage/storage1/my-team-storage/access

Note.png Note

Only the home owner can interact with his or her accesses, so you need to be authenticated. It's done automatically on the frontend. With curl, you can also use the -u username option and you will be prompted for your password before the request is sent.

Usage

We assume that we want to manage the home of user jpicard on nancy, so the storage API entry-point will be:

  https://api.grid5000.fr/stable/sites/nancy/storage/home/jpicard/access

Create access

Accesses creation is done by sending a POST request to the API with a JSON payload. We must provide a list of hosts to whom we want to give access to, for instance dahu-1.grenoble.grid5000.fr and dahu-2.grenoble.grid5000.fr. We also need a termination condition, it can be a specific date or a job termination.

Note.png Note

To give access to a home from a specific VLAN, you can use its domain name, for example for dahu-1 on VLAN 2, you can add dahu-1-kavlan-2.grenoble.grid5000.fr.

Until termination

If we want to use a specific time (for example 2018-12-25 19:38), we send the following request to the Storage API:

 curl -X POST 'https://api.grid5000.fr/stable/sites/nancy/storage/home/jpicard/access' 
 -H "Content-Type: application/json" 
 -d '{"hosts": ["dahu-1.grenoble.grid5000.fr", "dahu-2.grenoble.grid5000.fr"], 
      "termination" : {"until":"2018-12-25 19:38"}}'

Job termination

If we want our access to be valid until the end of a Grid'5000 job, for example the job 4548 of grenoble, we do:

 curl -X POST 'https://api.grid5000.fr/stable/sites/nancy/storage/home/jpicard/access'
 -H "Content-Type: application/json" 
 -d '{"hosts": ["dahu-1.grenoble.grid5000.fr", "dahu-2.grenoble.grid5000.fr"], 
      "termination" : {"job": 4548, "site": "grenoble"}}'

If we want to give access to all the assigned nodes of a job, we don't need to give any hosts, the API will fill them for us:

 curl -X POST 'https://api.grid5000.fr/stable/sites/nancy/storage/home/jpicard/access'
 -H "Content-Type: application/json"
 -d '{"termination" : {"job": 4548, "site": "grenoble"}}'
Warning.png Warning

The access is created immediately and is valid until the termination of the job, even if the job has not started yet.

The nfs_address field will contain the address used to manually mount the home:

Terminal.png node:
mount srv-data.nancy.grid5000.fr:/export/home/jpicard /mnt/


Note.png Note

debian10-x64-std,debian10-x64-big and debian10-x64-nfs use autofs for the home directories of the local NFS server. So doing cd /home/jpicard/ will automount the home of jpicard if you have the rights.

List access

To list all accesses, you should do:

 curl https://api.grid5000.fr/stable/sites/nancy/storage/home/jpicard/access

You get a list of accesses:

 {
   "G5k-home_jpicard_j_1666466-nancy_1": {
     "ipv4": [
       "172.16.64.97"
     ],
     "termination": {
       "job": 1666466,
       "site": "nancy"
     },
     "nfs_address": "srv-data.nancy.grid5000.fr:/export/home/jpicard"
   },
   "G5k-home_jpicard_u_1535456240_1": {
     "ipv4": [
       "172.16.64.16"
     ],
     "termination": {
       "until": 1535456240,
     },
     "nfs_address": "srv-data.nancy.grid5000.fr:/export/home/jpicard"
   }
 }

You can also ask for a specific access by providing its identifier, for instance:

 curl https://api.grid5000.fr/stable/sites/nancy/storage/home/jpicard/access/G5k-home_jpicard_u_1535456240_1

Delete an access

Access deletion is done by sending a DELETE request to the API with the access identifier.

curl -X DELETE https://api.grid5000.fr/stable/sites/nancy/storage/home/jpicard/access/G5k-home_jpicard_u_1535456240_1

API Specification:

The Storage API uses the same status codes as the rest of the Grid'5000 API.

GET /stable/sites/site/storage/home/username/access

Fetch a list of access.

GET /stable/sites/site/storage/home/username/access/access_id

Fetch information of a specific access.

DELETE /stable/sites/site/storage/home/username/access/access_id

Delete a specific access.

DELETE /stable/sites/site/storage/home/username/access/?job=job_id&site=job_site

Delete all access with a job termination job_id of site job_site.

POST /stable/sites/site/storage/home/username/access

Create new access. The payload must be in JSON format, and contains the following properties:

Parameter Type Description & Examples
ipv4 Optional Array of ipv4 allowed to access NFS. eg:
  ["172.16.72.1",
   "172.16.72.25"]
hosts Optional Array of hosts allowed to access NFS. eg:
  ["grisou-1.nancy.grid5000.fr",
   "grisou-2.nancy.grid5000.fr"]
termination Mandatory Termination condition can be of two types "Until" or "Job". The form is a structure/hash.

Until termination takes a date as an until parameter. The access will be deleted after the specify date. Eg:

  {"until" : "2018-12-25 19:38"}

Job terminations takes two parameters, job and site, which are respectively the id and the site of a Grid'5000 job. When the job ends, the export is deleted. eg:

  {"job": "4548, "site": "nancy"}

If no hosts and no ipv4 are provided, the API will use the assigned nodes from the job.