Create and manage volumes and snapshots

You can use the examples in this section to create and manage volumes and snapshots by using Cloud Block Storage API operations. Example requests are provided in cURL, followed by the response.

Before running the examples, review the Cloud Block Storage concepts.

For more information about all Cloud Block Storage operations, see the API reference.

Note

These examples use the $API_ENDPOINT, $AUTH_TOKEN, and $TENANT_ID environment variables to specify the API endpoint, authentication token, and project ID values for accessing the service. Be sure to configure these variables before running the code samples.

Creating a block storage volume

Your first step in Cloud Block Storage is to create a volume. To do this, send a POST request.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the volume was successfully created.

Note

You use the source_volid parameter for volume cloning, which has some limitations. You cannot create more than one clone per volume concurrently. Snapshots and volume cloning use the same locking mechanism, so you cannot run a snapshot and a clone of the same volume concurrently.

Example: cURL create a volume request

curl -i -X POST $API_ENDPOINT/v1/$TENANT_ID/volumes -d \
 '{
 "volume":{
 "display_name": "vol-001",
 "size": 100
 }
  }' \
 -H "X-Auth-Token: $AUTH_TOKEN" \
 -H "Content-Type: application/json"

Example: Create a volume response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-2af6c97a-2397-4e52-a0d0-4fde64cfb88c
Content-Type: application/json
Content-Length: 399
Date: Tue, 03 Jun 2014 21:45:46 GMT
 {
   "volume": {
     "status": "available",
     "display_name": "vol-001",
     "attachments": [

     ],
     "availability_zone": "nova",
     "bootable": "false",
     "created_at": "2014-06-03T21:45:45.000000",
     "display_description": null,
     "volume_type": "SATA",
     "snapshot_id": null,
     "source_volid": null,
     "metadata": {
       "storage-node": "3d0a6f43-d1d9-4fea-bffa-8cf9fc7bf7e8"
     },
     "id": "a3df5c35-3218-436e-b706-c85edc3f149d",
     "size": 100
   }
  }

Note

You use the os-volume_attachments API call (/servers/{server_id}/os-volume_attachments) to attach the new volume to your Next Generation Cloud Server (with the specified {server_id}). For details, see the Next Generation Cloud Servers API reference.

After the volume is attached, the new volume appears as another device on the Next Generation Cloud Server. The volume can then be partitioned, formatted, and mounted for use on the system.

Listing existing block storage volumes

To list all of the block storage volumes that you have created in a single region, send a GET request.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request successfully completed.

Example: cURL list volumes request

curl -i -X $API_ENDPOINT/v1/$TENANT_ID/volumes \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json"

Example: List volumes response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-7941b291-f226-459d-9a78-5d38660f3ae7
Content-Type: application/json
Content-Length: 1179
Date: Wed, 04 Jun 2014 16:52:15 GMT

{
   "volumes": [
     {
       "status": "available",
       "display_name": "vol-001",
       "attachments": [

       ],
       "availability_zone": "nova",
       "bootable": "false",
       "created_at": " 2014-06-03T21:45:45.000000 ",
       "display_description": null,
       "volume_type": "SATA",
       "snapshot_id": null,
       "source_volid": null,
       "metadata": {
         "storage-node": " 3d0a6f43-d1d9-4fea-bffa-8cf9fc7bf7e8 "
       },
       "id": " a3df5c35-3218-436e-b706-c85edc3f149d ",
       "size": 100
     }
   ]
 }

Showing volume details

To show details about a specified volume, send a GET request that includes the volume ID.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request successfully completed.

Example: cURL show volume details request

curl -i -X GET $API_ENDPOINT/v1/$TENANT_ID/volumes/yourVolumeID \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json"

Example: Show volume details response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-0ec1d1e0-c591-47d2-a8e7-9a8923e495b2
Content-Type: application/json
Content-Length: 554
Date: Wed, 04 Jun 2014 18:15:24 GMT

 {
   "volume": {
     "status": "available",
     "display_name": "vol-001",
     "attachments": [

     ],
     "availability_zone": "nova",
     "bootable": "false",
     "created_at": "2014-06-03T21:45:45.000000",
     "os-vol-tenant-attr:tenant_id": "yourAccountID",
     "display_description": null,
     "os-vol-host-attr:host": "lunr",
     "volume_type": "SATA",
     "snapshot_id": null,
     "source_volid": null,
     "os-vol-mig-status-attr:name_id": null,
     "metadata": {
       "storage-node": "3d0a6f43-d1d9-4fea-bffa-8cf9fc7bf7e8"
     },
     "id": "a3df5c35-3218-436e-b706-c85edc3f149d",
     "os-vol-mig-status-attr:migstat": null,
     "size": 100
   }
 }

