Block Storage API v2 (CURRENT)

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

API versions

GET
/

List API versions

Lists information about all Block Storage API versions.

 

Normal response codes

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

This operation does not accept a request body.

GET
/v2

Show API version details

Shows details for Block Storage API v2.

 

Normal response codes

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

This operation does not accept a request body.

API extensions

GET
/v2/​{tenant_id}​/extensions

List API extensions

Lists Block Storage API extensions.

 

Normal response codes

200, 300

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

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

This operation does not accept a request body.

Volumes

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

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

Volume statuses

Status Description

creating

The volume is being created.

available

The volume is ready to be attached to an instance.

attaching

The volume is attaching to an instance.

in-use

The volume is attached to an instance.

deleting

The volume is being deleted.

error

An error occurred during volume creation.

error_deleting

An error occurred during volume deletion.

backing-up

The volume is being backed up.

restoring-backup

A backup is being restored to the volume.

error_restoring

An error occurred during backup restoration to a volume.

error_extending

An error occurred while attempting to extend a volume.

POST
/v2/​{tenant_id}​/volumes

Create volume

Creates a volume.

 

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

Preconditions

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

Asynchronous Postconditions

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

Troubleshooting

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

Normal response codes

202

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

availability_zone (Optional) plain xsd:string

The availability zone.

source_volid (Optional) plain csapi:uuid

To create a volume from an existing volume, specify the ID of the existing volume. The volume is created with the same size as the source volume.

description (Optional) plain xsd:string

The volume description.

snapshot_id (Optional) plain csapi:uuid

To create a volume from an existing snapshot, specify the ID of the existing volume snapshot. The volume is created in same availability zone and with same size as the snapshot.

size plain xsd:int

The size of the volume, in GBs.

name (Optional) plain xsd:string

The volume name.

imageRef (Optional) plain csapi:uuid

The ID of the image from which you want to create the volume. Required to create a bootable volume.

volume_type (Optional) plain xsd:string

The associated volume type.

metadata (Optional) plain xsd:string

One or more metadata key and value pairs to associate with the volume.

Response parameters

Parameter Style Type Description
status plain xsd:string

The volume status.

name plain xsd:string

The volume name.

attachments plain xsd:string

One or more instance attachments.

availability_zone plain xsd:string

The availability zone.

created_at plain xsd:datetime

Date and time when the volume was created.

description plain xsd:string

The volume description.

volume_type plain xsd:string

The associated volume type.

snapshot_id plain csapi:uuid

To create a volume from an existing volume snapshot, specify the ID of the existing volume snapshot.

source_volid plain csapi:uuid

To create a volume from an existing volume, specify the ID of the existing volume.

metadata plain xsd:string

One or more metadata key and value pairs to associate with the volume.

id plain csapi:uuid

The volume ID.

size plain xsd:int

The size of the volume, in GBs.

