Volumes#

Create a volume
Retrieve volumes
Retrieve volumes (detailed)
Retrieve details for a volume
Update a volume
Delete a volume

A volume is a detachable block storage device. You can think of it as a USB hard drive. You can attach a volume to one instance at a time.

When you make an API call to create, list, or delete volumes, the following volume status values are possible:

CREATING: The volume is being created.
AVAILABLE: The volume is ready to be attached to any instance.
ATTACHING: The volume is attaching to an instance.
IN-USE: The volume is attached to an instance.
DELETING: The volume is being deleted.
ERROR: An error occurred with the volume.
ERROR_DELETING: An error occurred during volume deletion.

Create a volume #

POST /v1/{tenant_id}/volumes

This operation creates a volume.

Following are several options for consideration when using this operation:

source_volid for volume cloning: When you use source_volid for volume cloning, note that this feature currently has the following constraints. Concurrent clone requests are queued for processing. When one clone request completes, the next clone request in the queue starts.
os-volume_attachments: Note that 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}). Refer to the Next Generation Cloud Servers API reference for details of the call. Once 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.
Boot from volume: To create a bootable volume, include the imageRef parameter in the request. The corresponding response parameter is image_id. For more information about this feature, see Boot a server from a Cloud Block Storage volume.
Disaffinity for volume creation: To create volumes on a different node or rack than existing volumes, use the metadata parameter in the body of the request, and specify different_node or different_rack with a comma-separated list of volume IDs from which you want the volume that you are creating to be distinct. For example, specifying the following parameters in the request body creates a volume on a rack that is different from the three specified volume IDs:

“metadata”: “different_rack=45c2c5c4-2666-43e9-aa6b-e58eb733410b,8d472323-196d-47bf-8f17-a21b978d0f90,f158d108-aa30-4609-9d31-c2b230f8a871”

Note that if the criteria specified using metadata is not met, the volume is in an error state.

Also, note that the API does not accept metadata parameters for both different_node and different_rack simultaneously.

Request parameters#

The request has the following URI parameters.

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

The request has the following body parameters.

Name	Type	Description
volume	String (Required)	A partial representation of a volume used in the creation process. This parameter is required for this operation.
volume.size	Int (Required)	The size of the volume, in gibibytes (GiB). This is a required parameter. Note: When creating a volume from a snapshot, the volume size must be greater than the snapshot size.
volume.display_description	String	A description of the volume. This parameter is optional.
volume.display_name	String	The name of the volume. This parameter is optional.
volume.snapshot_id	Uuid	The snapshot from which to create a volume. This parameter is optional.
volume.volume_type	String	The type of volume to create, either SATA or SSD. This parameter is optional. If not defined, the default, SATA, is used.
volume.source_volid	Uuid	The source identifier of an existing Cloud Block Storage volume that you want to clone (copy) to create a new volume. This parameter is optional.
volume.availability_zone	String	This parameter is no longer used. Therefore, you can supply any value for `availability_zone`. If you specify no value, the default is `nova`.
volume.metadata	String	This optional parameter is available if you want to set any metadata values on the volume. Use `different_node` or `different_rack` with a comma-separated list of volume IDs from which you want the volume that you are creating to be distinct. Using these keywords will create the volume on a node or rack that is different from those whose volume IDs are specified.
volume.imageRef	Uuid	Specifying this parameter is required to create a bootable volume. This parameter is the ID of the image from which you want to create the volume.

Request examples#

The following XML example creates creates a 100 gibibytes (GiB) SATA volume called vol-001.

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.rackspace.com/volume/api/v1"
        display_name="vol-001"
        display_description="Another volume."
        size="100"
        source_volid="e3611474-589b-46b7-9bdf-5555e2e4999b"
        volume_type="SATA">

</volume>

The following JSON example creates creates a 100 gibibytes (GiB) SATA volume called vol-001.

{
    "volume": {
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "size": 100,
        "source_volid": "e3611474-589b-46b7-9bdf-5555e2e4999b",
        "volume_type": "SATA"
     }
}

Response examples#

The following example shows the XML response for creating a volume.

<?xml version='1.0' encoding='UTF-8'?>
<volume xmlns="http://docs.rackspace.com/volume/api/v1"
        status="available"
        display_name="vol-001"
        attachments=""
        availability_zone="nova"
        bootable="false"
        created_at="2012-02-14T20:53:07Z"
        display_description="Another volume."
        image_id="null"
        volume_type="SATA"
        snapshot_id="null"
        source_volid="e3611474-589b-46b7-9bdf-5555e2e4999b"
        metadata=""
        id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
        size="100"/>

The following example shows the JSON response for creating a volume.

