Block Storage API V2 (DEPRECATED)¶

GET

List Api Versions

Lists information for all Block Storage API versions.

Normal response codes: 200,300

Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400), unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404)

Request¶

Response¶

Example List Api Versions: JSON request

{
    "versions": [
        {
            "status": "SUPPORTED",
            "updated": "2014-06-28T12:20:21Z",
            "links": [
                {
                    "href": "https://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": "https://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"
        }
    ]
}

Limits (limits)¶

Shows absolute limits for a project.

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

GET

/v2/{project_id}/limits

Show absolute limits

Shows absolute limits for a project.

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

Normal response codes: 200

Error response codes: forbidden(403)

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.

Response Parameters¶

Name	In	Type	Description
totalSnapshotsUsed	body	integer	The total number of snapshots used.
maxTotalBackups	body	integer	The maximum number of backups.
maxTotalVolumeGigabytes	body	integer	The maximum total amount of volumes, in gibibytes (GiB).
limits	body	object	A list of `limit` objects.
maxTotalSnapshots	body	integer	The maximum number of snapshots.
maxTotalBackupGigabytes	body	integer	The maximum total amount of backups, in gibibytes (GiB).
totalBackupGigabytesUsed	body	integer	The total number of backups gibibytes (GiB) used.
maxTotalVolumes	body	integer	The maximum number of volumes.
totalVolumesUsed	body	integer	The total number of volumes used.
rate	body	array	Rate-limit volume copy bandwidth, used to mitigate slow down of data access from the instances.
totalBackupsUsed	body	integer	The total number of backups used.
totalGigabytesUsed	body	integer	The total number of gibibytes (GiB) used.
absolute	body	object	An `absolute` limits object.

Response Example¶

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

Quota sets extension (os-quota-sets)¶

Administrators only, depending on policy settings.

Shows, updates, and deletes quotas for a project.

GET

/v2/{admin_project_id}/os-quota-sets/{project_id}

Show quotas

Shows quotas for a project.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
admin_project_id	path	string	The UUID of the administrative project.
usage (Optional)	query	boolean	Set to `usage=true` to show quota usage. Default is `false`.

Response Parameters¶

Name	In	Type	Description
injected_file_content_bytes	body	integer	The number of bytes of content that are allowed for each injected file.
metadata_items	body	integer	The number of metadata items that are allowed for each instance.
reserved (Optional)	body	integer	Reserved volume size. Visible only if you set the `usage=true` query parameter.
in_use (Optional)	body	string	The in use data size. Visible only if you set the `usage=true` query parameter.
ram	body	integer	The amount of instance RAM in megabytes that are allowed for each project.
floating_ips	body	integer	The number of floating IP addresses that are allowed for each project.
key_pairs	body	integer	The number of key pairs that are allowed for each user.
injected_file_path_bytes	body	integer	The number of bytes that are allowed for each injected file path.
instances	body	integer	The number of instances that are allowed for each project.
security_group_rules (Optional)	body	integer	The number of rules that are allowed for each security group.
injected_files	body	integer	The number of injected files that are allowed for each project.
quota_set	body	object	A `quota_set` object.
cores	body	integer	The number of instance cores that are allowed for each project.
fixed_ips	body	integer	The number of fixed IP addresses that are allowed for each project. Must be equal to or greater than the number of allowed instances.
id	body	string	The UUID of the project.
security_groups	body	integer	The number of security groups that are allowed for each project.

Response Example¶

{
    "quota_set": {
        "gigabytes": 5,
        "snapshots": 10,
        "volumes": 20
    }
}

GET

/v2/{admin_project_id}/os-quota-sets/{project_id}/defaults

Get default quotas

Gets default quotas for a project.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
admin_project_id	path	string	The UUID of the administrative project.

Response Parameters¶

Name	In	Type	Description
injected_file_content_bytes	body	integer	The number of bytes of content that are allowed for each injected file.
metadata_items	body	integer	The number of metadata items that are allowed for each instance.
reserved (Optional)	body	integer	Reserved volume size. Visible only if you set the `usage=true` query parameter.
in_use (Optional)	body	string	The in use data size. Visible only if you set the `usage=true` query parameter.
ram	body	integer	The amount of instance RAM in megabytes that are allowed for each project.
floating_ips	body	integer	The number of floating IP addresses that are allowed for each project.
key_pairs	body	integer	The number of key pairs that are allowed for each user.
injected_file_path_bytes	body	integer	The number of bytes that are allowed for each injected file path.
instances	body	integer	The number of instances that are allowed for each project.
security_group_rules (Optional)	body	integer	The number of rules that are allowed for each security group.
injected_files	body	integer	The number of injected files that are allowed for each project.
quota_set	body	object	A `quota_set` object.
cores	body	integer	The number of instance cores that are allowed for each project.
fixed_ips	body	integer	The number of fixed IP addresses that are allowed for each project. Must be equal to or greater than the number of allowed instances.
id	body	string	The UUID of the project.
security_groups	body	integer	The number of security groups that are allowed for each project.

Response Example¶

{
    "quota_set": {
        "gigabytes": 5,
        "snapshots": 10,
        "volumes": 20
    }
}

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.

GET

/v2/{project_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¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_type	path	string	The ID of Volume Type to be accessed by project.

Response Parameters¶

Name	In	Type	Description
project_id	body	string	The UUID of the project.

Response Example¶

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

API extensions (extensions)¶

GET

/v2/{project_id}/extensions

List API extensions

Lists Block Storage API extensions.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.

Response Parameters¶

Name	In	Type	Description
updated	body	string	The date and time stamp when the extension was last updated.
description (Optional)	body	string	The backup description or null.
links	body	array	Links for the volume transfer.
namespace	body	string	Link associated to the extension.
alias	body	string	The alias for the extension. For example, "FOXNSOX", "os- availability-zone", "os-extended-quotas", "os- share-unmanage" or "os-used-limits."
name	body	string	The name of the Volume Transfer.

Response Example¶

{
    "extensions": [
        {
            "updated": "2013-04-18T00:00:00+00:00",
            "name": "SchedulerHints",
            "links": [],
            "namespace": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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 API."
        },
        {
            "updated": "2014-01-10T00:00:00-00:00",
            "name": "ExtendedServices",
            "links": [],
            "namespace": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://docs.openstack.org/volume/ext/services/api/v2",
            "alias": "os-services",
            "description": "Services support."
        }
    ]
}

Volume types (types)¶

GET

/v2/{project_id}/types/{volume_type_id}

Show volume type details for v2

Shows details for a volume type.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_type_id	path	string	The UUID for an existing volume type.

Response Parameters¶

Name	In	Type	Description
volume_type	body	object	A `volume_type` object.
is_public	body	boolean	Whether the volume type is publicly visible.
extra_specs (Optional)	body	object	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.
description	body	string	The volume type description.
name	body	string	The name of the volume type.
id	body	string	The UUID of the volume type.
os-volume-type-access:is_public	body	boolean	Whether the volume type is publicly visible.
qos_specs_id (Optional)	body	string	The QoS specifications ID.

Response Example¶

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "description": "volume type 001",
        "is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
        "qos_specs_id": null,
        "os-volume-type-access:is_public": true
    }
}

GET

/v2/{project_id}/types

List all volume types for v2

Lists volume types.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
sort_key (Optional)	query	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	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	integer	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.
offset (Optional)	query	integer	Used in conjunction with `limit` to return a slice of items. `offset` is where to start in the list.
marker (Optional)	query	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¶

Name	In	Type	Description
volume_types	body	array	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.
extra_specs	body	object	A set of key and value pairs that contains the specifications for a volume type.
name	body	string	The name of the Volume Transfer.
volume_type (Optional)	path	string	The ID of Volume Type to be accessed by project.

Response Example¶

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

API versions¶

GET

/v2/

Show API v2 details

Shows details for Block Storage API v2.

Normal response codes: 200

Request¶

Response Parameters¶

Name	In	Type	Description
location	body	string	Full URL to a service or server.

Response Example¶

{
    "versions": [
        {
            "status": "DEPRECATED",
            "updated": "2017-02-25T12:00:00Z",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.volume+json;version=2"
                }
            ],
            "id": "v2.0",
            "links": [
                {
                    "href": "https://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://23.253.248.171:8776/v2/",
                    "rel": "self"
                }
            ],
            "min_version": "",
            "version": ""
        }
    ]
}

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/{project_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¶

Name	In	Type	Description
os-extend	body	object	The `os-extend` action.
new_size	body	integer	The new size of the volume, in gibibytes (GiB).
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.

Request Example¶

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

POST

/v2/{project_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¶

Name	In	Type	Description
instance_uuid (Optional)	body	string	The UUID of the attaching instance.
mountpoint	body	string	The attaching mount point.
host_name (Optional)	body	string	The name of the attaching host.
os-attach	body	object	The `os-attach` action.
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.

Request Example¶

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

POST

/v2/{project_id}/volumes/{volume_id}/action

Detach volume from a server

Detaches a volume from a server. Specify the os-detach action in the request body.

Preconditions

Volume status must be in-use.

Normal response codes: 202

Request¶

Name	In	Type	Description
attachment_id (Optional)	body	string	The interface ID.
os-detach	body	object	The `os-detach` action.
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.

Request Example¶

{
    "os-detach": {
        "attachment_id": "d8777f54-84cf-4809-a679-468ffed56cf1"
    }
}

POST

/v2/{project_id}/volumes/{volume_id}/action

Update volume bootable status

Update the bootable status for a volume, mark it as a bootable volume. Specify the os-set_bootable action in the request body.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.
os-set_bootable	body	object	The `os-set_bootable` action.
bootable	body	boolean	Enables or disables the bootable attribute. You can boot an instance from a bootable volume.

Request Example¶

{
    "os-set_bootable": {
        "bootable": "True"
    }
}

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.
detaching	The volume is detaching from an instance.
in-use	The volume is attached to an instance.
maintenance	The volume is locked and being migrated.
deleting	The volume is being deleted.
awaiting-transfer	The volume is awaiting for transfer.
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_backing-up	A backup error occurred.
error_restoring	A backup restoration error occurred.
error_extending	An error occurred while attempting to extend a volume.
downloading	The volume is downloading an image.
uploading	The volume is being uploaded to an image.
retyping	The volume is changing type to another volume type.
extending	The volume is being extended.

GET

/v2/{project_id}/volumes/detail

List volumes with details

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

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
all_tenants (Optional)	query	string	Shows details for all projects. Admin only.
sort (Optional)	query	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	integer	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.
offset (Optional)	query	integer	Used in conjunction with `limit` to return a slice of items. `offset` is where to start in the list.
marker (Optional)	query	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¶

Name	In	Type	Description
migration_status	body	string	The volume migration status.
attachments	body	array	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	body	array	Links for the volume transfer.
availability_zone (Optional)	body	string	The name of the availability zone.
os-vol-host-attr:host	body	string	Current back-end of the volume. Host format is `host@backend#pool`.
encrypted	body	boolean	If true, this volume is encrypted.
updated_at	body	string	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)	body	string	The volume replication status managed by the driver of backend storage.
replication_status	body	string	The volume replication status.
snapshot_id (Optional)	body	string	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.
id	body	string	The UUID of the volume transfer.
size	body	integer	The size of the volume, in gibibytes (GiB).
user_id	body	string	The UUID of the user.
os-vol-tenant-attr:tenant_id	body	string	The project ID which the volume belongs to.
os-vol-mig-status-attr:migstat	body	string	The status of this volume migration (None means that a migration is not currently in progress).
metadata	body	object	One or more metadata key and value pairs for the snapshot, if any.
status	body	string	The volume status.
volume_image_metadata (Optional)	body	object	List of image metadata entries. Only included for volumes that were created from an image, or from a snapshot of a volume originally created from an image.
description (Optional)	body	string	The backup description or null.
multiattach	body	boolean	If true, this volume can attach to more than one instance.
source_volid (Optional)	body	string	The UUID of the source volume. The API creates a new volume with the same size as the source volume.
consistencygroup_id	body	string	The UUID of the consistency group.
os-vol-mig-status-attr:name_id	body	string	The volume ID that this volume name on the back- end is based on.
name	body	string	The name of the Volume Transfer.
bootable	body	string	Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at	body	string	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.
os-volume-replication:driver_data (Optional)	body	string	The name of the volume replication driver.
volumes	body	array	A list of `volume` objects.
volume_type (Optional)	path	string	The ID of Volume Type to be accessed by project.

Response Example¶

{
    "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"
        }
    ]
}