{
    "volume": {
        "availability_zone": null,
        "source_volid": null,
        "description": null,
        "snapshot_id": null,
        "size": 10,
        "name": "my_volume",
        "imageRef": null,
        "volume_type": null,
        "metadata": {}
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    name="vol-001" description="Another volume."
    size="2"/>
{
    "volume": {
        "status": "creating",
        "name": "my_volume",
        "attachments": [],
        "availability_zone": "nova",
        "bootable": "false",
        "created_at": "2014-02-21T19:52:04.949734",
        "description": null,
        "volume_type": "None",
        "snapshot_id": null,
        "source_volid": null,
        "metadata": {},
        "id": "93c2e2aa-7744-4fd6-a31a-80c4726b08d7",
        "size": 10
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<volume xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/volume/api/v1" status="creating"
    name="vol-001" availability_zone="nova" bootable="false"
    created_at="2014-02-21 20:18:33.122452"
    description="Another volume." volume_type="None"
    snapshot_id="None" source_volid="None"
    id="83960a54-8dad-4fd8-bc41-33c71e098e04" size="2">
    <attachments/>
    <metadata/>
</volume>
GET
/v2/​{tenant_id}​/volumes

List volumes

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

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

sort (Optional) query xsd:string

Comma-separated list of sort keys and optional sort directions in the form of <key>[:<direction>]. A valid direction is asc (ascending) or desc (descending).

limit (Optional) query xsd:int

Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional) query xsd:string

Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

{
"volumes": [
{
"id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
"links": [
    {
        "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
        "rel": "self"
    },
    {
        "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
        "rel": "bookmark"
    }
],
"name": "vol-004"
},
{
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"links": [
    {
        "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
        "rel": "self"
    },
    {
        "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
        "rel": "bookmark"
    }
],
"name": "vol-003"
}
]
}
<?xml version='1.0' encoding='UTF-8'?>
<volumes xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content">
<volume name="vol-004" id="45baf976-c20a-4894-a7c3-c94b7376bf55">
<attachments/>
<metadata/>
</volume>
<volume name="vol-003" id="5aa119a8-d25b-45a7-8d1b-88e127885635">
<attachments/>
<metadata/>
</volume>
</volumes>
GET
/v2/​{tenant_id}​/volumes/detail

List volumes (detailed)

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

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

sort (Optional) query xsd:string

Comma-separated list of sort keys and optional sort directions in the form of <key>[:<direction>]. A valid direction is asc (ascending) or desc (descending).

limit (Optional) query xsd:int

Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional) query xsd:string

Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

{
"volumes": [
{
"status": "available",
"attachments": [],
"links": [
    {
        "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
        "rel": "self"
    },
    {
        "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
        "rel": "bookmark"
    }
],
"availability_zone": "nova",
"os-vol-host-attr:host": "ip-10-168-107-25",
"source_volid": null,
"snapshot_id": null,
"id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
"description": "Another volume.",
"name": "vol-004",
"created_at": "2013-02-25T06:36:28.000000",
"volume_type": "None",
"os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"metadata": {
    "contents": "junk"
}
},
{
"status": "available",
"attachments": [],
"links": [
    {
        "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
        "rel": "self"
    },
    {
        "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
        "rel": "bookmark"
    }
],
"availability_zone": "nova",
"os-vol-host-attr:host": "ip-10-168-107-25",
"source_volid": null,
"snapshot_id": null,
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"description": "This is yet, another volume.",
"name": "vol-003",
"created_at": "2013-02-25T02:40:21.000000",
"volume_type": "None",
"os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"metadata": {
    "contents": "not junk"
}
}
]
}
<?xml version='1.0' encoding='UTF-8'?>
<volumes
xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Image_Metadata.html"
xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Tenant_Attribute.html"
xmlns:os-vol-host-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Host_Attribute.html"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content">
<volume status="available" name="vol-004" availability_zone="nova"
created_at="2013-02-25 06:36:28" description="Another volume."
volume_type="None" source_volid="None" snapshot_id="None"
id="45baf976-c20a-4894-a7c3-c94b7376bf55" size="1"
os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-vol-host-attr:host="ip-10-168-107-25">
<attachments/>
<metadata>
<meta key="contents">junk</meta>
</metadata>
</volume>
<volume status="available" name="vol-003" availability_zone="nova"
created_at="2013-02-25 02:40:21"
description="This is yet, another volume." volume_type="None"
source_volid="None" snapshot_id="None"
id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-vol-host-attr:host="ip-10-168-107-25">
<attachments/>
<metadata>
<meta key="contents">not junk</meta>
</metadata>
</volume>
</volumes>
GET
/v2/​{tenant_id}​/volumes/​{volume_id}​

Show volume information

Shows information about a specified volume.

 

Preconditions

  • The specified volume must exist.

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

volume_id URI csapi:UUID

The unique identifier of an existing volume.

{
"volume": {
"status": "available",
"attachments": [],
"links": [
{
    "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
    "rel": "self"
},
{
    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
    "rel": "bookmark"
}
],
"availability_zone": "nova",
"bootable": "false",
"os-vol-host-attr:host": "ip-10-168-107-25",
"source_volid": null,
"snapshot_id": null,
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"description": "Super volume.",
"name": "vol-002",
"created_at": "2013-02-25T02:40:21.000000",
"volume_type": "None",
"os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"metadata": {
"contents": "not junk"
}
}
}
<?xml version='1.0' encoding='UTF-8'?>
<volume
xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Image_Metadata.html"
xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Tenant_Attribute.html"
xmlns:os-vol-host-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Host_Attribute.html"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
status="available" name="vol-003" availability_zone="nova"
bootable="false" created_at="2013-02-25 02:40:21"
description="This is yet, another volume." volume_type="None"
source_volid="None" snapshot_id="None"
id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-vol-host-attr:host="ip-10-168-107-25">
<attachments/>
<metadata>
<meta key="contents">not junk</meta>
</metadata>
</volume>

