Block Storage API v2 (CURRENT)

Manages volumes and snapshots for use with the Block Storage API, 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 similar to a USB hard drive. You can attach a volume to one instance at a time.

The snapshot_id and source_volid parameters specify the ID of the snapshot or volume from which this volume originates. If the volume was not created from a snapshot or source volume, these values are null.

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

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.

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 back end.

  • 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 gibibytes (GiB).

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:dict

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

The ID of the source volume snapshot.

source_volid plain csapi:uuid

The ID of the source 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 gibibytes (GiB).

{
    "volume": {
        "status": "creating",
        "description": null,
        "availability_zone": null,
        "source_volid": null,
        "consistencygroup_id": null,
        "snapshot_id": null,
        "source_replica": null,
        "size": 10,
        "user_id": null,
        "name": null,
        "imageRef": null,
        "attach_status": "detached",
        "volume_type": null,
        "project_id": 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",
        "user_id": "{user_id}",
        "attachments": [],
        "links": [
            {
                "href": "http://volume.example.com:8776/v2/{tenant_id}/volumes/{volume_id}",
                "rel": "self"
            },
            {
                "href": "http://volume.example.com:8776/{tenant_id}/volumes/{volume_id}",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "encrypted": false,
        "created_at": "2015-05-17T18:14:34.000000",
        "description": null,
        "os-vol-tenant-attr:tenant_id": "{tenant_id}",
        "os-volume-replication:driver_data": null,
        "volume_type": "lvmdriver-1",
        "name": null,
        "replication_status": "disabled",
        "consistencygroup_id": null,
        "source_volid": null,
        "snapshot_id": null,
        "os-volume-replication:extended_status": null,
        "metadata": {},
        "id": "7449e332-9715-4185-b191-1cfd91d75d48",
        "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.

Response parameters
Parameter Style Type Description
status plain xsd:string

The volume status.

name plain xsd:string

The volume name.

attachments plain xsd:dict

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

The ID of the source volume snapshot.

source_volid plain csapi:uuid

The ID of the source 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 gibibytes (GiB).

{
    "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.

Response parameters
Parameter Style Type Description
status plain xsd:string

The volume status.

name plain xsd:string

The volume name.

attachments plain xsd:dict

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

The ID of the source volume snapshot.

source_volid plain csapi:uuid

The ID of the source 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 gibibytes (GiB).

{
    "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.

Response parameters
Parameter Style Type Description
status plain xsd:string

The volume status.

name plain xsd:string

The volume name.

attachments plain xsd:dict

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

The ID of the source volume snapshot.

source_volid plain csapi:uuid

The ID of the source 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 gibibytes (GiB).

{
    "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.

Response parameters
Parameter Style Type Description
status plain xsd:string

The volume status.

name plain xsd:string

The volume name.

attachments plain xsd:dict

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

The ID of the source volume snapshot.

source_volid plain csapi:uuid

The ID of the source 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 gibibytes (GiB).

{
    "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 back end.

  • 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.

Volume actions

Performs actions for a specified volume. Extends the size, resets statuses for, sets image metadata, or removes image metadata from a volume.

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/action
Extend volume

Extends the size of a specified volume to a new size requested in gibibytes (GiB). Specify the os-extend action in the request body.

 

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 again, investigate the storage back end.

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 of the volume, in gibibytes (GiB).

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

This operation does not return a response body.

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/action
Reset volume statuses

Resets the status, attach status, and migration status for a specified volume. Specify the os-reset_status action in the request body.

 
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.

status (Optional) plain xsd:string

The volume status.

attach_status (Optional) plain xsd:string

The volume attach status.

migration_status (Optional) plain xsd:string

The volume migration status.

{
    "os-reset_status": {
        "status": "available",
        "attach_status": "detached",
        "migration_status": "migrating"
    }
}

This operation does not return a response body.

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/action
Set image metadata for volume

Sets the image metadata for a specified volume. Specify the os-set_image_metadata action in the request body.

 
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.

os-set_image_metadata plain xsd:string

The os-set_image_metadata action.

metadata plain xsd:string

The image metadata to add to the volume as a set of metadata key and value pairs.

{
    "os-set_image_metadata": {
        "metadata": {
            "image_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "image_name": "image",
            "kernel_id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
            "ramdisk_id": "somedisk"
        }
    }
}

This operation does not return a response body.

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/action
Remove image metadata from volume

Removes image metadata, by key, from a specified volume. Specify the os-unset_image_metadata action in the request body and the key for the metadata key and value pair that you want to remove.

 
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.

os-unset_image_metadata plain xsd:string

The os-unset_image_metadata action.

key plain xsd:string

The metadata key name for the metadata that you want to remove.

{
    "os-unset_image_metadata": {
        "key": "ramdisk_id"
    }
}

This operation does not return a response body.

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/action
Attach volume

Attaches the specified volume to the specified server. Specify the os-attach action in the request body.

 

Preconditions

  • Volume status must be available.

  • You should set instance_uuid or host_name.

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.

os-attach plain xsd:string

The os-attach action.

instance_uuid (Optional) plain csapi:UUID

The UUID of the attaching instance.

host_name (Optional) plain xsd:string

The name of the attaching host.

mountpoint (Optional) plain xsd:string

The attaching mountpoint.

{
    "os-attach": {
        "instance_uuid": "95D9EF50-507D-11E5-B970-0800200C9A66",
        "host_name": "cinder-2",
        "mountpoint": "/dev/vdc"
    }
}

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>
PUT
/v2/​{tenant_id}​/types/​{volume_type_id}​
Update volume type

Updates 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_id URI csapi:UUID

The unique identifier for an existing volume type.

volume_type plain csapi:string

A volume type offers a way to categorize or group volumes.

{
    "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": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "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"
             id="289da7f8-6440-407c-9fb4-7db01ec49164"
             name="vol-type-001">
    <extra_specs>
        <extra_spec key="capabilities">gpu</extra_spec>
    </extra_specs>
</volume_type>
PUT
/v2/​{tenant_id}​/types/​{volume_type_id}​
Update extra specs for a volume type

Updates the extra specifications assigned to 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_id URI csapi:UUID

The unique identifier for an existing volume type.

volume_type plain csapi:string

A volume type offers a way to categorize or group volumes.

extra_specs plain csapi:string

A key:value pair that offers a way to show additional specifications associated with the volume type. Examples include capabilities, capacity, compression, and so on, depending on the storage driver in use.

{
    "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": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "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"
             id="289da7f8-6440-407c-9fb4-7db01ec49164"
             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 gibibytes (GiB).

{
    "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.

sort_key (Optional) query xsd:string

Sorts by the requested image attribute. Accepted values are name, status, container_format, disk_format, size, id, created_at, and updated_at. Default is created_at. The API uses the natural sorting direction of the image attribute that is provided as the sort_key.

sort_dir (Optional) query xsd:string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc.

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.

{
    "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>
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": "snap-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="snap-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>

Quality of service (QoS) specifications (qos-specs)

Administrators only, depending on policy settings.

Creates, lists, shows details for, associates, disassociates, sets keys, unsets keys, and deletes quality of service (QoS) specifications.

POST
/v2/​{tenant_id}​/qos-specs
Create QoS specification

Creates a QoS specification.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

qos_specs plain xsd:string

A qos_specs object.

name plain xsd:string

The name of the QoS specification.

specs plain xsd:string

Specification key and value pairs.

Response parameters
Parameter Style Type Description
qos_specs plain xsd:string

A qos_specs object.

specs plain xsd:string

A specs object.

consumer plain xsd:string

The consumer type.

name plain xsd:string

The name of the QoS specification.

id plain csapi:uuid

The generated ID for the QoS specification.

links plain xsd:dict

The QoS specification links.

{
    "qos_specs": {
        "availability": "100",
        "name": "reliability-spec",
        "numberOfFailures": "0"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<qos_specs name="performance-spec" delay="0" throughput="100"/>
{
    "qos_specs": {
        "specs": {
            "availability": "100",
            "numberOfFailures": "0"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v2/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "self"
        },
        {
            "href": "http://23.253.228.211:8776/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "bookmark"
        }
    ]
}
<?xml version='1.0' encoding='UTF-8'?>
<qos_specs>
    <qos_spec consumer="back-end"
        id="ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
        name="performance-spec">
        <specs>
            <delay>0</delay>
            <throughput>100</throughput>
        </specs>
    </qos_spec>
</qos_specs>
GET
/v2/​{tenant_id}​/qos-specs
List QoS specs

Lists quality of service (QoS) specifications.

 
Normal response codes
200, 300
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

Response parameters
Parameter Style Type Description
qos_specs plain xsd:string

A qos_specs object.

specs plain xsd:string

Specification key and value pairs.

consumer plain xsd:string

The consumer type.

name plain xsd:string

The name of the QoS specification.

id plain csapi:uuid

The generated ID for the QoS specification.

{
    "qos_specs": [
        {
            "specs": {
                "availability": "100",
                "numberOfFailures": "0"
            },
            "consumer": "back-end",
            "name": "reliability-spec",
            "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
        },
        {
            "specs": {
                "delay": "0",
                "throughput": "100"
            },
            "consumer": "back-end",
            "name": "performance-spec",
            "id": "ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
        }
    ]
}
<?xml version='1.0' encoding='UTF-8'?>
<qos_specs>
    <qos_spec consumer="back-end"
        id="0388d6c6-d5d4-42a3-b289-95205c50dd15"
        name="reliability-spec">
        <specs>
            <availability>100</availability>
            <numberOfFailures>0</numberOfFailures>
        </specs>
    </qos_spec>
    <qos_spec consumer="back-end"
        id="ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
        name="performance-spec">
        <specs>
            <delay>0</delay>
            <throughput>100</throughput>
        </specs>
    </qos_spec>
</qos_specs>

This operation does not accept a request body.

GET
/v2/​{tenant_id}​/qos-specs/​{qos_id}​
Show QoS specification details

Shows details for a specified QoS specification.

 
Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

qos_id URI csapi:UUID

The UUID for the QoS specification.

Response parameters
Parameter Style Type Description
qos_specs plain xsd:string

A qos_specs object.

specs plain xsd:string

Specification key and value pairs.

consumer plain xsd:string

The consumer type.

name plain xsd:string

The name of the QoS specification.

id plain csapi:uuid

The generated ID for the QoS specification.

links plain xsd:dict

The QoS specification links.

{
    "qos_specs": {
        "specs": {
            "availability": "100",
            "numberOfFailures": "0"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v2/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "self"
        },
        {
            "href": "http://23.253.228.211:8776/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "bookmark"
        }
    ]
}
<?xml version='1.0' encoding='UTF-8'?>
<qos_specs>
    <qos_spec consumer="back-end"
        id="0388d6c6-d5d4-42a3-b289-95205c50dd15"
        name="reliability-spec">
        <specs>
            <availability>100</availability>
            <numberOfFailures>0</numberOfFailures>
        </specs>
    </qos_spec>
</qos_specs>

This operation does not accept a request body.

PUT
/v2/​{tenant_id}​/qos-specs/​{qos_id}​
Set or unset keys in QoS specification

Sets or unsets keys in a specified QoS specification.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

qos_id URI csapi:UUID

The UUID for the QoS specification.

qos_specs plain xsd:string

A qos_specs object.

specs plain xsd:string

Specification key and value pairs.

{
    "qos_specs": {
        "delay": "1"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<qos_specs delay="2" throughput="100"/>
{
    "qos_specs": {
        "delay": "1"
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<qos_specs>
    <qos_spec/>
</qos_specs>
DELETE
/v2/​{tenant_id}​/qos-specs/​{qos_id}​
Delete QoS specification

Deletes a specified QoS specification.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

qos_id URI csapi:UUID

The UUID for the QoS specification.

qos_id URI xsd:string

The unique ID of the QoS specification.

force URI String

Optional flag that indicates whether to delete the specified QoS specification even if it is in-use.

This operation does not return a response body.

GET
/v2/​{tenant_id}​/qos-specs/​{qos_id}​/associate
Associate QoS specification with volume type

Associates a QoS specification with a specified volume type.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

qos_id URI csapi:UUID

The UUID for the QoS specification.

vol_type_id (Optional) query xsd:string

The unique ID of the volume type.

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

GET
/v2/​{tenant_id}​/qos-specs/​{qos_id}​/disassociate
Disassociate QoS specification from volume type

Disassociates a QoS specification from a specified volume type.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

qos_id URI csapi:UUID

The UUID for the QoS specification.

vol_type_id (Optional) query xsd:string

The unique ID of the volume type.

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

GET
/v2/​{tenant_id}​/qos-specs/​{qos_id}​/disassociate_all
Disassociate QoS specification from all associations

Disassociates a specified QoS specification from all associations.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

qos_id URI csapi:UUID

The UUID for the QoS specification.

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

GET
/v2/​{tenant_id}​/qos-specs/​{qos_id}​/associations
Get all associations for QoS specification

Gets all associations for a specified QoS specification.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique ID of the tenant or account.

qos_id URI csapi:UUID

The UUID for the QoS specification.

{
    "qos_associations": [
        {
            "association_type": "volume_type",
            "name": "reliability-type",
            "id": "a12983c2-83bd-4afa-be9f-ad796573ead6"
        }
    ]
}
<?xml version='1.0' encoding='UTF-8'?>
<qos_associations>
    <associations association_type="volume_type"
        name="reliability-type"
        id="a12983c2-83bd-4afa-be9f-ad796573ead6"/>
</qos_associations>

This operation does not accept a request body.

Quota sets extension (os-quota-sets)

Administrators only, depending on policy settings.

Shows, updates, and deletes quotas for a tenant.

GET
/v2/​{tenant_id}​/os-quota-sets/​{tenant_id}​
Show quotas

Shows quotas for a tenant.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The ID for the tenant or project in a multi-tenancy cloud.

tenant_id URI xsd:string

The ID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.

usage (Optional) query xsd:boolean

Set to usage=True to show quota usage. Default is False.

Response parameters
Parameter Style Type Description
quota_set plain xsd:string

A quota_set object.

gigabytes plain xsd:int

The number of gigabytes allowed for each tenant.

snapshots plain xsd:int

The number of snapshots allowed for each tenant.

volumes plain xsd:int

The number of volumes allowed for each tenant.

in_use (Optional) plain xsd:string

The in use data size. Visible only if you set the usage=True query parameter.

reserved (Optional) plain xsd:int

Reserved volume size. Visible only if you set the usage=True query parameter.

{
    "quota_set": {
        "gigabytes": 5,
        "snapshots": 10,
        "volumes": 20
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>
PUT
/v2/​{tenant_id}​/os-quota-sets/​{tenant_id}​
Update quotas

Updates quotas for a tenant.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The ID for the tenant or project in a multi-tenancy cloud.

tenant_id URI xsd:string

The ID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.

quota_set plain xsd:string

A quota_set object.

gigabytes plain xsd:int

The number of gigabytes allowed for each tenant.

snapshots plain xsd:int

The number of snapshots allowed for each tenant.

volumes plain xsd:int

The number of volumes allowed for each tenant.

Response parameters
Parameter Style Type Description
quota_set plain xsd:string

A quota_set object.

gigabytes plain xsd:int

The number of gigabytes allowed for each tenant.

snapshots plain xsd:int

The number of snapshots allowed for each tenant.

volumes plain xsd:int

The number of volumes allowed for each tenant.

{
    "quota_set": {
        "snapshots": 45
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <snapshots>45</snapshots>
</quota_set>
{
    "quota_set": {
        "snapshots": 45
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>
DELETE
/v2/​{tenant_id}​/os-quota-sets/​{tenant_id}​
Delete quotas

Deletes quotas for a tenant so the quotas revert to default values.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The ID for the tenant or project in a multi-tenancy cloud.

tenant_id URI xsd:string

The ID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.

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

GET
/v2/​{tenant_id}​/os-quota-sets/defaults
Get default quotas

Gets default quotas for a tenant.

 
Normal response codes
200
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
quota_set plain xsd:string

A quota_set object.

gigabytes plain xsd:int

The number of gigabytes allowed for each tenant.

snapshots plain xsd:int

The number of snapshots allowed for each tenant.

volumes plain xsd:int

The number of volumes allowed for each tenant.

{
    "quota_set": {
        "gigabytes": 5,
        "snapshots": 10,
        "volumes": 20
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>

This operation does not accept a request body.

GET
/v2/​{tenant_id}​/os-quota-sets/​{tenant_id}​/​{user_id}​
Show quotas for user

Enables an admin user to show quotas for a specified tenant and user.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The ID for the tenant or project in a multi-tenancy cloud.

tenant_id URI xsd:string

The ID for the tenant for which you want to show or update quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.

user_id URI xsd:string

The user ID. Specify in the URI as a query string: user_id={user_id}.

Response parameters
Parameter Style Type Description
quota_set plain xsd:string

A quota_set object.

gigabytes plain xsd:int

The number of gigabytes allowed for each tenant.

snapshots plain xsd:int

The number of snapshots allowed for each tenant.

volumes plain xsd:int

The number of volumes allowed for each tenant.

{
    "quota_set": {
        "snapshots": 45
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>

This operation does not accept a request body.

PUT
/v2/​{tenant_id}​/os-quota-sets/​{tenant_id}​/​{user_id}​
Update quotas for user

Updates quotas for a specified tenant/project and user.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The ID for the tenant or project in a multi-tenancy cloud.

tenant_id URI xsd:string

The ID for the tenant for which you want to show or update quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.

user_id URI xsd:string

The user ID. Specify in the URI as a query string: user_id={user_id}.

quota_set plain xsd:string

A quota_set object.

gigabytes plain xsd:int

The number of gigabytes allowed for each tenant.

snapshots plain xsd:int

The number of snapshots allowed for each tenant.

volumes plain xsd:int

The number of volumes allowed for each tenant.

Response parameters
Parameter Style Type Description
quota_set plain xsd:string

A quota_set object.

gigabytes plain xsd:int

The number of gigabytes allowed for each tenant.

snapshots plain xsd:int

The number of snapshots allowed for each tenant.

volumes plain xsd:int

The number of volumes allowed for each tenant.

{
    "quota_set": {
        "snapshots": 45
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <snapshots>45</snapshots>
</quota_set>
{
    "quota_set": {
        "snapshots": 45
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>
DELETE
/v2/​{tenant_id}​/os-quota-sets/​{tenant_id}​/​{user_id}​
Delete quotas for user

Deletes quotas for a user so that the quotas revert to default values.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The ID for the tenant or project in a multi-tenancy cloud.

tenant_id URI xsd:string

The ID for the tenant for which you want to show or update quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.

user_id URI xsd:string

The user ID. Specify in the URI as a query string: user_id={user_id}.

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

GET
/v2/​{tenant_id}​/os-quota-sets/​{tenant_id}​/detail/​{user_id}​
Show quota details for user

Shows details for quotas for a specified tenant and user.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The ID for the tenant or project in a multi-tenancy cloud.

tenant_id URI xsd:string

The ID for the tenant for which you want to show or update quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.

user_id URI xsd:string

The user ID. Specify in the URI as a query string: user_id={user_id}.

Response parameters
Parameter Style Type Description
quota_set plain xsd:string

A quota_set object.

gigabytes plain xsd:int

The number of gigabytes allowed for each tenant.

snapshots plain xsd:int

The number of snapshots allowed for each tenant.

volumes plain xsd:int

The number of volumes allowed for each tenant.

{
    "quota_set": {
        "snapshots": 45
    }
}

This operation does not accept a request body.

Limits extension (limits)

Shows absolute limits for a tenant.

An absolute limit value of -1 indicates that the absolute limit for the item is infinite.

GET
/v2/​{tenant_id}​/limits
Show absolute limits

Shows absolute limits for a tenant.

 

An absolute limit value of -1 indicates that the absolute limit for the item is infinite.

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, in gibibytes (GiB).

totalGigabytesUsed plain xsd:int

Total number of gibibytes (GiB) 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.

POST
/v2/​{tenant_id}​/backups
Create backup

Creates a Block Storage backup from a volume.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

backup plain xsd:string

A backup object.

container plain xsd:string

The container name or null.

name plain xsd:string

The backup name.

description plain xsd:string

The backup description or null.

volume_id plain csapi:uuid

The ID of the volume that you want to back up.

incremental (Optional) plain xsd:boolean

The backup mode. A valid value is True for incremental backup mode or False for full backup mode. Default is False.

Response parameters
Parameter Style Type Description
backup plain xsd:string

A backup object.

id plain csapi:uuid

The ID of the backup.

links plain xsd:dict

Links for the backup.

name plain xsd:string

The backup name.

{
    "backup": {
        "container": null,
        "description": null,
        "name": "backup001",
        "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607",
        "incremental": "True"
    }
}
{
    "backup": {
        "id": "deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
        "links": [
            {
                "href": "http://localhost:8776/v2/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
                "rel": "bookmark"
            }
        ],
        "name": "backup001"
    }
}
GET
/v2/​{tenant_id}​/backups
List backups

Lists backups defined in Block Storage to which the tenant who submits the request has 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_key (Optional) query xsd:string

Sorts by the requested image attribute. Accepted values are name, status, container_format, disk_format, size, id, created_at, and updated_at. Default is created_at. The API uses the natural sorting direction of the image attribute that is provided as the sort_key.

sort_dir (Optional) query xsd:string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc.

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.

Response parameters
Parameter Style Type Description
backups plain xsd:string

A backups object.

id plain csapi:uuid

The ID of the backup.

links plain xsd:dict

Links for the backup.

name plain xsd:string

The backup name.

{
    "backups": [
        {
            "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
            "links": [
                {
                    "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "bookmark"
                }
            ],
            "name": "backup001"
        },
        {
            "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
            "links": [
                {
                    "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "bookmark"
                }
            ],
            "name": "backup002"
        }
    ]
}
GET
/v2/​{tenant_id}​/backups/detail
List backups (detailed)

Lists detailed information for backups defined in Block Storage to which the tenant who submits the request has 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_key (Optional) query xsd:string

Sorts by the requested image attribute. Accepted values are name, status, container_format, disk_format, size, id, created_at, and updated_at. Default is created_at. The API uses the natural sorting direction of the image attribute that is provided as the sort_key.

sort_dir (Optional) query xsd:string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc.

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.

Response parameters
Parameter Style Type Description
backups plain xsd:string

A backups object.

availability_zone plain xsd:string

The availability zone.

container plain xsd:string

The container name or null.

created_at plain xsd:timestamp

The date and time when the backup was created.

description plain xsd:string

The backup description or null.

fail_reason plain xsd:string

If the backup failed, the reason for the failure. Otherwise, null.

id plain csapi:uuid

The ID of the backup.

links plain xsd:dict

Links for the backup.

name plain xsd:string

The backup name.

object_count plain xsd:int

The number of objects in the backup.

size plain xsd:int

The size of the backup, in GB.

status plain xsd:string

The backup status, such as available.

volume_id plain csapi:uuid

The ID of the volume from which the backup was created.

is_incremental plain xsd:boolean

Indicates whether the backup mode is incremental. If this value is True, the backup mode is incremental. If this value is False, the backup mode is full.

has_dependent_backups plain xsd:boolean

Indicates whether the backup depends on other backups. If this value is True, the backup depends on other backups.

{
    "backups": [
        {
            "availability_zone": "az1",
            "container": "volumebackups",
            "created_at": "2013-04-02T10:35:27.000000",
            "description": null,
            "fail_reason": null,
            "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
            "links": [
                {
                    "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "bookmark"
                }
            ],
            "name": "backup001",
            "object_count": 22,
            "size": 1,
            "status": "available",
            "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
            "is_incremental": "True",
            "has_dependent_backups": "False"
        },
        {
            "availability_zone": "az1",
            "container": "volumebackups",
            "created_at": "2013-04-02T10:21:48.000000",
            "description": null,
            "fail_reason": null,
            "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
            "links": [
                {
                    "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "bookmark"
                }
            ],
            "name": "backup002",
            "object_count": 22,
            "size": 1,
            "status": "available",
            "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
            "is_incremental": "True",
            "has_dependent_backups": "False"
        }
    ]
}
GET
/v2/​{tenant_id}​/backups/​{backup_id}​
Show backup details

Shows details for a specified backup.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

backup_id URI csapi:UUID

The unique identifier for a backup.

Response parameters
Parameter Style Type Description
backup plain xsd:string

A backup object.

availability_zone plain xsd:string

The availability zone.

container plain xsd:string

The container name or null.

created_at plain xsd:timestamp

The date and time when the backup was created.

description plain xsd:string

The backup description or null.

fail_reason plain xsd:string

If the backup failed, the reason for the failure. Otherwise, null.

id plain csapi:uuid

The ID of the backup.

links plain xsd:dict

Links for the backup.

name plain xsd:string

The backup name.

object_count plain xsd:int

The number of objects in the backup.

size plain xsd:int

The size of the backup, in GB.

status plain xsd:string

The backup status, such as available.

volume_id plain csapi:uuid

The ID of the volume from which the backup was created.

is_incremental plain xsd:boolean

Indicates whether the backup mode is incremental. If this value is True, the backup mode is incremental. If this value is False, the backup mode is full.

has_dependent_backups plain xsd:boolean

Indicates whether the backup depends on other backups. If this value is True, the backup depends on other backups.

{
    "backup": {
        "availability_zone": "az1",
        "container": "volumebackups",
        "created_at": "2013-04-02T10:35:27.000000",
        "description": null,
        "fail_reason": null,
        "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
        "links": [
            {
                "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                "rel": "bookmark"
            }
        ],
        "name": "backup001",
        "object_count": 22,
        "size": 1,
        "status": "available",
        "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
        "is_incremental": "True",
        "has_dependent_backups": "False"
    }
}

This operation does not accept a request body.

DELETE
/v2/​{tenant_id}​/backups/​{backup_id}​
Delete backup

Deletes a specified backup.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

backup_id URI csapi:UUID

The unique identifier for a backup.

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

POST
/v2/​{tenant_id}​/backups/​{backup_id}​/restore
Restore backup

Restores a Block Storage backup to an existing or new Block Storage volume.

 

You must specify either the volume ID or name. If you specify both the volume ID and name, the ID takes priority.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

backup_id URI csapi:UUID

The unique identifier for a backup.

restore plain xsd:string

The restore action.

volume_id (Optional) plain csapi:UUID

The ID of the volume to which you want to restore a backup.

name (Optional) plain xsd:string

The name of the volume to which you want to restore a backup.

Response parameters
Parameter Style Type Description
restore plain xsd:string

The restore action.

backup_id plain csapi:UUID

The ID of the backup.

volume_id plain csapi:UUID

The ID of the volume to which the backup was restored.

{
    "restore": {
        "name": "vol-01",
        "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607"
    }
}
{
    "restore": {
        "backup_id": "2ef47aee-8844-490c-804d-2a8efe561c65",
        "volume_id": "795114e8-7489-40be-a978-83797f2c1dd3"
    }
}

Backup actions

Force-deletes a backup.

POST
/v2/​{tenant_id}​/backups/​{backup_id}​/action
Force-delete backup

Force-deletes a specified backup. Specify the os-force_delete action in the request body.

 

The backup and any backup data is deleted.

The backup driver returns the 405 status code if it does not support this operation.

Normal response codes
202
Error response codes
404, 405
Request parameters
Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

backup_id URI csapi:UUID

The unique identifier for a backup.

os-force_delete plain xsd:string

The os-force_delete action.

{
    "os-force_delete": {}
}

This operation does not return a response body.

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 by using existing storage rather than allocating new storage.

 

The caller must specify a reference to an existing storage volume in the ref parameter in the request. Although each storage driver might interpret this reference differently, the driver should accept a reference structure that contains either a source-volume-id or source-volume-name element, if possible.

The API chooses the size of the volume by rounding up the size of the existing storage volume to the next gibibyte (GiB).

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 OpenStack Block Storage host where the existing volume resides.

ref plain xsd:string

A reference to the existing volume. The internal structure of this reference depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver.

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 image metadata extension (os-vol-image-meta)

Shows image metadata that is associated with a specified volume.

GET
/v2/​{tenant_id}​/os-vol-image-meta
Show image metadata for volume

Shows image metadata that is associated with a specified volume.

 

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 OpenStack Block Storage host where 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 accessible by users with the administrative role and context.

POST
/v2/​{tenant_id}​/volumes
Create private volume

Creates a 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 gibibytes (GiB).

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. Default is true.

Response parameters
Parameter Style Type Description
status plain xsd:string

The volume status.

name plain xsd:string

The volume name.

attachments plain xsd:dict

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

The ID of the source volume snapshot.

source_volid plain csapi:uuid

The ID of the source 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 gibibytes (GiB).

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>