{
  "volume": {
    "status": "available",
    "display_name": "vol-001",
    "attachments": [],
    "availability_zone": "nova",
    "bootable": "false",
    "created_at": "2012-02-14T20:53:07Z",
    "display_description": "Another volume.",
    "image_id": null,
    "volume_type": "SATA",
    "snapshot_id": null,
    "source_volid": "e3611474-589b-46b7-9bdf-5555e2e4999b",
    "metadata": {},
    "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
    "size": 100
  }
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

409 |SnapshotConflict |Existing snapshot: |operation on volume in

|progress.

————————–|-------------------------|———————— 409 |CloneConflict |Existing volume clone

|operation in progress.

Retrieve volumes #

GET /v1/{tenant_id}/volumes

This operation retrieves summary information for all Cloud Block Storage volumes that the tenant who submits the request can access.

Request#

The request has the following URI parameters.

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

This operation does not accept a request body.

Response examples#

The following example shows the XML response for retrieving summary information about volumes.

<?xml version="1.0" encoding="UTF-8"?>
<volumes xmlns="http://docs.rackspace.com/volume/api/v1">
    <volume xmlns="http://docs.rackspace.com/volume/api/v1"
            id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
            display_name="vol-001"
            display_description="Another volume."
            status="active"
            size="100"
            volume_type="SATA"
            created_at="2012-02-14T20:53:07Z">
    </volume>
    <volume xmlns="http://docs.rackspace.com/volume/api/v1"
            id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
            display_name="vol-002"
            display_description="Yet another volume."
            status="active"
            size="100"
            volume_type="SATA"
            created_at="2012-03-15T19:10:03Z" />
</volumes>

The following example shows the JSON response for retrieving summary information about volumes.

{
    "volumes": [
        {
            "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "display_name": "vol-001",
            "display_description": "Another volume.",
            "size": 100,
            "volume_type": "SATA",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-02-14T20:53:07Z"
        },
        {
            "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "display_name": "vol-002",
            "display_description": "Yet another volume.",
            "size": 100,
            "volume_type": "SATA",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-03-15T19:10:03Z"
        }
    ]
}

Response codes#

This operation can have the following response codes.

Response Code	Name	Description
200	OK	Success

Retrieve volumes (detailed)#

GET /v1/{tenant_id}/volumes/detail

This operation retrieves detailed information for all Cloud Block Storage volumes that the tenant who submits the request can access.

Request#

The request has the following URI parameters.

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

This operation does not accept a request body.

Response examples#

The following example shows the XML response for retrieving the volume details.

<?xml version='1.0' encoding='UTF-8'?>
<volumes xmlns="http://docs.rackspace.com/volume/api/v1">
    <volume xmlns="http://docs.rackspace.com/volume/api/v1"
        status="available" name="vol-004" availability_zone="nova"
        created_at="2013-02-25 06:36:28" description="Another volume."
        volume_type="None" source_volid="None" snapshot_id="None"
        id="45baf976-c20a-4894-a7c3-c94b7376bf55" size="1"
        tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
        host="ip-10-168-107-25">
        <attachments/>
        <metadata>
            <meta key="contents">junk</meta>
        </metadata>
    </volume>
    <volume status="available" name="vol-003" availability_zone="nova"
        created_at="2013-02-25 02:40:21"
        description="This is yet, another volume." volume_type="None"
        source_volid="None" snapshot_id="None"
        id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
        tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
        host="ip-10-168-107-25">
        <attachments/>
        <metadata>
            <meta key="contents">not junk</meta>
        </metadata>
    </volume>
</volumes>

The following example shows the JSON response for retrieving the volume details.

{
    "volumes": [
        {
            "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "display_name": "vol-001",
            "display_description": "Another volume.",
            "size": 100,
            "volume_type": "SATA",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-02-14T20:53:07Z"
        },
        {
            "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "display_name": "vol-002",
            "display_description": "Yet another volume.",
            "size": 100,
            "volume_type": "SATA",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-03-15T19:10:03Z"
        }
    ]
}

{
    "volumes":[
       {
          "status":"available",
          "attachments":[

          ],
          "links":[
             {
                "href":"http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                "rel":"self"
             },
             {
                "href":"http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                "rel":"bookmark"
             }
               ],
               "availability_zone":"nova",
               "host":"ip-10-168-107-25",
               "source_volid":null,
               "snapshot_id":null,
               "id":"45baf976-c20a-4894-a7c3-c94b7376bf55",
               "description":"Another volume.",
               "name":"vol-004",
               "created_at":"2013-02-25T06:36:28.000000",
               "volume_type":"None",
               "tenant_id":"0c2eba2c5af04d3f9e9d0d410b371fde",
               "size":1,
               "metadata":{
               "contents":"junk"
               }
            },
            {
               "status":"available",
               "attachments":[

               ],
               "links":[
                {
                    "href":"http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel":"self"
                },
                {
                    "href":"http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel":"bookmark"
                }
            ],
            "availability_zone":"nova",
            "host":"ip-10-168-107-25",
            "source_volid":null,
            "snapshot_id":null,
            "id":"5aa119a8-d25b-45a7-8d1b-88e127885635",
            "description":"This is yet, another volume.",
            "name":"vol-003",
            "created_at":"2013-02-25T02:40:21.000000",
            "volume_type":"None",
            "tenant_id":"0c2eba2c5af04d3f9e9d0d410b371fde",
            "size":1,
            "metadata":{
            "contents":"not junk"
            }
        }
    ]
}

Response codes#

Response Code	Name	Description
200	OK	Success

Retrieve details for a volume #

GET /v1/{tenant_id}/volumes/{volume_id}

This operation retrieves details for a specified volume.

Request#

The request has the following URI parameters.

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.
{volume_id}	String	The unique identifier of an existing volume.

This operation does not accept a request body.

Response examples#

The following example shows the XML response for retrieving the details for a specified volume.

<?xml version='1.0' encoding='UTF-8'?>
<volume xmlns="http://docs.rackspace.com/volume/api/v1"
        status="available"
        display_name="vol-001"
        attachments=""
        availability_zone="nova"
        bootable="false"
        created_at="2012-02-14T20:53:07Z"
        display_description="Another volume."
        image_id="null"
        volume_type="SATA"
        snapshot_id="null"
        source_volid="e3611474-589b-46b7-9bdf-5555e2e4999b"
        metadata=""
        id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
        size="100"/>

The following example shows the JSON response for retrieving the details for a specified volume.

{
  "volume": {
    "status": "available",
    "display_name": "vol-001",
    "attachments": [],
    "availability_zone": "nova",
    "bootable": "false",
    "created_at": "2012-02-14T20:53:07Z",
    "display_description": "Another volume.",
    "image_id": null,
    "volume_type": "SATA",
    "snapshot_id": null,
    "source_volid": "e3611474-589b-46b7-9bdf-5555e2e4999b",
    "metadata": {},
    "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
    "size": 100
  }
}

Response codes#

This operation can have the following response codes.

Response Code	Name	Description
200	OK	Success

Update a volume #

PUT /v1/{tenant_id}/volumes/{volume_id}

This operation updates the name and description for a volume.

Request parameters#

The request has the following URI parameters.

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.
{volume_id}	String	The unique identifier of an existing volume.

The request has the following body parameters.

Name	Type	Description
volume	String (Required)	Information about the volume.
volume.display_description	String	A description of the volume.
volume.display_name	String	The name of the volume.

Request example#

The following XML example updates two properties for the volume: display_description and display_name.

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns=""
        display_description="New Description"
        display_name="New Name">
</volume>

The following JSON example updates two properties for the volume: display_description and display_name.

{
  "volume": {
    "display_name": "new name",
    "display_description": "new description"
  }
}

Response examples#

The following example shows the XML response for updating the volume.

<?xml version='1.0' encoding='UTF-8'?>
<volume xmlns:atom="http://www.w3.org/2005/Atom"
        xmlns="http://docs.openstack.org/volume/api/v1"
        status="available"
        display_name="New Name"
        availability_zone="nova"
        created_at="2013-07-25 21:53:58"
        display_description="New Description"
        volume_type="SATA"
        snapshot_id="null"
        source_volid="null"
        id="82c9971b-3953-4ca7-b3d4-e671c71d6335"
        size="2">
<attachments/>
<metadata/>
</volume>

The following example shows the JSON response for updating the volume.

{
  "volume":
  {
    "status": "in-use",
    "display_name": "new name",
    "attachments": [],
    "availability_zone": "nova",
    "bootable": "false",
    "created_at": "2012-10-23T17:12:40.000000",
    "display_description": "new description",
    "volume_type": "SATA",
    "snapshot_id": null,
    "source_volid": null,
    "metadata": {},
    "id": "5e9c00de-60b3-48de-ae58-0a07ec842d51",
    "size": 100
  }
}

Response codes#

This operation can have the following response codes.

Response Code	Name	Description
200	OK	Success

Delete a volume #

DELETE /v1/{tenant_id}/volumes/{volume_id}

This operation deletes a volume.

Note

If a snapshot of the volume exists, you cannot delete the volume until you delete the snapshot.

Request#

The request has the following URI parameters.

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.
{volume_id}	String	The unique identifier of an existing volume.

This operation does not accept a request body.

Response#

This operation does not return a response body.

Response codes#

This operation can have the following response codes.

Response Code	Name	Description
202	Accepted	The request has been accepted for processing.

Volumes#

Create a volume#

Request parameters#

Request examples#

Response examples#

Response codes#

Retrieve volumes#

Request#

Response examples#

Response codes#

Retrieve volumes (detailed)#

Request#

Response examples#

Response codes#

Retrieve details for a volume#

Request#

Response examples#

Response codes#

Update a volume#

Request parameters#

Request example#

Response examples#

Response codes#

Delete a volume#

Request#

Response#

Response codes#

Create a volume #

Retrieve volumes #

Retrieve details for a volume #

Update a volume #

Delete a volume #