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 for all Block Storage API versions.

 
Normal response codes
200 300
{
    "versions": [
        {
            "status": "DEPRECATED",
            "updated": "2014-06-28T12:20:21Z",
            "links": [
                {
                    "href": "http://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://10.0.2.15:8776/v1/",
                    "rel": "self"
                }
            ],
            "min_version": "",
            "version": "",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.volume+json;version=1"
                }
            ],
            "id": "v1.0"
        },
        {
            "status": "SUPPORTED",
            "updated": "2014-06-28T12:20:21Z",
            "links": [
                {
                    "href": "http://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://10.0.2.15:8776/v2/",
                    "rel": "self"
                }
            ],
            "min_version": "",
            "version": "",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.volume+json;version=1"
                }
            ],
            "id": "v2.0"
        },
        {
            "status": "CURRENT",
            "updated": "2016-02-08T12:20:21Z",
            "links": [
                {
                    "href": "http://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://10.0.2.15:8776/v3/",
                    "rel": "self"
                }
            ],
            "min_version": "3.0",
            "version": "{Current_Max_Version}",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.volume+json;version=1"
                }
            ],
            "id": "v3.0"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<choices xmlns="http://docs.openstack.org/common/api/v1.0" xmlns:atom="http://www.w3.org/2005/Atom">
    <version status="DEPRECATED" id="v1.0">
        <media-types>
            <media-type base="application/xml" type="application/vnd.openstack.volume+xml;version=1" />
            <media-type base="application/json" type="application/vnd.openstack.volume+json;version=1" />
        </media-types>
        <atom:link href="http://23.253.248.171:8776/v1/.xml" rel="self" />
    </version>
    <version status="SUPPORTED" id="v2.0">
        <media-types>
            <media-type base="application/xml" type="application/vnd.openstack.volume+xml;version=1" />
            <media-type base="application/json" type="application/vnd.openstack.volume+json;version=1" />
        </media-types>
        <atom:link href="http://23.253.248.171:8776/v2/.xml" rel="self" />
    </version>
    <version status="CURRENT" id="v3.0">
        <media-types>
            <media-type base="application/xml" type="application/vnd.openstack.volume+xml;version=1" />
            <media-type base="application/json" type="application/vnd.openstack.volume+json;version=1" />
        </media-types>
        <atom:link href="http://23.253.248.171:8776/v3/.xml" rel="self" />
    </version>
</choices>

This operation does not accept a request body.

GET
/v2
Show API v2 details

Shows details for Block Storage API v2.

 
Normal response codes
200 203
Response parameters
Parameter Style Type Description
location plain xsd:anyURI

Full URL to a service or server.

