Block Storage API V3 (CURRENT)¶
Lists information for all Block Storage API versions.
Normal response codes: 300
Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400), unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404), conflict(409)
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=2"
}
],
"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=3"
}
],
"id": "v3.0"
}
]
}
API versions¶
Shows details for Block Storage API v3.
Normal response codes: 200
Error response codes: 403
Request¶
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
location |
body |
string |
Full URL to a service or server. |
Response Example¶
{
"versions": [
{
"id": "v2.0",
"links": [
{
"href": "https://docs.openstack.org/",
"rel": "describedby",
"type": "text/html"
},
{
"href": "http://23.253.248.171:8776/v2/",
"rel": "self"
}
],
"media-types": [
{
"base": "application/json",
"type": "application/vnd.openstack.volume+json;version=1"
}
],
"min_version": "",
"status": "SUPPORTED",
"updated": "2014-06-28T12:20:21Z",
"version": ""
},
{
"id": "v3.0",
"links": [
{
"href": "https://docs.openstack.org/",
"rel": "describedby",
"type": "text/html"
},
{
"href": "http://23.253.248.171:8776/v3/",
"rel": "self"
}
],
"media-types": [
{
"base": "application/json",
"type": "application/vnd.openstack.volume+json;version=1"
}
],
"min_version": "3.0",
"status": "CURRENT",
"updated": "2016-02-08T12:20:21Z",
"version": "3.0"
}
]
}
API extensions (extensions)¶
Lists Block Storage API extensions.
Normal response codes: 200
Error response codes: 300
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 |
body |
string |
The extension description. |
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/v3",
"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/v3",
"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/v3",
"alias": "os-services",
"description": "Services support."
}
]
}
Volume types (types)¶
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.
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 |
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
}
}
Shows details for the default volume type if configured.
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 |
|---|---|---|---|
volume_type |
body |
object |
A |
is_public |
body |
boolean |
Whether the volume type is publicly visible. |
extra_specs |
body |
object |
A set of key and value pairs that contains the specifications for a volume type. |
description |
body |
string |
The volume type description. |
name |
body |
string |
The name of the volume type. |
Response Example¶
{
"volume_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "volume-type-test",
"description": "default volume type",
"is_public": true,
"extra_specs": {
"volume_backend_name": "rbd"
}
}
}
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 (Optional) |
query |
string |
Comma-separated list of sort keys and optional
sort directions in the form of < key > [: < direction > ]. A valid
direction is |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
offset (Optional) |
query |
integer |
Used in conjunction with |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
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 type. |
Response Example¶
{
"volume_types": [
{
"name": "SSD",
"qos_specs_id": null,
"extra_specs": {
"volume_backend_name": "lvmdriver-1"
},
"os-volume-type-access:is_public": true,
"is_public": true,
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"description": null
},
{
"name": "SATA",
"qos_specs_id": null,
"extra_specs": {
"volume_backend_name": "lvmdriver-1"
},
"os-volume-type-access:is_public": true,
"is_public": true,
"id": "8eb69a46-df97-4e41-9586-9a40a7533803",
"description": null
}
]
}
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.
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"
}
}
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. |
reserved |
The volume is reserved for attaching or shelved. |
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. |
Lists all Block Storage volumes, with details, that the project can access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.
Normal response codes: 200
Error response codes: badRequest(400)
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 project. 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 |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
offset (Optional) |
query |
integer |
Used in conjunction with |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
with_count (Optional) |
query |
boolean |
Whether to show New in version 3.45 |
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 |
The volume links. |
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 |
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, The If the |
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. |
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 |
body |
string |
The volume description. |
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 volume name. |
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, The |
os-volume-replication:driver_data (Optional) |
body |
string |
The name of the volume replication driver. |
volumes |
body |
array |
A list of |
volume_type |
body |
string |
The associated volume type for the volume. |
count (Optional) |
body |
integer |
The total count of requested resource before pagination is applied. New in version 3.45 |
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/v3/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/v3/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"
}
],
"count": 10
}
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
availablethrough 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
creatingor 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 |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume |
body |
object |
A |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
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. |
description (Optional) |
body |
string |
The volume description. |
multiattach (Optional) |
body |
boolean |
To enable this volume to attach to more than one
server, set this value to |
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. |
backup_id (Optional) |
body |
string |
The UUID of the backup. New in version 3.46 |
name |
body |
string |
The volume name. |
imageRef (Optional) |
body |
string |
The UUID of the image from which you want to create the volume. Required to create a bootable volume. |
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 |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
OS-SCH-HNT:scheduler_hints (Optional) |
body |
object |
The dictionary of data to send to the scheduler. |
Request Example¶
{
"volume": {
"size": 10,
"availability_zone": null,
"source_volid": null,
"description": null,
"multiattach": false,
"snapshot_id": null,
"backup_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 |
The volume links. |
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, The If the |
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. |
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 |
body |
string |
The volume description. |
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 |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
name |
body |
string |
The volume name. |
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, The |
volume_type |
body |
string |
The associated volume type for the volume. |
Response Example¶
{
"volume": {
"status": "creating",
"migration_status": null,
"user_id": "0eea4eabcf184061a3b6db1e0daaf010",
"attachments": [],
"links": [
{
"href": "http://23.253.248.171:8776/v3/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
}
}
Lists summary information for all Block Storage volumes that the project can access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.
Normal response codes: 200
Error response codes: badRequest(400)
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 project. 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 |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
offset (Optional) |
query |
integer |
Used in conjunction with |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
with_count (Optional) |
query |
boolean |
Whether to show New in version 3.45 |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
volumes |
body |
array |
A list of |
id |
body |
string |
The UUID of the volume. |
links |
body |
array |
The volume links. |
name |
body |
string |
The volume name. |
count (Optional) |
body |
integer |
The total count of requested resource before pagination is applied. New in version 3.45 |
Response Example¶
{
"volumes": [
{
"id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
"links": [
{
"href": "http://localhost:8776/v3/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/v3/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"
}
],
"count": 10
}
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 |
The volume links. |
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 |
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, The If the |
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. |
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 |
body |
string |
The volume description. |
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 |
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 volume name. |
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, The |
os-volume-replication:driver_data (Optional) |
body |
string |
The name of the volume replication driver. |
volume_type |
body |
string |
The associated volume type for the volume. |
service_uuid |
body |
string |
A unique identifier that's used to indicate what node the volume-service for a particular volume is being serviced by. |
shared_targets |
body |
boolean |
An indicator whether the back-end hosting the volume utilizes shared_targets or not. Default=True. |
Response Example¶
{
"volume": {
"status": "available",
"attachments": [],
"links": [
{
"href": "http://localhost:8776/v3/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"
}
}
}
Updates 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. |
volume |
body |
object |
A |
description (Optional) |
body |
string |
The volume description. |
name (Optional) |
body |
string |
The volume name. |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
Request Example¶
{
"volume": {
"name": "vol-003",
"description": "This is yet, another volume.",
"metadata": {
"name": "metadata0"
}
}
}
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 |
The volume links. |
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, The If the |
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. |
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 |
body |
string |
The volume description. |
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 |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
name |
body |
string |
The volume name. |
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, The |
volume_type |
body |
string |
The associated volume type for the volume. |
Response Example¶
{
"volume": {
"status": "available",
"migration_status": null,
"user_id": "0eea4eabcf184061a3b6db1e0daaf010",
"attachments": [],
"links": [
{
"href": "http://localhost:8776/v3/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
}
}
Deletes a volume.
Preconditions
Volume status must be
available,in-use,error, orerror_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
deletingor becomeserror_deletingthe 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. |
force (Optional) |
path |
boolean |
Indicates whether to force delete a volume even if
the volume is in deleting or error_deleting. Default is New in version 3.23 |
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 |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume_id |
path |
string |
The UUID of the volume. |
metadata |
body |
object |
One or more metadata key and value pairs that are associated with 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"
}
}
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": {}
}
Replaces all the volume's metadata with the key-value pairs in the request.
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. |
metadata |
body |
object |
One or more metadata key and value pairs that are associated with 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"
}
}
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 |
|---|---|---|---|
meta |
body |
object |
The metadata key and value pair for the volume. |
Response Example¶
{
"meta": {
"name": "test"
}
}
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. |
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"
}
}
Display volumes summary with total number of volumes and total size in GB
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 project. Admin only. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
volume-summary |
body |
object |
Dictionary of |
total_size |
body |
integer |
Total size of volumes in GB. |
total_count |
body |
integer |
Total number of volumes. |
metadata |
body |
object |
The dictionary of lists contains all the volumes' metadata, classified by metadata key. New in version 3.36 |
Response Example¶
{
"volume-summary": {
"total_size": 4,
"total_count": 4,
"metadata": {
"key1": ["value1", "value2"],
"key2": ["value2"]
}
}
}
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.
Extends the size of a volume to a requested size, in gibibytes (GiB).
Specify the os-extend action in the request body.
Preconditions
Prior to microversion
3.42the volume status must beavailable. Starting with microversion3.42, attached volumes with statusin-usemay be able to be extended depending on policy and backend volume and compute driver constraints in the cloud. Note thatreservedis not a valid state for extend.Sufficient amount of storage must exist to extend the volume.
The user quota must have sufficient volume storage.
Postconditions
If the request is processed successfully, the volume status will change to
extendingwhile the volume size is being extended.Upon successful completion of the extend operation, the volume status will go back to its original value.
Starting with microversion
3.42, when extending the size of an attached volume, the Block Storage service will notify the Compute service that an attached volume has been extended. The Compute service will asynchronously process the volume size change for the related server instance. This can be monitored using theGET /servers/{server_id}/os-instance-actionsAPI in the Compute service.
Troubleshooting
An
error_extendingvolume 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 |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume_id |
path |
string |
The UUID of the volume. |
os-extend |
body |
object |
The |
new_size |
body |
integer |
The new size of the volume, in gibibytes (GiB). 注釈 Some volume backends require the storage to be in some multiple value rather than incremental. For example, the EMC ScaleIO backend requires storage in multiples of 8GB. There is a known limitation such that a request to extend the size of a volume for these backends will be rounded up to the nearest multiple but the actual physical size of the storage will not be reflected back in the API for the volume size. For example, a request to extend the size of an 8GB ScaleIO-backed volume to 9GB will actually result in 16GB of physical storage but only 9GB will be reflected in the API and counted for quota usage. |
Request Example¶
{
"os-extend": {
"new_size": 3
}
}
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_uuidorhost_name.
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. |
os-attach |
body |
object |
The |
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. |
Request Example¶
{
"os-attach": {
"instance_uuid": "95D9EF50-507D-11E5-B970-0800200C9A66",
"mountpoint": "/dev/vdc"
}
}
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 |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume_id |
path |
string |
The UUID of the volume. |
os-detach |
body |
object |
The |
attachment_id (Optional) |
body |
string |
The ID of the attachment. |
Request Example¶
{
"os-detach": {
"attachment_id": "d8777f54-84cf-4809-a679-468ffed56cf1"
}
}
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 |
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"
}
}
Uploads the specified volume to image service.
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. |
os-volume_upload_image |
body |
object |
The |
image_name |
body |
string |
The name for the new image. |
force (Optional) |
body |
boolean |
Enables or disables upload of a volume that is attached to an instance. Default=False. |
disk_format (Optional) |
body |
string |
Disk format for the new image. Default is raw. |
container_format (Optional) |
body |
string |
Container format for the new image. Default is bare. |
visibility (Optional) |
body |
string |
The visibility property of the new image. Default is private. |
protected (Optional) |
body |
boolean |
Whether the new image is protected. Default=False. |
Request Example¶
{
"os-volume_upload_image":{
"image_name": "test",
"force": false,
"disk_format": "raw",
"container_format": "bare",
"visibility": "private",
"protected": false
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
os-volume_upload_image |
body |
object |
The |
status |
body |
string |
The volume status. |
image_name |
body |
string |
The name for the new image. |
disk_format (Optional) |
body |
string |
Disk format for the new image. Default is raw. |
container_format (Optional) |
body |
string |
Container format for the new image. Default is bare. |
visibility (Optional) |
body |
string |
The visibility property of the new image. Default is private. |
protected (Optional) |
body |
boolean |
Whether the new image is protected. Default=False. |
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, The If the |
image_id |
body |
string |
The uuid for the new image. |
display_description |
body |
string |
The volume description. |
id |
body |
string |
The UUID of the volume. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
volume_type |
body |
string |
The associated volume type for the volume. |
Response Example¶
{
"os-volume_upload_image": {
"status": "uploading",
"container_format": "bare",
"image_name": "test",
"visibility": "private",
"updated_at": "2017-06-05T08:44:28.000000",
"image_id": "de75b74e-7f0d-4b59-a263-bd87bfc313bd",
"display_description": null,
"id": "3a81fdac-e8ae-4e61-b6a2-2e14ff316f19",
"size": 1,
"disk_format": "raw",
"volume_type": null,
"protected": false
}
}
Attachments¶
Lists all, lists all with details, shows details for, creates, and deletes attachment.
注釈
Everything except for Complete attachment is new as of the 3.27 microversion. Complete attachment is new as of the 3.44 microversion.
Deletes an attachment.
Available starting in the 3.27 microversion.
Normal response codes: 200
Error response codes: badRequest(400), itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
attachment_id |
path |
string |
The ID of the attachment. |
Shows details for an attachment.
Available starting in the 3.27 microversion.
Normal response codes: 200
Error response codes: badRequest(400), itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
attachment_id |
path |
string |
The ID of the attachment. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
status |
body |
string |
The status of the attachment. |
detached_at (Optional) |
body |
string |
The time when attachment is detached. |
connection_info |
body |
object |
The connection info used for server to connect the volume. |
attached_at (Optional) |
body |
string |
The time when attachment is attached. |
attach_mode (Optional) |
body |
string |
The attach mode of attachment, read-only ('ro') or read-and-write ('rw'), default is 'ro'. |
instance (Optional) |
body |
string |
The UUID of the attaching instance. |
volume_id |
body |
string |
The UUID of the volume which the attachment belongs to. |
id |
body |
string |
The ID of attachment. |
Response Example¶
{
"attachment": {
"status": "attaching",
"detached_at": "2015-09-16T09:28:52.000000",
"connection_info": {},
"attached_at": "2015-09-16T09:28:52.000000",
"attach_mode": "ro",
"instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
"volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
"id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
}
}
Lists all attachments with details. Since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.
Available starting in the 3.27 microversion.
Normal response codes: 200
Error response codes: badRequest(400)
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 project. 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 |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
offset (Optional) |
query |
integer |
Used in conjunction with |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
status |
body |
string |
The status of the attachment. |
detached_at (Optional) |
body |
string |
The time when attachment is detached. |
connection_info |
body |
object |
The connection info used for server to connect the volume. |
attached_at (Optional) |
body |
string |
The time when attachment is attached. |
attach_mode (Optional) |
body |
string |
The attach mode of attachment, read-only ('ro') or read-and-write ('rw'), default is 'ro'. |
instance (Optional) |
body |
string |
The UUID of the attaching instance. |
volume_id |
body |
string |
The UUID of the volume which the attachment belongs to. |
id |
body |
string |
The ID of attachment. |
Response Example¶
{
"attachments": [
{
"status": "attaching",
"detached_at": "2015-09-16T09:28:52.000000",
"connection_info": {},
"attached_at": "2015-09-16T09:28:52.000000",
"attach_mode": "ro",
"instance": "31c79baf-b59e-469c-979f-1df4ecb6eea7",
"volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
"id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
}
]
}
Lists all attachments, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.
Available starting in the 3.27 microversion.
Normal response codes: 200
Error response codes: badRequest(400)
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 project. 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 |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
offset (Optional) |
query |
integer |
Used in conjunction with |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
status |
body |
string |
The status of the attachment. |
instance (Optional) |
body |
string |
The UUID of the attaching instance. |
volume_id |
body |
string |
The UUID of the volume which the attachment belongs to. |
id |
body |
string |
The ID of attachment. |
Response Example¶
{
"attachments": [
{
"status": "attaching",
"instance": "31c79baf-b59e-469c-979f-1df4ecb6eea7",
"id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c",
"volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d"
}
]
}
Creates an attachment.
Available starting in the 3.27 microversion.
Normal response codes: 200
Error response codes: badRequest(400), itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
attachment |
body |
object |
An attachment object. |
instance_uuid |
body |
string |
The UUID of the attaching instance. |
connector (Optional) |
body |
object |
The |
volume_uuid |
body |
string |
The UUID of the volume which the attachment belongs to. |
Request Example¶
{
"attachment": {
"instance_uuid": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
"connector": {
"initiator": "iqn.1993-08.org.debian: 01: cad181614cec",
"ip": "192.168.1.20",
"platform": "x86_64",
"host": "tempest-1",
"os_type": "linux2",
"multipath": false,
"mountpoint": "/dev/vdb",
"mode": "ro"
},
"volume_uuid": "462dcc2d-130d-4654-8db1-da0df2da6a0d"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
attachment |
body |
object |
An attachment object. |
status |
body |
string |
The status of the attachment. |
detached_at (Optional) |
body |
string |
The time when attachment is detached. |
connection_info |
body |
object |
The connection info used for server to connect the volume. |
attached_at (Optional) |
body |
string |
The time when attachment is attached. |
attach_mode (Optional) |
body |
string |
The attach mode of attachment, read-only ('ro') or read-and-write ('rw'), default is 'ro'. |
instance (Optional) |
body |
string |
The UUID of the attaching instance. |
volume_id |
body |
string |
The UUID of the volume which the attachment belongs to. |
id |
body |
string |
The ID of attachment. |
Response Example¶
{
"attachment": {
"status": "attaching",
"detached_at": "2015-09-16T09:28:52.000000",
"connection_info": {},
"attached_at": "2015-09-16T09:28:52.000000",
"attach_mode": "ro",
"instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
"volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
"id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
}
}
Update a reserved attachment record with connector information and set up the appropriate connection_info from the driver.
Available starting in the 3.27 microversion.
Normal response codes: 200
Error response codes: badRequest(400), itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
attachment_id |
path |
string |
The ID of the attachment. |
attachement |
body |
object |
An attachment object. |
connector |
body |
object |
The |
Request Example¶
{
"attachment": {
"connector": {
"initiator": "iqn.1993-08.org.debian: 01: cad181614cec",
"ip": "192.168.1.20",
"platform": "x86_64",
"host": "tempest-1",
"os_type": "linux2",
"multipath": false,
"mountpoint": "/dev/vdb",
"mode": "ro"
}
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
attachment |
body |
object |
An attachment object. |
status |
body |
string |
The status of the attachment. |
detached_at (Optional) |
body |
string |
The time when attachment is detached. |
connection_info |
body |
object |
The connection info used for server to connect the volume. |
attached_at (Optional) |
body |
string |
The time when attachment is attached. |
attach_mode (Optional) |
body |
string |
The attach mode of attachment, read-only ('ro') or read-and-write ('rw'), default is 'ro'. |
instance (Optional) |
body |
string |
The UUID of the attaching instance. |
volume_id |
body |
string |
The UUID of the volume which the attachment belongs to. |
id |
body |
string |
The ID of attachment. |
Response Example¶
{
"attachment": {
"status": "attaching",
"detached_at": "2015-09-16T09:28:52.000000",
"connection_info": {},
"attached_at": "2015-09-16T09:28:52.000000",
"attach_mode": "ro",
"instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
"volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
"id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
}
}
Complete an attachment for a cinder volume.
Available starting in the 3.44 microversion.
Normal response codes: 204
Error response codes: badRequest(400), itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
attachment_id |
path |
string |
The ID of the attachment. |
Request Example¶
{
"os-complete": {
}
}
Group types¶
To create a generic volume group, you must specify a group type.
Lists group 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 (Optional) |
query |
string |
Comma-separated list of sort keys and optional
sort directions in the form of < key > [: < direction > ]. A valid
direction is |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
offset (Optional) |
query |
integer |
Used in conjunction with |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_types |
body |
array |
The list of group types. |
id |
body |
string |
The group type ID. |
group_specs (Optional) |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
name |
body |
string |
The group type name. |
Response Example¶
{
"group_types": [
{
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
},
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "group_type1"
},
{
"group_specs": {},
"id": "8eb69a46-df97-4e41-9586-9a40a7533803",
"name": "group_type2"
}
]
}
Limits (limits)¶
Shows absolute limits for a project.
An absolute limit value of -1 indicates that the absolute limit
for the item is infinite.
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 |
|---|---|---|---|
limits |
body |
object |
A list of |
rate |
body |
array |
Rate-limit volume copy bandwidth, used to mitigate slow down of data access from the instances. |
absolute |
body |
object |
An |
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). |
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. |
totalBackupsUsed |
body |
integer |
The total number of backups used. |
totalGigabytesUsed |
body |
integer |
The total number of gibibytes (GiB) used. |
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
}
}
}
Resource Filters¶
Lists all resource filters, available since microversion 3.33.
List filters.
Normal response codes: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
resource (Optional) |
query |
string |
Filter for resource name. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
resource_filters |
body |
array |
A collection of resource filters. |
filters |
body |
array |
The resource filter array. |
resource |
body |
string |
Resource which the filters will be applied to. |
Response Example¶
{
"resource_filters": [
{
"filters": [
"name",
"status",
"image_metadata", "bootable",
"migration_status"
],
"resource": "volume"
},
{
"filters": [
"name",
"status",
"volume_id"
],
"resource": "snapshot"
}
]
}
Quota sets extension (os-quota-sets)¶
Administrators only, depending on policy settings.
Shows, updates, and deletes quotas for a project.
Shows quotas for a project.
Normal response codes: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
admin_project_id |
path |
string |
The UUID of the administrative project. |
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
usage (Optional) |
query |
boolean |
Show project's quota usage information.
Default is |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_set |
body |
object |
A |
id |
body |
string |
The UUID of the project. |
volumes |
body |
integer |
The number of volumes that are allowed for each project. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
snapshots |
body |
integer |
The number of snapshots that are allowed for each project. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
backups |
body |
integer |
The number of backups that are allowed for each project. |
groups |
body |
integer |
The number of groups that are allowed for each project. |
per_volume_gigabytes |
body |
integer |
The size (GB) of volumes that are allowed for each volume. |
gigabytes |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project. |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specifed volume type. |
backup_gigabytes |
body |
integer |
The size (GB) of backups that are allowed for each project. |
Response Example¶
{
"quota_set": {
"id": "a7090a26bc554d93aa845a4d41808251",
"volumes": 10,
"volumes_ceph": -1,
"volumes_lvm-thin": -1,
"volumes_lvmdriver-1": -1,
"snapshots": 10,
"snapshots_ceph": -1,
"snapshots_lvm-thin": -1,
"snapshots_lvmdriver-1": -1,
"backups": 10,
"groups": 10,
"per_volume_gigabytes": -1,
"gigabytes": 1000,
"gigabytes_ceph": -1,
"gigabytes_lvm-thin": -1,
"gigabytes_lvmdriver-1": -1,
"backup_gigabytes": 1000
}
}
Shows quota usage 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 |
Show project's quota usage information.
Default is |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_set |
body |
object |
A |
id |
body |
string |
The UUID of the project. |
volumes |
body |
object |
The volume usage information for this project, including |
volumes_{volume_type} |
body |
object |
The volume usage information for this project and this volume type,
including |
snapshots |
body |
object |
The snapshot usage information for this project, including |
snapshots_{volume_type} |
body |
object |
The snapshot usage information for this project and this volume type,
including |
backups |
body |
object |
The backup usage information for this project, including |
groups |
body |
object |
The group usage information for this project, including |
per_volume_gigabytes |
body |
object |
The size (GB) usage information for each volume, including |
gigabytes |
body |
object |
The size (GB) usage information of volumes and snapshots for this project,
including |
gigabytes_{volume_type} |
body |
object |
The size (GB) usage information of volumes and snapshots for this project
and this volume type, including |
backup_gigabytes |
body |
object |
The size (GB) usage information of backup for this project, including |
Response Example¶
{
"quota_set": {
"id": "a7090a26bc554d93aa845a4d41808251",
"volumes": {
"reserved": 0,
"allocated": 0,
"limit": 10,
"in_use": 0
},
"volumes_lvmdriver-1": {
"reserved": 0,
"allocated": 0,
"limit": -1,
"in_use": 0
},
"snapshots": {
"reserved": 0,
"allocated": 0,
"limit": 10,
"in_use": 0
},
"snapshots_lvmdriver-1": {
"reserved": 0,
"allocated": 0,
"limit": -1,
"in_use": 0
},
"backups": {
"reserved": 0,
"allocated": 0,
"limit": 10,
"in_use": 0
},
"groups": {
"reserved": 0,
"allocated": 0,
"limit": 10,
"in_use": 0
},
"per_volume_gigabytes": {
"reserved": 0,
"allocated": 0,
"limit": -1,
"in_use": 0
},
"gigabytes": {
"reserved": 0,
"allocated": 0,
"limit": 1000,
"in_use": 0
},
"gigabytes_lvmdriver-1": {
"reserved": 0,
"allocated": 0,
"limit": 1000,
"in_use": 0
},
"backup_gigabytes": {
"reserved": 0,
"allocated": 0,
"limit": 1000,
"in_use": 0
}
}
}
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 |
|---|---|---|---|
quota_set |
body |
object |
A |
id |
body |
string |
The UUID of the project. |
volumes |
body |
integer |
The number of volumes that are allowed for each project. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
snapshots |
body |
integer |
The number of snapshots that are allowed for each project. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
backups |
body |
integer |
The number of backups that are allowed for each project. |
groups |
body |
integer |
The number of groups that are allowed for each project. |
per_volume_gigabytes |
body |
integer |
The size (GB) of volumes that are allowed for each volume. |
gigabytes |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project. |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specifed volume type. |
backup_gigabytes |
body |
integer |
The size (GB) of backups that are allowed for each project. |
Response Example¶
{
"quota_set": {
"id": "a7090a26bc554d93aa845a4d41808251",
"volumes": 10,
"volumes_ceph": -1,
"volumes_lvm-thin": -1,
"volumes_lvmdriver-1": -1,
"snapshots": 10,
"snapshots_ceph": -1,
"snapshots_lvm-thin": -1,
"snapshots_lvmdriver-1": -1,
"backups": 10,
"groups": 10,
"per_volume_gigabytes": -1,
"gigabytes": 1000,
"gigabytes_ceph": -1,
"gigabytes_lvm-thin": -1,
"gigabytes_lvmdriver-1": -1,
"backup_gigabytes": 1000
}
}