Block Storage API v2 (CURRENT)

Manages volumes and snapshots for use with the Block Storage API, which is also known as cinder services.

API versions

GET

List API versions

Lists information about all Block Storage API versions.

Normal response codes

200, 300

{
    "versions": [
        {
            "status": "CURRENT",
            "updated": "2012-01-04T11:33:21Z",
            "id": "v1.0",
            "links": [
                {
                    "href": "http://23.253.228.211:8776/v1/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "updated": "2012-11-21T11:33:21Z",
            "id": "v2.0",
            "links": [
                {
                    "href": "http://23.253.228.211:8776/v2/",
                    "rel": "self"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

GET

/v2

Show API version details

Shows details for Block Storage API v2.

Normal response codes

200, 203

{
    "version": {
        "status": "CURRENT",
        "updated": "2012-01-04T11:33:21Z",
        "media-types": [
            {
                "base": "application/xml",
                "type": "application/vnd.openstack.volume+xml;version=1"
            },
            {
                "base": "application/json",
                "type": "application/vnd.openstack.volume+json;version=1"
            }
        ],
        "id": "v1.0",
        "links": [
            {
                "href": "http://23.253.228.211:8776/v2/",
                "rel": "self"
            },
            {
                "href": "http://jorgew.github.com/block-storage-api/content/os-block-storage-1.0.pdf",
                "type": "application/pdf",
                "rel": "describedby"
            },
            {
                "href": "http://docs.rackspacecloud.com/servers/api/v1.1/application.wadl",
                "type": "application/vnd.sun.wadl+xml",
                "rel": "describedby"
            }
        ]
    }
}

This operation does not accept a request body.

API extensions

GET

/v2/{tenant_id}/extensions

List API extensions

Lists Block Storage API extensions.

Normal response codes

200, 300

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
    "extensions": [
        {
            "updated": "2013-04-18T00:00:00+00:00",
            "name": "SchedulerHints",
            "links": [],
            "namespace": "http://docs.openstack.org/block-service/ext/scheduler-hints/api/v2",
            "alias": "OS-SCH-HNT",
            "description": "Pass arbitrary key/value pairs to the scheduler."
        },
        {
            "updated": "2011-06-29T00:00:00+00:00",
            "name": "Hosts",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/hosts/api/v1.1",
            "alias": "os-hosts",
            "description": "Admin-only host administration."
        },
        {
            "updated": "2011-11-03T00:00:00+00:00",
            "name": "VolumeTenantAttribute",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume_tenant_attribute/api/v1",
            "alias": "os-vol-tenant-attr",
            "description": "Expose the internal project_id as an attribute of a volume."
        },
        {
            "updated": "2011-08-08T00:00:00+00:00",
            "name": "Quotas",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/quotas-sets/api/v1.1",
            "alias": "os-quota-sets",
            "description": "Quota management support."
        },
        {
            "updated": "2011-08-24T00:00:00+00:00",
            "name": "TypesManage",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/types-manage/api/v1",
            "alias": "os-types-manage",
            "description": "Types manage support."
        },
        {
            "updated": "2013-07-10T00:00:00+00:00",
            "name": "VolumeEncryptionMetadata",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/os-volume-encryption-metadata/api/v1",
            "alias": "os-volume-encryption-metadata",
            "description": "Volume encryption metadata retrieval support."
        },
        {
            "updated": "2012-12-12T00:00:00+00:00",
            "name": "Backups",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/backups/api/v1",
            "alias": "backups",
            "description": "Backups support."
        },
        {
            "updated": "2013-07-16T00:00:00+00:00",
            "name": "SnapshotActions",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/snapshot-actions/api/v1.1",
            "alias": "os-snapshot-actions",
            "description": "Enable snapshot manager actions."
        },
        {
            "updated": "2012-05-31T00:00:00+00:00",
            "name": "VolumeActions",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume-actions/api/v1.1",
            "alias": "os-volume-actions",
            "description": "Enable volume actions\n    "
        },
        {
            "updated": "2013-10-03T00:00:00+00:00",
            "name": "UsedLimits",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/used-limits/api/v1.1",
            "alias": "os-used-limits",
            "description": "Provide data on limited resources that are being used."
        },
        {
            "updated": "2012-05-31T00:00:00+00:00",
            "name": "VolumeUnmanage",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume-unmanage/api/v1.1",
            "alias": "os-volume-unmanage",
            "description": "Enable volume unmanage operation."
        },
        {
            "updated": "2011-11-03T00:00:00+00:00",
            "name": "VolumeHostAttribute",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume_host_attribute/api/v1",
            "alias": "os-vol-host-attr",
            "description": "Expose host as an attribute of a volume."
        },
        {
            "updated": "2013-07-01T00:00:00+00:00",
            "name": "VolumeTypeEncryption",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume-type-encryption/api/v1",
            "alias": "encryption",
            "description": "Encryption support for volume types."
        },
        {
            "updated": "2013-06-27T00:00:00+00:00",
            "name": "AvailabilityZones",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/os-availability-zone/api/v1",
            "alias": "os-availability-zone",
            "description": "Describe Availability Zones."
        },
        {
            "updated": "2013-08-02T00:00:00+00:00",
            "name": "Qos_specs_manage",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/qos-specs/api/v1",
            "alias": "qos-specs",
            "description": "QoS specs support."
        },
        {
            "updated": "2011-08-24T00:00:00+00:00",
            "name": "TypesExtraSpecs",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/types-extra-specs/api/v1",
            "alias": "os-types-extra-specs",
            "description": "Type extra specs support."
        },
        {
            "updated": "2013-08-08T00:00:00+00:00",
            "name": "VolumeMigStatusAttribute",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume_mig_status_attribute/api/v1",
            "alias": "os-vol-mig-status-attr",
            "description": "Expose migration_status as an attribute of a volume."
        },
        {
            "updated": "2012-08-13T00:00:00+00:00",
            "name": "CreateVolumeExtension",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/image-create/api/v1",
            "alias": "os-image-create",
            "description": "Allow creating a volume from an image in the Create Volume v1 API."
        },
        {
            "updated": "2014-01-10T00:00:00-00:00",
            "name": "ExtendedServices",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/extended_services/api/v2",
            "alias": "os-extended-services",
            "description": "Extended services support."
        },
        {
            "updated": "2012-06-19T00:00:00+00:00",
            "name": "ExtendedSnapshotAttributes",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1",
            "alias": "os-extended-snapshot-attributes",
            "description": "Extended SnapshotAttributes support."
        },
        {
            "updated": "2012-12-07T00:00:00+00:00",
            "name": "VolumeImageMetadata",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume_image_metadata/api/v1",
            "alias": "os-vol-image-meta",
            "description": "Show image metadata associated with the volume."
        },
        {
            "updated": "2012-03-12T00:00:00+00:00",
            "name": "QuotaClasses",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/quota-classes-sets/api/v1.1",
            "alias": "os-quota-class-sets",
            "description": "Quota classes management support."
        },
        {
            "updated": "2013-05-29T00:00:00+00:00",
            "name": "VolumeTransfer",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume-transfer/api/v1.1",
            "alias": "os-volume-transfer",
            "description": "Volume transfer management support."
        },
        {
            "updated": "2014-02-10T00:00:00+00:00",
            "name": "VolumeManage",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/os-volume-manage/api/v1",
            "alias": "os-volume-manage",
            "description": "Allows existing backend storage to be 'managed' by Cinder."
        },
        {
            "updated": "2012-08-25T00:00:00+00:00",
            "name": "AdminActions",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/admin-actions/api/v1.1",
            "alias": "os-admin-actions",
            "description": "Enable admin actions."
        },
        {
            "updated": "2012-10-28T00:00:00-00:00",
            "name": "Services",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/services/api/v2",
            "alias": "os-services",
            "description": "Services support."
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<extensions xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/common/api/v1.0">
    <extension alias="OS-SCH-HNT" updated="2013-04-18T00:00:00+00:00"
        namespace="http://docs.openstack.org/block-service/ext/scheduler-hints/api/v2"
        name="SchedulerHints">
        <description>Pass arbitrary key/value pairs to the
            scheduler.</description>
    </extension>
    <extension alias="os-hosts" updated="2011-06-29T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/hosts/api/v1.1"
        name="Hosts">
        <description>Admin-only host administration.</description>
    </extension>
    <extension alias="os-vol-tenant-attr"
        updated="2011-11-03T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume_tenant_attribute/api/v1"
        name="VolumeTenantAttribute">
        <description>Expose the internal project_id as an attribute of
            a volume.</description>
    </extension>
    <extension alias="os-quota-sets"
        updated="2011-08-08T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/quotas-sets/api/v1.1"
        name="Quotas">
        <description>Quota management support.</description>
    </extension>
    <extension alias="os-types-manage"
        updated="2011-08-24T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/types-manage/api/v1"
        name="TypesManage">
        <description>Types manage support.</description>
    </extension>
    <extension alias="os-volume-encryption-metadata"
        updated="2013-07-10T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/os-volume-encryption-metadata/api/v1"
        name="VolumeEncryptionMetadata">
        <description>Volume encryption metadata retrieval
            support.</description>
    </extension>
    <extension alias="backups" updated="2012-12-12T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/backups/api/v1"
        name="Backups">
        <description>Backups support.</description>
    </extension>
    <extension alias="os-snapshot-actions"
        updated="2013-07-16T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/snapshot-actions/api/v1.1"
        name="SnapshotActions">
        <description>Enable snapshot manager actions.</description>
    </extension>
    <extension alias="os-volume-actions"
        updated="2012-05-31T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume-actions/api/v1.1"
        name="VolumeActions">
        <description>Enable volume actions </description>
    </extension>
    <extension alias="os-used-limits"
        updated="2013-10-03T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/used-limits/api/v1.1"
        name="UsedLimits">
        <description>Provide data on limited resources that are being
            used.</description>
    </extension>
    <extension alias="os-volume-unmanage"
        updated="2012-05-31T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume-unmanage/api/v1.1"
        name="VolumeUnmanage">
        <description>Enable volume unmanage operation.</description>
    </extension>
    <extension alias="os-vol-host-attr"
        updated="2011-11-03T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume_host_attribute/api/v1"
        name="VolumeHostAttribute">
        <description>Expose host as an attribute of a
            volume.</description>
    </extension>
    <extension alias="encryption" updated="2013-07-01T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume-type-encryption/api/v1"
        name="VolumeTypeEncryption">
        <description>Encryption support for volume
            types.</description>
    </extension>
    <extension alias="os-availability-zone"
        updated="2013-06-27T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/os-availability-zone/api/v1"
        name="AvailabilityZones">
        <description>Describe Availability Zones.</description>
    </extension>
    <extension alias="qos-specs" updated="2013-08-02T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/qos-specs/api/v1"
        name="Qos_specs_manage">
        <description>QoS specs support.</description>
    </extension>
    <extension alias="os-types-extra-specs"
        updated="2011-08-24T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/types-extra-specs/api/v1"
        name="TypesExtraSpecs">
        <description>Type extra specs support.</description>
    </extension>
    <extension alias="os-vol-mig-status-attr"
        updated="2013-08-08T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume_mig_status_attribute/api/v1"
        name="VolumeMigStatusAttribute">
        <description>Expose migration_status as an attribute of a
            volume.</description>
    </extension>
    <extension alias="os-image-create"
        updated="2012-08-13T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/image-create/api/v1"
        name="CreateVolumeExtension">
        <description>Allow creating a volume from an image in the
            Create Volume v1 API.</description>
    </extension>
    <extension alias="os-extended-services"
        updated="2014-01-10T00:00:00-00:00"
        namespace="http://docs.openstack.org/volume/ext/extended_services/api/v2"
        name="ExtendedServices">
        <description>Extended services support.</description>
    </extension>
    <extension alias="os-extended-snapshot-attributes"
        updated="2012-06-19T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1"
        name="ExtendedSnapshotAttributes">
        <description>Extended SnapshotAttributes
            support.</description>
    </extension>
    <extension alias="os-vol-image-meta"
        updated="2012-12-07T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume_image_metadata/api/v1"
        name="VolumeImageMetadata">
        <description>Show image metadata associated with the
            volume.</description>
    </extension>
    <extension alias="os-quota-class-sets"
        updated="2012-03-12T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/quota-classes-sets/api/v1.1"
        name="QuotaClasses">
        <description>Quota classes management support.</description>
    </extension>
    <extension alias="os-volume-transfer"
        updated="2013-05-29T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume-transfer/api/v1.1"
        name="VolumeTransfer">
        <description>Volume transfer management support.</description>
    </extension>
    <extension alias="os-volume-manage"
        updated="2014-02-10T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/os-volume-manage/api/v1"
        name="VolumeManage">
        <description>Allows existing backend storage to be 'managed'
            by Cinder.</description>
    </extension>
    <extension alias="os-admin-actions"
        updated="2012-08-25T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/admin-actions/api/v1.1"
        name="AdminActions">
        <description>Enable admin actions.</description>
    </extension>
    <extension alias="os-services" updated="2012-10-28T00:00:00-00:00"
        namespace="http://docs.openstack.org/volume/ext/services/api/v2"
        name="Services">
        <description>Services support.</description>
    </extension>
</extensions>

This operation does not accept a request body.

Volumes

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

When you create, list, update, extend or delete volumes, these status values are possible:

Volume statuses

Status	Description
creating	The volume is being created.
available	The volume is ready to be attached to an 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 during volume creation.
error_deleting	An error occurred during volume deletion.
backing-up	The volume is being backed up.
restoring-backup	A backup is being restored to the volume.
error_restoring	An error occurred during backup restoration to a volume.
error_extending	An error occurred while attempting to extend a volume.

POST

/v2/{tenant_id}/volumes

Create volume

Creates a volume.

To create a bootable volume, include the ID of the image from which you want to create the volume in the imageRef attribute in the request body.

Preconditions

You must have enough volume storage quota remaining to create a volume of size requested./li>

Asynchronous Postconditions

With correct permissions, you can see the volume status as available through API calls.
With correct access, you can see the created volume in the storage system that OpenStack Block Storage manages.

Troubleshooting

If volume status remains creating or shows another error status, the request failed. Ensure you meet the preconditions then investigate the storage backend.
Volume is not created in the storage system which OpenStack Block Storage manages.
The storage node needs enough free storage space to match the specified size of the volume creation request.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
availability_zone (Optional)	plain	xsd:string	The availability zone.
source_volid (Optional)	plain	csapi:uuid	To create a volume from an existing volume, specify the ID of the existing volume. The volume is created with the same size as the source volume.
description (Optional)	plain	xsd:string	The volume description.
snapshot_id (Optional)	plain	csapi:uuid	To create a volume from an existing snapshot, specify the ID of the existing volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
size	plain	xsd:int	The size of the volume, in GBs.
name (Optional)	plain	xsd:string	The volume name.
imageRef (Optional)	plain	csapi:uuid	The ID of the image from which you want to create the volume. Required to create a bootable volume.
volume_type (Optional)	plain	xsd:string	The associated volume type.
metadata (Optional)	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.

Response parameters

Parameter	Style	Type	Description
status	plain	xsd:string	The volume status.
name	plain	xsd:string	The volume name.
attachments	plain	xsd:string	One or more instance attachments.
availability_zone	plain	xsd:string	The availability zone.
created_at	plain	xsd:datetime	Date and time when the volume was created.
description	plain	xsd:string	The volume description.
volume_type	plain	xsd:string	The associated volume type.
snapshot_id	plain	csapi:uuid	To create a volume from an existing volume snapshot, specify the ID of the existing volume snapshot.
source_volid	plain	csapi:uuid	To create a volume from an existing volume, specify the ID of the existing volume.
metadata	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
id	plain	csapi:uuid	The volume ID.
size	plain	xsd:int	The size of the volume, in GBs.

{
    "volume": {
        "availability_zone": null,
        "source_volid": null,
        "description": null,
        "snapshot_id": null,
        "size": 10,
        "name": "my_volume",
        "imageRef": null,
        "volume_type": null,
        "metadata": {}
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    name="vol-001" description="Another volume."
    size="2"/>

{
    "volume": {
        "status": "creating",
        "name": "my_volume",
        "attachments": [],
        "availability_zone": "nova",
        "bootable": "false",
        "created_at": "2014-02-21T19:52:04.949734",
        "description": null,
        "volume_type": "None",
        "snapshot_id": null,
        "source_volid": null,
        "metadata": {},
        "id": "93c2e2aa-7744-4fd6-a31a-80c4726b08d7",
        "size": 10
    }
}

<?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="creating"
    name="vol-001" availability_zone="nova" bootable="false"
    created_at="2014-02-21 20:18:33.122452"
    description="Another volume." volume_type="None"
    snapshot_id="None" source_volid="None"
    id="83960a54-8dad-4fd8-bc41-33c71e098e04" size="2">
    <attachments/>
    <metadata/>
</volume>

GET

/v2/{tenant_id}/volumes

List volumes

Lists summary information for all Block Storage volumes that the tenant who submits the request can access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
sort (Optional)	query	xsd:string	Comma-separated list of sort keys and optional sort directions in the form of <key>[:<direction>]. A valid direction is `asc` (ascending) or `desc` (descending).
limit (Optional)	query	xsd:int	Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.
marker (Optional)	query	xsd:string	Specifies the ID of the last-seen item. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.

{
"volumes": [
{
"id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
"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"
    }
],
"name": "vol-004"
},
{
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"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"
    }
],
"name": "vol-003"
}
]
}

<?xml version='1.0' encoding='UTF-8'?>
<volumes xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content">
<volume name="vol-004" id="45baf976-c20a-4894-a7c3-c94b7376bf55">
<attachments/>
<metadata/>
</volume>
<volume name="vol-003" id="5aa119a8-d25b-45a7-8d1b-88e127885635">
<attachments/>
<metadata/>
</volume>
</volumes>

GET

/v2/{tenant_id}/volumes/detail

List volumes (detailed)

Lists detailed information for all Block Storage volumes that the tenant who submits the request can access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
sort (Optional)	query	xsd:string	Comma-separated list of sort keys and optional sort directions in the form of <key>[:<direction>]. A valid direction is `asc` (ascending) or `desc` (descending).
limit (Optional)	query	xsd:int	Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.
marker (Optional)	query	xsd:string	Specifies the ID of the last-seen item. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.

{
"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",
"os-vol-host-attr: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",
"os-vol-tenant-attr: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",
"os-vol-host-attr: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",
"os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"metadata": {
    "contents": "not junk"
}
}
]
}

<?xml version='1.0' encoding='UTF-8'?>
<volumes
xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Image_Metadata.html"
xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Tenant_Attribute.html"
xmlns:os-vol-host-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Host_Attribute.html"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content">
<volume 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"
os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-vol-host-attr: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"
os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-vol-host-attr:host="ip-10-168-107-25">
<attachments/>
<metadata>
<meta key="contents">not junk</meta>
</metadata>
</volume>
</volumes>

GET

/v2/{tenant_id}/volumes/{volume_id}

Show volume information

Shows information about a specified volume.

Preconditions

The specified volume must exist.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.

{
"volume": {
"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",
"bootable": "false",
"os-vol-host-attr:host": "ip-10-168-107-25",
"source_volid": null,
"snapshot_id": null,
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"description": "Super volume.",
"name": "vol-002",
"created_at": "2013-02-25T02:40:21.000000",
"volume_type": "None",
"os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"metadata": {
"contents": "not junk"
}
}
}

<?xml version='1.0' encoding='UTF-8'?>
<volume
xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Image_Metadata.html"
xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Tenant_Attribute.html"
xmlns:os-vol-host-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Host_Attribute.html"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
status="available" name="vol-003" availability_zone="nova"
bootable="false" 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"
os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-vol-host-attr:host="ip-10-168-107-25">
<attachments/>
<metadata>
<meta key="contents">not junk</meta>
</metadata>
</volume>

This operation does not accept a request body.

PUT

/v2/{tenant_id}/volumes/{volume_id}

Update volume

Updates a volume.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.

{
"volume": {
"name": "vol-003",
"description": "This is yet, another volume."
}
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshot
xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
name="vol-003" description="This is yet, another volume."/>

{
"volume": {
"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",
"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",
"size": 1,
"metadata": {
"contents": "not junk"
}
}
}

<?xml version='1.0' encoding='UTF-8'?>
<volume xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
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">
<attachments/>
<metadata>
<meta key="contents">not junk</meta>
</metadata>
</volume>

DELETE

/v2/{tenant_id}/volumes/{volume_id}

Delete volume

Deletes a specified volume.

Preconditions

Volume status must be available, in-use, error, or error_restoring.
You cannot already have a snapshot related to the specified volume.
You cannot delete a volume that is in a migration.

Asynchronous Postconditions

The volume is deleted in volume index.
The volume managed by OpenStack Block Storage is deleted in storage node.

Troubleshooting

If volume status remains in deleting or becomes error_deleting the request failed. Ensure you meet the preconditions then investigate the storage backend.
The volume managed by OpenStack Block Storage is not deleted from the storage system.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.

This operation does not accept a request body and does not return a response body.

POST

/v2/{tenant_id}/volumes/{volume_id}/action

Extend volume

Extends the size of a specified volume to a new size requested in GB.

Preconditions

Volume status must be available.

Sufficient amount of storage must exist to extend the volume.

The user quota must have sufficient volume storage.

Troubleshooting

An error_extending volume status indicates that the request failed. Ensure that you meet the preconditions and retry the request. If the request fails, investigate the storage backend.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.
new_size	plain	xsd:int	The new size (in GB) of the volume.

{
"os-extend": {
"new_size": 3
}
}

This operation does not return a response body.

Volume types

GET

/v2/{tenant_id}/types

List volume types

Lists volume types.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
    "volume_types": [
        {
            "extra_specs": {
                "capabilities": "gpu"
            },
            "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
            "name": "SSD"
        },
        {
            "extra_specs": {},
            "id": "8eb69a46-df97-4e41-9586-9a40a7533803",
            "name": "SATA"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_types
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content">
    <volume_type id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="SSD">
        <extra_specs>
            <extra_spec key="capabilities">gpu</extra_spec>
        </extra_specs>
    </volume_type>
    <volume_type id="8eb69a46-df97-4e41-9586-9a40a7533803" name="SATA"
    />
</volume_types>

This operation does not accept a request body.

POST

/v2/{tenant_id}/types

Create volume type

Creates a volume type.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
"volume_type": {
"name": "vol-type-001",
"extra_specs": {
"capabilities": "gpu"
}
}
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
name="vol-type-001">
<extra_specs>
<extra_spec key="capabilities">gpu</extra_spec>
</extra_specs>
</volume_type>

{
"volume_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "vol-type-001",
"extra_specs": {
"capabilities": "gpu"
}
}
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type
xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="vol-type-001">
<extra_specs>
<extra_spec key="capabilities">gpu</extra_spec>
</extra_specs>
</volume_type>

GET

/v2/{tenant_id}/types/{volume_type_id}

Show volume type information

Shows information about a specified volume type.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_type_id	URI	csapi:UUID	The unique identifier for an existing volume type.

{
"volume_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "vol-type-001",
"extra_specs": {
"capabilities": "gpu"
}
}
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type
xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="vol-type-001">
<extra_specs>
<extra_spec key="capabilities">gpu</extra_spec>
</extra_specs>
</volume_type>

This operation does not accept a request body.

DELETE

/v2/{tenant_id}/types/{volume_type_id}

Delete volume type

Deletes a specified volume type.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_type_id	URI	csapi:UUID	The unique identifier for an existing volume type.

This operation does not accept a request body and does not return a response body.

Snapshots

A snapshot is a point-in-time copy of the data that a volume contains.

When you create, list, or delete snapshots, these status values are possible:

Snapshot statuses

Status	Description
creating	The snapshot is being created.
available	The snapshot is ready to be used.
deleting	The snapshot is being deleted.
error	An error occurred during snapshot creation.
error_deleting	An error occurred during snapshot deletion.

POST

/v2/{tenant_id}/snapshots

Create snapshot

Creates a snapshot, which is a point-in-time complete copy of a volume. You can create a volume from the snapshot.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot	query	string	A partial representation of a snapshot used in the creation process.
volume_id	query	string	To create a snapshot from an existing volume, specify the ID of the existing volume.
force (Optional)	query	xsd:boolean	[True/False] Indicate whether to snapshot, even if the volume is attached. Default==False.
name (Optional)	query	string	Name of the snapshot. Default==None.
description (Optional)	query	string	Description of snapshot. Default==None.

Response parameters

Parameter	Style	Type	Description
size	plain	xsd:int	The size of the volume, in GBs.

{
    "snapshot": {
        "name": "snap-001",
        "description": "Daily backup",
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "force": true
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshot
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    name="snap-001" description="Daily backup"
    volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" force="true"/>

{
    "snapshot": {
        "status": "creating",
        "description": "Daily backup",
        "created_at": "2013-02-25T03:56:53.081642",
        "metadata": {},
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "size": 1,
        "id": "ffa9bc5e-1172-4021-acaf-cdcd78a9584d",
        "name": "snap-001"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot status="creating" description="Daily backup"
    created_at="2013-02-25T03:56:53.081642"
    volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
    id="ffa9bc5e-1172-4021-acaf-cdcd78a9584d" name="snap-001">
    <metadata/>
</snapshot>

GET

/v2/{tenant_id}/snapshots

List snapshots

Lists summary information for all Block Storage snapshots that the tenant who submits the request can access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
"snapshots": [
{
"status": "available",
"description": "Very important",
"created_at": "2013-02-25T04:13:17.000000",
"metadata": {},
"volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"size": 1,
"id": "2bb856e1-b3d8-4432-a858-09e4ce939389",
"name": "snap-001"
},
{
"status": "available",
"description": "Weekly backup",
"created_at": "2013-02-25T07:20:38.000000",
"metadata": {},
"volume_id": "806092e3-7551-4fff-a005-49016f4943b1",
"size": 1,
"id": "e820db06-58b5-439d-bac6-c01faa3f6499",
"name": "snap-002"
}
]
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshots>
<snapshot status="available" description="Very important"
created_at="2013-02-25 04:13:17"
volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
id="2bb856e1-b3d8-4432-a858-09e4ce939389" name="snap-001">
<metadata/>
</snapshot>
<snapshot status="available" description="Weekly backup"
created_at="2013-02-25 07:20:38"
volume_id="806092e3-7551-4fff-a005-49016f4943b1" size="1"
id="e820db06-58b5-439d-bac6-c01faa3f6499" name="snap-002">
<metadata/>
</snapshot>
</snapshots>

This operation does not accept a request body.

GET

/v2/{tenant_id}/snapshots/detail

List snapshots (detailed)

Lists detailed information for all Block Storage snapshots that the tenant who submits the request can access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
"snapshots": [
{
"status": "available",
"os-extended-snapshot-attributes:progress": "100%",
"description": "Daily backup",
"created_at": "2013-02-25T07:30:12.000000",
"metadata": {},
"volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 30,
"id": "43f20e0e-2c2c-4770-9d4e-c3d769ae5470",
"name": "snap-001"
},
{
"status": "available",
"os-extended-snapshot-attributes:progress": "100%",
"description": "Weekly backup",
"created_at": "2013-02-25T07:20:38.000000",
"metadata": {},
"volume_id": "806092e3-7551-4fff-a005-49016f4943b1",
"os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"id": "e820db06-58b5-439d-bac6-c01faa3f6499",
"name": "snap-002"
}
]
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshots
xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html">
<snapshot status="available" description="Daily backup"
created_at="2013-02-25 07:30:12"
volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="30"
id="43f20e0e-2c2c-4770-9d4e-c3d769ae5470" name="snap-001"
os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-extended-snapshot-attributes:progress="100%">
<metadata/>
</snapshot>
<snapshot status="available" description="Weekly backup"
created_at="2013-02-25 07:20:38"
volume_id="806092e3-7551-4fff-a005-49016f4943b1" size="1"
id="e820db06-58b5-439d-bac6-c01faa3f6499" name="snap-002"
os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-extended-snapshot-attributes:progress="100%">
<metadata/>
</snapshot>
</snapshots>

This operation does not accept a request body.

GET

/v2/{tenant_id}/snapshots/{snapshot_id}

Show snapshot information

Shows information for a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
"snapshot": {
"status": "available",
"os-extended-snapshot-attributes:progress": "100%",
"description": "Daily backup",
"created_at": "2013-02-25T04:13:17.000000",
"metadata": {},
"volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"id": "2bb856e1-b3d8-4432-a858-09e4ce939389",
"name": "snap-001"
}
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot
xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html"
status="available" description="Very important"
created_at="2013-02-25 04:13:17"
volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
id="2bb856e1-b3d8-4432-a858-09e4ce939389" name="snap-001"
os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-extended-snapshot-attributes:progress="100%">
<metadata/>
</snapshot>

This operation does not accept a request body.

PUT

/v2/{tenant_id}/snapshots/{snapshot_id}

Update snapshot

Updates a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
"snapshot": {
"name": "snap-002",
"description": "This is yet, another snapshot."
}
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshot
xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
name="snap-002" description="This is yet, another snapshot."/>

{
"snapshot": {
"created_at": "2013-02-20T08:11:34.000000",
"description": "This is yet, another snapshot",
"name": "vol-002",
"id": "4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2",
"size": 1,
"status": "available",
"volume_id": "2402b902-0b7a-458c-9c07-7435a826f794"
}
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot
xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html"
status="available"
description="This is yet, another snapshot"
created_at="2013-02-20T08:11:34.000000"
volume_id="2402b902-0b7a-458c-9c07-7435a826f794"
size="1"
id="4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2"
name="vol-002"
os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-extended-snapshot-attributes:progress="100%">
<metadata/>
</snapshot>

DELETE

/v2/{tenant_id}/snapshots/{snapshot_id}

Delete snapshot

Deletes a specified snapshot.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

This operation does not accept a request body and does not return a response body.

GET

/v2/{tenant_id}/snapshots/{snapshot_id}/metadata

Show snapshot metadata

Shows the metadata for a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
"snapshot": {
"status": "available",
"os-extended-snapshot-attributes:progress": "0%",
"description": null,
"created_at": "2014-05-06T17:59:52.000000",
"metadata": {
"key": "v2"
},
"volume_id": "ebd80b99-bc3d-4154-9d28-5583baa80580",
"os-extended-snapshot-attributes:project_id": "7e0105e19cd2466193729ef78b604f79",
"size": 10,
"id": "dfcd17fe-3b64-44ba-b95f-1c9c7109ef95",
"name": "my-snapshot"
}
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot
xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1"
status="available" description="None"
created_at="2014-05-06 17:59:52"
volume_id="ebd80b99-bc3d-4154-9d28-5583baa80580" size="10"
id="dfcd17fe-3b64-44ba-b95f-1c9c7109ef95" name="my-snapshot"
os-extended-snapshot-attributes:project_id="7e0105e19cd2466193729ef78b604f79"
os-extended-snapshot-attributes:progress="0%">
<metadata>
<meta key="key">v2</meta>
</metadata>
</snapshot>

This operation does not accept a request body.

PUT

/v2/{tenant_id}/snapshots/{snapshot_id}/metadata

Update snapshot metadata

Updates the metadata for a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
"metadata": {
"key": "v2"
}
}

<?xml version='1.0' encoding='UTF-8'?>
<metadata>
<meta key="key">v2</meta>
</metadata>

{
"metadata": {
"key": "v2"
}
}

<?xml version='1.0' encoding='UTF-8'?>
<metadata xmlns="http://docs.openstack.org/compute/api/v1.1">
<meta key="key">v2</meta>
</metadata>

Limits extension (limits)

Shows absolute limits for a tenant.

GET

v2/{tenant_id}/limits

Show absolute limits

Shows absolute limits for a tenant.

Normal response codes

200, 203

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.

Response parameters

Parameter	Style	Type	Description
limits	plain	xsd:string	A `limits` object.
absolute	plain	xsd:string	An `absolute` limits object.
totalSnapshotsUsed	plain	xsd:int	Total number of snapshots used.
maxTotalVolumeGigabytes	plain	xsd:int	Maximum total amount of volumes (GB).
totalGigabytesUsed	plain	xsd:int	Total number of GBs used.
maxTotalSnapshots	plain	xsd:int	Maximum number of snapshots.
totalVolumesUsed	plain	xsd:int	Total number of volumes used.
maxTotalVolumes	plain	xsd:int	Maximum number of volumes.

{
    "limits": {
        "rate": [],
        "absolute": {
            "totalSnapshotsUsed": 0,
            "maxTotalVolumeGigabytes": 1000,
            "totalGigabytesUsed": 0,
            "maxTotalSnapshots": 10,
            "totalVolumesUsed": 0,
            "maxTotalVolumes": 10
        }
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<limits xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/common/api/v1.0">
    <rates/>
    <absolute>
        <limit name="totalSnapshotsUsed" value="0"/>
        <limit name="maxTotalVolumeGigabytes" value="1000"/>
        <limit name="totalGigabytesUsed" value="0"/>
        <limit name="maxTotalSnapshots" value="10"/>
        <limit name="totalVolumesUsed" value="0"/>
        <limit name="maxTotalVolumes" value="10"/>
    </absolute>
</limits>

This operation does not accept a request body.

Backups

A backup is a full copy of a volume stored in an external service. The service can be configured. The only supported service for now is Object Storage. A backup can subsequently be restored from the external service to either the same volume that the backup was originally taken from, or to a new volume. backup and restore operations can only be carried out on volumes which are in an unattached and available state.

When you create, list, or delete backups, these status values are possible:

Backup statuses

Status	Description
creating	The backup is being created.
available	The backup is ready to be restored to a volume.
deleting	The backup is being deleted.
error	An error has occurred with the backup.
restoring	The backup is being restored to a volume.
error_restoring	An error occurred during backup restoration to a volume.

In the event of an error, more information about the error can be found in the fail_reason field for the backup.

Volume manage extension (os-volume-manage)

Creates volumes by using existing storage instead of allocating new storage.

POST

/v2/{tenant_id}/os-volume-manage

Manage existing volume

Creates a Block Storage volume using existing storage instead of creating new storage.

When the request is made, the caller must specify (in the ref element) a reference to an existing storage volume. Each storage driver may interpret the existing storage volume reference differently, but should accept a reference structure containing either a source-volume-id or source-volume-name element if possible.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume	plain	xsd:string	A `volume` object.
host	plain	xsd:string	The cinder host on which the existing volume resides.
ref	plain	xsd:string	A reference to the existing volume. The internal structure of this reference is dependent on the implementation of the volume driver, see the specific driver's documentation for details of the required elements in the structure.
name (Optional)	plain	xsd:string	The volume name.
availability_zone (Optional)	plain	xsd:string	The availability zone.
description (Optional)	plain	xsd:string	The volume description.
volume_type (Optional)	plain	xsd:string	The associated volume type.
bootable (Optional)	plain	xsd:boolean	Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
metadata (Optional)	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.

{
    "volume": {
        "host": "geraint-VirtualBox",
        "ref": {
            "source-volume-name": "existingLV",
            "source-volume-id": "1234"
        },
        "name": "New Volume",
        "availability_zone": "az2",
        "description": "Volume imported from existingLV",
        "volume_type": null,
        "bootable": "True",
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

{
    "volume": {
        "status": "creating",
        "user_id": "eae1472b5fc5496998a3d06550929e7e",
        "attachments": [],
        "links": [
            {
                "href": "http://10.0.2.15:8776/v2/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
                "rel": "self"
            },
            {
                "href": "http://10.0.2.15:8776/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "az2",
        "bootable": "false",
        "encrypted": "false",
        "created_at": "2014-07-18T00:12:54.000000",
        "description": "Volume imported from existingLV",
        "os-vol-tenant-attr:tenant_id": "87c8522052ca4eed98bc672b4c1a3ddb",
        "volume_type": null,
        "name": "New Volume",
        "source_volid": null,
        "snapshot_id": null,
        "metadata": {
            "key2": "value2",
            "key1": "value1"
        },
        "id": "23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
        "size": 0
    }
}

Volume type access (volumes)

Creates private volumes.

By default, volumes are public. To create a private volume, set the is_public boolean field to false at volume creation time. To control access to a private volume, you add a project to or remove a project from the volume. Private volume types without projects are only visible by users with the administrative role and context.

POST

/v2/{tenant_id}/volumes

Create volume

Creates and get details for private Block Storage volume.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
availability_zone (Optional)	plain	xsd:string	The availability zone.
source_volid (Optional)	plain	csapi:uuid	To create a volume from an existing volume, specify the ID of the existing volume. The volume is created with the same size as the source volume.
description (Optional)	plain	xsd:string	The volume description.
snapshot_id (Optional)	plain	csapi:uuid	To create a volume from an existing snapshot, specify the ID of the existing volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
size	plain	xsd:int	The size of the volume, in GBs.
name (Optional)	plain	xsd:string	The volume name.
imageRef (Optional)	plain	csapi:uuid	The ID of the image from which you want to create the volume. Required to create a bootable volume.
volume_type (Optional)	plain	xsd:string	The associated volume type.
metadata (Optional)	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
os-volume-type-access:is_public (Optional)	plain	xsd:boolean	The volume type access. Set to `true` if access is public. Set to `false` if access is private.

Response parameters

Parameter	Style	Type	Description
status	plain	xsd:string	The volume status.
name	plain	xsd:string	The volume name.
attachments	plain	xsd:string	One or more instance attachments.
availability_zone	plain	xsd:string	The availability zone.
created_at	plain	xsd:datetime	Date and time when the volume was created.
description	plain	xsd:string	The volume description.
volume_type	plain	xsd:string	The associated volume type.
snapshot_id	plain	csapi:uuid	To create a volume from an existing volume snapshot, specify the ID of the existing volume snapshot.
source_volid	plain	csapi:uuid	To create a volume from an existing volume, specify the ID of the existing volume.
metadata	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
id	plain	csapi:uuid	The volume ID.
size	plain	xsd:int	The size of the volume, in GBs.
os-volume-type-access:is_public	plain	xsd:boolean	The volume type access. Set to `true` if access is public. Set to `false` if access is private.

{
    "volume": {
        "availability_zone": null,
        "source_volid": null,
        "description": null,
        "snapshot_id": null,
        "size": 10,
        "name": "my_volume",
        "imageRef": null,
        "volume_type": null,
        "metadata": {},
        "os-volume-type-access: is_public": false
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" name="vol-001" description="Another volume." size="2" os-volume-type-access:is_public="false" />

{
    "volume": {
        "status": "creating",
        "name": "my_volume",
        "attachments": [],
        "availability_zone": "nova",
        "bootable": "false",
        "created_at": "2014-02-21T19: 52: 04.949734",
        "description": null,
        "volume_type": "None",
        "snapshot_id": null,
        "source_volid": null,
        "metadata": {},
        "id": "93c2e2aa-7744-4fd6-a31a-80c4726b08d7",
        "size": 10,
        "os-volume-type-access: is_public": false
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" status="creating" name="vol-001" availability_zone="nova" bootable="false" created_at="2014-02-21 20:18:33.122452" description="Another volume." volume_type="None" snapshot_id="None" source_volid="None" id="83960a54-8dad-4fd8-bc41-33c71e098e04" size="2" os-volume-type-access:is_public="false">
    <attachments />
    <metadata />
</volume>