Updating a volume

To modify a volume’s name, description, or both, send a PUT request that includes the volume ID.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request successfully completed.

Example: cURL update a volume request

curl -i -X PUT $API_ENDPOINT/v1/$TENANT_ID/volumes/yourVolumeID -d \
   '{
    "volume":{
        "display_name":"newName",
        "display_description":"newDescription"
        }
    }'\
    -H "X-Auth-Token: $AUTH_TOKEN" \
    -H "Content-Type: application/json"

Example: Update a volume response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-8a131657-46a3-435b-bee4-b612c79c8c09
Content-Type: application/json
Content-Length: 411
Date: Wed, 04 Jun 2014 18:29:43 GMT

 {
   "volume": {
     "status": "available",
     "display_name": "newName",
     "attachments": [

     ],
     "availability_zone": "nova",
     "bootable": "false",
     "created_at": "2014-06-03T21:45:45.000000",
     "display_description": "newDescription",
     "volume_type": "SATA",
     "snapshot_id": null,
     "source_volid": null,
     "metadata": {
       "storage-node": "3d0a6f43-d1d9-4fea-bffa-8cf9fc7bf7e8"
     },
     "id": "a3df5c35-3218-436e-b706-c85edc3f149d",
     "size": 100
   }
 }

Deleting a volume

To delete a volume when it is no longer in use and the data that it contains is not needed, send a DELETE request that includes the volume ID.

Note

Deleting a volume deletes all the data within it. You cannot recover the data unless it is backed up before the volume is deleted.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 202 (Accepted) in the response indicates that the delete request has been accepted for processing and the volume will be deleted.

Example: cURL delete a volume request

curl -i -X DELETE $API_ENDPOINT/v1/$TENANT_ID/volumes/yourVolumeID \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json"

Example: Delete a volume response

HTTP/1.1 202 Accepted
Content-Type: text/html; charset=UTF-8
Content-Length: 0
Date: Wed, 04 Jun 2014 19:17:35 GMT

Creating a snapshot

A snapshot is a point-in-time copy of the data that a volume contains. You must flush all writes to the volume before you create a snapshot. To do so, either unmount any file systems on the volume or detach the volume. Snapshots are incremental, so each time that you create a snapshot, the incremental changes for the new snapshot are appended to the previous snapshot, which is still available. Note that you can create a volume from the snapshot.

To create a snapshot of a block storage volume, send a POST request.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) indicates that the request was accepted and "status": "creating" indicates that the snapshot is in progress.

Example: cURL create a snapshot request

curl -i -X POST $API_ENDPOINT/v1/$TENANT_ID/snapshots -d \
   '{
   "snapshot": {
       "display_name": "snap-001",
       "display_description": "Daily Backup",
       "volume_id": "yourVolumeID"
     }
   }'\
   -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json"

Example: Create a snapshot response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-99d94a3a-1086-4c19-99b4-65d05e2e02f1
Content-Type: application/json
Content-Length: 275
Date: Wed, 04 Jun 2014 20:16:19 GMT

{
   "snapshot": {
     "status": "creating",
     "display_name": "snap-001",
     "created_at": "2014-06-04T20:16:17.000000",
     "display_description": "Daily Backup",
     "volume_id": "c849a193-5275-4527-9e5a-69b2a05933aa",
     "metadata": {

     },
     "id": "a6211a94-937f-4770-8dae-1813cb643213",
     "size": 100
   }
 }

Listing snapshots

To list all of the snapshots that you have created in a single region, send a GET request.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request successfully completed.

Example: cURL list snapshots request

curl -i -X GET $API_ENDPOINT/v1/$TENANT_ID/snapshots \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json"