This operation does not accept a request body.

PUT
/v2/​{tenant_id}​/volumes/​{volume_id}​

Update volume

Updates a volume.

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

volume_id URI csapi:UUID

The unique identifier of an existing volume.

{
"volume": {
"name": "vol-003",
"description": "This is yet, another volume."
}
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshot
xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
name="vol-003" description="This is yet, another volume."/>
{
"volume": {
"status": "available",
"attachments": [],
"links": [
{
    "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
    "rel": "self"
},
{
    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
    "rel": "bookmark"
}
],
"availability_zone": "nova",
"source_volid": null,
"snapshot_id": null,
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"description": "This is yet, another volume.",
"name": "vol-003",
"created_at": "2013-02-25T02:40:21.000000",
"volume_type": "None",
"size": 1,
"metadata": {
"contents": "not junk"
}
}
}
<?xml version='1.0' encoding='UTF-8'?>
<volume xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
status="available" name="vol-003" availability_zone="nova"
created_at="2013-02-25 02:40:21"
description="This is yet, another volume." volume_type="None"
source_volid="None" snapshot_id="None"
id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1">
<attachments/>
<metadata>
<meta key="contents">not junk</meta>
</metadata>
</volume>
DELETE
/v2/​{tenant_id}​/volumes/​{volume_id}​

Delete volume

Deletes a specified volume.

 

Preconditions

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

Asynchronous Postconditions

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

Troubleshooting

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

Normal response codes

202

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

volume_id URI csapi:UUID

The unique identifier of an existing volume.

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

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

Extend volume

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

 

Preconditions

  • Volume status must be available.
  • Sufficient amount of storage must exist to extend the volume.
  • The user quota must have sufficient volume storage.

Troubleshooting

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

Normal response codes

202

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

volume_id URI csapi:UUID

The unique identifier of an existing volume.

new_size plain xsd:int

The new size (in GB) of the volume.

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

This operation does not return a response body.

Volume types

GET
/v2/​{tenant_id}​/types

List volume types

Lists volume types.

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

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

This operation does not accept a request body.

POST
/v2/​{tenant_id}​/types

Create volume type

Creates a volume type.

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

{
"volume_type": {
"name": "vol-type-001",
"extra_specs": {
"capabilities": "gpu"
}
}
}
<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
name="vol-type-001">
<extra_specs>
<extra_spec key="capabilities">gpu</extra_spec>
</extra_specs>
</volume_type>
{
"volume_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "vol-type-001",
"extra_specs": {
"capabilities": "gpu"
}
}
}
<?xml version="1.0" encoding="UTF-8"?>
<volume_type
xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="vol-type-001">
<extra_specs>
<extra_spec key="capabilities">gpu</extra_spec>
</extra_specs>
</volume_type>
GET
/v2/​{tenant_id}​/types/​{volume_type_id}​

Show volume type information

Shows information about a specified volume type.

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

volume_type_id URI csapi:UUID

The unique identifier for an existing volume type.

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

This operation does not accept a request body.

DELETE
/v2/​{tenant_id}​/types/​{volume_type_id}​

Delete volume type

Deletes a specified volume type.

 

Normal response codes

202

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

volume_type_id URI csapi:UUID

The unique identifier for an existing volume type.

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

Snapshots

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

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

Snapshot statuses

Status Description

creating

The snapshot is being created.

available

The snapshot is ready to be used.

deleting

The snapshot is being deleted.

error

An error occurred during snapshot creation.

error_deleting

An error occurred during snapshot deletion.

POST
/v2/​{tenant_id}​/snapshots

Create snapshot

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

 

Normal response codes

202

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

snapshot query string

A partial representation of a snapshot used in the creation process.