POST

/v2/{project_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¶

Name	In	Type	Description
size	body	integer	The size of the volume, in gibibytes (GiB).
description	body	string	The volume description.
imageRef (Optional)	body	string	The UUID of the image from which you want to create the volume. Required to create a bootable volume.
multiattach (Optional)	body	boolean	To enable this volume to attach to more than one server, set this value to `true`. Default is `false`. Note that support for multiattach volumes depends on the volume type being used.
availability_zone (Optional)	body	string	The name of the availability zone.
source_volid (Optional)	body	string	The UUID of the source volume. The API creates a new volume with the same size as the source volume.
name	body	string	The volume name.
volume	body	object	A `volume` object.
consistencygroup_id (Optional)	body	string	The UUID of the consistency group.
volume_type (Optional)	body	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.
snapshot_id (Optional)	body	string	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.
OS-SCH-HNT:scheduler_hints (Optional)	body	object	The dictionary of data to send to the scheduler.
source_replica (Optional)	body	string	The UUID of the replication volume to clone. This was for legacy replication functionality and is no longer supported.
metadata (Optional)	body	object	One or more metadata key and value pairs that are associated with the volume.
project_id	path	string	The UUID of the project in a multi-tenancy cloud.

Request Example¶

{
    "volume": {
        "size": 10,
        "availability_zone": null,
        "source_volid": null,
        "description": null,
        "multiattach": false,
        "snapshot_id": null,
        "name": null,
        "imageRef": null,
        "volume_type": null,
        "metadata": {},
        "consistencygroup_id": null
    },
    "OS-SCH-HNT:scheduler_hints": {
        "same_host": [
            "a0cf03a5-d921-4877-bb5c-86d26cf818e1",
            "8c19174f-4220-44f0-824a-cd1eeef10287"
        ]
    }
}

Response Parameters¶

Name	In	Type	Description
migration_status	body	string	The volume migration status.
attachments	body	array	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	body	array	Links for the volume transfer.
availability_zone (Optional)	body	string	The name of the availability zone.
encrypted	body	boolean	If true, this volume is encrypted.
updated_at	body	string	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`.
replication_status	body	string	The volume replication status.
snapshot_id (Optional)	body	string	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.
id	body	string	The UUID of the volume transfer.
size	body	integer	The size of the volume, in gibibytes (GiB).
user_id	body	string	The UUID of the user.
metadata	body	object	One or more metadata key and value pairs for the snapshot, if any.
status	body	string	The volume status.
description (Optional)	body	string	The backup description or null.
multiattach	body	boolean	If true, this volume can attach to more than one instance.
source_volid (Optional)	body	string	The UUID of the source volume. The API creates a new volume with the same size as the source volume.
volume	body	object	A `volume` object.
consistencygroup_id	body	string	The UUID of the consistency group.
name	body	string	The name of the Volume Transfer.
bootable	body	string	Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at	body	string	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 (Optional)	path	string	The ID of Volume Type to be accessed by project.

Response Example¶

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

GET

/v2/{project_id}/volumes

List volumes

Lists summary information for all Block Storage volumes that the project can access.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
all_tenants (Optional)	query	string	Shows details for all projects. Admin only.
sort (Optional)	query	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	integer	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.
offset (Optional)	query	integer	Used in conjunction with `limit` to return a slice of items. `offset` is where to start in the list.
marker (Optional)	query	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¶

Name	In	Type	Description
volumes	body	array	A list of `volume` objects.
id	body	string	The UUID of the volume transfer.
links	body	array	Links for the volume transfer.
name	body	string	The name of the Volume Transfer.

Response Example¶

{
    "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"
        }
    ]
}

GET

/v2/{project_id}/volumes/{volume_id}

Show volume details

Shows details for a volume.

Preconditions

The volume must exist.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.

Response Parameters¶

Name	In	Type	Description
migration_status	body	string	The volume migration status.
attachments	body	array	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	body	array	Links for the volume transfer.
availability_zone (Optional)	body	string	The name of the availability zone.
os-vol-host-attr:host	body	string	Current back-end of the volume. Host format is `host@backend#pool`.
encrypted	body	boolean	If true, this volume is encrypted.
updated_at	body	string	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)	body	string	The volume replication status managed by the driver of backend storage.
replication_status	body	string	The volume replication status.
snapshot_id (Optional)	body	string	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.
id	body	string	The UUID of the volume transfer.
size	body	integer	The size of the volume, in gibibytes (GiB).
user_id	body	string	The UUID of the user.
os-vol-tenant-attr:tenant_id	body	string	The project ID which the volume belongs to.
os-vol-mig-status-attr:migstat	body	string	The status of this volume migration (None means that a migration is not currently in progress).
metadata	body	object	One or more metadata key and value pairs for the snapshot, if any.
status	body	string	The volume status.
volume_image_metadata (Optional)	body	object	List of image metadata entries. Only included for volumes that were created from an image, or from a snapshot of a volume originally created from an image.
description (Optional)	body	string	The backup description or null.
multiattach	body	boolean	If true, this volume can attach to more than one instance.
source_volid (Optional)	body	string	The UUID of the source volume. The API creates a new volume with the same size as the source volume.
volume	body	object	A `volume` object.
consistencygroup_id	body	string	The UUID of the consistency group.
os-vol-mig-status-attr:name_id	body	string	The volume ID that this volume name on the back- end is based on.
name	body	string	The name of the Volume Transfer.
bootable	body	string	Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at	body	string	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.
os-volume-replication:driver_data (Optional)	body	string	The name of the volume replication driver.
volume_type (Optional)	path	string	The ID of Volume Type to be accessed by project.