Example: List snapshots response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-1a938da7-cf74-4ac6-a72f-4c927ae23605
Content-Type: application/json
Content-Length: 541
Date: Wed, 04 Jun 2014 20:28:01 GMT

  {
   "snapshots": [
     {
       "status": "creating",
       "display_name": "snap-001",
       "created_at": "2014-06-04T20:16:17.000000",
       "display_description": "Daily Backup",
       "volume_id": "c849a193-5275-4527-9e5a-69b2a05933aa",
       "metadata": {

       },
       "id": "a6211a94-937f-4770-8dae-1813cb643213",
       "size": 100
     },
     {
       "status": "available",
       "display_name": "snap-002",
       "created_at": "2014-06-04T20:13:34.000000",
       "display_description": "Weekly Backup",
       "volume_id": "1a036384-99b2-4fed-ac05-31f964d6925d",
       "metadata": {

       },
       "id": "ca320eb7-b371-4dbe-b2e9-2543c952f507",
       "size": 100
     }
   ]
 }

Showing snapshot details

To show details about a specified snapshot, send a GET request that includes the snapshot ID.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request successfully completed.

Note

os-extended-snapshot-attributes:progress in the response body shows snapshot creation progress.

Example: cURL show snapshot details request

curl -i -X GET $API_ENDPOINT/v1/$TENANT_ID/snapshots/yourSnapshotID \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json"

Example: Show snapshot details response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-7314746b-0670-4160-b6a7-388cafbfd082
Content-Type: application/json
Content-Length: 383
Date: Wed, 04 Jun 2014 20:47:48 GMT

{
   "snapshot": {
     "status": "available",
     "display_name": "snap-002",
     "created_at": "2014-06-04T20:13:34.000000",
     "display_description": "Weekly Backup",
     "os-extended-snapshot-attributes:progress": "100%",
     "volume_id": "1a036384-99b2-4fed-ac05-31f964d6925d",
     "os-extended-snapshot-attributes:project_id": "yourAccountID",
     "metadata": {

     },
     "id": "ca320eb7-b371-4dbe-b2e9-2543c952f507",
     "size": 100
   }
 }

Updating a snapshot

To modify a snapshot’s name, description, or both, send a PUT request that includes the snapshot ID.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request successfully completed.

Example: cURL update a snapshot request

curl -i -X PUT $API_ENDPOINT/v1/$TENANT_ID/snapshots/yourSnapshotID  -d \
   '{
    "snapshot":{
        "display_name":"newSnapshotName",
        "display_description":"newSnapshotDescription"
        }
    }' \
    -H "X-Auth-Token: $AUTH_TOKEN" \
    -H "Content-Type: application/json"

Example: Update a snapshot response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-8a131657-46a3-435b-bee4-b612c79c8c09
Content-Length: 358
Content-Type: text/html; charset=UTF-8
Date: Wed, 04 Jun 2014 20:59:12 GMT

 {
   "snapshot": {
     "created_at" : "2014-06-04T20:13:34.000000",
     "status": "available",
     "display_name": "newSnapshotName",
     "display_description": "newSnapshotDescription",
     "id": "a3df5c35-3218-436e-b706-c85edc3f149d",
     "size": 100,
     "volume_id" : "1a036384-99b2-4fed-ac05-31f964d6925d"
   }
 }

Deleting a snapshot

To delete a snapshot, send a DELETE request that includes the snapshot ID.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 202 (Accepted) in the response indicates that the delete request has been accepted for processing and the snapshot will be deleted.

Example: cURL delete a snapshot request

curl -i -X DELETE $API_ENDPOINT/v1/$TENANT_ID/snapshots/yourSnapshotID \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json"

Example: Delete a snapshot response

HTTP/1.1 202 Accepted
Content-Type: text/html; charset=UTF-8
Content-Length: 0
Date: Wed, 04 Jun 2014 21:09:15 GMT

Other cURL commands

You can issue any of the REST requests defined for Cloud Block Storage with the cURL utility.

Note that generally each time cURL is invoked to perform an operation, a separate TCP/IP and SSL connection is created and then discarded. The language APIs, in contrast, are designed to reuse connections between operations and therefore provide much better performance. We recommend that you use one of the language APIs (for example, Python or Ruby) in your production applications and limit cURL to quick-and-easy testing and troubleshooting.