volume_id query string

To create a snapshot from an existing volume, specify the ID of the existing volume.

force (Optional) query xsd:boolean

[True/False] Indicate whether to snapshot, even if the volume is attached. Default==False.

name (Optional) query string

Name of the snapshot. Default==None.

description (Optional) query string

Description of snapshot. Default==None.

Response parameters

Parameter Style Type Description
size plain xsd:int

The size of the volume, in GBs.

{
    "snapshot": {
        "name": "snap-001",
        "description": "Daily backup",
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "force": true
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshot
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    name="snap-001" description="Daily backup"
    volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" force="true"/>
{
    "snapshot": {
        "status": "creating",
        "description": "Daily backup",
        "created_at": "2013-02-25T03:56:53.081642",
        "metadata": {},
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "size": 1,
        "id": "ffa9bc5e-1172-4021-acaf-cdcd78a9584d",
        "name": "snap-001"
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<snapshot status="creating" description="Daily backup"
    created_at="2013-02-25T03:56:53.081642"
    volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
    id="ffa9bc5e-1172-4021-acaf-cdcd78a9584d" name="snap-001">
    <metadata/>
</snapshot>
GET
/v2/​{tenant_id}​/snapshots

List snapshots

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

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

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

This operation does not accept a request body.

GET
/v2/​{tenant_id}​/snapshots/detail

List snapshots (detailed)

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

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

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

This operation does not accept a request body.

GET
/v2/​{tenant_id}​/snapshots/​{snapshot_id}​

Show snapshot information

Shows information for a specified snapshot.

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

snapshot_id URI csapi:UUID

The unique identifier of an existing snapshot.

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

This operation does not accept a request body.

PUT
/v2/​{tenant_id}​/snapshots/​{snapshot_id}​

Update snapshot

Updates a specified snapshot.

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

snapshot_id URI csapi:UUID

The unique identifier of an existing snapshot.

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

Delete snapshot

Deletes a specified snapshot.

 

Normal response codes

202

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

snapshot_id URI csapi:UUID

The unique identifier of an existing snapshot.

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

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

Show snapshot metadata

Shows the metadata for a specified snapshot.

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

snapshot_id URI csapi:UUID

The unique identifier of an existing snapshot.

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

This operation does not accept a request body.

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

Update snapshot metadata

Updates the metadata for a specified snapshot.

 

Normal response codes

200

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

snapshot_id URI csapi:UUID

The unique identifier of an existing snapshot.

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

Limits extension (limits)

Shows absolute limits for a tenant.

GET
v2/​{tenant_id}​/limits

Show absolute limits

Shows absolute limits for a tenant.

 

Normal response codes

200, 203

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

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

Response parameters

Parameter Style Type Description
limits plain xsd:string

A limits object.

absolute plain xsd:string

An absolute limits object.

totalSnapshotsUsed plain xsd:int

Total number of snapshots used.

maxTotalVolumeGigabytes plain xsd:int

Maximum total amount of volumes (GB).

totalGigabytesUsed plain xsd:int

Total number of GBs used.

maxTotalSnapshots plain xsd:int

Maximum number of snapshots.

totalVolumesUsed plain xsd:int

Total number of volumes used.

maxTotalVolumes plain xsd:int

Maximum number of volumes.

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

This operation does not accept a request body.

Backups

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

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

Backup statuses

Status Description

creating

The backup is being created.

available

The backup is ready to be restored to a volume.

deleting

The backup is being deleted.

error

An error has occurred with the backup.

restoring

The backup is being restored to a volume.

error_restoring

An error occurred during backup restoration to a volume.

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

Volume manage extension (os-volume-manage)

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

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

Manage existing volume

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

 

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

Normal response codes

202

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

volume plain xsd:string

A volume object.

host plain xsd:string

The cinder host on which the existing volume resides.

ref plain xsd:string

A reference to the existing volume. The internal structure of this reference is dependent on the implementation of the volume driver, see the specific driver's documentation for details of the required elements in the structure.

name (Optional) plain xsd:string

The volume name.

availability_zone (Optional) plain xsd:string

The availability zone.

description (Optional) plain xsd:string

The volume description.

volume_type (Optional) plain xsd:string

The associated volume type.

bootable (Optional) plain xsd:boolean

Enables or disables the bootable attribute. You can boot an instance from a bootable volume.

metadata (Optional) plain xsd:string

One or more metadata key and value pairs to associate with the volume.

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

Volume type access (volumes)

Creates private volumes.

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

POST
/v2/​{tenant_id}​/volumes

Create volume

Creates and get details for private Block Storage volume.

 

Normal response codes

202

Request parameters

Parameter Style Type Description
tenant_id URI xsd:string

The unique identifier of the tenant or account.

availability_zone (Optional) plain xsd:string

The availability zone.

source_volid (Optional) plain csapi:uuid

To create a volume from an existing volume, specify the ID of the existing volume. The volume is created with the same size as the source volume.

description (Optional) plain xsd:string

The volume description.

snapshot_id (Optional) plain csapi:uuid

To create a volume from an existing snapshot, specify the ID of the existing volume snapshot. The volume is created in same availability zone and with same size as the snapshot.

size plain xsd:int

The size of the volume, in GBs.

name (Optional) plain xsd:string

The volume name.

imageRef (Optional) plain csapi:uuid

The ID of the image from which you want to create the volume. Required to create a bootable volume.

volume_type (Optional) plain xsd:string

The associated volume type.

metadata (Optional) plain xsd:string

One or more metadata key and value pairs to associate with the volume.

os-volume-type-access:is_public (Optional) plain xsd:boolean

The volume type access.

Set to true if access is public. Set to false if access is private.

Response parameters

Parameter Style Type Description
status plain xsd:string

The volume status.

name plain xsd:string

The volume name.

attachments plain xsd:string

One or more instance attachments.

availability_zone plain xsd:string

The availability zone.

created_at plain xsd:datetime

Date and time when the volume was created.

description plain xsd:string

The volume description.

volume_type plain xsd:string

The associated volume type.

snapshot_id plain csapi:uuid

To create a volume from an existing volume snapshot, specify the ID of the existing volume snapshot.

source_volid plain csapi:uuid

To create a volume from an existing volume, specify the ID of the existing volume.

metadata plain xsd:string

One or more metadata key and value pairs to associate with the volume.

id plain csapi:uuid

The volume ID.

size plain xsd:int

The size of the volume, in GBs.

os-volume-type-access:is_public plain xsd:boolean

The volume type access.

Set to true if access is public. Set to false if access is private.

{
    "volume": {
        "availability_zone": null,
        "source_volid": null,
        "description": null,
        "snapshot_id": null,
        "size": 10,
        "name": "my_volume",
        "imageRef": null,
        "volume_type": null,
        "metadata": {},
        "os-volume-type-access: is_public": false
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" name="vol-001" description="Another volume." size="2" os-volume-type-access:is_public="false" />
{
    "volume": {
        "status": "creating",
        "name": "my_volume",
        "attachments": [],
        "availability_zone": "nova",
        "bootable": "false",
        "created_at": "2014-02-21T19: 52: 04.949734",
        "description": null,
        "volume_type": "None",
        "snapshot_id": null,
        "source_volid": null,
        "metadata": {},
        "id": "93c2e2aa-7744-4fd6-a31a-80c4726b08d7",
        "size": 10,
        "os-volume-type-access: is_public": false
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" status="creating" name="vol-001" availability_zone="nova" bootable="false" created_at="2014-02-21 20:18:33.122452" description="Another volume." volume_type="None" snapshot_id="None" source_volid="None" id="83960a54-8dad-4fd8-bc41-33c71e098e04" size="2" os-volume-type-access:is_public="false">
    <attachments />
    <metadata />
</volume>
  • AURO
  • Latest News

Canadian Cloud Leader AURO Announces $100 in Cloud Credits for All New Customers in Honour of OpenStack Summit

With Tier 1 high performance, this addition to AURO's cloud computing product suite will guarantee IOPS and give customers faster storage for their database and applications.

  • Download
  • Free Whitepapers

Get the guides, facts, reports, and diagrams you need.

Download Now

See more resources

  • Get in Touch
  • 1.855.226.4678

Call Free anytime:

MORE CONTACT OPTIONS