Response Example¶

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

PUT

/v2/{project_id}/volumes/{volume_id}

Update volume

Updates a volume.

Normal response codes: 200

Request¶

Name	In	Type	Description
volume	body	object	A `volume` object.
description (Optional)	body	string	The backup description or null.
name	body	string	The name of the Volume Transfer.
metadata (Optional)	body	object	One or more metadata key and value pairs that are associated with the volume.
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.

Request Example¶

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

Response Parameters¶

Name	In	Type	Description
migration_status	body	string	The volume migration status.
attachments	body	array	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	body	array	Links for the volume transfer.
availability_zone (Optional)	body	string	The name of the availability zone.
encrypted	body	boolean	If true, this volume is encrypted.
updated_at	body	string	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`.
replication_status	body	string	The volume replication status.
snapshot_id (Optional)	body	string	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.
id	body	string	The UUID of the volume transfer.
size	body	integer	The size of the volume, in gibibytes (GiB).
user_id	body	string	The UUID of the user.
metadata	body	object	One or more metadata key and value pairs that are associated with the volume.
status	body	string	The volume status.
description (Optional)	body	string	The backup description or null.
multiattach	body	boolean	If true, this volume can attach to more than one instance.
source_volid (Optional)	body	string	The UUID of the source volume. The API creates a new volume with the same size as the source volume.
volume	body	object	A `volume` object.
consistencygroup_id	body	string	The UUID of the consistency group.
name	body	string	The name of the Volume Transfer.
bootable	body	string	Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at	body	string	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 (Optional)	path	string	The ID of Volume Type to be accessed by project.

Response Example¶

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

DELETE

/v2/{project_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¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.
cascade (Optional)	path	boolean	Remove any snapshots along with the volume. Default=False.

POST

/v2/{project_id}/volumes/{volume_id}/metadata

Create volume metadata

Creates or replaces metadata for a volume. Does not modify items that are not in the request.

Normal response codes: 202

Request¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs that are associated with the volume.
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.

Request Example¶

{
    "metadata": {
        "name": "metadata0"
    }
}

Response Parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs that are associated with the volume.

Response Example¶

{
    "metadata": {
        "name": "metadata0"
    }
}

GET

/v2/{project_id}/volumes/{volume_id}/metadata

Show volume metadata

Shows metadata for a volume.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.

Response Parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs that are associated with the volume.

Response Example¶

{
    "metadata": {}
}

PUT

/v2/{project_id}/volumes/{volume_id}/metadata

Update volume metadata

Replaces all the volume's metadata with the key-value pairs in the request.

Normal response codes: 200

Request¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs that are associated with the volume.
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.

Request Example¶

{
    "metadata": {
        "name": "metadata1"
    }
}

Response Parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs that are associated with the volume.

Response Example¶

{
    "metadata": {
        "name": "metadata1"
    }
}

GET

/v2/{project_id}/volumes/{volume_id}/metadata/{key}

Show volume metadata for a specific key

Shows metadata for a volume for a specific key.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.
key	path	string	The metadata key name for the metadata that you want to see.

Response Parameters¶

Name	In	Type	Description
metadata	body	object	One or more metadata key and value pairs that are associated with the volume.

Response Example¶

{
    "metadata": {}
}

DELETE

/v2/{project_id}/volumes/{volume_id}/metadata/{key}

Delete volume metadata

Deletes metadata for a volume.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.
key	path	string	The metadata key name for the metadata that you want to remove.

PUT

/v2/{project_id}/volumes/{volume_id}/metadata/{key}

Update volume metadata for a specific key

Update metadata for a volume for a specific key.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The UUID of the project in a multi-tenancy cloud.
volume_id	path	string	The UUID of the volume.
key	path	string	The metadata key name for the metadata that you want to update.
meta	body	object	The metadata key and value pair for the volume.

Request Example¶

{
  "meta": {
    "name": "new_name"
  }
}

Response Parameters¶

Name	In	Type	Description
meta	body	object	The metadata key and value pair for the volume.

Response Example¶

{
  "meta": {
    "name": "new_name"
  }
}

3.2. Virtual Server (Cinder)

Block Storage API V3 (CURRENT)