Persistent disk

Persistent Storage provides on-site management of persistent storage areas (a la Amazon Elastic Block Store) allowing users to create disks of a given size, to launch a machine with the disks attached, and to persist the disks after their use, so that the disks are available for use by another machine instance.

• Create persistent disk from 1GB to 1TB that you can mount on a StratusLab instance.
• Persistent disk behave like raw, unformatted block device. You can create a file system on top of this disk or use them in any other way you would use a block device (like a hard drive).
• Persistent disk a created on a specific storage area and can be used in every StratusLab cloud.
• When creating a disk, you can choose the visibility of it. It can be private, you will be the only one able to view it in the disk list, read it, write it and delete it. The disk can also be public, then other users can view it in the disk list, read it, write it but you are the only one able to delete it.
• Persistent disks can be hot-plugged to a running instance, no need to restart it to use a disk.
• You can attach many disk as you want on a machine. This means that you can strip your data across them for increased I/O and throughput performance. This is particularly helpful for database style applications that frequently encounter many random reads and writes across the dataset.

• Disk across storage area and the VM node a shared with iSCSI or NFS.
• Persistent disk can be either LVM partition or simple block file
• Properties of persistent disk are stored in Hadoop Zookeeper, which automatically allow fault tolerance with redundancy.
• This service is independent from a cloud installation, you don't need to have a cloud frontend install on the same machine or in your farm to run it.
• Simultaneous users on a disk can be limited to avoid i/o errors.

The persistent disk API provide a simple way to interact with it in programs. The API URLs starts with /api/ and has no ending slash.

List disks properties available for a user.

 GET /api/disks

Status: 200 OK

 [
     {
         "users": "0",
         "created": "2011/07/28 15:01:40",
         "visibility": "private",
         "tag": "a simple disk",
         "owner": "test",
         "uuid": "eb198dec-3560-4a9a-b3b4-5f043410a3dd",
         "size": "2"
     },
     {
         "users": "0",
         "created": "2011/07/28 15:01:54",
         "visibility": "public",
         "tag": "a public disk",
         "owner": "test",
         "uuid": "7d409aed-3207-4dd1-85f3-3bca3605b1fb",
         "size": "1"
     }
 ]

 GET /api/disks/:uuid

Status: 200 OK

X-DiskUser-Limit: 2

X-DiskUser-Remaining: 1

 {
    "users": "1",
    "created": "2011/07/28 15:01:40",
    "visibility": "private",
    "tag": "a simple disk",
    "owner": "test",
    "uuid": "eb198dec-3560-4a9a-b3b4-5f043410a3dd",
    "size": "2"
 }
 

Disk user limit and disk user remaining for a disk are send in the HTTP headers as X-DiskUser-Limit and X-DiskUser-Remaining. Client should not try to attach a disk which as less than one remaining disk user.

 DELETE /api/disks/:uuid

Status: 200 OK

 { "uuid": "eb198dec-3560-4a9a-b3b4-5f043410a3dd" }

 POST /api/create

• size: Size of the disk in GiBs. Between 1 and 1024.
• tag: Tag of the disk.
• visibility: Visibility of the disk. Can be private or public.

All of the inputs are required.

Status: 201 Created

 { "uuid": "a00539f7-d40d-4d8d-95c0-5b0c9713c92e" }

The returned content is the UUID of the newly created persistent disk.

 POST /api/hotattach/:uuid

• node: Node on which the VM is running.
• vm_id: Identifier of the VM on which the disk is attached.

Status: 200 OK

 { 
   "node": "onehost-2.lal.in2p3.fr",
   "vm_id": "722",
   "target": "vda",
   "uuid": ["a00539f7-d40d-4d8d-95c0-5b0c9713c92e", "eb198dec-3560-4a9a-b3b4-5f043410a3dd"]
 }

The returned UUIDs are all the disk that are attached to the VM.

 POST /api/hotdetach/:uuid

Only hot-plugged disk can be detached with this method.

• node: Node on which the VM is running.
• vm_id: Identifier of the VM on which the disk is attached.

Status: 200 OK

 { 
   "node": "onehost-2.lal.in2p3.fr",
   "vm_id": "722",
   "target": "vda",
   "uuid": ["a00539f7-d40d-4d8d-95c0-5b0c9713c92e", "eb198dec-3560-4a9a-b3b4-5f043410a3dd"]
 }

The returned UUIDs are the remaining attached disks on the VM.

This method is intended to be used by the cloud frontend.

 POST /api/attach/:uuid

This method will not check disk availability, it have to be done by the client before launching a VM.

Disk attached this way can only be removed when the VM is killed.

• node: Node on which the VM is running.
• vm_id: Identifier of the VM on which the disk is attached.

Status: 200 OK

 { 
   "node": "onehost-2.lal.in2p3.fr",
   "vm_id": "722",
   "uuid": ["a00539f7-d40d-4d8d-95c0-5b0c9713c92e", "eb198dec-3560-4a9a-b3b4-5f043410a3dd"]
 }

The returned UUIDs are all the disk that are attached to the VM.

This method is intended to be used by the cloud frontend.

 POST /api/detach

This method should be called only when the VM is killed.

• node: Node on which the VM is running.
• vm_id: Identifier of the VM on which the disk is attached.

Status: 200 OK

 { 
   "node": "onehost-2.lal.in2p3.fr",
   "vm_id": "722",
   "uuid": ["a00539f7-d40d-4d8d-95c0-5b0c9713c92e", "eb198dec-3560-4a9a-b3b4-5f043410a3dd"]
 }

The returned UUIDs are all the disk that have been detached from the VM.

Client error on API calls are returned with either a 400 Bad Request or a 422 Unprocessable Entity response. Error messages as structured as follows:

 {"message": ["First error message", "Second error message"] }