{
    "choices": [
        {
            "status": "SUPPORTED",
            "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.248.171:8776/v1/v2.json",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "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": "v2.0",
            "links": [
                {
                    "href": "http://23.253.248.171:8776/v2/v2.json",
                    "rel": "self"
                }
            ]
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<choices xmlns="http://docs.openstack.org/common/api/v1.0" xmlns:atom="http://www.w3.org/2005/Atom">
    <version status="SUPPORTED" id="v1.0">
        <media-types>
            <media-type base="application/xml" type="application/vnd.openstack.volume+xml;version=1" />
            <media-type base="application/json" type="application/vnd.openstack.volume+json;version=1" />
        </media-types>
        <atom:link href="http://23.253.248.171:8776/v1/v2.xml" rel="self" />
    </version>
    <version status="CURRENT" id="v2.0">
        <media-types>
            <media-type base="application/xml" type="application/vnd.openstack.volume+xml;version=1" />
            <media-type base="application/json" type="application/vnd.openstack.volume+json;version=1" />
        </media-types>
        <atom:link href="http://23.253.248.171:8776/v2/v2.xml" rel="self" />
    </version>
</choices>

This operation does not accept a request body.

API extensions (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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the extension. For example, "Fox In Socks."

description plain xsd:string

The extension description.

namespace plain xsd:string

Link associated to the extension.

alias plain xsd:string

The alias for the extension. For example, "FOXNSOX", "os-availability-zone", "os-extended-quotas", "os-share-unmanage" or "os-used-limits."

links plain xsd:list

List of links related to the extension.

updated plain xsd:dateTime

The date and time stamp when the extension was last updated.

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

Limits (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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

Response parameters
Parameter Style Type Description
limits plain xsd:dict

A list of limit objects.

absolute plain xsd:dict

An absolute limits object.

rate plain xsd:list

Rate-limit volume copy bandwidth, used to mitigate slow down of data access from the instances.

totalSnapshotsUsed plain xsd:int

The total number of snapshots used.

maxTotalBackups plain xsd:int

The maximum number of backups.

maxTotalVolumeGigabytes plain xsd:int

The maximum total amount of volumes, in gibibytes (GiB).

maxTotalSnapshots plain xsd:int

The maximum number of snapshots.

maxTotalBackupGigabytes plain xsd:int

The maximum total amount of backups, in gibibytes (GiB).

totalBackupGigabytesUsed plain xsd:int

The total number of backups gibibytes (GiB) used.

maxTotalVolumes plain xsd:int

The maximum number of volumes.

totalVolumesUsed plain xsd:int

The total number of volumes used.

totalBackupsUsed plain xsd:int

The total number of backups used.

totalGigabytesUsed plain xsd:int

The total number of gibibytes (GiB) used.

{
    "limits": {
        "rate": [],
        "absolute": {
            "totalSnapshotsUsed": 0,
            "maxTotalBackups": 10,
            "maxTotalVolumeGigabytes": 1000,
            "maxTotalSnapshots": 10,
            "maxTotalBackupGigabytes": 1000,
            "totalBackupGigabytesUsed": 0,
            "maxTotalVolumes": 10,
            "totalVolumesUsed": 0,
            "totalBackupsUsed": 0,
            "totalGigabytesUsed": 0
        }
    }
}
<?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="maxTotalBackups" value="10"/>
        <limit name="maxTotalVolumeGigabytes" value="1000"/>
        <limit name="maxTotalSnapshots" value="10"/>
        <limit name="maxTotalBackupGigabytes" value="1000"/>
        <limit name="totalBackupGigabytesUsed" value="0"/>
        <limit name="maxTotalVolumes" value="10"/>
        <limit name="totalVolumesUsed" value="0"/>
        <limit name="totalBackupsUsed" value="0"/>
        <limit name="totalGigabytesUsed" value="0"/>
    </absolute>
</limits>

This operation does not accept a request body.

Volumes (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 attach 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

A volume creation error occurred.

error_deleting

A volume deletion error occurred.

backing-up

The volume is being backed up.

restoring-backup

A backup is being restored to the volume.

error_restoring

A backup restoration error occurred.

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 UUID 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 that OpenStack Block Storage manages.

  • The storage node needs enough free storage space to match the size of the volume creation request.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume plain xsd:dict

A volume object.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

availability_zone (Optional) plain xsd:string

The availability zone.

source_volid (Optional) plain csapi:UUID

The UUID of the source volume. The API creates a new volume with the same size as the source volume.

description (Optional) plain xsd:string

The volume description.

multiattach (Optional) plain xsd:boolean

To enable this volume to attach to more than one server, set this value to true. Default is false.

snapshot_id (Optional) plain csapi:UUID

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

name (Optional) plain xsd:string

The volume name.

imageRef (Optional) plain csapi:UUID

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

volume_type (Optional) plain xsd:string

The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder-volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type.

Default is None.

For information about how to use volume types to create multiple-storage back ends, see Configure multiple-storage back ends.

metadata (Optional) plain xsd:dict

One or more metadata key and value pairs that are associated with the volume.

source_replica (Optional) plain csapi:UUID

The UUID of the primary volume to clone.

consistencygroup_id (Optional) plain csapi:UUID

The UUID of the consistency group.

scheduler_hints (Optional) plain xsd:dict

The dictionary of data to send to the scheduler.

Response parameters
Parameter Style Type Description
volume plain xsd:dict

A volume object.

status plain xsd:string

The volume status.

migration_status plain xsd:string

The volume migration status.

user_id plain csapi:UUID

The UUID of the user.

attachments plain xsd:list

Instance attachment information.

If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID.

Otherwise, this list is empty.

links plain xsd:list

The volume links.

availability_zone plain xsd:string

The availability zone.

bootable plain xsd:boolean

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

encrypted plain xsd:boolean

If true, this volume is encrypted.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

description plain xsd:string

The volume description.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

volume_type plain xsd:string

The volume type. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type.

For information about how to use volume types to create multiple-storage back ends, see Configure multiple-storage back ends.

name plain xsd:string

The volume name.

replication_status plain xsd:string

The volume replication status.

consistencygroup_id plain csapi:UUID

The UUID of the consistency group.

source_volid plain csapi:UUID

The UUID of the source volume.

snapshot_id plain csapi:UUID

The UUID of the source volume snapshot. The API creates a new volume snapshot with the same size as the source volume snapshot.

multiattach plain xsd:boolean

If true, this volume can attach to more than one instance.

metadata plain xsd:dict

One or more metadata key and value pairs that are associated with the volume.

id plain csapi:UUID

The UUID of the volume.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

{
    "volume": {
        "size": 10,
        "availability_zone": null,
        "source_volid": null,
        "description": null,
        "multiattach ": false,
        "snapshot_id": null,
        "name": null,
        "imageRef": null,
        "volume_type": null,
        "metadata": {},
        "source_replica": null,
        "consistencygroup_id": null
    }
}
<?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",
        "migration_status": null,
        "user_id": "0eea4eabcf184061a3b6db1e0daaf010",
        "attachments": [],
        "links": [
            {
                "href": "http://23.253.248.171:8776/v2/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                "rel": "self"
            },
            {
                "href": "http://23.253.248.171:8776/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "encrypted": false,
        "created_at": "2015-11-29T03:01:44.000000",
        "description": null,
        "updated_at": null,
        "volume_type": "lvmdriver-1",
        "name": "test-volume-attachments",
        "replication_status": "disabled",
        "consistencygroup_id": null,
        "source_volid": null,
        "snapshot_id": null,
        "multiattach": false,
        "metadata": {},
        "id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
        "size": 2
    }
}
<?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 can access.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

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 page size of items. Returns a number of items up to a 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

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
volumes plain xsd:list

A list of volume objects.

name plain xsd:string

The volume name.

id plain csapi:UUID

The UUID of the volume.

links plain xsd:list

The volume links.

{
    "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 with details

Lists all Block Storage volumes, with details, that the tenant can access.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

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 page size of items. Returns a number of items up to a 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

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
volumes plain xsd:list

A list of volume objects.

migration_status plain xsd:string

The volume migration status.

attachments plain xsd:list

Instance attachment information.

If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID.

Otherwise, this list is empty.

links plain xsd:list

The volume links.

availability_zone plain xsd:string

The availability zone.

os-vol-host-attr:host plain xsd:string

Current back-end of the volume.

encrypted plain xsd:boolean

If true, this volume is encrypted.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

os-volume-replication:extended_status (Optional) plain xsd:string

The volume replication status managed by the driver of backend storage.

replication_status plain xsd:string

The volume replication status.

snapshot_id plain csapi:UUID

The UUID of the source volume snapshot.

id plain csapi:UUID

The UUID of the volume.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

user_id plain csapi:UUID

The UUID of the user.

os-vol-tenant-attr:tenant_id plain csapi:UUID

The tenant ID which the volume belongs to.

os-vol-mig-status-attr:migstat plain xsd:string

The status of this volume migration (None means that a migration is not currently in progress).

metadata plain xsd:dict

One or more metadata key and value pairs that are associated with the volume.

status plain xsd:string

The volume status.

description plain xsd:string

The volume description.

multiattach plain xsd:boolean

If true, this volume can attach to more than one instance.

os-volume-replication:driver_data (Optional) plain xsd:string

The name of the volume replication driver.

source_volid plain csapi:UUID

The UUID of the source volume.

consistencygroup_id plain csapi:UUID

The UUID of the consistency group.

os-vol-mig-status-attr:name_id plain csapi:UUID

The volume ID that this volume name on the back-end is based on.

name plain xsd:string

The volume name.

bootable plain xsd:boolean

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

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

volume_type plain xsd:string

The volume type. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type.

For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

{
    "volumes": [
        {
            "migration_status": null,
            "attachments": [
                {
                    "server_id": "f4fda93b-06e0-4743-8117-bc8bcecd651b",
                    "attachment_id": "3b4db356-253d-4fab-bfa0-e3626c0b8405",
                    "host_name": null,
                    "volume_id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                    "device": "/dev/vdb",
                    "id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38"
                }
            ],
            "links": [
                {
                    "href": "http://23.253.248.171:8776/v2/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                    "rel": "self"
                },
                {
                    "href": "http://23.253.248.171:8776/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "os-vol-host-attr:host": "difleming@lvmdriver-1#lvmdriver-1",
            "encrypted": false,
            "os-volume-replication:extended_status": null,
            "replication_status": "disabled",
            "snapshot_id": null,
            "id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
            "size": 2,
            "user_id": "32779452fcd34ae1a53a797ac8a1e064",
            "os-vol-tenant-attr:tenant_id": "bab7d5c60cd041a0a36f7c4b6e1dd978",
            "os-vol-mig-status-attr:migstat": null,
            "metadata": {
                "readonly": false,
                "attached_mode": "rw"
            },
            "status": "in-use",
            "description": null,
            "multiattach": true,
            "os-volume-replication:driver_data": null,
            "source_volid": null,
            "consistencygroup_id": null,
            "os-vol-mig-status-attr:name_id": null,
            "name": "test-volume-attachments",
            "bootable": "false",
            "created_at": "2015-11-29T03:01:44.000000",
            "volume_type": "lvmdriver-1"
        },
        {
            "migration_status": null,
            "attachments": [],
            "links": [
                {
                    "href": "http://23.253.248.171:8776/v2/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/173f7b48-c4c1-4e70-9acc-086b39073506",
                    "rel": "self"
                },
                {
                    "href": "http://23.253.248.171:8776/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/173f7b48-c4c1-4e70-9acc-086b39073506",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "os-vol-host-attr:host": "difleming@lvmdriver-1#lvmdriver-1",
            "encrypted": false,
            "os-volume-replication:extended_status": null,
            "replication_status": "disabled",
            "snapshot_id": null,
            "id": "173f7b48-c4c1-4e70-9acc-086b39073506",
            "size": 1,
            "user_id": "32779452fcd34ae1a53a797ac8a1e064",
            "os-vol-tenant-attr:tenant_id": "bab7d5c60cd041a0a36f7c4b6e1dd978",
            "os-vol-mig-status-attr:migstat": null,
            "metadata": {},
            "status": "available",
            "volume_image_metadata": {
                "kernel_id": "8a55f5f1-78f7-4477-8168-977d8519342c",
                "checksum": "eb9139e4942121f22bbc2afc0400b2a4",
                "min_ram": "0",
                "ramdisk_id": "5f6bdf8a-92db-4988-865b-60bdd808d9ef",
                "disk_format": "ami",
                "image_name": "cirros-0.3.4-x86_64-uec",
                "image_id": "b48c53e1-9a96-4a5a-a630-2e74ec54ddcc",
                "container_format": "ami",
                "min_disk": "0",
                "size": "25165824"
            },
            "description": "",
            "multiattach": false,
            "os-volume-replication:driver_data": null,
            "source_volid": null,
            "consistencygroup_id": null,
            "os-vol-mig-status-attr:name_id": null,
            "name": "test-volume",
            "bootable": "true",
            "created_at": "2015-11-29T02:25:18.000000",
            "volume_type": "lvmdriver-1"
        }
    ]
}
<?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 details

Shows details for a volume.

 

Preconditions

  • The volume must exist.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

Response parameters
Parameter Style Type Description
volume plain xsd:dict

A volume object.

migration_status plain xsd:string

The volume migration status.

attachments plain xsd:list

Instance attachment information.

If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID.

Otherwise, this list is empty.

links plain xsd:list

The volume links.

availability_zone plain xsd:string

The availability zone.

os-vol-host-attr:host plain xsd:string

Current back-end of the volume.

encrypted plain xsd:boolean

If true, this volume is encrypted.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

os-volume-replication:extended_status (Optional) plain xsd:string

The volume replication status managed by the driver of backend storage.

replication_status plain xsd:string

The volume replication status.

snapshot_id plain csapi:UUID

The UUID of the source volume snapshot.

id plain csapi:UUID

The UUID of the volume.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

user_id plain csapi:UUID

The UUID of the user.

os-vol-tenant-attr:tenant_id plain csapi:UUID

The tenant ID which the volume belongs to.

os-vol-mig-status-attr:migstat plain xsd:string

The status of this volume migration (None means that a migration is not currently in progress).

metadata plain xsd:dict

One or more metadata key and value pairs that are associated with the volume.

status plain xsd:string

The volume status.

description plain xsd:string

The volume description.

multiattach plain xsd:boolean

If true, this volume can attach to more than one instance.

os-volume-replication:driver_data (Optional) plain xsd:string

The name of the volume replication driver.

source_volid plain csapi:UUID

The UUID of the source volume.

consistencygroup_id plain csapi:UUID

The UUID of the consistency group.

os-vol-mig-status-attr:name_id plain csapi:UUID

The volume ID that this volume name on the back-end is based on.

name plain xsd:string

The volume name.

bootable plain xsd:boolean

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

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

volume_type plain xsd:string

The volume type. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type.

For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

{
    "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,
        "os-volume-replication:driver_data": null,
        "os-volume-replication:extended_status": null,
        "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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

volume plain xsd:dict

A volume object.

name (Optional) plain xsd:string

The volume name.

description (Optional) plain xsd:string

The volume description.

metadata (Optional) plain xsd:dict

One or more metadata key and value pairs that are associated with the volume.

Response parameters
Parameter Style Type Description
volume plain xsd:dict

A volume object.

status plain xsd:string

The volume status.

migration_status plain xsd:string

The volume migration status.

user_id plain csapi:UUID

The UUID of the user.

attachments plain xsd:list

Instance attachment information.

If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID.

Otherwise, this list is empty.

links plain xsd:list

The volume links.

availability_zone plain xsd:string

The availability zone.

bootable plain xsd:boolean

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

encrypted plain xsd:boolean

If true, this volume is encrypted.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

description plain xsd:string

The volume description.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

volume_type plain xsd:string

The volume type. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type.

For information about how to use volume types to create multiple-storage back ends, see Configure multiple-storage back ends.

name plain xsd:string

The volume name.

replication_status plain xsd:string

The volume replication status.

consistencygroup_id plain csapi:UUID

The UUID of the consistency group.

source_volid plain csapi:UUID

The UUID of the source volume.

snapshot_id plain csapi:UUID

The UUID of the source volume snapshot. The API creates a new volume snapshot with the same size as the source volume snapshot.

multiattach plain xsd:boolean

If true, this volume can attach to more than one instance.

metadata plain xsd:dict

One or more metadata key and value pairs that are associated with the volume.

id plain csapi:UUID

The UUID of the volume.

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",
        "migration_status": null,
        "user_id": "0eea4eabcf184061a3b6db1e0daaf010",
        "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",
        "encrypted": false,
        "created_at": "2015-11-29T03:01:44.000000",
        "description": "This is yet, another volume.",
        "updated_at": null,
        "volume_type": "lvmdriver-1",
        "name": "vol-003",
        "replication_status": "disabled",
        "consistencygroup_id": null,
        "source_volid": null,
        "snapshot_id": null,
        "multiattach": false,
        "metadata": {
            "contents": "not junk"
        },
        "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "size": 1
    }
}
<?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 volume.

 

Preconditions

  • Volume status must be available, in-use, error, or error_restoring.

  • You cannot already have a snapshot of the 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

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

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/metadata
Create volume metadata

Creates metadata for a volume.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

metadata plain xsd:dict

A metadata object. Contains one or more metadata key and value pairs that are associated with the volume.

Response parameters
Parameter Style Type Description
metadata plain xsd:dict

A metadata object. Contains one or more metadata key and value pairs that are associated with the volume.

{
    "metadata": {
        "name": "metadata0"
    }
}
{
    "metadata": {
        "name": "metadata0"
    }
}
GET
/v2/​{tenant_id}​/volumes/​{volume_id}​/metadata
Show volume metadata

Shows metadata for a volume.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

Response parameters
Parameter Style Type Description
metadata plain xsd:dict

A metadata object. Contains one or more metadata key and value pairs that are associated with the volume.

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

This operation does not accept a request body.

PUT
/v2/​{tenant_id}​/volumes/​{volume_id}​/metadata
Update volume metadata

Updates metadata for a volume.

 

Replaces metadata items that match keys. Does not modify items that are not in the request.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

metadata plain xsd:dict

A metadata object. Contains one or more metadata key and value pairs that are associated with the volume.

Response parameters
Parameter Style Type Description
metadata plain xsd:dict

A metadata object. Contains one or more metadata key and value pairs that are associated with the volume.

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

Volume type access (volumes)

Private volume type access to project.

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

POST
/v2/​{tenant_id}​/types/​{volume_type}​/action
Add private volume type access

Adds private volume type access to a project.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The ID of the project. Volume Type access to be added to this project ID.

volume_type URI csapi:UUID

The ID of Volume Type to be accessed by project.

project plain xsd:string

The ID of the project. Volume Type access to be added to this project ID.

{
    "addProjectAccess": {
        "project": "f270b245cb11498ca4031deb7e141cfa"
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<addProjectAccess id="bb4f8f7f-fc38-4807-bd78-5710792205e1">
  <project>"f270b245cb11498ca4031deb7e141cfa"</project>
</addProjectAccess>

This operation does not return a response body.

POST
/v2/​{tenant_id}​/types/​{volume_type}​/action
Remove private volume type access

Removes private volume type access from a project.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The ID of the project. Volume Type access to be added to this project ID.

volume_type URI csapi:UUID

The ID of Volume Type to be accessed by project.

project plain xsd:string

The ID of the project. Volume Type access to be added to this project ID.

{
    "removeProjectAccess": {
        "project": "f270b245cb11498ca4031deb7e141cfa"
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<removeProjectAccess id="bb4f8f7f-fc38-4807-bd78-5710792205e1">
  <project>"f270b245cb11498ca4031deb7e141cfa"</project>
</removeProjectAccess>

This operation does not return a response body.

GET
/v2/​{tenant_id}​/types/​{volume_type}​/os-volume-type-access
List private volume type access details

Lists project IDs that have access to private volume type.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The ID of the project. Volume Type access to be added to this project ID.

volume_type URI csapi:UUID

The ID of Volume Type to be accessed by project.

Response parameters
Parameter Style Type Description
project_id plain xsd:string

The Project ID having access to this volume type.

volume_type_id URI csapi:UUID

The ID of Volume Type.

{
    "volume_type_access": {
        "volume_type_id": "3c67e124-39ad-4ace-a507-8bb7bf510c26",
        "project_id": "f270b245cb11498ca4031deb7e141cfa"
    }
}

Volume actions (volumes, action)

Extends the size of, resets statuses for, sets image metadata for, and removes image metadata from a volume. Attaches a volume to a server, detaches a volume from a server, and removes a volume from Block Storage management without actually removing the back-end storage object associated with it.

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

Extends the size of a volume to a requested size, 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-extend plain xsd:dict

The os-extend action.

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 volume. Specify the os-reset_status action in the request body.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-reset_status plain xsd:dict

The os-reset_status action.

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 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-set_image_metadata plain xsd:dict

The os-set_image_metadata action.

metadata plain xsd:dict

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 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-unset_image_metadata plain xsd:dict

The os-unset_image_metadata action. This action removes the key-value pairs from the image metadata.

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 to server

Attaches a volume to a 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-attach plain xsd:dict

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 mount point.

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

This operation does not return a response body.

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

Removes a volume from Block Storage management without removing the back-end storage object that is associated with it. Specify the os-unmanage action in the request body.

 

Preconditions

  • Volume status must be available.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-unmanage plain xsd:dict

The os-unmanage action. This action removes the specified volume from Cinder management.

{
    "os-unmanage": {}
}

This operation does not return a response body.

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/action
Force detach volume

Forces a volume to detach. Specify the os-force_detach action in the request body.

 

Rolls back an unsuccessful detach operation after you disconnect the volume.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-force_detach plain xsd:dict

The os-force_detach action.

connector plain xsd:dict

The connector object.

attachment_id (Optional) plain csapi:UUID

The interface ID.

{
    "os-force_detach": {
        "attachment_id": "d8777f54-84cf-4809-a679-468ffed56cf1",
        "connector": {
            "initiator": "iqn.2012-07.org.fake:01"
        }
    }
}

This operation does not return a response body.

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/action
Promote replicated volume

Promotes a replicated volume. Specify the os-promote-replica action in the request body.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-promote-replica plain xsd:dict

The os-promote-replica action.

{
    "os-promote-replica": {}
}

This operation does not return a response body.

POST
/v2/​{tenant_id}​/volumes/​{volume_id}​/action
Reenable volume replication

Re-enables replication of a volume. Specify the volume-replica-reenable action in the request body.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id URI csapi:UUID

The UUID of the volume.

os-reenable-replica plain xsd:dict

The os-reenable-replica action.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

os-volume-replication:driver_data (Optional) plain xsd:string

The name of the volume replication driver.

os-volume-replication:extended_status (Optional) plain xsd:string

The status of the volume replication.

{
    "os-reenable-replica": {}
}

This operation does not return a response body.

Backups (backups)

A backup is a full copy of a volume stored in an external service. The service can be configured. The only supported service 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 that 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 restore to a volume.

deleting

The backup is being deleted.

error

A backup error occurred.

restoring

The backup is being restored to a volume.

error_restoring

A backup restoration error occurred.

If an error occurs, you can find more information about the error 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

backup plain xsd:dict

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

force (Optional) plain xsd:boolean

Indicates whether to backup, even if the volume is attached. Default is false.

Response parameters
Parameter Style Type Description
backup plain xsd:dict

A backup object.

id plain csapi:UUID

The UUID of the backup.

links plain xsd:list

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 Block Storage backups to which the tenant has access.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

sort_key (Optional) query xsd:string

Sorts by an attribute. A valid value is name, status, container_format, disk_format, size, id, created_at, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value.

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 page size of items. Returns a number of items up to a 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

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

A list of backup objects.

id plain csapi:UUID

The UUID of the backup.

links plain xsd:list

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 with details

Lists Block Storage backups, with details, to which the tenant has access.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

sort_key (Optional) query xsd:string

Sorts by an attribute. A valid value is name, status, container_format, disk_format, size, id, created_at, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value.

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 page size of items. Returns a number of items up to a 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

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

A list of backup objects.

availability_zone plain xsd:string

The availability zone.

container plain xsd:string

The container name or null.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

description plain xsd:string

The backup description or null.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

fail_reason plain xsd:string

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

id plain csapi:UUID

The UUID of the backup.

links plain xsd:list

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. Refer to Backup statuses table for the possible status value.

volume_id plain csapi:UUID

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

is_incremental (Optional) 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 (Optional) plain xsd:boolean

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

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

backup_id URI csapi:UUID

The UUID for a backup.

Response parameters
Parameter Style Type Description
backup plain xsd:dict

A backup object.

availability_zone plain xsd:string

The availability zone.

container plain xsd:string

The container name or null.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

description plain xsd:string

The backup description or null.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

fail_reason plain xsd:string

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

id plain csapi:UUID

The UUID of the backup.

links plain xsd:list

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. Refer to Backup statuses table for the possible status value.

volume_id plain csapi:UUID

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

is_incremental (Optional) 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 (Optional) plain xsd:boolean

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

 
Normal response codes
204
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

backup_id URI csapi:UUID

The UUID 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 UUID or name of the volume. If you specify both the UUID and name, the UUID takes priority.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

backup_id URI csapi:UUID

The UUID for a backup.

restore plain xsd:dict

A restore object.

volume_id (Optional) plain csapi:UUID

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

A restore object.

backup_id plain csapi:UUID

The UUID of the backup.

volume_id plain csapi:UUID

The UUID 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 (backups, action)

Force-deletes a backup.

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

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

 

This operations deletes the backup and any backup data.

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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

backup_id URI csapi:UUID

The UUID 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.

Capabilities for storage back ends (capabilities)

Shows capabilities for a storage back end.

GET
/v2/​{tenant_id}​/capabilities/​{hostname}​
Show back-end capabilities

Shows capabilities for a storage back end.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

hostname URI xsd:string

The name of the host that hosts the storage back end.

Response parameters
Parameter Style Type Description
pool_name plain xsd:string

The name of the storage pool.

visibility plain xsd:string

The volume type access.

description plain xsd:string

The capabilities description.

driver_version plain xsd:string

The driver version.

volume_backend_name plain xsd:string

The name of the back-end volume.

vendor_name plain xsd:string

The name of the vendor.

namespace plain xsd:string

The storage namespace, such as OS::Storage::Capabilities::foo.

properties plain xsd:dict

The backend volume capabilities list, which is consisted of cinder standard capabilities and vendor unique properties.

storage_protocol plain xsd:string

The storage protocol, such as Fibre Channel, iSCSI, NFS, and so on.

{
    "namespace": "OS::Storage::Capabilities::fake",
    "vendor_name": "OpenStack",
    "volume_backend_name": "lvm",
    "pool_name": "pool",
    "driver_version": "2.0.0",
    "storage_protocol": "iSCSI",
    "display_name": "Capabilities of Cinder LVM driver",
    "description": "These are volume type options provided by Cinder LVM driver, blah, blah.",
    "visibility": "public",
    "properties": {
        "compression": {
            "title": "Compression",
            "description": "Enables compression.",
            "type": "boolean"
        },
        "qos": {
            "title": "QoS",
            "description": "Enables QoS.",
            "type": "boolean"
        },
        "replication": {
            "title": "Replication",
            "description": "Enables replication.",
            "type": "boolean"
        },
        "thin_provisioning": {
            "title": "Thin Provisioning",
            "description": "Sets thin provisioning.",
            "type": "boolean"
        }
    }
}

Quota sets extension (os-quota-sets)

Administrators only, depending on policy settings.

Shows, updates, and deletes quotas for a tenant.

GET
/v2/​{admin_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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

admin_tenant_id URI csapi:UUID

The UUID of the administrative 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:dict

A quota_set object.

cores plain xsd:int

The number of instance cores that are allowed for each tenant.

fixed_ips plain xsd:int

The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.

floating_ips plain xsd:int

The number of floating IP addresses that are allowed for each tenant.

id plain xsd:int

The ID for the quota set.

injected_file_content_bytes plain xsd:int

The number of bytes of content that are allowed for each injected file.

injected_file_path_bytes plain xsd:int

The number of bytes that are allowed for each injected file path.

injected_files plain xsd:int

The number of injected files that are allowed for each tenant.

instances plain xsd:int

The number of instances that are allowed for each tenant.

key_pairs plain xsd:int

The number of key pairs that are allowed for each user.

metadata_items plain xsd:int

The number of metadata items that are allowed for each instance.

ram plain xsd:int

The amount of instance RAM in megabytes that are allowed for each tenant.

security_group_rules (Optional) plain xsd:int

The number of rules that are allowed for each security group.

security_groups plain xsd:int

The number of security groups that are 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/​{admin_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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

admin_tenant_id URI csapi:UUID

The UUID of the administrative tenant.

quota_set plain xsd:dict

A quota_set object.

cores plain xsd:int

The number of instance cores that are allowed for each tenant.

fixed_ips plain xsd:int

The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.

floating_ips plain xsd:int

The number of floating IP addresses that are allowed for each tenant.

id plain xsd:int

The ID for the quota set.

injected_file_content_bytes plain xsd:int

The number of bytes of content that are allowed for each injected file.

injected_file_path_bytes plain xsd:int

The number of bytes that are allowed for each injected file path.

injected_files plain xsd:int

The number of injected files that are allowed for each tenant.

instances plain xsd:int

The number of instances that are allowed for each tenant.

key_pairs plain xsd:int

The number of key pairs that are allowed for each user.

metadata_items plain xsd:int

The number of metadata items that are allowed for each instance.

ram plain xsd:int

The amount of instance RAM in megabytes that are allowed for each tenant.

security_group_rules (Optional) plain xsd:int

The number of rules that are allowed for each security group.

security_groups plain xsd:int

The number of security groups that are 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.

Response parameters
Parameter Style Type Description
quota_set plain xsd:dict

A quota_set object.

cores plain xsd:int

The number of instance cores that are allowed for each tenant.

fixed_ips plain xsd:int

The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.

floating_ips plain xsd:int

The number of floating IP addresses that are allowed for each tenant.

id plain xsd:int

The ID for the quota set.

injected_file_content_bytes plain xsd:int

The number of bytes of content that are allowed for each injected file.

injected_file_path_bytes plain xsd:int

The number of bytes that are allowed for each injected file path.

injected_files plain xsd:int

The number of injected files that are allowed for each tenant.

instances plain xsd:int

The number of instances that are allowed for each tenant.

key_pairs plain xsd:int

The number of key pairs that are allowed for each user.

metadata_items plain xsd:int

The number of metadata items that are allowed for each instance.

ram plain xsd:int

The amount of instance RAM in megabytes that are allowed for each tenant.

security_group_rules (Optional) plain xsd:int

The number of rules that are allowed for each security group.

security_groups plain xsd:int

The number of security groups that are 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": {
        "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/​{admin_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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

admin_tenant_id URI csapi:UUID

The UUID of the administrative 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

Response parameters
Parameter Style Type Description
quota_set plain xsd:dict

A quota_set object.

cores plain xsd:int

The number of instance cores that are allowed for each tenant.

fixed_ips plain xsd:int

The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.

floating_ips plain xsd:int

The number of floating IP addresses that are allowed for each tenant.

id plain xsd:int

The ID for the quota set.

injected_file_content_bytes plain xsd:int

The number of bytes of content that are allowed for each injected file.

injected_file_path_bytes plain xsd:int

The number of bytes that are allowed for each injected file path.

injected_files plain xsd:int

The number of injected files that are allowed for each tenant.

instances plain xsd:int

The number of instances that are allowed for each tenant.

key_pairs plain xsd:int

The number of key pairs that are allowed for each user.

metadata_items plain xsd:int

The number of metadata items that are allowed for each instance.

ram plain xsd:int

The amount of instance RAM in megabytes that are allowed for each tenant.

security_group_rules (Optional) plain xsd:int

The number of rules that are allowed for each security group.

security_groups plain xsd:int

The number of security groups that are 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>

This operation does not accept a request body.

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

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

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

admin_tenant_id URI csapi:UUID

The UUID of the administrative tenant.

user_id URI xsd:string

The user ID. Specify in the URI as user_id={user_id}.

Response parameters
Parameter Style Type Description
quota_set plain xsd:dict

A quota_set object.

cores plain xsd:int

The number of instance cores that are allowed for each tenant.

fixed_ips plain xsd:int

The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.

floating_ips plain xsd:int

The number of floating IP addresses that are allowed for each tenant.

id plain xsd:int

The ID for the quota set.

injected_file_content_bytes plain xsd:int

The number of bytes of content that are allowed for each injected file.

injected_file_path_bytes plain xsd:int

The number of bytes that are allowed for each injected file path.

injected_files plain xsd:int

The number of injected files that are allowed for each tenant.

instances plain xsd:int

The number of instances that are allowed for each tenant.

key_pairs plain xsd:int

The number of key pairs that are allowed for each user.

metadata_items plain xsd:int

The number of metadata items that are allowed for each instance.

ram plain xsd:int

The amount of instance RAM in megabytes that are allowed for each tenant.

security_group_rules (Optional) plain xsd:int

The number of rules that are allowed for each security group.

security_groups plain xsd:int

The number of security groups that are 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": {
        "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/​{admin_tenant_id}​/os-quota-sets/​{tenant_id}​/​{user_id}​
Update quotas for user

Updates quotas for a tenant and user.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

admin_tenant_id URI csapi:UUID

The UUID of the administrative tenant.

user_id URI xsd:string

The user ID. Specify in the URI as user_id={user_id}.

quota_set plain xsd:dict

A quota_set object.

cores plain xsd:int

The number of instance cores that are allowed for each tenant.

fixed_ips plain xsd:int

The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.

floating_ips plain xsd:int

The number of floating IP addresses that are allowed for each tenant.

id plain xsd:int

The ID for the quota set.

injected_file_content_bytes plain xsd:int

The number of bytes of content that are allowed for each injected file.

injected_file_path_bytes plain xsd:int

The number of bytes that are allowed for each injected file path.

injected_files plain xsd:int

The number of injected files that are allowed for each tenant.

instances plain xsd:int

The number of instances that are allowed for each tenant.

key_pairs plain xsd:int

The number of key pairs that are allowed for each user.

metadata_items plain xsd:int

The number of metadata items that are allowed for each instance.

ram plain xsd:int

The amount of instance RAM in megabytes that are allowed for each tenant.

security_group_rules (Optional) plain xsd:int

The number of rules that are allowed for each security group.

security_groups plain xsd:int

The number of security groups that are 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.

Response parameters
Parameter Style Type Description
quota_set plain xsd:dict

A quota_set object.

cores plain xsd:int

The number of instance cores that are allowed for each tenant.

fixed_ips plain xsd:int

The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.

floating_ips plain xsd:int

The number of floating IP addresses that are allowed for each tenant.

id plain xsd:int

The ID for the quota set.

injected_file_content_bytes plain xsd:int

The number of bytes of content that are allowed for each injected file.

injected_file_path_bytes plain xsd:int

The number of bytes that are allowed for each injected file path.

injected_files plain xsd:int

The number of injected files that are allowed for each tenant.

instances plain xsd:int

The number of instances that are allowed for each tenant.

key_pairs plain xsd:int

The number of key pairs that are allowed for each user.

metadata_items plain xsd:int

The number of metadata items that are allowed for each instance.

ram plain xsd:int

The amount of instance RAM in megabytes that are allowed for each tenant.

security_group_rules (Optional) plain xsd:int

The number of rules that are allowed for each security group.

security_groups plain xsd:int

The number of security groups that are 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": {
        "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/​{admin_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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

admin_tenant_id URI csapi:UUID

The UUID of the administrative tenant.

user_id URI xsd:string

The user ID. Specify in the URI as user_id={user_id}.

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

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

Shows details for quotas for a tenant and user.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

admin_tenant_id URI csapi:UUID

The UUID of the administrative tenant.

user_id URI xsd:string

The user ID. Specify in the URI as user_id={user_id}.

Response parameters
Parameter Style Type Description
quota_set plain xsd:dict

A quota_set object.

cores plain xsd:int

The number of instance cores that are allowed for each tenant.

fixed_ips plain xsd:int

The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.

floating_ips plain xsd:int

The number of floating IP addresses that are allowed for each tenant.

id plain xsd:int

The ID for the quota set.

injected_file_content_bytes plain xsd:int

The number of bytes of content that are allowed for each injected file.

injected_file_path_bytes plain xsd:int

The number of bytes that are allowed for each injected file path.

injected_files plain xsd:int

The number of injected files that are allowed for each tenant.

instances plain xsd:int

The number of instances that are allowed for each tenant.

key_pairs plain xsd:int

The number of key pairs that are allowed for each user.

metadata_items plain xsd:int

The number of metadata items that are allowed for each instance.

ram plain xsd:int

The amount of instance RAM in megabytes that are allowed for each tenant.

security_group_rules (Optional) plain xsd:int

The number of rules that are allowed for each security group.

security_groups plain xsd:int

The number of security groups that are 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": {
        "snapshots": 45
    }
}

This operation does not accept a request body.

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.

 

Specify one or more key and value pairs in the request body.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

qos_specs plain xsd:dict

A qos_specs object.

name plain xsd:string

The name of the QoS specification.

consumer (Optional) plain xsd:string

The consumer type.

Response parameters
Parameter Style Type Description
qos_specs plain xsd:dict

A qos_specs object.

specs plain xsd:dict

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

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": {
            "numberOfFailures": "0",
            "availability": "100"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "599ef437-1c99-42ec-9fc6-239d0519fef1"
    },
    "links": [
        {
            "href": "http://23.253.248.171:8776/v2/bab7d5c60cd041a0a36f7c4b6e1dd978/qos_specs/599ef437-1c99-42ec-9fc6-239d0519fef1",
            "rel": "self"
        },
        {
            "href": "http://23.253.248.171:8776/bab7d5c60cd041a0a36f7c4b6e1dd978/qos_specs/599ef437-1c99-42ec-9fc6-239d0519fef1",
            "rel": "bookmark"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<qos_specs>
    <qos_spec consumer="back-end" id="e1f84cf3-6b1e-4f25-8130-3244f69ec7c1" 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

sort_key (Optional) query xsd:string

Sorts by an image attribute. A valid value is name, status, container_format, disk_format, size, id, created_at, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value.

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 page size of items. Returns a number of items up to a 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

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
qos_specs plain xsd:dict

A qos_specs object.

specs plain xsd:dict

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>
GET
/v2/​{tenant_id}​/qos-specs/​{qos_id}​
Show QoS specification details

Shows details for a 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

qos_id URI xsd:string

The ID of the QoS specification.

Response parameters
Parameter Style Type Description
qos_specs plain xsd:dict

A qos_specs object.

specs plain xsd:dict

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

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 keys in QoS specification

Sets keys in a QoS specification.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

qos_id URI xsd:string

The ID of the QoS specification.

qos_specs plain xsd:dict

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 QoS specification.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

qos_id URI xsd:string

The ID of the QoS specification.

force URI xsd:boolean

To delete a QoS specification even if it is in-use, set to true. Default is false.

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 volume type.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

qos_id URI xsd:string

The ID of the QoS specification.

volume_type_id URI csapi:UUID

The UUID for an existing 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 volume type.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

qos_id URI xsd:string

The ID of the QoS specification.

volume_type_id URI csapi:UUID

The UUID for an existing 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 QoS specification from all associations.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

qos_id URI xsd:string

The ID of 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

Lists all associations for a QoS specification.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

qos_id URI xsd:string

The ID of the QoS specification.

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

Volume types (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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

sort_key (Optional) query xsd:string

Sorts by an attribute. A valid value is name, status, container_format, disk_format, size, id, created_at, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value.

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 page size of items. Returns a number of items up to a 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

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
volume_types plain xsd:list

A list of volume_type objects.

volume_type plain xsd:dict

The volume_type object.

name plain xsd:string

The name of the volume type.

extra_specs plain xsd:dict

A set of key and value pairs that contains the specifications for a volume type.

{
    "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>
POST
/v2/​{tenant_id}​/types
Create volume type

Creates a volume type.

 

To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder-volume, and they are keyed from a unique queue. They are named cinder-volume.HOST.BACKEND. For example, cinder-volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type.

For information about how to use volume types to create multiple-storage back ends, see Configure multiple-storage back ends.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_type plain xsd:dict

A volume_type object.

Response parameters
Parameter Style Type Description
volume_type plain xsd:dict

A volume_type object.

volume_type plain xsd:dict

The volume_type object.

name plain xsd:string

The name of the volume type.

extra_specs plain xsd:dict

A set of key and value pairs that contains the specifications for a volume type.

description (Optional) plain xsd:string

The description of the volume type.

is_public (Optional) plain xsd:boolean

Indicates whether the volume type is public or not. Default is true.

{
    "volume_type": {
        "name": "vol-type-001",
        "description": "volume type 0001",
        "os-volume-type-access:is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" name="vol-type-001" description="volume type 0001" os-volume-type-access:is_public="true">
        <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",
        "description": "volume type 001",
        "is_public": "true",
        "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"
    description="volume type 001" is_public="true">
    <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.

 

To create an environment with multiple-storage back ends, you must specify a volume type. The API spawns Block Storage volume back ends as children to cinder-volume, and keys them from a unique queue. The API names the back ends cinder-volume.HOST.BACKEND. For example, cinder-volume.ubuntu.lvmdriver. When you create a volume, the scheduler chooses an appropriate back end for the volume type to handle the request.

For information about how to use volume types to create multiple-storage back ends, see Configure multiple-storage back ends.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_type_id URI csapi:UUID

The UUID for an existing volume type.

volume_type plain xsd:dict

A volume_type object.

Response parameters
Parameter Style Type Description
volume_type plain xsd:dict

The volume_type object.

name plain xsd:string

The name of the volume type.

extra_specs plain xsd:dict

A set of key and value pairs that contains the specifications for a volume type.

description (Optional) plain xsd:string

The description of the volume type.

is_public (Optional) plain xsd:boolean

Indicates whether the volume type is public or not. Default is true.

{
    "volume_type": {
        "name": "vol-type-001",
        "description": "volume type 0001",
        "is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" name="vol-type-001" description="volume type 0001" is_public="true">
        <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",
        "description": "volume type 001",
        "is_public": "true",
        "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"
    description="volume type 001" is_public="true">
    <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 that are assigned to a volume type.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_type_id URI csapi:UUID

The UUID for an existing volume type.

volume_type plain xsd:dict

A volume_type object.

extra_specs plain xsd:dict

A key and value pair that contains additional specifications that are associated with the volume type. Examples include capabilities, capacity, compression, and so on, depending on the storage driver in use.

Response parameters
Parameter Style Type Description
volume_type plain xsd:dict

The volume_type object.

name plain xsd:string

The name of the volume type.

extra_specs plain xsd:dict

A set of key and value pairs that contains the specifications for a volume type.

description (Optional) plain xsd:string

The description of the volume type.

is_public (Optional) plain xsd:boolean

Indicates whether the volume type is public or not. Default is true.

{
    "volume_type": {
        "name": "vol-type-001",
        "description": "volume type 0001",
        "is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" name="vol-type-001" description="volume type 0001" is_public="true">
        <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",
        "description": "volume type 001",
        "is_public": "true",
        "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"
    description="volume type 001" is_public="true">
    <extra_specs>
        <extra_spec key="capabilities">gpu</extra_spec>
    </extra_specs>
</volume_type>
GET
/v2/​{tenant_id}​/types/​{volume_type_id}​
Show volume type details

Shows details for a volume type.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_type_id URI csapi:UUID

The UUID for an existing volume type.

Response parameters
Parameter Style Type Description
volume_type plain xsd:dict

The volume_type object.

name plain xsd:string

The name of the volume type.

extra_specs plain xsd:dict

A set of key and value pairs that contains the specifications for a volume type.

description (Optional) plain xsd:string

The description of the volume type.

is_public (Optional) plain xsd:boolean

Indicates whether the volume type is public or not. Default is true.

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "description": "volume type 001",
        "is_public": "true",
        "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"
    description="volume type 001" is_public="true">
    <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 volume type.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_type_id URI csapi:UUID

The UUID for an existing volume type.

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

Volume snapshots (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 use.

deleting

The snapshot is being deleted.

error

A snapshot creation error occurred.

error_deleting

A snapshot deletion error occurred.

POST
/v2/​{tenant_id}​/snapshots
Create snapshot

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

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

snapshot plain xsd:string

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

name (Optional) plain xsd:string

The name of the snapshot. Default is None.

description (Optional) plain xsd:string

A description for the snapshot. Default is None.

volume_id plain csapi:UUID

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

force (Optional) plain xsd:boolean

Indicates whether to snapshot, even if the volume is attached. Default is false.

Response parameters
Parameter Style Type Description
snapshot plain xsd:dict

A snapshot object.

status plain xsd:string

The status for the snapshot.

description plain xsd:string

A description for the snapshot.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

metadata plain xsd:dict

One or more metadata key and value pairs for the snapshot, if any.

volume_id plain csapi:UUID

If the snapshot was created from a volume, the volume ID.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

id plain csapi:UUID

The snapshot UUID.

name plain xsd:string

The name of the snapshot.

{
    "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 all Block Storage snapshots, with summary information, that the tenant can access.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

sort_key (Optional) query xsd:string

Sorts by an attribute. A valid value is name, status, container_format, disk_format, size, id, created_at, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value.

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 page size of items. Returns a number of items up to a 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

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 status for the snapshot.

description plain xsd:string

A description for the snapshot.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

metadata plain xsd:dict

One or more metadata key and value pairs for the snapshot, if any.

volume_id plain csapi:UUID

If the snapshot was created from a volume, the volume ID.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

id plain csapi:UUID

The snapshot UUID.

name plain xsd:string

The name of the snapshot.

{
    "snapshots": [
        {
            "status": "available",
            "metadata": {
                "name": "test"
            },
            "name": "test-volume-snapshot",
            "volume_id": "173f7b48-c4c1-4e70-9acc-086b39073506",
            "created_at": "2015-11-29T02:25:51.000000",
            "size": 1,
            "id": "b1323cda-8e4b-41c1-afc5-2fc791809c8c",
            "description": "volume snapshot"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshots>
    <snapshot status="available"
        description="volume snapshot"
        created_at="2015-11-29 02:25:51+00:00"
        volume_id="173f7b48-c4c1-4e70-9acc-086b39073506"
        size="1" id="b1323cda-8e4b-41c1-afc5-2fc791809c8c"
        name="test-volume-snapshot">
        <metadata>
            <meta key="name">test</meta>
        </metadata>
    </snapshot>
</snapshots>
GET
/v2/​{tenant_id}​/snapshots/detail
List snapshots with details

Lists all Block Storage snapshots, with details, that the tenant can access.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status for the snapshot.

description plain xsd:string

A description for the snapshot.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

metadata plain xsd:dict

One or more metadata key and value pairs for the snapshot, if any.

volume_id plain csapi:UUID

If the snapshot was created from a volume, the volume ID.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

id plain csapi:UUID

The snapshot UUID.

name plain xsd:string

The name of the snapshot.

os-extended-snapshot-attributes:progress plain xsd:int

A percentage value for the build progress.

os-extended-snapshot-attributes:project_id plain csapi:UUID

The UUID of the owning project.

{
    "snapshots": [
        {
            "status": "available",
            "metadata": {
                "name": "test"
            },
            "os-extended-snapshot-attributes:progress": "100%",
            "name": "test-volume-snapshot",
            "volume_id": "173f7b48-c4c1-4e70-9acc-086b39073506",
            "os-extended-snapshot-attributes:project_id": "bab7d5c60cd041a0a36f7c4b6e1dd978",
            "created_at": "2015-11-29T02:25:51.000000",
            "size": 1,
            "id": "b1323cda-8e4b-41c1-afc5-2fc791809c8c",
            "description": "volume snapshot"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshots
    xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1">
    <snapshot status="available"
        description="volume snapshot"
        created_at="2015-11-29 02:25:51+00:00"
        volume_id="173f7b48-c4c1-4e70-9acc-086b39073506"
        size="1" id="b1323cda-8e4b-41c1-afc5-2fc791809c8c"
        name="test-volume-snapshot"
        os-extended-snapshot-attributes:project_id="bab7d5c60cd041a0a36f7c4b6e1dd978"
        os-extended-snapshot-attributes:progress="100%">
        <metadata>
            <meta key="name">test</meta>
        </metadata>
    </snapshot>
</snapshots>

This operation does not accept a request body.

GET
/v2/​{tenant_id}​/snapshots/​{snapshot_id}​
Show snapshot details

Shows details for a snapshot.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

snapshot_id URI csapi:UUID

The UUID of the snapshot.

Response parameters
Parameter Style Type Description
snapshot plain xsd:dict

A snapshot object.

status plain xsd:string

The status for the snapshot.

description plain xsd:string

A description for the snapshot.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

metadata plain xsd:dict

One or more metadata key and value pairs for the snapshot, if any.

volume_id plain csapi:UUID

If the snapshot was created from a volume, the volume ID.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

id plain csapi:UUID

The snapshot UUID.

name plain xsd:string

The name of the snapshot.

os-extended-snapshot-attributes:progress plain xsd:int

A percentage value for the build progress.

os-extended-snapshot-attributes:project_id plain csapi:UUID

The UUID of the owning project.

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

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

snapshot_id URI csapi:UUID

The UUID of the snapshot.

snapshot plain xsd:string

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

name (Optional) plain xsd:string

The name of the snapshot. Default is None.

description (Optional) plain xsd:string

A description for the snapshot. Default is None.

Response parameters
Parameter Style Type Description
snapshot plain xsd:dict

A snapshot object.

status plain xsd:string

The status for the snapshot.

description plain xsd:string

A description for the snapshot.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

metadata plain xsd:dict

One or more metadata key and value pairs for the snapshot, if any.

volume_id plain csapi:UUID

If the snapshot was created from a volume, the volume ID.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

id plain csapi:UUID

The snapshot UUID.

name plain xsd:string

The name of the 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 snapshot.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

snapshot_id URI csapi:UUID

The UUID of the 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 metadata for a snapshot.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

snapshot_id URI csapi:UUID

The UUID of the snapshot.

Response parameters
Parameter Style Type Description
snapshot plain xsd:dict

A snapshot object.

status plain xsd:string

The status for the snapshot.

description plain xsd:string

A description for the snapshot.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

metadata plain xsd:dict

One or more metadata key and value pairs for the snapshot, if any.

volume_id plain csapi:UUID

If the snapshot was created from a volume, the volume ID.

size plain xsd:int

The size of the volume, in gibibytes (GiB).

id plain csapi:UUID

The snapshot UUID.

name plain xsd:string

The name of the snapshot.

os-extended-snapshot-attributes:progress plain xsd:int

A percentage value for the build progress.

os-extended-snapshot-attributes:project_id plain csapi:UUID

The UUID of the owning project.

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

This operation does not accept a request body.

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

Updates metadata for a snapshot.

 

Replaces metadata items that match keys. Does not modify items that are not in the request.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

snapshot_id URI csapi:UUID

The UUID of the snapshot.

metadata (Optional) plain xsd:dict

One or more metadata key and value pairs for the 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>

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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

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

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

Shows image metadata for a volume.

 

When the request is made, the caller must specify a reference to an existing storage volume in the ref element. 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 csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume plain xsd:string

A volume object.

host plain xsd:string

The OpenStack Block Storage host where the existing volume resides.

ref plain xsd:dict

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

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
    }
}

Back-end storage pools

Administrator only. Lists all back-end storage pools that are known to the scheduler service.

GET
/v2/​{tenant_id}​/scheduler-stats/get_pools
List back-end storage pools

Lists all back-end storage pools.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

detail (Optional) query xsd:boolean

Indicates whether to show pool details or only pool names in the response.

Set to true to show pool details. Set to false to show only pool names. Default is false.

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the back-end volume.

capabilities plain xsd:dict

The capabilities for the back end.

The value is either null or a string value that indicates the capabilities for each pool. For example, total_capacity or QoS_support.

updated plain xsd:dateTime

The date and time stamp when the API request was issued.

total_capacity plain xsd:string

The total capacity for the back-end volume, in GBs. A valid value is a string, such as unknown, or an integer.

free_capacity plain xsd:string

The amount of free capacity for the back-end volume, in GBs. A valid value is a string, such as unknown, or an integer.

volume_backend_name plain xsd:string

The name of the back-end volume.

reserved_percentage plain xsd:int

The percentage of the total capacity that is reserved for the internal use by the back end.

driver_version plain xsd:string

The driver version.

storage_protocol plain xsd:string

The storage back end for the back-end volume. For example, iSCSI or FC.

QoS_support plain xsd:boolean

The quality of service (QoS) support.

{
    "pools": [
        {
            "name": "pool1",
            "capabilities": {
                "updated": "2014-10-28T00:00:00-00:00",
                "total_capacity": 1024,
                "free_capacity": 100,
                "volume_backend_name": "pool1",
                "reserved_percentage": 0,
                "driver_version": "1.0.0",
                "storage_protocol": "iSCSI",
                "QoS_support": false
            }
        },
        {
            "name": "pool2",
            "capabilities": {
                "updated": "2014-10-28T00:00:00-00:00",
                "total_capacity": 512,
                "free_capacity": 200,
                "volume_backend_name": "pool2",
                "reserved_percentage": 0,
                "driver_version": "1.0.1",
                "storage_protocol": "iSER",
                "QoS_support": true
            }
        }
    ]
}

Volume transfer

Transfers a volume from one user to another user.

POST
/v2/​{tenant_id}​/os-volume-transfer
Create volume transfer

Creates a volume transfer.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

volume_id plain csapi:UUID

The UUID of the volume.

name (Optional) plain xsd:string

The volume transfer name.

Response parameters
Parameter Style Type Description
id plain csapi:UUID

The UUID of the volume transfer.

created_at plain xsd:dateTime

Date and time when the volume was created.

name plain xsd:string

The volume transfer name.

volume_id plain csapi:UUID

The UUID of the volume.

auth_key plain xsd:string

The authentication key for the volume transfer.

links plain xsd:list

Links for the volume transfer.

{
    "transfer": {
        "volume_id": "c86b9af4-151d-4ead-b62c-5fb967af0e37",
        "name": "first volume"
    }
}
{
    "transfer": {
        "id": "1a7059f5-8ed7-45b7-8d05-2811e5d09f24",
        "created_at": "2015-02-25T03:56:53.081642",
        "name": "first volume",
        "volume_id": "c86b9af4-151d-4ead-b62c-5fb967af0e37",
        "auth_key": "9266c59563c84664",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/3",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/3",
                "rel": "bookmark"
            }
        ]
    }
}
GET
/v2/​{tenant_id}​/os-volume-transfer
List volume transfers

Lists volume transfers.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

Response parameters
Parameter Style Type Description
id plain csapi:UUID

The UUID of the volume transfer.

name plain xsd:string

The name of the volume transfer.

volume_id plain csapi:UUID

The UUID of the volume.

links plain xsd:list

Links for the volume transfer.

{
    "transfers": [
        {
            "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
            "name": "first volume transfer",
            "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/1",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/1",
                    "rel": "bookmark"
                }
            ]
        },
        {
            "id": "f26c0dee-d20d-4e80-8dee-a8d91b9742a1",
            "name": "second volume transfer",
            "volume_id": "673db275-379f-41af-8371-e1652132b4c1",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/2",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/2",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

GET
/v2/​{tenant_id}​/os-volume-transfer/detail
List volume transfers, with details

Lists volume transfers, with details.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

Response parameters
Parameter Style Type Description
id plain csapi:UUID

The UUID of the volume transfer.

created_at plain xsd:dateTime

Date and time when the volume was created.

name plain xsd:string

The name of the volume transfer.

volume_id plain csapi:UUID

The UUID of the volume.

links plain xsd:list

Links for the volume transfer.

{
    "transfers": [
        {
            "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
            "created_at": "2015-02-25T03:56:53.081642",
            "name": "first volume transfer",
            "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/1",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/1",
                    "rel": "bookmark"
                }
            ]
        },
        {
            "id": "f26c0dee-d20d-4e80-8dee-a8d91b9742a1",
            "created_at": "2015-03-25T03:56:53.081642",
            "name": "second volume transfer",
            "volume_id": "673db275-379f-41af-8371-e1652132b4c1",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/2",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/2",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

GET
/v2/​{tenant_id}​/os-volume-transfer/​{transfer_id}​
Show volume transfer details

Shows details for a volume transfer.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

transfer_id URI csapi:UUID

The unique identifier for a volume transfer.

Response parameters
Parameter Style Type Description
id plain csapi:UUID

The UUID of the volume transfer.

created_at plain xsd:dateTime

Date and time when the volume was created.

name plain xsd:string

The name of the volume transfer.

volume_id plain csapi:UUID

The UUID of the volume.

links plain xsd:list

Links for the volume transfer.

{
    "transfer": {
        "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
        "created_at": "2015-02-25T03:56:53.081642",
        "name": "first volume transfer",
        "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/1",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/1",
                "rel": "bookmark"
            }
        ]
    }
}

This operation does not accept a request body.

DELETE
/v2/​{tenant_id}​/os-volume-transfer/​{transfer_id}​
Delete volume transfer

Deletes a volume transfer.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

transfer_id URI csapi:UUID

The unique identifier for a volume transfer.

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

POST
/v2/​{tenant_id}​/os-volume-transfer/​{transfer_id}​/accept
Accept volume transfer

Accepts a volume transfer.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

transfer_id URI csapi:UUID

The unique identifier for a volume transfer.

auth_key plain xsd:string

The authentication key for the volume transfer.

Response parameters
Parameter Style Type Description
id plain csapi:UUID

The UUID of the volume transfer.

name plain xsd:string

The name of the volume transfer.

volume_id plain csapi:UUID

The UUID of the volume.

links plain xsd:list

Links for the volume transfer.

{
    "accept": {
        "auth_key": "9266c59563c84664"
    }
}
{
    "transfer": {
        "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
        "name": "first volume transfer",
        "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/1",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/1",
                "rel": "bookmark"
            }
        ]
    }
}

Consistency groups

Consistency groups enable you to create snapshots at the exact same point in time from multiple volumes. For example, a database might place its tables, logs, and configuration on separate volumes. To restore this database from a previous point in time, it makes sense to restore the logs, tables, and configuration together from the exact same point in time.

Use the policy.json file to grant permissions for these actions to limit roles.

GET
/v2/​{tenant_id}​/consistencygroups
List consistency groups

Lists consistency groups.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

sort_key (Optional) query xsd:string

Sorts by an image attribute. A valid value is name, status, container_format, disk_format, size, id, created_at, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value.

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 page size of items. Returns a number of items up to a 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

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
id plain csapi:UUID

The UUID of the consistency group.

name plain xsd:string

The consistency group name.

{
    "consistencygroups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my-cg1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my-cg2"
        }
    ]
}
POST
/v2/​{tenant_id}​/consistencygroups
Create consistency group

Creates a consistency group.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

name plain xsd:string

The name of the consistency group.

description plain xsd:string

The description of the consistency group.

volume_types plain xsd:list

The list of volume types.

In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type.

For information about how to use volume types to create multiple-storage back ends, see Configure multiple-storage back ends.

user_id plain csapi:UUID

The UUID of the user.

project_id plain csapi:UUID

The UUID of the project.

availability_zone (Optional) plain xsd:string

The name of the availability zone.

status plain xsd:string

The status of the consistency group.

{
    "consistencygroup": {
        "name": "firstcg",
        "description": "first consistency group",
        "volume_types": [
            "type1",
            "type2"
        ],
        "user_id": "6f519a48-3183-46cf-a32f-41815f814546",
        "project_id": "6f519a48-3183-46cf-a32f-41815f815555",
        "availability_zone": "az0",
        "status": "creating"
    }
}
{
    "consistencygroup": {
        "id": "6f519a48-3183-46cf-a32f-41815f816666",
        "name": "firstcg"
    }
}
GET
/v2/​{tenant_id}​/consistencygroups/detail
List consistency groups with details

Lists consistency groups with details.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

sort_key (Optional) query xsd:string

Sorts by an image attribute. A valid value is name, status, container_format, disk_format, size, id, created_at, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value.

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 page size of items. Returns a number of items up to a 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

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
id plain csapi:UUID

The UUID of the consistency group.

status plain xsd:string

The consistency group status. A valid value is creating, available, error, deleting, updating, or invalid.

availability_zone plain xsd:string

The availability zone name.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

name plain xsd:string

The consistency group name.

description plain xsd:string

The consistency group description.

volume_types plain xsd:list

The list of volume type IDs.

id plain csapi:UUID

The UUID of the consistency group.

status plain xsd:string

The consistency group status. A valid value is creating, available, error, deleting, updating, or invalid.

availability_zone plain xsd:string

The availability zone name.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

name plain xsd:string

The consistency group name.

description plain xsd:string

The consistency group description.

volume_types plain xsd:list

The list of volume type IDs.

{
    "consistencygroups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "status": "available",
            "availability_zone": "az1",
            "created_at": "2015-09-16T09:28:52.000000",
            "name": "my-cg1",
            "description": "my first consistency group",
            "volume_types": [
                "123456"
            ]
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "status": "error",
            "availability_zone": "az2",
            "created_at": "2015-09-16T09:31:15.000000",
            "name": "my-cg2",
            "description": "Edited description",
            "volume_types": [
                "234567"
            ]
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<consistencygroups xmlns:consistencygroups="http://docs.openstack.org/volume/ext/consistencygroups/api/v1">
    <consistencygroup
        id="6f519a48-3183-46cf-a32f-41815f813986"
        status="available"
        availability_zone="az1"
        created_at="2015-09-16T09:28:52.000000"
        name="my-cg1"
        description="my first consistency group">
        <volume_types>
            <volume_type>"123456"</volume_type>
        </volume_types>
    </consistencygroup>
    <consistencygroup
        id="aed36625-a6d7-4681-ba59-c7ba3d18c148"
        status="error"
        availability_zone="az2"
        created_at="2015-09-16T09:31:15.000000"
        name="my-cg2"
        description="Edited description">
        <volume_types>
            <volume_type>"234567"</volume_type>
        </volume_types>
    </consistencygroup>
</consistencygroups>
POST
/v2/​{tenant_id}​/consistencygroups/create_from_src
Create consistency group from source

Creates a consistency group from source.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

name plain xsd:string

The name of the consistency group.

description (Optional) plain xsd:string

The description of the consistency group.

cgsnapshot_id (Optional) plain csapi:UUID

The UUID of the consistency group snapshot.

source_cgid (Optional) plain csapi:UUID

The UUID of the source consistency group.

user_id plain csapi:UUID

The UUID of the user.

project_id plain csapi:UUID

The UUID of the project.

status plain xsd:string

The status of the consistency group.

{
    "consistencygroup-from-src": {
        "name": "firstcg",
        "description": "first consistency group",
        "cgsnapshot_id": "6f519a48-3183-46cf-a32f-41815f813986",
        "source_cgid": "6f519a48-3183-46cf-a32f-41815f814546",
        "user_id": "6f519a48-3183-46cf-a32f-41815f815555",
        "project_id": "6f519a48-3183-46cf-a32f-41815f814444",
        "status": "creating"
    }
}
{
    "consistencygroup": {
        "id": "6f519a48-3183-46cf-a32f-41815f816666",
        "name": "firstcg"
    }
}
GET
/v2/​{tenant_id}​/consistencygroups/​{consistencygroup_id}​
Show consistency group details

Shows details for a consistency group.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The UUID of the tenant in a multi-tenancy cloud.

consistencygroup_id URI xsd:string

The ID of the consistency group.

Response parameters
Parameter Style Type Description
id plain csapi:UUID

The UUID of the consistency group.

status plain xsd:string

The consistency group status. A valid value is creating, available, error, deleting, updating, or invalid.

availability_zone plain xsd:string

The availability zone name.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

name plain xsd:string

The consistency group name.

description plain xsd:string

The consistency group description.

volume_types plain xsd:list

The list of volume type IDs.

{
    "consistencygroup": {
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "status": "available",
        "availability_zone": "az1",
        "created_at": "2015-09-16T09:28:52.000000",
        "name": "my-cg1",
        "description": "my first consistency group",
        "volume_types": [
            "123456"
        ]
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<consistencygroups xmlns:consistencygroups="http://docs.openstack.org/volume/ext/consistencygroups/api/v1">
    <consistencygroup
        id="6f519a48-3183-46cf-a32f-41815f813986"
        status="available"
        availability_zone="az1"
        created_at="2015-09-16T09:28:52.000000"
        name="my-cg1"
        description="my first consistency group">
        <volume_types>
            <volume_type>"123456"</volume_type>
        </volume_types>
    </consistencygroup>
</consistencygroups>

This operation does not accept a request body.

POST
/v2/​{tenant_id}​/consistencygroups/​{consistencygroup_id}​/delete
Delete consistency group

Deletes a consistency group.