Block Storage API V3 (CURRENT)¶
Note
The URL for most API methods includes a {project_id}
placeholder that
represents the caller’s project ID. As of v3.67, the project_id is optional
in the URL, and the following are equivalent:
GET /v3/{project_id}/volumes
GET /v3/volumes
In both instances, the actual project ID used by the API method is the one in the caller’s keystone context. For that reason, including a project ID in the URL is redundant.
The v3.67 microversion is only used as an indicator that the API accepts a
URL without a {project_id}
segment, and this applies to all requests
regardless of the microversion in the request. For example, an API node
serving v3.67 or greater will accept a URL without a {project_id}
segment even if the request asks for v3.0. Likewise, it will accept a URL
containing a {project_id}
segment even if the request asks for v3.67.
API versions¶
Lists information for all Block Storage API versions.
Response codes¶
Success¶
Code |
Reason |
---|---|
300 - Multiple Choices |
The resource corresponds to more than one representation. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
401 - Unauthorized |
User must authenticate before making a request. |
403 - Forbidden |
Policy does not allow current user to do this operation. |
405 - Method Not Allowed |
Method is not valid for this endpoint and resource. |
404 - Not Found |
The requested resource could not be found. |
409 - Conflict |
This resource has an action in progress that would conflict with this request. |
500 - Internal Server Error |
Something went wrong with the service which prevents it from fulfilling the request. |
503 - Service Unavailable |
The service cannot handle the request right now. |
Request¶
Response¶
Example List Api Versions: JSON request
{
"versions": [
{
"id": "v3.0",
"links": [
{
"href": "https://docs.openstack.org/",
"rel": "describedby",
"type": "text/html"
},
{
"href": "http://127.0.0.1:45697/v3/",
"rel": "self"
}
],
"media-types": [
{
"base": "application/json",
"type": "application/vnd.openstack.volume+json;version=3"
}
],
"min_version": "3.0",
"status": "CURRENT",
"updated": "2022-08-31T00:00:00Z",
"version": "3.71"
}
]
}
API version details¶
Shows details for Block Storage API v3.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
403 - Forbidden |
Policy does not allow current user to do this operation. |
Request¶
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
status |
body |
string |
The status of this API version. This can be one of:
|
updated |
body |
string |
This is a fixed string that API version updates. |
links |
body |
array |
Links to the resources in question. |
min_version |
body |
string |
If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported. |
version |
body |
string |
If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported. |
media-types |
body |
array |
The media types. It is an array of a fixed dict. Note It is vestigial and provide no useful information. It will be deprecated and removed in the future. |
id |
body |
string |
A common name for the version in question. Informative only, it has no real semantic meaning. |
Response Example¶
{
"versions": [
{
"id": "v3.0",
"links": [
{
"href": "https://docs.openstack.org/",
"rel": "describedby",
"type": "text/html"
},
{
"href": "http://127.0.0.1:44895/v3/",
"rel": "self"
}
],
"media-types": [
{
"base": "application/json",
"type": "application/vnd.openstack.volume+json;version=3"
}
],
"min_version": "3.0",
"status": "CURRENT",
"updated": "2023-08-31T00:00:00Z",
"version": "3.71"
}
]
}
API extensions (extensions)¶
Lists Block Storage API extensions.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
300 - Multiple Choices |
The resource corresponds to more than one representation. |
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 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 |
description |
body |
string |
The extension description. |
links |
body |
array |
Links for the volume transfer. |
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 (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"extensions": [
{
"alias": "os-hosts",
"description": "Admin-only host administration.",
"links": [],
"name": "Hosts",
"updated": "2011-06-29T00:00:00+00:00"
},
{
"alias": "os-vol-tenant-attr",
"description": "Expose the internal project_id as an attribute of a volume.",
"links": [],
"name": "VolumeTenantAttribute",
"updated": "2011-11-03T00:00:00+00:00"
},
{
"alias": "os-quota-sets",
"description": "Quota management support.",
"links": [],
"name": "Quotas",
"updated": "2011-08-08T00:00:00+00:00"
},
{
"alias": "os-availability-zone",
"description": "Describe Availability Zones.",
"links": [],
"name": "AvailabilityZones",
"updated": "2013-06-27T00:00:00+00:00"
},
{
"alias": "os-volume-encryption-metadata",
"description": "Volume encryption metadata retrieval support.",
"links": [],
"name": "VolumeEncryptionMetadata",
"updated": "2013-07-10T00:00:00+00:00"
},
{
"alias": "backups",
"description": "Backups support.",
"links": [],
"name": "Backups",
"updated": "2012-12-12T00:00:00+00:00"
},
{
"alias": "os-snapshot-actions",
"description": "Enable snapshot manager actions.",
"links": [],
"name": "SnapshotActions",
"updated": "2013-07-16T00:00:00+00:00"
},
{
"alias": "os-volume-actions",
"description": "Enable volume actions.",
"links": [],
"name": "VolumeActions",
"updated": "2012-05-31T00:00:00+00:00"
},
{
"alias": "os-snapshot-manage",
"description": "Allows existing backend storage to be 'managed' by Cinder.",
"links": [],
"name": "SnapshotManage",
"updated": "2014-12-31T00:00:00+00:00"
},
{
"alias": "os-volume-unmanage",
"description": "Enable volume unmanage operation.",
"links": [],
"name": "VolumeUnmanage",
"updated": "2012-05-31T00:00:00+00:00"
},
{
"alias": "consistencygroups",
"description": "consistency groups support.",
"links": [],
"name": "Consistencygroups",
"updated": "2014-08-18T00:00:00+00:00"
},
{
"alias": "os-vol-host-attr",
"description": "Expose host as an attribute of a volume.",
"links": [],
"name": "VolumeHostAttribute",
"updated": "2011-11-03T00:00:00+00:00"
},
{
"alias": "encryption",
"description": "Encryption support for volume types.",
"links": [],
"name": "VolumeTypeEncryption",
"updated": "2013-07-01T00:00:00+00:00"
},
{
"alias": "os-vol-image-meta",
"description": "Show image metadata associated with the volume.",
"links": [],
"name": "VolumeImageMetadata",
"updated": "2012-12-07T00:00:00+00:00"
},
{
"alias": "os-types-manage",
"description": "Types manage support.",
"links": [],
"name": "TypesManage",
"updated": "2011-08-24T00:00:00+00:00"
},
{
"alias": "capabilities",
"description": "Capabilities support.",
"links": [],
"name": "Capabilities",
"updated": "2015-08-31T00:00:00+00:00"
},
{
"alias": "cgsnapshots",
"description": "cgsnapshots support.",
"links": [],
"name": "Cgsnapshots",
"updated": "2014-08-18T00:00:00+00:00"
},
{
"alias": "os-types-extra-specs",
"description": "Type extra specs support.",
"links": [],
"name": "TypesExtraSpecs",
"updated": "2011-08-24T00:00:00+00:00"
},
{
"alias": "os-used-limits",
"description": "Provide data on limited resources that are being used.",
"links": [],
"name": "UsedLimits",
"updated": "2013-10-03T00:00:00+00:00"
},
{
"alias": "os-vol-mig-status-attr",
"description": "Expose migration_status as an attribute of a volume.",
"links": [],
"name": "VolumeMigStatusAttribute",
"updated": "2013-08-08T00:00:00+00:00"
},
{
"alias": "os-volume-type-access",
"description": "Volume type access support.",
"links": [],
"name": "VolumeTypeAccess",
"updated": "2014-06-26T00:00:00Z"
},
{
"alias": "os-extended-services",
"description": "Extended services support.",
"links": [],
"name": "ExtendedServices",
"updated": "2014-01-10T00:00:00-00:00"
},
{
"alias": "os-extended-snapshot-attributes",
"description": "Extended SnapshotAttributes support.",
"links": [],
"name": "ExtendedSnapshotAttributes",
"updated": "2012-06-19T00:00:00+00:00"
},
{
"alias": "os-snapshot-unmanage",
"description": "Enable volume unmanage operation.",
"links": [],
"name": "SnapshotUnmanage",
"updated": "2014-12-31T00:00:00+00:00"
},
{
"alias": "qos-specs",
"description": "QoS specs support.",
"links": [],
"name": "Qos_specs_manage",
"updated": "2013-08-02T00:00:00+00:00"
},
{
"alias": "os-quota-class-sets",
"description": "Quota classes management support.",
"links": [],
"name": "QuotaClasses",
"updated": "2012-03-12T00:00:00+00:00"
},
{
"alias": "os-volume-transfer",
"description": "Volume transfer management support.",
"links": [],
"name": "VolumeTransfer",
"updated": "2013-05-29T00:00:00+00:00"
},
{
"alias": "os-volume-manage",
"description": "Allows existing backend storage to be 'managed' by Cinder.",
"links": [],
"name": "VolumeManage",
"updated": "2014-02-10T00:00:00+00:00"
},
{
"alias": "os-admin-actions",
"description": "Enable admin actions.",
"links": [],
"name": "AdminActions",
"updated": "2012-08-25T00:00:00+00:00"
},
{
"alias": "os-services",
"description": "Services support.",
"links": [],
"name": "Services",
"updated": "2012-10-28T00:00:00-00:00"
},
{
"alias": "scheduler-stats",
"description": "Scheduler stats support.",
"links": [],
"name": "Scheduler_stats",
"updated": "2014-09-07T00:00:00+00:00"
},
{
"alias": "OS-SCH-HNT",
"description": "Pass arbitrary key/value pairs to the scheduler.",
"links": [],
"name": "SchedulerHints",
"updated": "2013-04-18T00:00:00+00:00"
}
]
}
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.
Updates a volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. |
volume_type |
body |
object |
A |
name (Optional) |
body |
string |
The name of the volume type. |
description (Optional) |
body |
string |
The volume type description. |
is_public (Optional) |
body |
boolean |
Whether the volume type is publicly visible. See valid boolean values |
Request Example¶
{
"volume_type": {
"name": "vol-type-001",
"description": "volume type 0001",
"is_public": true
}
}
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 |
path |
string |
The UUID for an existing volume type. |
Response Example¶
{
"volume_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "vol-type-001",
"description": "volume type 0001",
"is_public": true,
"extra_specs": {
"capabilities": "gpu"
}
}
}
Adds new extra specifications to a volume type, or updates the extra specifications that are assigned to a volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. |
extra_specs |
body |
object |
A set of key and value pairs that contains the specifications for a volume type. |
Request Example¶
{
"extra_specs": {
"key1": "value1",
"key2": "value2"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
extra_specs |
body |
object |
A set of key and value pairs that contains the specifications for a volume type. |
Response Example¶
{
"extra_specs": {
"key1": "value1",
"key2": "value2"
}
}
Shows all extra specifications assigned to a volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
---|---|---|---|
extra_specs |
body |
object |
A set of key and value pairs that contains the specifications for a volume type. |
Response Example¶
{
"extra_specs": {
"capabilities": "gpu"
}
}
Shows the specific extra specification assigned to a volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. |
key |
path |
string |
The key name of the extra spec for a volume type. |
Response Example¶
{
"capabilities": "gpu"
}
Update the specific extra specification assigned to a volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. |
key |
path |
string |
The key name of the extra spec for a volume type. |
Request Example¶
{
"key1": "value1"
}
Response Example¶
{
"key1": "value1"
}
Deletes the specific extra specification assigned to a volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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. |
key |
path |
string |
The key name of the extra spec for a volume type. |
Shows details for a volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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",
"qos_specs_id": null,
"name": "vol-type-001",
"description": "volume type 0001",
"os-volume-type-access:is_public": true,
"is_public": true,
"extra_specs": {
"capabilities": "gpu"
}
}
}
Shows details for the default volume type, that is, the volume type that will be used in the Create a volume request if you do not specify one. This could be one of the following:
Your project’s default volume type (since microversion 3.62)
The installation’s default volume type as configured by the operator
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
404 - Not Found |
The requested resource could not be found. |
500 - Internal Server Error |
Something went wrong with the service which prevents it from fulfilling the request. |
Error conditions¶
It is only possible to receive a 404 (Not Found) response in pre-Train versions of the Block Storage service, as a configured default volume type has been required since the Train release.
If you receive a 500 (Internal Error Response), then the default volume type has not been configured correctly by the operator. Please contact your cloud provider.
When the default volume type is misconfigured, requests to Create a volume that do not include a volume type will fail.
The workaround is to include a volume type in your request. You can List all volume types to determine a volume type to use.
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 (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. |
qos_specs_id (Optional) |
body |
string |
The QoS specifications ID. |
Response Example¶
{
"volume_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"qos_specs_id": null,
"name": "vol-type-001",
"description": "volume type 0001",
"is_public": true,
"extra_specs": {
"capabilities": "gpu"
}
}
}
Deletes a volume type.
Note to operators: Since the Train release, untyped volumes are not allowed, and a configured default volume type is required in each deployment. An attempt to delete the configured default volume type will fail.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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. |
Lists volume types.
To determine which of these is the default type that will be used if you do not specify one in the Create a volume request, use the Show default volume type request.
Note to users: There may be a volume type named __DEFAULT__
in the
list. Try not to use this volume type, unless necessary or instructed by the
operator, in a Create a volume request. If you wish to create a volume of
your default volume type, simply omit the volume_type
parameter in your
Create a volume request.
Note to operators: The __DEFAULT__
volume type was introduced in
the Train release as a placeholder to prevent the creation of untyped
volumes. Under the proper conditions, it may be removed from your
deployment. Consult the Default Volume Types section in
Cinder Administration Guide
for details.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
is_public (Optional) |
query |
boolean |
Filter the volume type by public visibility. See valid boolean values. |
sort (Optional) |
query |
string |
Comma-separated list of sort keys and optional
sort directions in the form of |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 (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. |
name |
body |
string |
The name of the volume type. |
is_public |
body |
boolean |
Whether the volume type is publicly visible. |
description |
body |
string |
The volume type description. |
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_types": [
{
"description": "volume type 0002",
"extra_specs": {
"capabilities": "gpu"
},
"id": "ef512777-6552-4013-82f0-57a96e5804b7",
"is_public": true,
"name": "vol-type-002",
"os-volume-type-access:is_public": true,
"qos_specs_id": null
},
{
"description": "volume type 0001",
"extra_specs": {
"capabilities": "gpu"
},
"id": "18947ff2-ad57-42b2-9350-34262e530203",
"is_public": true,
"name": "vol-type-001",
"os-volume-type-access:is_public": true,
"qos_specs_id": null
},
{
"description": "Default Volume Type",
"extra_specs": {},
"id": "7a56b996-b73f-4233-9f00-dd6a68b49b27",
"is_public": true,
"name": "__DEFAULT__",
"os-volume-type-access:is_public": true,
"qos_specs_id": null
}
]
}
Creates a volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume_type |
body |
object |
A |
name |
body |
string |
The name of the volume type. |
os-volume-type-access:is_public (Optional) |
body |
boolean |
Whether the volume type is publicly visible. See valid boolean values |
description (Optional) |
body |
string |
The volume type description. |
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. |
Request Example¶
{
"volume_type": {
"name": "vol-type-001",
"description": "volume type 0001",
"os-volume-type-access:is_public": true,
"extra_specs": {
"capabilities": "gpu"
}
}
}
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. |
Response Example¶
{
"volume_type": {
"name": "vol-type-001",
"extra_specs": {
"capabilities": "gpu"
},
"os-volume-type-access:is_public": true,
"is_public": true,
"id": "6d0ff92a-0007-4780-9ece-acfe5876966a",
"description": "volume type 0001"
}
}
To show an encryption type for an existing volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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_id |
body |
string |
The UUID of the volume type. |
encryption_id |
body |
string |
The UUID of the encryption. |
key_size (Optional) |
body |
integer |
Size of encryption key, in bits. This is usually 256. The default value is None. |
provider |
body |
string |
The class that provides encryption support. |
control_location (Optional) |
body |
string |
Notional service where encryption is performed. Valid values are “front-end” or “back-end”. The default value is “front-end”. |
cipher (Optional) |
body |
string |
The encryption algorithm or mode. For example, aes-xts-plain64. The default value is None. |
deleted |
body |
boolean |
The resource is deleted or not. |
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 |
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 |
deleted_at |
body |
string |
The date and time when the resource was deleted. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The If the |
Response Example¶
{
"volume_type_id": "2d29462d-76cb-417c-8a9f-fb23140f1577",
"control_location": "front-end",
"deleted": false,
"created_at": "2016-12-28T02:32:25.000000",
"updated_at": null,
"encryption_id": "81e069c6-7394-4856-8df7-3b237ca61f74",
"key_size": 256,
"provider": "luks",
"deleted_at": null,
"cipher": "aes-xts-plain64"
}
To show encryption specs item for an existing volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. |
key |
path |
string |
The key name of the encryption spec for a volume type. |
Response Example¶
{
"cipher": "aes-xts-plain64"
}
To delete an encryption type for an existing volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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. |
encryption_id |
path |
string |
The ID of the encryption type. |
To create an encryption type for an existing volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. |
encryption |
body |
object |
The encryption information. |
key_size (Optional) |
body |
integer |
Size of encryption key, in bits. This is usually 256. The default value is None. |
provider |
body |
string |
The class that provides encryption support. Choices are:
|
control_location (Optional) |
body |
string |
Notional service where encryption is performed. Valid values are “front-end” or “back-end”. The default value is “front-end”. |
cipher (Optional) |
body |
string |
The encryption algorithm or mode. For example, aes-xts-plain64. The default value is None. |
Request Example¶
{
"encryption":{
"key_size": 256,
"provider": "luks",
"control_location":"front-end",
"cipher": "aes-xts-plain64"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
encryption |
body |
object |
The encryption information. |
volume_type_id |
body |
string |
The UUID of the volume type. |
encryption_id |
body |
string |
The UUID of the encryption. |
key_size (Optional) |
body |
integer |
Size of encryption key, in bits. This is usually 256. The default value is None. |
provider |
body |
string |
The class that provides encryption support. |
control_location (Optional) |
body |
string |
Notional service where encryption is performed. Valid values are “front-end” or “back-end”. The default value is “front-end”. |
cipher (Optional) |
body |
string |
The encryption algorithm or mode. For example, aes-xts-plain64. The default value is None. |
Response Example¶
{
"encryption": {
"volume_type_id": "2d29462d-76cb-417c-8a9f-fb23140f1577",
"control_location": "front-end",
"encryption_id": "81e069c6-7394-4856-8df7-3b237ca61f74",
"key_size": 256,
"provider": "luks",
"cipher": "aes-xts-plain64"
}
}
To update an encryption type for an existing volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. |
encryption_id |
path |
string |
The ID of the encryption type. |
encryption |
body |
object |
The encryption information. |
key_size (Optional) |
body |
integer |
Size of encryption key, in bits. This is usually 256. The default value is None. |
provider (Optional) |
body |
string |
The class that provides encryption support. Choices are:
|
control_location (Optional) |
body |
string |
Notional service where encryption is performed. Valid values are “front-end” or “back-end”. The default value is “front-end”. |
cipher (Optional) |
body |
string |
The encryption algorithm or mode. For example, aes-xts-plain64. The default value is None. |
Request Example¶
{
"encryption":{
"key_size": 64,
"provider": "luks",
"control_location":"back-end",
"cipher": "aes-xts-plain64"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
encryption |
body |
object |
The encryption information. |
key_size (Optional) |
body |
integer |
Size of encryption key, in bits. This is usually 256. The default value is None. |
provider (Optional) |
body |
string |
The class that provides encryption support. |
control_location (Optional) |
body |
string |
Notional service where encryption is performed. Valid values are “front-end” or “back-end”. The default value is “front-end”. |
cipher (Optional) |
body |
string |
The encryption algorithm or mode. For example, aes-xts-plain64. The default value is None. |
Response Example¶
{
"encryption":{
"key_size": 64,
"provider": "luks",
"control_location":"back-end",
"cipher": "aes-xts-plain64"
}
}
Volume type access (types, action) (types, os-volume-type-access)¶
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.
Adds private volume type access to a project.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume_type |
path |
string |
The UUID for an existing volume type. |
addProjectAccess |
body |
object |
Adds volume type access to a project. |
project |
body |
string |
The ID of the project. Volume Type access to be added to this project ID. |
Request Example¶
{
"addProjectAccess": {
"project": "6f70656e737461636b20342065766572"
}
}
Removes private volume type access from a project.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume_type |
path |
string |
The UUID for an existing volume type. |
removeProjectAccess |
body |
object |
Removes volume type access from a project. |
project |
body |
string |
The ID of the project. Volume Type access to be added to this project ID. |
Request Example¶
{
"removeProjectAccess": {
"project": "f270b245cb11498ca4031deb7e141cfa"
}
}
Lists project IDs that have access to private volume type.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume_type |
path |
string |
The UUID for an existing volume type. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
volume_type_access |
body |
array |
List of objects containing volume type to be accessed by project. |
project_id |
body |
string |
The UUID of the project. |
volume_type_id |
body |
string |
The UUID of the volume type. |
Response Example¶
{
"volume_type_access": [
{
"project_id": "6f70656e737461636b20342065766572",
"volume_type_id": "a5082c24-2a27-43a4-b48e-fcec1240e36b"
}
]
}
Default Volume Types (default-types)¶
Manage a default volume type for individual projects.
By default, a volume-create request that does not specify a volume-type will assign the configured system default volume type to the volume. You can override this behavior on a per-project basis by setting a different default volume type for any project.
Available in microversion 3.62 or higher.
NOTE: The default policy for list API is system admin so you would require a system scoped token to access it. To get a system scoped token, you need to run the following command:
openstack –os-system-scope all –os-project-name=’’ token issue
Create or update the default volume type for a project
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
Request Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume_type |
path |
string |
The name or UUID for an existing volume type. |
Request Example¶
{
"default_type": {
"volume_type": "lvm_backend"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
body |
string |
The UUID of the project. |
volume_type_id |
path |
string |
The UUID for an existing volume type. |
Response Example¶
{
"default_type": {
"project_id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"volume_type_id": "40ec6e5e-c9bd-4170-8740-c1cd42d7eabb"
}
}
Show the default volume type for a project
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
404 - Not Found |
The requested resource could not be found. |
Request Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
body |
string |
The UUID of the project. |
volume_type_id |
path |
string |
The UUID for an existing volume type. |
Response Example¶
{
"default_type": {
"project_id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"volume_type_id": "40ec6e5e-c9bd-4170-8740-c1cd42d7eabb"
}
}
Get a list of all default volume types
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
404 - Not Found |
The requested resource could not be found. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
body |
string |
The UUID of the project. |
volume_type_id |
path |
string |
The UUID for an existing volume type. |
Response Example¶
{
"default_types": [
{
"project_id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"volume_type_id": "40ec6e5e-c9bd-4170-8740-c1cd42d7eabb"
},
{
"project_id": "dd46ea3e-6f3f-4e50-85fa-40c182e25d12",
"volume_type_id": "9fb51b63-3cd4-493f-9380-53d8f0a04bd4"
}
]
}
Unset the default volume type for a project.
This operation does not do anything to the volume type itself. It simply removes the volume type from being the default volume type for the specified project.
Response codes¶
Success¶
Code |
Reason |
---|---|
204 - No Content |
Request fulfilled but service does not return anything. |
Error¶
Code |
Reason |
---|---|
404 - Not Found |
The requested resource could not be found. |
Request Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
Volumes (volumes)¶
A volume is a detachable block storage device similar to a USB hard drive. You can attach a volume to an instance, and if the volume is of an appropriate volume type, a volume can be attached to multiple instances.
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
created_at (Optional) |
query |
string |
Filters reuslts by a time that resources are created at with time comparison operators: gt/gte/eq/neq/lt/lte. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. The ±hh:mm value, if included, returns the time zone as an offset from UTC. New in version 3.60 |
updated_at (Optional) |
query |
string |
Filters reuslts by a time that resources are updated at with time comaprison operators: gt/gte/eq/neq/lt/lte. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. The ±hh:mm value, if included, returns the time zone as an offset from UTC. New in version 3.60 |
consumes_quota (Optional) |
query |
boolean |
Filters results by New in version 3.65 |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
migration_status (Optional) |
body |
string |
The volume migration status. Admin only. |
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. For example: [
{
'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
'attached_at': '2019-09-30T19:30:34.000000',
'host_name': null,
'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
'device': '/dev/vda',
'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
}
]
|
links |
body |
array |
The volume links. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
os-vol-host-attr:host (Optional) |
body |
string |
Current back-end of the volume.
Host format is |
encrypted |
body |
boolean |
If true, this volume is encrypted. |
encryption_key_id (Optional) |
body |
string |
The UUID of the encryption key. Only included for encrypted volumes. New in version 3.64 |
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. |
os-vol-tenant-attr:tenant_id |
body |
string |
The project ID which the volume belongs to. |
os-vol-mig-status-attr:migstat (Optional) |
body |
string |
The status of this volume migration (None means that a migration is not currently in progress). |
metadata |
body |
object |
A |
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 unless a larger size is requested. |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
os-vol-mig-status-attr:name_id (Optional) |
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 |
volumes |
body |
array |
A list of |
volume_type |
body |
string |
The associated volume type name for the volume. |
volume_type_id |
body |
object |
The associated volume type ID for the volume. New in version 3.63 |
group_id (Optional) |
body |
string |
The ID of the group. New in version 3.13 |
volumes_links (Optional) |
body |
array |
The volume links. |
provider_id (Optional) |
body |
string |
The provider ID for the volume. The value is either a string set by the
driver or New in version 3.21 |
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. New in version 3.48 |
shared_targets |
body |
boolean |
An indicator whether the back-end hosting the volume utilizes shared_targets or not. Default=True. New in version 3.48 Available until version 3.68 |
shared_targets |
body |
boolean |
An indicator whether the host connecting the volume should lock for the
whole attach/detach process or not. New in version 3.69 |
cluster_name (Optional) |
body |
string |
The cluster name of volume backend. New in version 3.61 |
consumes_quota (Optional) |
body |
boolean |
Whether this resource consumes quota or not. Resources that not counted for quota usage are usually temporary internal resources created to perform an operation. New in version 3.65 |
count (Optional) |
body |
integer |
The total count of requested resource before pagination is applied. New in version 3.45 |
Response Example (v3.65)¶
{
"volumes": [
{
"attachments": [],
"availability_zone": "nova",
"bootable": "false",
"consistencygroup_id": null,
"created_at": "2018-11-28T06:25:15.288987",
"description": null,
"encrypted": false,
"id": "cb49b381-9012-40cb-b8ee-80c19a4801b5",
"links": [
{
"href": "http://127.0.0.1:43543/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/cb49b381-9012-40cb-b8ee-80c19a4801b5",
"rel": "self"
},
{
"href": "http://127.0.0.1:43543/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/cb49b381-9012-40cb-b8ee-80c19a4801b5",
"rel": "bookmark"
}
],
"metadata": {},
"migration_status": null,
"multiattach": false,
"name": null,
"os-vol-host-attr:host": null,
"os-vol-mig-status-attr:migstat": null,
"os-vol-mig-status-attr:name_id": null,
"os-vol-tenant-attr:tenant_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
"replication_status": null,
"size": 10,
"snapshot_id": null,
"source_volid": null,
"status": "creating",
"updated_at": null,
"user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
"volume_type": "__DEFAULT__",
"volume_type_id": "5fed9d7c-401d-46e2-8e80-f30c70cb7e1d",
"provider_id": null,
"group_id": null,
"service_uuid": null,
"shared_targets": true,
"cluster_name": null,
"consumes_quota": true
}
]
}
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.
Since the Train release, every volume must have a volume type. It is optional to specify a volume type as part of your Create a volume request. If you do not specify one, a default volume type will be supplied for you. This type may vary according to what project you are in and how the operator has configured the Block Storage service. Use the Show default volume type request to determine your effective default volume type.
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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 unless a larger size is requested. |
description (Optional) |
body |
string |
The volume description. |
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.47 |
name (Optional) |
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 (either name or ID). 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 (Optional) |
body |
object |
One or more metadata key and value pairs to be associated with the new volume. |
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 (Optional) |
body |
string |
The volume migration status. Admin only. |
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. For example: [
{
'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
'attached_at': '2019-09-30T19:30:34.000000',
'host_name': null,
'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
'device': '/dev/vda',
'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
}
]
|
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 |
A |
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 unless a larger size is requested. |
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 name for the volume. |
volume_type_id |
body |
object |
The associated volume type ID for the volume. New in version 3.63 |
group_id (Optional) |
body |
string |
The ID of the group. New in version 3.13 |
provider_id (Optional) |
body |
string |
The provider ID for the volume. The value is either a string set by the
driver or New in version 3.21 |
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. New in version 3.48 |
shared_targets |
body |
boolean |
An indicator whether the back-end hosting the volume utilizes shared_targets or not. Default=True. New in version 3.48 Available until version 3.68 |
shared_targets |
body |
boolean |
An indicator whether the host connecting the volume should lock for the
whole attach/detach process or not. New in version 3.69 |
cluster_name (Optional) |
body |
string |
The cluster name of volume backend. New in version 3.61 |
consumes_quota (Optional) |
body |
boolean |
Whether this resource consumes quota or not. Resources that not counted for quota usage are usually temporary internal resources created to perform an operation. New in version 3.65 |
Response Example (v3.65)¶
{
"volume": {
"attachments": [],
"availability_zone": "nova",
"bootable": "false",
"consistencygroup_id": null,
"created_at": "2018-11-28T06:21:12.715987",
"description": null,
"encrypted": false,
"id": "2b955850-f177-45f7-9f49-ecb2c256d161",
"links": [
{
"href": "http://127.0.0.1:33951/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/2b955850-f177-45f7-9f49-ecb2c256d161",
"rel": "self"
},
{
"href": "http://127.0.0.1:33951/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/2b955850-f177-45f7-9f49-ecb2c256d161",
"rel": "bookmark"
}
],
"metadata": {},
"migration_status": null,
"multiattach": false,
"name": null,
"replication_status": null,
"size": 10,
"snapshot_id": null,
"source_volid": null,
"status": "creating",
"updated_at": null,
"user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
"volume_type": "__DEFAULT__",
"group_id": null,
"provider_id": null,
"service_uuid": null,
"shared_targets": true,
"cluster_name": null,
"volume_type_id": "5fed9d7c-401d-46e2-8e80-f30c70cb7e1d",
"consumes_quota": true
}
}
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
created_at (Optional) |
query |
string |
Filters reuslts by a time that resources are created at with time comparison operators: gt/gte/eq/neq/lt/lte. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. The ±hh:mm value, if included, returns the time zone as an offset from UTC. New in version 3.60 |
consumes_quota (Optional) |
query |
boolean |
Filters results by New in version 3.65 |
updated_at (Optional) |
query |
string |
Filters reuslts by a time that resources are updated at with time comaprison operators: gt/gte/eq/neq/lt/lte. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. The ±hh:mm value, if included, returns the time zone as an offset from UTC. New in version 3.60 |
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. |
volumes_links (Optional) |
body |
array |
The volume links. |
count (Optional) |
body |
integer |
The total count of requested resource before pagination is applied. New in version 3.45 |
Response Example¶
{
"volumes": [
{
"id": "efa54464-8fab-47cd-a05a-be3e6b396188",
"links": [
{
"href": "http://127.0.0.1:37097/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/efa54464-8fab-47cd-a05a-be3e6b396188",
"rel": "self"
},
{
"href": "http://127.0.0.1:37097/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/efa54464-8fab-47cd-a05a-be3e6b396188",
"rel": "bookmark"
}
],
"name": null
}
]
}
Shows details for a volume.
Preconditions
The volume must exist.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 (Optional) |
body |
string |
The volume migration status. Admin only. |
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. For example: [
{
'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
'attached_at': '2019-09-30T19:30:34.000000',
'host_name': null,
'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
'device': '/dev/vda',
'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
}
]
|
links |
body |
array |
The volume links. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
os-vol-host-attr:host (Optional) |
body |
string |
Current back-end of the volume.
Host format is |
encrypted |
body |
boolean |
If true, this volume is encrypted. |
encryption_key_id (Optional) |
body |
string |
The UUID of the encryption key. Only included for encrypted volumes. New in version 3.64 |
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. |
os-vol-tenant-attr:tenant_id |
body |
string |
The project ID which the volume belongs to. |
os-vol-mig-status-attr:migstat (Optional) |
body |
string |
The status of this volume migration (None means that a migration is not currently in progress). |
metadata |
body |
object |
A |
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 unless a larger size is requested. |
volume |
body |
object |
A |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
os-vol-mig-status-attr:name_id (Optional) |
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 |
volume_type |
body |
string |
The associated volume type name for the volume. |
volume_type_id |
body |
object |
The associated volume type ID for the volume. New in version 3.63 |
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. New in version 3.48 |
shared_targets |
body |
boolean |
An indicator whether the back-end hosting the volume utilizes shared_targets or not. Default=True. New in version 3.48 Available until version 3.68 |
shared_targets |
body |
boolean |
An indicator whether the host connecting the volume should lock for the
whole attach/detach process or not. New in version 3.69 |
cluster_name (Optional) |
body |
string |
The cluster name of volume backend. New in version 3.61 |
provider_id (Optional) |
body |
string |
The provider ID for the volume. The value is either a string set by the
driver or New in version 3.21 |
group_id (Optional) |
body |
string |
The ID of the group. New in version 3.13 |
consumes_quota (Optional) |
body |
boolean |
Whether this resource consumes quota or not. Resources that not counted for quota usage are usually temporary internal resources created to perform an operation. New in version 3.65 |
Response Example (v3.65)¶
{
"volume": {
"attachments": [],
"availability_zone": "nova",
"bootable": "false",
"consistencygroup_id": null,
"created_at": "2018-11-29T06:50:07.770785",
"description": null,
"encrypted": false,
"id": "f7223234-1afc-4d19-bfa3-d19deb6235ef",
"links": [
{
"href": "http://127.0.0.1:45839/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/f7223234-1afc-4d19-bfa3-d19deb6235ef",
"rel": "self"
},
{
"href": "http://127.0.0.1:45839/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/f7223234-1afc-4d19-bfa3-d19deb6235ef",
"rel": "bookmark"
}
],
"metadata": {},
"migration_status": null,
"multiattach": false,
"name": null,
"os-vol-host-attr:host": null,
"os-vol-mig-status-attr:migstat": null,
"os-vol-mig-status-attr:name_id": null,
"os-vol-tenant-attr:tenant_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
"replication_status": null,
"size": 10,
"snapshot_id": null,
"source_volid": null,
"status": "creating",
"updated_at": null,
"user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
"volume_type": "__DEFAULT__",
"provider_id": null,
"group_id": null,
"service_uuid": null,
"shared_targets": true,
"cluster_name": null,
"volume_type_id": "5fed9d7c-401d-46e2-8e80-f30c70cb7e1d",
"consumes_quota": true
}
}
Updates a volume.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 (Optional) |
body |
object |
One or more metadata key and value pairs that are associated with the volume. |
Request Example¶
{
"volume": {
"name": "vol-003",
"description": "This is yet, another volume.",
"metadata": {
"name": "metadata0"
}
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
migration_status (Optional) |
body |
string |
The volume migration status. Admin only. |
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. For example: [
{
'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
'attached_at': '2019-09-30T19:30:34.000000',
'host_name': null,
'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
'device': '/dev/vda',
'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
}
]
|
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 |
A |
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 unless a larger size is requested. |
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 name for the volume. |
volume_type_id |
body |
object |
The associated volume type ID for the volume. New in version 3.63 |
group_id (Optional) |
body |
string |
The ID of the group. New in version 3.13 |
provider_id (Optional) |
body |
string |
The provider ID for the volume. The value is either a string set by the
driver or New in version 3.21 |
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. New in version 3.48 |
shared_targets |
body |
boolean |
An indicator whether the back-end hosting the volume utilizes shared_targets or not. Default=True. New in version 3.48 Available until version 3.68 |
shared_targets |
body |
boolean |
An indicator whether the host connecting the volume should lock for the
whole attach/detach process or not. New in version 3.69 |
cluster_name (Optional) |
body |
string |
The cluster name of volume backend. New in version 3.61 |
consumes_quota (Optional) |
body |
boolean |
Whether this resource consumes quota or not. Resources that not counted for quota usage are usually temporary internal resources created to perform an operation. New in version 3.65 |
Response Example (v3.65)¶
{
"volume": {
"attachments": [],
"availability_zone": "nova",
"bootable": "false",
"consistencygroup_id": null,
"created_at": "2018-11-29T06:59:23.679903",
"description": "This is yet, another volume.",
"encrypted": false,
"id": "8b2459d1-0059-4e14-a89f-dfa73a452af6",
"links": [
{
"href": "http://127.0.0.1:41467/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/8b2459d1-0059-4e14-a89f-dfa73a452af6",
"rel": "self"
},
{
"href": "http://127.0.0.1:41467/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/8b2459d1-0059-4e14-a89f-dfa73a452af6",
"rel": "bookmark"
}
],
"metadata": {
"name": "metadata0"
},
"migration_status": null,
"multiattach": false,
"name": "vol-003",
"replication_status": null,
"size": 10,
"snapshot_id": null,
"source_volid": null,
"status": "creating",
"updated_at": null,
"user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
"volume_type": "__DEFAULT__",
"group_id": null,
"provider_id": null,
"service_uuid": null,
"shared_targets": true,
"cluster_name": null,
"volume_type_id": "5fed9d7c-401d-46e2-8e80-f30c70cb7e1d",
"consumes_quota": true
}
}
Deletes a volume.
Preconditions
Volume status must be
available
,in-use
,error
,error_restoring
,error_extending
,error_managing
, and must not bemigrating
,attached
,awaiting-transfer
, belong to a group, have snapshots or be disassociated from snapshots after volume transfer.The
cascade
option can be passed in the request if you want all snapshots of this volume to be deleted automatically, which should allow the volume deletion to succeed.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 becomeserror_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.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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) |
query |
boolean |
Remove any snapshots along with the volume. Default=False. |
force (Optional) |
query |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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": "metadata1"
}
}
Deletes metadata for a volume.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. Available since API microversion 3.12.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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.42
the volume status must beavailable
. Starting with microversion3.42
, attached volumes with statusin-use
may be able to be extended depending on policy and backend volume and compute driver constraints in the cloud. Note thatreserved
is 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
extending
while 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-actions
API in the Compute service.
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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). |
Request Example¶
{
"os-extend": {
"new_size": 3
}
}
Specify the os-extend_volume_completion
action in the request body.
Complete extending an attached volume that has been left in status
extending
after notifying the compute agent.
Depending on the value of the error
parameter, the extend operation
will be either rolled back or finalized.
Preconditions
The volume must have the status
extending
.The volume’s admin metadata must contain a set of keys indicating that Cinder was waiting for external feedback on the success of the operation.
Asynchronous Postconditions
If the error
parameter is false
or missing, and the extend operation
was successfully finalized, the volume status will be in-use
.
Otherwise, the volume status will be error_extending
.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
volume_id |
path |
string |
The UUID of the volume. |
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
os-extend_volume_completion |
body |
object |
The |
error (Optional) |
body |
boolean |
Used to indicate that the extend operation has failed outside of cinder. |
Request Example¶
{
"os-extend_volume_completion": {
"error": false
}
}
Administrator only. Resets the status, attach status, revert to snapshot,
and migration status for a volume. Specify the os-reset_status
action in
the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-reset_status |
body |
object |
The |
status |
body |
string |
The volume status. |
migration_status (Optional) |
body |
string |
The volume migration status. Admin only. |
attach_status (Optional) |
body |
string |
The volume attach status. |
Request Example¶
{
"os-reset_status": {
"status": "available",
"attach_status": "detached",
"migration_status": "migrating"
}
}
Revert a volume to its latest snapshot, this API only support reverting a
detached volume, and the volume status must be available
.
Available since API microversion 3.40
.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
403 - Forbidden |
Policy does not allow current user to do this operation. |
404 - Not Found |
The requested resource could not be found. |
409 - Conflict |
This resource has an action in progress that would conflict with this request. |
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. |
revert |
body |
object |
The |
snapshot_id |
body |
string |
The UUID of the snapshot. The API reverts the volume with this snapshot. |
Request Example¶
{
"revert": {
"snapshot_id": "5aa119a8-d25b-45a7-8d1b-88e127885635"
}
}
Sets the image metadata for a volume. Specify the os-set_image_metadata
action in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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_image_metadata |
body |
object |
The |
metadata |
body |
object |
The image metadata to add to the volume as a set of metadata key and value pairs. |
Request Example¶
{
"os-set_image_metadata": {
"metadata": {
"image_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
"image_name": "image",
"kernel_id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
"ramdisk_id": "somedisk"
}
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
metadata |
body |
object |
The image metadata to add to the volume as a set of metadata key and value pairs. |
Response Example¶
{
"metadata": {
"kernel_id": "6ff710d2-942b-4d6b-9168-8c9cc2404ab1",
"container_format": "bare",
"min_ram": "0",
"ramdisk_id": "somedisk",
"disk_format": "qcow2",
"image_name": "image",
"image_id": "5137a025-3c5f-43c1-bc64-5f41270040a5",
"checksum": "f8ab98ff5e73ebab884d80c9dc9c7290",
"min_disk": "0",
"size": "13267968"
}
}
Removes image metadata, by key, from a volume. Specify the
os-unset_image_metadata
action in the request body and the key
for the
metadata key and value pair that you want to remove.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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-unset_image_metadata |
body |
object |
The |
key |
body |
string |
The metadata key name for the metadata that you want to remove. |
Request Example¶
{
"os-unset_image_metadata": {
"key": "ramdisk_id"
}
}
Shows image metadata for a volume.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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-show_image_metadata (Optional) |
body |
object |
The |
Request Example¶
{
"os-show_image_metadata": {}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
metadata |
body |
object |
The image metadata to add to the volume as a set of metadata key and value pairs. |
Response Example¶
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
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
orhost_name
.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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
.
For security reasons (see bug #2004555), regardless of the policy defaults, the Block Storage API rejects REST API calls manually made from users with a 409 status code if completing the request could pose a risk, which happens if all of these happen:
The request comes from a user
There’s an instance uuid in provided attachment or in the volume’s attachment
VM exists in Nova
Instance has the volume attached
Attached volume in instance is using the attachment
Calls coming from other OpenStack services (like the Compute Service) are always accepted.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
409 - Conflict |
This resource has an action in progress that would conflict with this request. |
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"
}
}
Removes a volume from Block Storage management without removing the back-end
storage object that is associated with it. Specify the os-unmanage
action
in the request body.
Preconditions
Volume status must be
available
.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-unmanage |
body |
object |
The |
Request Example¶
{
"os-unmanage": {}
}
Forces a volume to detach. Specify the os-force_detach
action in the
request body.
Rolls back an unsuccessful detach operation after you disconnect the volume.
Policy defaults enable only users with the administrative role to
perform this operation. Cloud providers can change these permissions
through the volume_extension:volume_admin_actions:force_detach
rule in
the policy configuration file.
For security reasons (see bug #2004555), regardless of the policy defaults, the Block Storage API rejects REST API calls manually made from users with a 409 status code if completing the request could pose a risk, which happens if all of these happen:
The request comes from a user
There’s an instance uuid in provided attachment or in the volume’s attachment
VM exists in Nova
Instance has the volume attached
Attached volume in instance is using the attachment
Calls coming from other OpenStack services (like the Compute Service) are always accepted.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
409 - Conflict |
This resource has an action in progress that would conflict with this request. |
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-force_detach |
body |
object |
The |
attachment_id (Optional) |
body |
string |
The ID of the attachment. |
connector (Optional) |
body |
object |
The |
Request Example¶
{
"os-force_detach": {
"attachment_id": "d8777f54-84cf-4809-a679-468ffed56cf1",
"connector": {
"initiator": "iqn.2012-07.org.fake:01"
}
}
}
Change type of existing volume. Specify the os-retype
action in the request
body.
Change the volume type of existing volume, Cinder may migrate the volume to proper volume host according to the new volume type.
Retyping an in-use volume from a multiattach-capable type to a non-multiattach-capable type, or vice-versa, is not supported. It is generally not recommended to retype an in-use multiattach volume if that volume has more than one active read/write attachment.
Policy defaults enable only users with the administrative role or the owner of the volume to perform this operation. Cloud providers can change these permissions through the policy configuration file.
Retyping an unencrypted volume to the same size encrypted volume will most likely fail. Even though the volume is the same size as the source volume, the encrypted volume needs to store additional encryption information overhead. This results in the new volume not being large enough to hold all data.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-retype |
body |
object |
The |
new_type |
body |
string |
The new volume type that volume is changed with. |
migration_policy (Optional) |
body |
string |
Specify if the volume should be migrated when it is re-typed.
Possible values are Note If the volume is attached to a server instance and will be migrated, then by default policy only users with the administrative role should attempt the retype operation. A retype which involves a migration to a new host for an in-use encrypted volume is not supported. |
Request Example¶
{
"os-retype": {
"new_type": "dedup-tier-replicaton",
"migration_policy": "never"
}
}
Specify the os-migrate_volume
action in the request body.
Migrates a volume to the specified host. Starting with the 3.16 microversion a cluster can be specified instead of a host.
It is generally not recommended to migrate an in-use multiattach volume if that volume has more than one active read/write attachment.
Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy configuration file.
Preconditions
The volume
status
must beavailable
orin-use
.The volume
migration_status
must beNone
,deleting
,error
, orsuccess
.The volume
replication_status
must beNone
,disabled
ornot-capable
.The migration must happen to another host (or cluster) from which the volume currently resides.
The volume must not be a member of a group.
The volume must not have snapshots.
Asynchronous Postconditions
On success, the volume status
will return to its original status of
available
or in-use
and the migration_status
will be success
.
On failure, the migration_status
will be error
. In the case of failure,
if lock_volume
was true and the volume was originally available
when
it was migrated, the status
will go back to available
.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
volume_id |
path |
string |
The UUID of the volume. |
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
os-migrate_volume |
body |
object |
The |
host (Optional) |
body |
string |
The target host for the volume migration. Host format is |
force_host_copy (Optional) |
body |
boolean |
If false (the default), rely on the volume backend driver to perform the migration, which might be optimized. If true, or the volume driver fails to migrate the volume itself, a generic host-based migration is performed. |
lock_volume (Optional) |
body |
boolean |
If true, migrating an |
cluster (Optional) |
body |
string |
The target cluster for the volume migration. Cluster format is
New in version 3.16 |
Request Example¶
{
"os-migrate_volume": {
"host": "node1@lvm"
}
}
Specify the os-migrate_volume_completion
action in the request body.
Complete the migration of a volume, updating the new volume in the DB,
returning the status
of the new volume to that of the original volume
and finally deleting the original volume.
Preconditions
Both the original and new volume
migration_status
must beNone
or both must be set to a nonNone
value.Additionally when set the new volume
migration_status
must take the form oftarget:VOLUME_UUID
where VOLUME_UUID is the original volume UUID.
Asynchronous Postconditions
On success, the volume status
will return to its original status of
available
or in-use
and the migration_status
will be success
.
On failure, the migration_status
will be error
.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
volume_id |
path |
string |
The UUID of the volume. |
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
os-migrate_volume_completion |
body |
object |
The |
new_volume |
body |
string |
The UUID of the new volume. |
error (Optional) |
body |
boolean |
Used to indicate if an error has occured elsewhere that requires clean up. |
Request Example¶
{
"os-migrate_volume_completion": {
"new_volume": "2b955850-f177-45f7-9f49-ecb2c256d161",
"error": false,
}
}
Attempts force-delete of volume, regardless of state. Specify the
os-force_delete
action in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-force_delete |
body |
string |
The |
Request Example¶
{
"os-force_delete": {}
}
Update the bootable status for a volume, mark it as a bootable volume. Specify
the os-set_bootable
action in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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. See valid boolean values |
Request Example¶
{
"os-set_bootable": {
"bootable": "True"
}
}
Uploads the specified volume to image service.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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. See valid boolean values |
disk_format (Optional) |
body |
string |
Disk format for the new image. Default is raw. (Note: volumes of an encrypted volume type can only be uploaded in raw format.) |
container_format (Optional) |
body |
string |
Container format for the new image. Default is bare. (Note: Volumes of an encrypted volume type must use a bare container format.) |
visibility (Optional) |
body |
string |
The visibility property of the new image. Default is private. New in version 3.1 |
protected (Optional) |
body |
boolean |
Whether the new image is protected. Default=False. See valid boolean values New in version 3.1 |
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. New in version 3.1 |
protected (Optional) |
body |
boolean |
Whether the new image is protected. Default=False. See valid boolean values New in version 3.1 |
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 name for the volume. |
Response Example¶
{
"os-volume_upload_image": {
"container_format": "bare",
"disk_format": "raw",
"display_description": null,
"id": "3a81fdac-e8ae-4e61-b6a2-2e14ff316f19",
"image_id": "de75b74e-7f0d-4b59-a263-bd87bfc313bd",
"image_name": "test",
"protected": false,
"size": 1,
"status": "uploading",
"updated_at": "2017-06-05T08:44:28.000000",
"visibility": "private",
"volume_type": null
}
}
Mark volume as reserved. Specify the os-reserve
action in the
request body.
Preconditions
Volume status must be
available
.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-reserve |
body |
object |
The |
Request Example¶
{
"os-reserve": {}
}
Unmark volume as reserved. Specify the os-unreserve
action in
the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-unreserve |
body |
object |
The |
Request Example¶
{
"os-unreserve":{}
}
Update volume status to ‘detaching’.. Specify the os-begin_detaching
action
in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-begin_detaching |
body |
object |
The |
Request Example¶
{
"os-begin_detaching": {}
}
Roll back volume status to ‘in-use’. Specify the os-roll_detaching
action
in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-roll_detaching |
body |
object |
The |
Request Example¶
{
"os-roll_detaching": {}
}
Terminate volume attachment. Specify the os-terminate_connection
action in the request body.
Preconditions
Volume status must be
in-use
.
For security reasons (see bug #2004555), regardless of the policy defaults, the Block Storage API rejects REST API calls manually made from users with a 409 status code if completing the request could pose a risk, which happens if all of these happen:
The request comes from a user
There’s an instance uuid in the volume’s attachment
VM exists in Nova
Instance has the volume attached
Attached volume in instance is using the attachment
Calls coming from other OpenStack services (like the Compute Service) are always accepted.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
409 - Conflict |
This resource has an action in progress that would conflict with this request. |
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-terminate_connection (Optional) |
body |
object |
The |
connector |
body |
object |
The |
Request Example¶
{
"os-terminate_connection": {
"connector": {
"platform": "x86_64",
"host": "node2",
"do_local_attach": false,
"ip": "192.168.13.101",
"os_type": "linux2",
"multipath": false,
"initiator": "iqn.1994-05.com.redhat:d16cbb5d31e5"
}
}
}
Initialize volume attachment. Specify the os-initialize_connection
action in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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-initialize_connection |
body |
object |
The |
connector |
body |
object |
The |
Request Example¶
{
"os-initialize_connection": {
"connector": {
"platform":"x86_64",
"host": "node2",
"do_local_attach": false,
"ip": "192.168.13.101",
"os_type": "linux2",
"multipath": false,
"initiator": "iqn.1994-05.com.redhat:d16cbb5d31e5"
}
}
}
Enables or disables update of volume to read-only access mode.
Specify the os-update_readonly_flag
action in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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-update_readonly_flag |
body |
object |
The |
readonly |
body |
boolean |
Enables or disables read-only access mode. This value can be True, true, False, false. |
Request Example¶
{
"os-update_readonly_flag": {
"readonly": true
}
}
Re-image a volume with a specific image. Specify the os-reimage
action
in the request body.
A volume in available
or error
status can be re-imaged directly. To
re-image a volume in reserved
status, you must include the
reimage_reserved
parameter set to true
.
Note
Image signature verification is currently unsupported when re-imaging a volume.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
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. |
image_id |
body |
string |
The uuid for the new image. |
reimage_reserved (Optional) |
body |
boolean |
Normally, volumes to be re-imaged are in |
os-reimage |
body |
object |
The New in version 3.68 |
Request Example¶
{
"os-reimage": {
"image_id": "71543ced-a8af-45b6-a5c4-a46282108a90",
"reimage_reserved": false
}
}
Volume manage extension (manageable_volumes)¶
Creates or lists volumes by using existing storage instead of allocating new storage.
Creates a Block Storage volume by using existing storage rather than allocating new storage.
The caller must specify a reference to an existing storage volume in the ref parameter in the request. Although each storage driver might interpret this reference differently, the driver should accept a reference structure that contains either a source-id or source-name element, if possible.
The API chooses the size of the volume by rounding up the size of the existing storage volume to the next gibibyte (GiB).
You cannot manage a volume to an encrypted volume type.
Prior to microversion 3.16 host field was required, with the possibility of defining the cluster it is no longer required, but we must have either a host or a cluster field but we cannot have them both with values.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
volume |
body |
object |
A |
description (Optional) |
body |
string |
The volume description. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
bootable (Optional) |
body |
boolean |
Enables or disables the bootable attribute. You can boot an instance from a bootable volume. See valid boolean values |
volume_type (Optional) |
body |
string |
The name of the volume type. |
name (Optional) |
body |
string |
The volume name. |
host (Optional) |
body |
string |
The OpenStack Block Storage host where the existing resource resides. Optional only if cluster field is provided. |
cluster (Optional) |
body |
string |
The OpenStack Block Storage cluster where the resource resides. Optional only if host field is provided. |
ref |
body |
object |
A reference to the existing volume. The internal structure of this reference depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver. |
metadata (Optional) |
body |
object |
One or more metadata key and value pairs to be associated with the new volume. |
Request Example¶
{
"volume": {
"host": "geraint-VirtualBox",
"ref": {
"source-name": "existingLV",
"source-id": "1234"
},
"name": "New Volume",
"availability_zone": "az2",
"description": "Volume imported from existingLV",
"volume_type": null,
"bootable": true,
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
}
{
"volume": {
"host": null,
"cluster": "cluster@backend",
"ref": {
"source-name": "existingLV",
"source-id": "1234"
},
"name": "New Volume",
"availability_zone": "az2",
"description": "Volume imported from existingLV",
"volume_type": null,
"bootable": true,
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
volume |
body |
object |
A |
status |
body |
string |
The volume status. |
migration_status (Optional) |
body |
string |
The volume migration status. Admin only. |
user_id |
body |
string |
The UUID of the user. |
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. For example: [
{
'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
'attached_at': '2019-09-30T19:30:34.000000',
'host_name': null,
'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
'device': '/dev/vda',
'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
}
]
|
links |
body |
array |
The volume links. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
bootable |
body |
string |
Enables or disables the bootable attribute. You can boot an instance from a bootable volume. |
encrypted |
body |
boolean |
If true, this volume is encrypted. |
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 |
description (Optional) |
body |
string |
The volume description. |
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 |
volume_type |
body |
object |
A |
name |
body |
string |
The volume name. |
replication_status |
body |
string |
The volume replication status. |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
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 unless a larger size is requested. |
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. |
multiattach |
body |
boolean |
If true, this volume can attach to more than one instance. |
metadata |
body |
object |
A |
id |
body |
string |
The UUID of the volume. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
Response Example¶
{
"volume": {
"attachments": [],
"availability_zone": "az2",
"bootable": "false",
"created_at": "2014-07-18T00:12:54.000000",
"description": "Volume imported from existingLV",
"encrypted": "false",
"id": "23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
"links": [
{
"href": "http://10.0.2.15:8776/v3/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
"rel": "self"
},
{
"href": "http://10.0.2.15:8776/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
"rel": "bookmark"
}
],
"metadata": {
"key1": "value1",
"key2": "value2"
},
"name": "New Volume",
"os-vol-tenant-attr:tenant_id": "87c8522052ca4eed98bc672b4c1a3ddb",
"size": 0,
"snapshot_id": "null",
"source_volid": "null",
"status": "creating",
"user_id": "eae1472b5fc5496998a3d06550929e7e",
"volume_type": "null"
}
}
Search a volume backend and list summary of volumes which are available to manage.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
offset (Optional) |
query |
integer |
Used in conjunction with |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
host |
path |
string |
The name of the host that hosts the storage back end. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
manageable-volumes |
body |
list |
A list of manageable volumes. |
safe_to_manage |
body |
boolean |
If the resource can be managed or not. |
reference |
body |
object |
Some information for the resource. |
source-name |
body |
string |
The resource’s name. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
Response Example¶
{
"manageable-volumes": [
{
"safe_to_manage": false,
"reference": {
"source-name": "volume-3a81fdac-e8ae-4e61-b6a2-2e14ff316f19"
},
"size": 1
},
{
"safe_to_manage": true,
"reference": {
"source-name": "lvol0"
},
"size": 1
}
]
}
Search a volume backend and list detail of volumes which are available to manage.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
offset (Optional) |
query |
integer |
Used in conjunction with |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
host (Optional) |
query |
string |
Filter the service list result by host name of the service. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
manageable-volumes |
body |
list |
A list of manageable volumes. |
cinder_id |
body |
string |
The UUID of the resource in Cinder. |
safe_to_manage |
body |
boolean |
If the resource can be managed or not. |
reason_not_safe |
body |
string |
The reason why the resource can’t be managed. |
reference |
body |
object |
Some information for the resource. |
source-name |
body |
string |
The resource’s name. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
extra_info |
body |
string |
More information about the resource. |
Response Example¶
{
"manageable-volumes": [
{
"cinder_id": "9ba5bb53-4a18-4b38-be06-992999da338d",
"reason_not_safe": "already managed",
"reference": {
"source-name": "volume-9ba5bb53-4a18-4b38-be06-992999da338d"
},
"safe_to_manage": false,
"size": 1,
"extra_info": null
},
{
"cinder_id": null,
"reason_not_safe": null,
"reference": {
"source-name": "lvol0"
},
"safe_to_manage": true,
"size": 1,
"extra_info": null
}
]
}
Volume snapshots (snapshots)¶
A snapshot is a point-in-time copy of the data that a volume contains.
When you create, list, or delete snapshots, these status values are possible:
Snapshot statuses
Status |
Description |
creating |
The snapshot is being created. |
available |
The snapshot is ready to use. |
backing-up |
The snapshot is being backed up. |
deleting |
The snapshot is being deleted. |
error |
A snapshot creation error occurred. |
deleted |
The snapshot has been deleted. |
unmanaging |
The snapshot is being unmanaged. |
restoring |
The snapshot is being restored to a volume. |
error_deleting |
A snapshot deletion error occurred. |
Lists all Block Storage snapshots, 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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
consumes_quota (Optional) |
query |
boolean |
Filters results by New in version 3.65 |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
status |
body |
string |
The status for the snapshot. |
os-extended-snapshot-attributes:progress |
body |
string |
A percentage value for the build progress. |
description |
body |
string |
A description for the snapshot. |
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 |
name (Optional) |
body |
string |
The name of the object. |
user_id |
body |
string |
The UUID of the user. New in version 3.41 |
volume_id |
body |
string |
If the snapshot was created from a volume, the volume ID. |
os-extended-snapshot-attributes:project_id |
body |
string |
The UUID of the owning project. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
id |
body |
string |
The snapshot UUID. |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
count (Optional) |
body |
integer |
The total count of requested resource before pagination is applied. New in version 3.45 |
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 |
snapshots_links (Optional) |
body |
array |
Links for the snapshot. |
group_snapshot_id |
body |
string |
The ID of the group snapshot. New in version 3.14 |
consumes_quota (Optional) |
body |
boolean |
Whether this resource consumes quota or not. Resources that not counted for quota usage are usually temporary internal resources created to perform an operation. New in version 3.65 |
Response Example (v3.65)¶
{
"snapshots": [
{
"created_at": "2019-03-11T16:24:36.464445",
"description": "Daily backup",
"id": "d0083dc5-8795-4c1a-bc9c-74f70006c205",
"metadata": {
"key": "v3"
},
"name": "snap-001",
"os-extended-snapshot-attributes:progress": "0%",
"os-extended-snapshot-attributes:project_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
"size": 10,
"status": "creating",
"updated_at": null,
"volume_id": "7acd675e-4e06-4653-af9f-2ecd546342d6",
"group_snapshot_id": null,
"user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
"consumes_quota": true
}
]
}
Creates a volume snapshot, which is a point-in-time, complete copy of a volume. You can create a volume from a snapshot.
Prior to API version 3.66, a ‘force’ flag was required to create a snapshot of an in-use volume, but this is no longer the case. From API version 3.66, the ‘force’ flag is invalid when passed in a volume snapshot request. (For backward compatibility, however, a ‘force’ flag with a value evaluating to True is silently ignored.)
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot |
body |
object |
A |
volume_id |
body |
string |
The UUID of the volume. |
name |
body |
string |
The name of the snapshot. |
description (Optional) |
body |
string |
A description for the snapshot. Default is
|
force (Optional) |
body |
boolean |
Indicates whether to snapshot, even if the volume
is attached. Default is |
metadata (Optional) |
body |
object |
One or more metadata key and value pairs for the snapshot. |
Request Example¶
{
"snapshot": {
"name": "snap-001",
"description": "Daily backup",
"volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"force": true,
"metadata": {
"key": "v3"
}
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
status |
body |
string |
The status for the snapshot. |
description |
body |
string |
A description for the snapshot. |
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 |
name |
body |
string |
The name of the snapshot. |
snapshot |
body |
object |
A |
user_id |
body |
string |
The UUID of the user. New in version 3.41 |
volume_id |
body |
string |
If the snapshot was created from a volume, the volume ID. |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
id |
body |
string |
The snapshot UUID. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
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 |
group_snapshot_id |
body |
string |
The ID of the group snapshot. New in version 3.14 |
consumes_quota (Optional) |
body |
boolean |
Whether this resource consumes quota or not. Resources that not counted for quota usage are usually temporary internal resources created to perform an operation. New in version 3.65 |
Response Example (v3.65)¶
{
"snapshot": {
"created_at": "2019-03-11T16:24:34.469003",
"description": "Daily backup",
"id": "b36476e5-d18b-47f9-ac69-4818cb43ee21",
"metadata": {
"key": "v3"
},
"name": "snap-001",
"size": 10,
"status": "creating",
"updated_at": null,
"volume_id": "d291b81c-6e40-4525-8231-90aa1588121e",
"group_snapshot_id": null,
"user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
"consumes_quota": true
}
}
Lists all Block Storage snapshots, with summary information, that the project can access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
consumes_quota (Optional) |
query |
boolean |
Filters results by New in version 3.65 |
with_count (Optional) |
query |
boolean |
Whether to show New in version 3.45 |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
status |
body |
string |
The status for the snapshot. |
description |
body |
string |
A description for the snapshot. |
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 |
name (Optional) |
body |
string |
The name of the object. |
volume_id |
body |
string |
If the snapshot was created from a volume, the volume ID. |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
id |
body |
string |
The snapshot UUID. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
count (Optional) |
body |
integer |
The total count of requested resource before pagination is applied. New in version 3.45 |
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 |
snapshots_links (Optional) |
body |
array |
Links for the snapshot. |
Response Example¶
{
"snapshots": [
{
"created_at": "2019-03-11T16:29:08.973832",
"description": "Daily backup",
"id": "2c228773-50eb-422d-be7e-b5c6ced0c7a9",
"metadata": {
"key": "v3"
},
"name": "snap-001",
"size": 10,
"status": "creating",
"updated_at": null,
"volume_id": "428ec041-b999-40d8-8a54-9e98b19406cc"
}
]
}
Shows metadata for a snapshot.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
Response Example¶
{
"metadata": {
"key": "v3"
}
}
Updates metadata for a snapshot.
Creates or replaces metadata items that match keys. Does not modify items that are not in the request.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
Request Example¶
{
"metadata": {
"key": "v3"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
Response Example¶
{
"metadata": {
"key": "value"
}
}
Replaces all the snapshot’s metadata with the key-value pairs in the request.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
Request Example¶
{
"metadata": {
"new_key": "new_value"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
Response Example¶
{
"metadata": {
"new_key": "new_value"
}
}
Shows details for a snapshot.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
status |
body |
string |
The status for the snapshot. |
os-extended-snapshot-attributes:progress |
body |
string |
A percentage value for the build progress. |
description |
body |
string |
A description for the snapshot. |
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 |
name (Optional) |
body |
string |
The name of the object. |
snapshot |
body |
object |
A |
user_id |
body |
string |
The UUID of the user. New in version 3.41 |
volume_id |
body |
string |
If the snapshot was created from a volume, the volume ID. |
os-extended-snapshot-attributes:project_id |
body |
string |
The UUID of the owning project. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
id |
body |
string |
The snapshot UUID. |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
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 |
group_snapshot_id |
body |
string |
The ID of the group snapshot. New in version 3.14 |
consumes_quota (Optional) |
body |
boolean |
Whether this resource consumes quota or not. Resources that not counted for quota usage are usually temporary internal resources created to perform an operation. New in version 3.65 |
Response Example (v3.65)¶
{
"snapshot": {
"created_at": "2019-03-12T04:42:00.809352",
"description": "Daily backup",
"id": "4a584cae-e4ce-429b-9154-d4c9eb8fda4c",
"metadata": {
"key": "v3"
},
"name": "snap-001",
"os-extended-snapshot-attributes:progress": "0%",
"os-extended-snapshot-attributes:project_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
"size": 10,
"status": "creating",
"updated_at": null,
"volume_id": "b72c48f1-64b7-4cd8-9745-b12e0be82d37",
"group_snapshot_id": null,
"user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
"consumes_quota": true
}
}
Updates a snapshot.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
snapshot |
body |
object |
A |
description (Optional) |
body |
string |
A description for the snapshot. Default is
|
name (Optional) |
body |
string |
The name of the snapshot. |
Request Example¶
{
"snapshot": {
"name": "snap-002",
"description": "This is yet, another snapshot."
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
status |
body |
string |
The status for the snapshot. |
description |
body |
string |
A description for the snapshot. |
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 |
name (Optional) |
body |
string |
The name of the object. |
snapshot |
body |
object |
A |
id |
body |
string |
The snapshot UUID. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
volume_id |
body |
string |
If the snapshot was created from a volume, the volume ID. |
user_id |
body |
string |
The UUID of the user. New in version 3.41 |
metadata |
body |
object |
One or more metadata key and value pairs for the snapshot, if any. |
group_snapshot_id |
body |
string |
The ID of the group snapshot. New in version 3.14 |
consumes_quota (Optional) |
body |
boolean |
Whether this resource consumes quota or not. Resources that not counted for quota usage are usually temporary internal resources created to perform an operation. New in version 3.65 |
Response Example (v3.65)¶
{
"snapshot": {
"created_at": "2019-03-12T04:53:53.426591",
"description": "This is yet, another snapshot.",
"id": "43666194-8e72-451a-b7bb-54fef763b2b8",
"metadata": {
"key": "v3"
},
"name": "snap-002",
"size": 10,
"status": "creating",
"updated_at": null,
"volume_id": "070c942d-9909-42e9-a467-7a781f150c58",
"group_snapshot_id": null,
"user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
"consumes_quota": true
}
}
Deletes a snapshot.
Preconditions:
Snapshot status must be
available
orerror
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
403 - Forbidden |
Policy does not allow current user to do this operation. |
404 - Not Found |
The requested resource could not be found. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
Shows metadata for a snapshot for a specific key.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
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 snapshot. |
Response Example¶
{
"meta": {
"key": "v3"
}
}
Deletes metadata for a snapshot.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
key |
path |
string |
The metadata key name for the metadata that you want to remove. |
Update metadata for a snapshot for a specific key.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
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 snapshot. |
Request Example¶
{
"meta": {
"key": "new_value"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
meta |
body |
object |
The metadata key and value pair for the snapshot. |
Response Example¶
{
"meta": {
"key": "new_value"
}
}
Snapshot actions (snapshots, action)¶
Administrator only, depending on policy settings. Resets, updates status for a snapshot.
Resets the status. Specify the os-reset_status
action in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
os-reset_status |
body |
object |
The |
status |
body |
string |
The status for the snapshot. |
Request Example¶
{
"os-reset_status": {
"status": "available"
}
}
Update fields related to the status of a snapshot.
Specify the os-update_snapshot_status
action in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
os-update_snapshot_status |
body |
object |
The |
status |
body |
string |
The status for the snapshot. |
progress (Optional) |
body |
string |
A percentage value for snapshot build progress. |
Request Example¶
{
"os-update_snapshot_status": {
"status": "creating",
"progress": "80%"
}
}
Attempts to force delete a snapshot, regardless of state. Specify the
os-force_delete
action in the request body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot_id |
path |
string |
The UUID of the snapshot. |
os-force_delete |
body |
string |
The |
Request Example¶
{
"os-force_delete": {}
}
Snapshot manage extension (manageable_snapshots)¶
Creates or lists snapshots by using existing storage instead of allocating new storage.
Creates a snapshot by using existing storage rather than allocating new storage.
The caller must specify a reference to an existing storage volume in the ref parameter in the request. Although each storage driver might interpret this reference differently, the driver should accept a reference structure that contains either a source-id or source-name element, if possible.
The API chooses the size of the snapshot by rounding up the size of the existing snapshot to the next gibibyte (GiB).
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
snapshot |
body |
object |
A |
description (Optional) |
body |
string |
A description for the snapshot. Default is
|
metadata (Optional) |
body |
object |
One or more metadata key and value pairs for the snapshot. |
name (Optional) |
body |
string |
The name of the snapshot. Default is |
ref |
body |
object |
A reference to the existing volume. The internal structure of this reference depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver. |
volume_id |
body |
string |
The UUID of the volume. |
Request Example¶
{
"snapshot": {
"description": null,
"metadata": null,
"ref": {
"source-name": "lvol0"
},
"name": null,
"volume_id": "1df34919-aba7-4a1b-a614-3b409d71ac03"
}
}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
snapshot |
body |
object |
A |
status |
body |
string |
The status for the snapshot. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
metadata (Optional) |
body |
object |
One or more metadata key and value pairs for the snapshot. |
name (Optional) |
body |
string |
The name of the snapshot. Default is |
volume_id |
body |
string |
The UUID of the 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 |
description |
body |
string |
A description for the snapshot. |
id |
body |
string |
The UUID of the object. |
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 |
Response Example¶
{
"snapshot": {
"created_at": "2018-09-26T03:45:03.893592",
"description": "this is a new snapshot",
"id": "b6314a71-9d3d-439a-861d-b790def0d693",
"metadata": {
"manage-snap-meta1": "value1",
"manage-snap-meta2": "value2",
"manage-snap-meta3": "value3"
},
"name": "new_snapshot",
"size": 1,
"status": "creating",
"updated_at": "null",
"volume_id": "1df34919-aba7-4a1b-a614-3b409d71ac03"
}
}
Search a volume backend and list summary of snapshots which are available to manage.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
offset (Optional) |
query |
integer |
Used in conjunction with |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
host (Optional) |
query |
string |
Filter the service list result by host name of the service. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
manageable-snapshots |
body |
list |
A list of manageable snapshots. |
source_reference |
body |
object |
The snapshot’s origin volume information. |
safe_to_manage |
body |
boolean |
If the resource can be managed or not. |
reference |
body |
object |
Some information for the resource. |
source-name |
body |
string |
The resource’s name. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
Response Example¶
{
"manageable-snapshots": [
{
"source_reference": {
"source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
},
"safe_to_manage": true,
"reference": {
"source-name": "lvol0"
},
"size": 1
},
{
"source_reference": {
"source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
},
"safe_to_manage": false,
"reference": {
"source-name": "_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
},
"size": 1
}
]
}
Search a volume backend and list detail of snapshots which are available to manage.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
offset (Optional) |
query |
integer |
Used in conjunction with |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
host (Optional) |
query |
string |
Filter the service list result by host name of the service. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
manageable-snapshots |
body |
list |
A list of manageable snapshots. |
cinder_id |
body |
string |
The UUID of the resource in Cinder. |
source_reference |
body |
object |
The snapshot’s origin volume information. |
safe_to_manage |
body |
boolean |
If the resource can be managed or not. |
reason_not_safe |
body |
string |
The reason why the resource can’t be managed. |
reference |
body |
object |
Some information for the resource. |
source-name |
body |
string |
The resource’s name. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
extra_info |
body |
string |
More information about the resource. |
Response Example¶
{
"manageable-snapshots": [
{
"cinder_id": null,
"reason_not_safe": null,
"reference": {
"source-name": "lvol0"
},
"source_reference": {
"source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
},
"safe_to_manage": true,
"size": 1,
"extra_info": null
},
{
"cinder_id": "d0c84570-a01f-4579-9789-5e9f266587cd",
"reason_not_safe": "already managed",
"reference": {
"source-name":"_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
},
"source_reference": {
"source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
},
"safe_to_manage": false,
"size": 1,
"extra_info": null
}
]
}
Volume transfer¶
Transfers a volume from one user to another user.
Accepts a volume transfer.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
transfer_id |
path |
string |
The unique identifier for a volume transfer. |
auth_key |
body |
string |
The authentication key for the volume transfer. |
Request Example¶
{
"accept": {
"auth_key": "9266c59563c84664"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
transfer |
body |
object |
The volume transfer object. |
volume_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the volume transfer. |
links |
body |
array |
Links for the volume transfer. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"transfer": {
"id": "0a840aa1-8f8f-4042-86d7-09d8ca755272",
"links": [
{
"href": "http://127.0.0.1:46057/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/0a840aa1-8f8f-4042-86d7-09d8ca755272",
"rel": "self"
},
{
"href": "http://127.0.0.1:46057/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/0a840aa1-8f8f-4042-86d7-09d8ca755272",
"rel": "bookmark"
}
],
"name": "first volume",
"volume_id": "e56dee53-e565-40f4-9c6b-b983f74a2aa5"
}
}
Creates a volume transfer.
Preconditions
The volume
status
must beavailable
Transferring encrypted volumes is not supported
If the volume has snapshots, those snapshots must be
available
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
transfer |
body |
object |
The volume transfer object. |
name (Optional) |
body |
string |
The name of the object. |
volume_id |
body |
string |
The UUID of the volume. |
Request Example¶
{
"transfer": {
"volume_id": "c86b9af4-151d-4ead-b62c-5fb967af0e37",
"name": "first volume"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
auth_key |
body |
string |
The authentication key for the volume transfer. |
links |
body |
array |
Links for the volume transfer. |
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_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the volume transfer. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"transfer": {
"auth_key": "dbccabcdbad19e07",
"created_at": "2019-03-20T09:29:46.743632",
"id": "3d26db0c-69cd-42e4-ae42-7552759ab361",
"links": [
{
"href": "http://127.0.0.1:40345/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/3d26db0c-69cd-42e4-ae42-7552759ab361",
"rel": "self"
},
{
"href": "http://127.0.0.1:40345/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/3d26db0c-69cd-42e4-ae42-7552759ab361",
"rel": "bookmark"
}
],
"name": "first volume",
"volume_id": "59fe2097-931b-4ceb-b74b-f862ff3b6277"
}
}
Lists volume transfers.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the volume transfer. |
links |
body |
array |
Links for the volume transfer. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"transfers": [
{
"id": "a0f13fb9-904c-41c8-8c2e-495cac61a78f",
"links": [
{
"href": "http://127.0.0.1:45017/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/a0f13fb9-904c-41c8-8c2e-495cac61a78f",
"rel": "self"
},
{
"href": "http://127.0.0.1:45017/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/a0f13fb9-904c-41c8-8c2e-495cac61a78f",
"rel": "bookmark"
}
],
"name": "first volume",
"volume_id": "e72d7454-0234-4e3e-99e9-560d1ff79a71"
}
]
}
Shows details for a volume transfer.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
transfer_id |
path |
string |
The unique identifier for a volume transfer. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
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_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the volume transfer. |
links |
body |
array |
Links for the volume transfer. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"transfer": {
"created_at": "2019-03-20T09:29:48.732953",
"id": "5055b9c2-527b-47ef-bdd6-62e1130f511f",
"links": [
{
"href": "http://127.0.0.1:41845/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/5055b9c2-527b-47ef-bdd6-62e1130f511f",
"rel": "self"
},
{
"href": "http://127.0.0.1:41845/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/5055b9c2-527b-47ef-bdd6-62e1130f511f",
"rel": "bookmark"
}
],
"name": "first volume",
"volume_id": "8cdd62be-4bea-4b7c-bb53-c0b5424ee2af"
}
}
Deletes a volume transfer.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
transfer_id |
path |
string |
The unique identifier for a volume transfer. |
Lists volume transfers, with details.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
---|---|---|---|
transfers |
body |
array |
List of transfer details. |
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_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the volume transfer. |
links |
body |
array |
Links for the volume transfer. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"transfers": [
{
"created_at": "2019-03-20T09:29:52.758407",
"id": "1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
"links": [
{
"href": "http://127.0.0.1:37479/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
"rel": "self"
},
{
"href": "http://127.0.0.1:37479/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
"rel": "bookmark"
}
],
"name": "first volume",
"volume_id": "acb5a860-3f17-4c35-9484-394a12dd7dfc"
}
]
}
Volume transfers (volume-transfers) (3.55 or later)¶
Transfers a volume from one user to another user. This is the new transfer APIs with microversion 3.55.
Accepts a volume transfer.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
413 - Request Entity Too Large |
This operation cannot be completed. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
transfer_id |
path |
string |
The unique identifier for a volume transfer. |
auth_key |
body |
string |
The authentication key for the volume transfer. |
Request Example¶
{
"accept": {
"auth_key": "f318375a4400391e"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
transfer |
body |
object |
The volume transfer object. |
volume_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the object. |
links |
body |
array |
Links for the volume transfer. |
name |
body |
string |
The name of the volume transfer. |
Response Example¶
{
"transfer": {
"id": "9e395d6d-5138-423c-a63c-7b62c6265fa1",
"links": [
{
"href": "http://127.0.0.1:39369/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/9e395d6d-5138-423c-a63c-7b62c6265fa1",
"rel": "self"
},
{
"href": "http://127.0.0.1:39369/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/9e395d6d-5138-423c-a63c-7b62c6265fa1",
"rel": "bookmark"
}
],
"name": "first volume",
"volume_id": "8d19f929-f1da-4a76-acad-9ed17da0981e"
}
}
Creates a volume transfer.
Preconditions
The volume
status
must beavailable
Transferring encrypted volumes is not supported
If the volume has snapshots, those snapshots must be
available
unlessno_snapshots=True
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
transfer |
body |
object |
The volume transfer object. |
name (Optional) |
body |
string |
The name of the object. |
volume_id |
body |
string |
The UUID of the volume. |
no_snapshots (Optional) |
body |
boolean |
Transfer volume without snapshots. Defaults to False if not specified. New in version 3.55 |
Request Example¶
{
"transfer": {
"volume_id": "80d68197-b67e-4c8e-bbb9-030b2581f921",
"name": "first volume",
"no_snapshots": false
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
auth_key |
body |
string |
The authentication key for the volume transfer. |
links |
body |
array |
Links for the volume transfer. |
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_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the object. |
name (Optional) |
body |
string |
The name of the object. |
destination_project_id (Optional) |
body |
string |
Records the destination project_id after volume transfer. New in version 3.57 |
source_project_id (Optional) |
body |
string |
Records the source project_id before volume transfer. New in version 3.57 |
accepted (Optional) |
body |
boolean |
Records if this transfer was accepted or not. New in version 3.57 |
no_snapshots (Optional) |
body |
boolean |
Transfer volume without snapshots. Defaults to False if not specified. New in version 3.55 |
Response Example¶
{
"transfer": {
"accepted": false,
"auth_key": "e2cb02466324813c",
"created_at": "2023-06-12T21:21:38.392033",
"destination_project_id": null,
"id": "94bae1a0-83fb-496c-9cd2-800d8237ab0d",
"links": [
{
"href": "http://127.0.0.1:45193/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/94bae1a0-83fb-496c-9cd2-800d8237ab0d",
"rel": "self"
},
{
"href": "http://127.0.0.1:45193/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/94bae1a0-83fb-496c-9cd2-800d8237ab0d",
"rel": "bookmark"
}
],
"name": "first volume",
"no_snapshots": false,
"source_project_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
"volume_id": "202eead8-3c82-41e1-914f-83638a063be9"
}
}
Lists volume transfers.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 New in version 3.59 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. Default is
New in version 3.59 |
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 New in version 3.59 |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the New in version 3.59 |
offset (Optional) |
query |
integer |
Used in conjunction with New in version 3.59 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the New in version 3.59 |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
volume_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the object. |
links |
body |
array |
Links for the volume transfer. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"transfers": [
{
"id": "a0f13fb9-904c-41c8-8c2e-495cac61a78f",
"links": [
{
"href": "http://127.0.0.1:45017/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/a0f13fb9-904c-41c8-8c2e-495cac61a78f",
"rel": "self"
},
{
"href": "http://127.0.0.1:45017/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/a0f13fb9-904c-41c8-8c2e-495cac61a78f",
"rel": "bookmark"
}
],
"name": "first volume",
"volume_id": "e72d7454-0234-4e3e-99e9-560d1ff79a71"
}
]
}
Shows details for a volume transfer.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
transfer_id |
path |
string |
The unique identifier for a volume transfer. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
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_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the object. |
links |
body |
array |
Links for the volume transfer. |
name (Optional) |
body |
string |
The name of the object. |
destination_project_id (Optional) |
body |
string |
Records the destination project_id after volume transfer. New in version 3.57 |
source_project_id (Optional) |
body |
string |
Records the source project_id before volume transfer. New in version 3.57 |
accepted (Optional) |
body |
boolean |
Records if this transfer was accepted or not. New in version 3.57 |
no_snapshots (Optional) |
body |
boolean |
Transfer volume without snapshots. Defaults to False if not specified. New in version 3.55 |
Response Example¶
{
"transfer": {
"accepted": false,
"created_at": "2023-06-22T08:28:17.647081",
"destination_project_id": null,
"id": "3d79fbda-8d9c-4da3-a016-e5612fcb7f65",
"links": [
{
"href": "http://127.0.0.1:34593/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/3d79fbda-8d9c-4da3-a016-e5612fcb7f65",
"rel": "self"
},
{
"href": "http://127.0.0.1:34593/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/3d79fbda-8d9c-4da3-a016-e5612fcb7f65",
"rel": "bookmark"
}
],
"name": "first volume",
"no_snapshots": false,
"source_project_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
"volume_id": "7e31e409-2a7a-4ea6-aa0b-bc7be056fc57"
}
}
Deletes a volume transfer.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
transfer_id |
path |
string |
The unique identifier for a volume transfer. |
Lists volume transfers, with details.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
---|---|---|---|
transfers |
body |
array |
List of transfer details. |
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_id |
body |
string |
The UUID of the volume. |
id |
body |
string |
The UUID of the object. |
links |
body |
array |
Links for the volume transfer. |
name (Optional) |
body |
string |
The name of the object. |
destination_project_id (Optional) |
body |
string |
Records the destination project_id after volume transfer. New in version 3.57 |
source_project_id (Optional) |
body |
string |
Records the source project_id before volume transfer. New in version 3.57 |
accepted (Optional) |
body |
boolean |
Records if this transfer was accepted or not. New in version 3.57 |
Response Example¶
{
"transfers": [
{
"created_at": "2019-03-20T09:29:52.758407",
"id": "1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
"links": [
{
"href": "http://127.0.0.1:37479/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
"rel": "self"
},
{
"href": "http://127.0.0.1:37479/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
"rel": "bookmark"
}
],
"name": "first volume",
"volume_id": "acb5a860-3f17-4c35-9484-394a12dd7dfc"
}
]
}
Attachments (attachments)¶
Lists all, lists all with details, shows details for, creates, and deletes attachment.
Note
Everything except for Complete attachment is new as of the 3.27 microversion. Complete attachment is new as of the 3.44 microversion.
When you create, list, update, or delete attachment, the possible status values are:
VolumeAttachment statuses
Status |
Description |
attached |
A volume is attached for the attachment. |
attaching |
A volume is attaching for the attachment. |
detached |
A volume is detached for the attachment. |
reserved |
A volume is reserved for the attachment. |
error_attaching |
A volume is error attaching for the attachment. |
error_detaching |
A volume is error detaching for the attachment. |
deleted |
The attachment is deleted. |
Deletes an attachment.
For security reasons (see bug #2004555) the Block Storage API rejects REST API calls manually made from users with a 409 status code if there is a Nova instance currently using the attachment, which happens when all the following conditions are met:
Attachment has an instance uuid
VM exists in Nova
Instance has the volume attached
Attached volume in instance is using the attachment
Calls coming from other OpenStack services (like the Compute Service) are always accepted.
Available starting in the 3.27 microversion.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
409 - Conflict |
This resource has an action in progress that would conflict with this request. |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
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 |
body |
string |
The time when attachment is detached. |
connection_info |
body |
object |
The connection info used for server to connect the volume. |
attached_at |
body |
string |
The time when attachment is attached. |
attach_mode |
body |
string |
The attach mode of attachment, read-only (‘ro’) or read-and-write (‘rw’), default is ‘rw’. |
instance |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
body |
string |
The time when attachment is detached. |
connection_info |
body |
object |
The connection info used for server to connect the volume. |
attached_at |
body |
string |
The time when attachment is attached. |
attach_mode |
body |
string |
The attach mode of attachment, read-only (‘ro’) or read-and-write (‘rw’), default is ‘rw’. |
instance |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
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 (Optional) |
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. |
mode (Optional) |
body |
string |
The attach mode of attachment, acceptable values are read-only (‘ro’) and read-and-write (‘rw’). New in version 3.54 |
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 |
body |
string |
The time when attachment is detached. |
connection_info |
body |
object |
The connection info used for server to connect the volume. |
attached_at |
body |
string |
The time when attachment is attached. |
attach_mode |
body |
string |
The attach mode of attachment, read-only (‘ro’) or read-and-write (‘rw’), default is ‘rw’. |
instance |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
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 |
body |
string |
The time when attachment is detached. |
connection_info |
body |
object |
The connection info used for server to connect the volume. |
attached_at |
body |
string |
The time when attachment is attached. |
attach_mode |
body |
string |
The attach mode of attachment, read-only (‘ro’) or read-and-write (‘rw’), default is ‘rw’. |
instance |
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.
Response codes¶
Success¶
Code |
Reason |
---|---|
204 - No Content |
Request fulfilled but service does not return anything. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
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": {}
}
Availability zones (os-availability-zone)¶
List availability zone information.
List availability zone information.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
Response Parameter¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
body |
string |
The UUID of the project. |
availabilityZoneInfo |
body |
array |
The list of availability zone information. |
zoneName |
body |
string |
The availability zone name. |
zoneState |
body |
object |
The current state of the availability zone. |
available |
body |
boolean |
Whether the availability zone is available for use. |
Response Example¶
{
"availabilityZoneInfo": [{
"zoneState": {
"available": true
},
"zoneName": "nova"
}]
}
Back-end storage pools¶
Administrator only. Lists all back-end storage pools that are known to the scheduler service.
Lists all back-end storage pools. Since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
detail (Optional) |
query |
boolean |
Indicates whether to show pool details or only
pool names in the response. Set to |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
pools |
body |
array |
List of storage pools. |
updated |
body |
string |
The date and time stamp when the extension was last updated. |
QoS_support |
body |
boolean |
The quality of service (QoS) support. |
name |
body |
string |
The name of the backend pool. |
total_capacity_gb |
body |
string |
The total capacity for the back-end volume, in
GBs. A valid value is a string, such as |
volume_backend_name |
body |
string |
The name of the back-end volume. |
capabilities |
body |
object |
The capabilities for the back end. The value is
either |
free_capacity_gb |
body |
string |
The amount of free capacity for the back-end
volume, in GBs. A valid value is a string, such as |
driver_version |
body |
string |
The driver version. |
reserved_percentage |
body |
integer |
The percentage of the total capacity that is reserved for the internal use by the back end. |
storage_protocol |
body |
string |
The storage back end for the back-end volume. For
example, |
Response Example¶
{
"pools": [
{
"name": "pool1",
"capabilities": {
"updated": "2014-10-28T00:00:00-00:00",
"total_capacity_gb": 1024,
"free_capacity_gb": 100,
"volume_backend_name": "pool1",
"reserved_percentage": 0,
"driver_version": "1.0.0",
"storage_protocol": "iSCSI",
"QoS_support": false
}
},
{
"name": "pool2",
"capabilities": {
"updated": "2014-10-28T00:00:00-00:00",
"total_capacity_gb": 512,
"free_capacity_gb": 200,
"volume_backend_name": "pool2",
"reserved_percentage": 0,
"driver_version": "1.0.1",
"storage_protocol": "iSER",
"QoS_support": true
}
}
]
}
Backups (backups)¶
A backup is a full copy of a volume stored in an external service. The service can be configured. The only supported service is Object Storage. A backup can subsequently be restored from the external service to either the same volume that the backup was originally taken from or to a new volume.
When you create, list, or delete backups, these status values are possible:
Backup statuses
Status |
Description |
creating |
The backup is being created. |
available |
The backup is ready to restore to a volume. |
deleting |
The backup is being deleted. |
error |
A backup error occurred. |
restoring |
The backup is being restored to a volume. |
error_deleting |
An error occurred while deleting the backup. |
If an error occurs, you can find more information about the error
in the fail_reason
field for the backup.
Lists Block Storage backups, with details, to which the project has access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
---|---|---|---|
backups |
body |
array |
A list of |
status |
body |
string |
The backup status. Refer to Backup statuses table for the possible status value. |
object_count |
body |
integer |
The number of objects in the backup. |
fail_reason |
body |
string |
If the backup failed, the reason for the failure. Otherwise, null. |
description (Optional) |
body |
string |
The backup description or null. |
links |
body |
array |
Links for the backup. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
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 |
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 |
name |
body |
string |
The backup name. |
has_dependent_backups (Optional) |
body |
boolean |
If this value is |
volume_id |
body |
string |
The UUID of the volume. |
container (Optional) |
body |
string |
The container name or null. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
id |
body |
string |
The UUID of the backup. |
is_incremental (Optional) |
body |
boolean |
Indicates whether the backup mode is incremental.
If this value is |
data_timestamp |
body |
string |
The time when the data on the volume was first saved. If it is
a backup from volume, it will be the same as |
snapshot_id (Optional) |
body |
string |
The UUID of the source volume snapshot. |
os-backup-project-attr:project_id |
body |
string |
The UUID of the owning project. New in version 3.18 |
count (Optional) |
body |
integer |
The total count of requested resource before pagination is applied. New in version 3.45 |
metadata (Optional) |
body |
object |
The backup metadata key value pairs. New in version 3.43 |
user_id |
body |
string |
The UUID of the project owner. New in version 3.56 |
encryption_key_id (Optional) |
body |
string |
The UUID of the encryption key. Only included for encrypted volumes. New in version 3.64 |
backup_links (Optional) |
body |
array |
An array containing an object with the following fields:
|
Response Example¶
{
"backups": [
{
"availability_zone": null,
"container": null,
"created_at": "2023-07-10T13:23:21.178739",
"data_timestamp": "2023-07-10T13:23:21.178739",
"description": "Test backup",
"fail_reason": null,
"has_dependent_backups": false,
"id": "7ab823f7-1174-4447-9a76-863ae2dcf372",
"is_incremental": false,
"links": [
{
"href": "http://127.0.0.1:44197/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/7ab823f7-1174-4447-9a76-863ae2dcf372",
"rel": "self"
},
{
"href": "http://127.0.0.1:44197/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/7ab823f7-1174-4447-9a76-863ae2dcf372",
"rel": "bookmark"
}
],
"name": "backup001",
"object_count": 0,
"size": 10,
"snapshot_id": null,
"status": "creating",
"updated_at": "2023-07-10T13:23:21.189552",
"volume_id": "9fc31617-303d-4b52-826e-b598cca40419"
}
]
}
Shows details for a backup.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup_id |
path |
string |
The UUID for a backup. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
backup |
body |
object |
A |
status |
body |
string |
The backup status. Refer to Backup statuses table for the possible status value. |
object_count |
body |
integer |
The number of objects in the backup. |
container (Optional) |
body |
string |
The container name or null. |
description (Optional) |
body |
string |
The backup description or null. |
links |
body |
array |
Links for the backup. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
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 |
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 |
name |
body |
string |
The backup name. |
has_dependent_backups (Optional) |
body |
boolean |
If this value is |
volume_id |
body |
string |
The UUID of the volume. |
fail_reason |
body |
string |
If the backup failed, the reason for the failure. Otherwise, null. |
size |
body |
integer |
The size of the volume, in gibibytes (GiB). |
backup |
body |
object |
A |
id |
body |
string |
The UUID of the backup. |
is_incremental (Optional) |
body |
boolean |
Indicates whether the backup mode is incremental.
If this value is |
data_timestamp |
body |
string |
The time when the data on the volume was first saved. If it is
a backup from volume, it will be the same as |
snapshot_id (Optional) |
body |
string |
The UUID of the source volume snapshot. |
os-backup-project-attr:project_id |
body |
string |
The UUID of the owning project. New in version 3.18 |
metadata (Optional) |
body |
object |
The backup metadata key value pairs. New in version 3.43 |
user_id |
body |
string |
The UUID of the project owner. New in version 3.56 |
encryption_key_id (Optional) |
body |
string |
The UUID of the encryption key. Only included for encrypted volumes. New in version 3.64 |
Response Example¶
{
"backup": {
"availability_zone": null,
"container": null,
"created_at": "2023-06-23T11:56:02.509831",
"data_timestamp": "2023-06-23T11:56:02.509831",
"description": "Test backup",
"fail_reason": null,
"has_dependent_backups": false,
"id": "6a122f4b-d2f6-448f-aeb5-68bae5ff8358",
"is_incremental": false,
"links": [
{
"href": "http://127.0.0.1:46627/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/6a122f4b-d2f6-448f-aeb5-68bae5ff8358",
"rel": "self"
},
{
"href": "http://127.0.0.1:46627/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/6a122f4b-d2f6-448f-aeb5-68bae5ff8358",
"rel": "bookmark"
}
],
"name": "backup001",
"object_count": 0,
"size": 10,
"snapshot_id": null,
"status": "creating",
"updated_at": "2023-06-23T11:56:02.512426",
"volume_id": "49a784cf-b759-4594-acdf-5238ee50976b"
}
}
Deletes a backup.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup_id |
path |
string |
The UUID for a backup. |
Restores a Block Storage backup to an existing or new Block Storage volume.
The name parameter will work only if a new volume is created.
If UUID is specified, the backup will be restored to the specified volume. The specified volume has the following requirements:
the specified volume status is
available
.the size of specified volume must be equal to or greater than the size of backup.
If no existing volume UUID is provided, the backup will be restored to a new volume matching the size and name of the originally backed up volume. In this case, if the name parameter is provided, it will be used as the name of the new volume.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
413 - Request Entity Too Large |
This operation cannot be completed. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup_id |
path |
string |
The UUID for a backup. |
restore |
body |
object |
A |
name (Optional) |
body |
string |
The volume name. |
volume_id (Optional) |
body |
string |
The UUID of the volume to which you want to restore a backup. |
Request Example¶
{
"restore": {
"name": "vol-01",
"volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
restore |
body |
object |
A |
backup_id |
path |
string |
The UUID for a backup. |
volume_id |
body |
string |
The UUID of the volume. |
volume_name |
body |
string |
The volume name. |
Response Example¶
{
"restore": {
"backup_id": "2ef47aee-8844-490c-804d-2a8efe561c65",
"volume_id": "795114e8-7489-40be-a978-83797f2c1dd3",
"volume_name": "volume01"
}
}
Creates a Block Storage backup from a volume or snapshot.
The status of the volume must be available
or if the force
flag is
used, backups of in-use
volumes may also be created.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup |
body |
object |
A |
volume_id |
body |
string |
The UUID of the volume that you want to back up. |
container (Optional) |
body |
string |
The container name or null. |
description (Optional) |
body |
string |
The backup description or null. |
incremental (Optional) |
body |
boolean |
The backup mode. A valid value is |
force (Optional) |
body |
boolean |
Indicates whether to backup, even if the volume
is attached. Default is |
name (Optional) |
body |
string |
The name of the Volume Backup. |
snapshot_id (Optional) |
body |
string |
The UUID of the source snapshot that you want to back up. |
metadata (Optional) |
body |
object |
The backup metadata key value pairs. New in version 3.43 |
availability_zone (Optional) |
body |
string |
The backup availability zone key value pair. New in version 3.51 |
Request Example¶
{
"backup": {
"container": null,
"description": "Test backup",
"name": "backup001",
"volume_id": "0aa67a0c-7339-4be6-b5d5-2afe21ca270c",
"incremental": false,
"snapshot_id": null,
"force": false
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
backup |
body |
object |
A |
id |
body |
string |
The UUID of the backup. |
links |
body |
array |
Links for the backup. |
name |
body |
string |
The backup name. |
metadata (Optional) |
body |
object |
The backup metadata key value pairs. New in version 3.43 |
Response Example¶
{
"backup": {
"id": "b1f41f9b-741e-4992-a246-b97de7e6e87e",
"links": [
{
"href": "http://127.0.0.1:40797/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/b1f41f9b-741e-4992-a246-b97de7e6e87e",
"rel": "self"
},
{
"href": "http://127.0.0.1:40797/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/b1f41f9b-741e-4992-a246-b97de7e6e87e",
"rel": "bookmark"
}
],
"name": "backup001"
}
}
Update a Block Storage backup. This API is available since v3.9.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup_id |
path |
string |
The UUID for a backup. |
backup |
body |
object |
A |
description (Optional) |
body |
string |
The backup description or null. |
name (Optional) |
body |
string |
The name of the Volume Backup. |
metadata (Optional) |
body |
object |
The backup metadata key value pairs. New in version 3.43 |
Request Example¶
{
"backup":{
"name":"backup001",
"description": "this is a backup"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
backup |
body |
object |
A |
id |
body |
string |
The UUID of the backup. |
links |
body |
array |
Links for the backup. |
name |
body |
string |
The backup name. |
metadata (Optional) |
body |
object |
The backup metadata key value pairs. New in version 3.43 |
Response Example¶
{
"backup": {
"id": "06d5db4f-1f80-4a71-99a6-99368cfb8f8e",
"links": [
{
"href": "http://127.0.0.1:45187/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/06d5db4f-1f80-4a71-99a6-99368cfb8f8e",
"rel": "self"
},
{
"href": "http://127.0.0.1:45187/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/06d5db4f-1f80-4a71-99a6-99368cfb8f8e",
"rel": "bookmark"
}
],
"name": "backup001"
}
}
Lists Block Storage backups to which the project has access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
---|---|---|---|
backups |
body |
array |
A list of |
id |
body |
string |
The UUID of the backup. |
links |
body |
array |
Links for the backup. |
name |
body |
string |
The backup name. |
count (Optional) |
body |
integer |
The total count of requested resource before pagination is applied. New in version 3.45 |
backup_links (Optional) |
body |
array |
An array containing an object with the following fields:
|
Response Example¶
{
"backups": [
{
"id": "c26d9897-cace-44cc-ad0f-3a0d0b6d1450",
"links": [
{
"href": "http://127.0.0.1:46803/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/c26d9897-cace-44cc-ad0f-3a0d0b6d1450",
"rel": "self"
},
{
"href": "http://127.0.0.1:46803/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/c26d9897-cace-44cc-ad0f-3a0d0b6d1450",
"rel": "bookmark"
}
],
"name": "backup001"
}
]
}
Export information about a backup.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup_id |
path |
string |
The UUID for a backup. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
backup-record |
body |
object |
An object recording volume backup metadata, including |
backup_service |
body |
string |
The service used to perform the backup. |
backup_url |
body |
string |
An identifier string to locate the backup. |
Response Example¶
{
"backup-record": {
"backup_service": "cinder.backup.drivers.swift",
"backup_url": "eyJzdGF0"
}
}
Import information about a backup.
Response codes¶
Success¶
Code |
Reason |
---|---|
201 - Created |
Request has been fulfilled and new resource created. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
503 - Service Unavailable |
The service cannot handle the request right now. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup-record |
body |
object |
An object recording volume backup metadata, including |
backup_service |
body |
string |
The service used to perform the backup. |
backup_url |
body |
string |
An identifier string to locate the backup. |
Request Example¶
{
"backup-record": {
"backup_service": "cinder.backup.drivers.swift",
"backup_url": "eyJzdGF0"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
id |
body |
string |
The UUID of the backup. |
links |
body |
array |
Links for the backup. |
name |
body |
string |
The backup name. |
Response Example¶
{
"backup": {
"id": "deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
"links": [
{
"href": "http://localhost:8776/v3/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
"rel": "self"
},
{
"href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
"rel": "bookmark"
}
],
"name": null
}
}
Backup actions (backups, action)¶
Force-deletes a backup and reset status for a backup.
Force-deletes a backup. Specify the os-force_delete
action in the request
body.
This operation deletes the backup and any backup data.
The backup driver returns the 405
status code if it does not
support this operation.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
404 - Not Found |
The requested resource could not be found. |
405 - Method Not Allowed |
Method is not valid for this endpoint and resource. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup_id |
path |
string |
The UUID for a backup. |
os-force_delete |
body |
string |
The |
Request Example¶
{
"os-force_delete": {}
}
Reset a backup’s status. Specify the os-reset_status
action in the request
body.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
backup_id |
path |
string |
The UUID for a backup. |
os-reset_status |
body |
object |
The |
status |
body |
string |
The status for the backup. |
Request Example¶
{
"os-reset_status": {
"status": "available"
}
}
Capabilities for storage back ends (capabilities)¶
Shows capabilities for a storage back end.
Shows capabilities for a storage back end on the host.
The hostname
takes the form of hostname@volume_backend_name
.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
hostname |
path |
string |
The name of the host that hosts the storage back end. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
pool_name |
body |
string |
The name of the storage pool. |
description |
body |
string |
The capabilities description. |
volume_backend_name |
body |
string |
The name of the back-end volume. |
namespace |
body |
string |
The storage namespace, such as
|
visibility |
body |
string |
The volume type access. |
driver_version |
body |
string |
The driver version. |
vendor_name |
body |
string |
The name of the vendor. |
properties |
body |
object |
The backend volume capabilities list, which is consisted of cinder standard capabilities and vendor unique properties. |
storage_protocol |
body |
string |
The storage back end for the back-end volume. For
example, |
replication_targets |
body |
list |
A list of volume backends used to replicate volumes on this backend. |
display_name |
body |
string |
The name of volume backend capabilities. |
Response Example¶
{
"namespace": "OS::Storage::Capabilities::fake",
"vendor_name": "OpenStack",
"volume_backend_name": "lvmdriver-1",
"pool_name": "pool",
"driver_version": "2.0.0",
"storage_protocol": "iSCSI",
"display_name": "Capabilities of Cinder LVM driver",
"description": "These are volume type options provided by Cinder LVM driver, blah, blah.",
"visibility": "public",
"replication_targets": [],
"properties": {
"compression": {
"title": "Compression",
"description": "Enables compression.",
"type": "boolean"
},
"qos": {
"title": "QoS",
"description": "Enables QoS.",
"type": "boolean"
},
"replication": {
"title": "Replication",
"description": "Enables replication.",
"type": "boolean"
},
"thin_provisioning": {
"title": "Thin Provisioning",
"description": "Sets thin provisioning.",
"type": "boolean"
}
}
}
Clusters (clusters)¶
Administrator only. Lists all Cinder clusters, show cluster detail, enable or disable a cluster.
Each cinder service runs on a host computer (possibly multiple services on the same host; it depends how you decide to deploy cinder). In order to support High Availibility scenarios, services can be grouped into clusters where the same type of service (for example, cinder-volume) can run on different hosts so that if one host goes down the service is still available on a different host. Since there’s no point having these services sitting around doing nothing while waiting for some other host to go down (which is also known as Active/Passive mode), grouping services into clusters also allows cinder to support Active/Active mode in which all services in a cluster are doing work all the time.
Note
Currently the only service that can be grouped into clusters is
cinder-volume
.
Clusters are determined by the deployment configuration; that’s why there is no ‘create-cluster’ API call listed below. Once your services are up and running, however, you can use the following API requests to get information about your clusters and to update their status.
Disables a cluster. Specify the cluster by its name and optionally the binary name in the request body.
Available starting in the 3.7 microversion.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
name |
body |
string |
The name to identify the service cluster. |
binary (Optional) |
body |
string |
The binary name of the services in the cluster. |
disabled_reason (Optional) |
body |
string |
The reason for disabling a resource. |
Request Example¶
{
"name": "cluster_name",
"binary": "cinder-volume",
"disabled_reason": "for testing"
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
cluster |
body |
object |
A cluster object. |
name |
body |
string |
The name of the service cluster. |
binary |
body |
string |
The binary name of the services in the cluster. |
state |
body |
string |
The state of the cluster. One of |
status |
body |
string |
The status of the cluster. One of |
replication_status (Optional) |
body |
string |
The cluster replication status. Only included in responses if configured.
One of: |
disabled_reason (Optional) |
body |
string |
The reason for disabling a resource. |
Response Example¶
{
"cluster": {
"name": "cluster_name",
"state": "up",
"binary": "cinder-volume",
"status": "disabled",
"disabled_reason": "for testing",
"replication_status": "disable"
}
}
Enables a cluster. Specify the cluster by its name and optionally the binary name in the request body.
Available starting in the 3.7 microversion.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
name |
body |
string |
The name to identify the service cluster. |
binary (Optional) |
body |
string |
The binary name of the services in the cluster. |
Request Example¶
{
"name": "cluster_name",
"binary": "cinder-volume"
}
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
cluster |
body |
object |
A cluster object. |
name |
body |
string |
The name of the service cluster. |
binary |
body |
string |
The binary name of the services in the cluster. |
state |
body |
string |
The state of the cluster. One of |
status |
body |
string |
The status of the cluster. One of |
replication_status (Optional) |
body |
string |
The cluster replication status. Only included in responses if configured.
One of: |
disabled_reason (Optional) |
body |
string |
The reason for disabling a resource. |
Response Example¶
{
"cluster": {
"name": "cluster_name",
"state": "up",
"binary": "cinder-volume",
"status": "enabled",
"disabled_reason": null,
"replication_status": "enable"
}
}
Shows details for a cluster by its name and optionally the binary name.
Available starting in the 3.7 microversion.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
404 - Not Found |
The requested resource could not be found. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
cluster_name |
path |
string |
The name of the cluster. |
binary (Optional) |
query |
string |
Filter the cluster list result by binary name of the clustered services.
One of |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
cluster |
body |
object |
A cluster object. |
name |
body |
string |
The name of the service cluster. |
binary |
body |
string |
The binary name of the services in the cluster. |
state |
body |
string |
The state of the cluster. One of |
status |
body |
string |
The status of the cluster. One of |
num_hosts |
body |
integer |
The number of hosts in the cluster. |
num_down_hosts |
body |
integer |
The number of down hosts in the cluster. |
last_heartbeat |
body |
string |
The last periodic heartbeat received. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The |
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 |
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 |
disabled_reason (Optional) |
body |
string |
The reason for disabling a resource. |
replication_status (Optional) |
body |
string |
The cluster replication status. Only included in responses if configured.
One of: |
frozen (Optional) |
body |
boolean |
Whether the cluster is frozen or not. New in version 3.26 |
active_backend_id (Optional) |
body |
string |
The ID of active storage backend. Only in New in version 3.26 |
Response Example¶
{
"cluster": {
"name": "cluster_name",
"binary": "cinder-volume",
"state": "up",
"status": "enabled",
"disabled_reason": null,
"created_at": "2016-06-01T02:46:28",
"updated_at": "2016-06-01T02:46:28",
"num_down_hosts": 0,
"num_hosts": 0,
"last_heartbeat": "2016-06-01T02:46:28",
"replication_status": "enable",
"frozen": false,
"active_backend_id": "replication1"
}
}
Lists all clusters.
Available starting in the 3.7 microversion.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
name (Optional) |
query |
string |
Filter the cluster list result by cluster name. |
binary (Optional) |
query |
string |
Filter the cluster list result by binary name of the clustered services.
One of |
is_up (Optional) |
query |
boolean |
Filter the cluster list result by state. |
disabled (Optional) |
query |
boolean |
Filter the cluster list result by status. |
num_hosts (Optional) |
query |
integer |
Filter the cluster list result by number of hosts. |
num_down_hosts (Optional) |
query |
integer |
Filter the cluster list result by number of down hosts. |
replication_status (Optional) |
query |
string |
Filter the cluster list result by replication status. One of: |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
clusters |
body |
array |
A list of cluster objects. |
name |
body |
string |
The name of the service cluster. |
binary |
body |
string |
The binary name of the services in the cluster. |
state |
body |
string |
The state of the cluster. One of |
status |
body |
string |
The status of the cluster. One of |
replication_status (Optional) |
body |
string |
The cluster replication status. Only included in responses if configured.
One of: |
Response Example¶
{
"clusters": [
{
"name": "cluster_name",
"binary": "cinder-volume",
"state": "up",
"status": "enabled",
"replication_status": "enable"
}
]
}
Lists all clusters with details.
Available starting in the 3.7 microversion.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
---|---|
400 - Bad Request |
Some content in the request was invalid. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
name (Optional) |
query |
string |
Filter the cluster list result by cluster name. |
binary (Optional) |
query |
string |
Filter the cluster list result by binary name of the clustered services.
One of |
is_up (Optional) |
query |
boolean |
Filter the cluster list result by state. |
disabled (Optional) |
query |
boolean |
Filter the cluster list result by status. |
num_hosts (Optional) |
query |
integer |
Filter the cluster list result by number of hosts. |
num_down_hosts (Optional) |
query |
integer |
Filter the cluster list result by number of down hosts. |
replication_status (Optional) |
query |
string |
Filter the cluster list result by replication status. One of: |
frozen (Optional) |
body |
boolean |
Whether the cluster is frozen or not. New in version 3.26 |
active_backend_id (Optional) |
body |
string |
The ID of active storage backend. Only in New in version 3.26 |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
clusters |
body |
array |
A list of cluster objects. |
name |
body |
string |
The name of the service cluster. |
binary |
body |
string |
The binary name of the services in the cluster. |
state |
body |
string |
The state of the cluster. One of |
status |
body |
string |
The status of the cluster. One of |
num_hosts |
body |
integer |
The number of hosts in the cluster. |
num_down_hosts |
body |
integer |
The number of down hosts in the cluster. |
last_heartbeat |
body |
string |
The last periodic heartbeat received. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The |
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 |
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 |
disabled_reason (Optional) |
body |
string |
The reason for disabling a resource. |
replication_status (Optional) |
body |
string |
The cluster replication status. Only included in responses if configured.
One of: |
frozen (Optional) |
body |
boolean |
Whether the cluster is frozen or not. New in version 3.26 |
active_backend_id (Optional) |
body |
string |
The ID of active storage backend. Only in New in version 3.26 |
Response Example¶
{
"clusters": [
{
"name": "cluster_name",
"binary": "cinder-volume",
"state": "up",
"status": "enabled",
"disabled_reason": null,
"created_at": "2016-06-01T02:46:28",
"updated_at": "2016-06-01T02:46:28",
"num_down_hosts": 0,
"num_hosts": 0,
"last_heartbeat": "2016-06-01T02:46:28",
"replication_status": "enable",
"frozen": false,
"active_backend_id": "replication1"
}
]
}
Consistency groups (DEPRECATED)¶
Consistency groups enable you to create snapshots at the exact same point in time from multiple volumes. For example, a database might place its tables, logs, and configuration on separate volumes. To restore this database from a previous point in time, it makes sense to restore the logs, tables, and configuration together from the exact same point in time.
Use the policy configuration file to grant permissions for these actions to limit roles.
Lists consistency groups.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
---|---|---|---|
consistencygroups |
body |
array |
A list of consistency groups. |
id |
body |
string |
The UUID of the object. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"consistencygroups": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"name": "my-cg1"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"name": "my-cg2"
}
]
}
Creates a consistency group.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
consistencygroup |
body |
object |
A consistency group. |
description (Optional) |
body |
string |
The consistency group description. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
volume_types |
body |
string |
The list of volume types separated by commas. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type. For information about how to use volume types to create multiple-storage back ends, see Configure multiple-storage back ends. |
name (Optional) |
body |
string |
The consistency group name. |
Request Example¶
{
"consistencygroup": {
"name": "firstcg",
"description": "first consistency group",
"volume_types": "type1,type2",
"availability_zone": "az0"
}
}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
consistencygroup |
body |
object |
A consistency group. |
status |
body |
string |
The status of the consistency group. |
description |
body |
string |
The consistency group description. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
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_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. |
name (Optional) |
body |
string |
The consistency group name. |
id (Optional) |
body |
string |
The UUID of the consistency group. |
Response Example¶
{
"consistencygroup": {
"status": "error",
"description": "first consistency group",
"availability_zone": "az0",
"created_at": "2016-08-19T19:32:19.000000",
"volume_types": ["type1", "type2"],
"id": "63d1a274-de38-4384-a97e-475306777027",
"name": "firstcg"
}
}
Shows details for a consistency group.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
consistencygroup_id |
path |
string |
The ID of the consistency group. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
status |
body |
string |
The status of the consistency group. |
description |
body |
string |
The consistency group description. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
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_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. |
id |
body |
string |
The UUID of the object. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"consistencygroup": {
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"status": "available",
"availability_zone": "az1",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my-cg1",
"description": "my first consistency group",
"volume_types": [
"123456"
]
}
}
Creates a consistency group from source.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
consistencygroup-from-src |
body |
object |
The consistency group from source object. |
status |
body |
string |
The status of the consistency group. |
user_id |
body |
string |
The UUID of the user. |
description (Optional) |
body |
string |
The consistency group description. |
cgsnapshot_id (Optional) |
body |
string |
The UUID of the consistency group snapshot. |
source_cgid (Optional) |
body |
string |
The UUID of the source consistency group. |
project_id |
body |
string |
The UUID of the project. |
name (Optional) |
body |
string |
The name of the object. |
Request Example¶
{
"consistencygroup-from-src": {
"name": "firstcg",
"description": "first consistency group",
"cgsnapshot_id": "6f519a48-3183-46cf-a32f-41815f813986",
"source_cgid": "6f519a48-3183-46cf-a32f-41815f814546",
"user_id": "6f519a48-3183-46cf-a32f-41815f815555",
"project_id": "6f519a48-3183-46cf-a32f-41815f814444",
"status": "creating"
}
}
Deletes a consistency group.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
consistencygroup_id |
path |
string |
The ID of the consistency group. |
consistencygroup |
body |
object |
A consistency group. |
force (Optional) |
body |
boolean |
Indicates whether to backup, even if the volume
is attached. Default is |
Request Example¶
{
"consistencygroup": {
"force": false
}
}
Lists consistency groups with details.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is |
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 |
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 |
---|---|---|---|
consistencygroups |
body |
array |
A list of consistency groups. |
status |
body |
string |
The status of the consistency group. |
description |
body |
string |
The consistency group description. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
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_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. |
id |
body |
string |
The UUID of the object. |
name (Optional) |
body |
string |
The name of the object. |
Response Example¶
{
"consistencygroups": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"status": "available",
"availability_zone": "az1",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my-cg1",
"description": "my first consistency group",
"volume_types": [
"123456"
]
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"status": "error",
"availability_zone": "az2",
"created_at": "2015-09-16T09:31:15.000000",
"name": "my-cg2",
"description": "Edited description",
"volume_types": [
"234567"
]
}
]
}
Updates a consistency group.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
consistencygroup_id |
path |
string |
The ID of the consistency group. |
consistencygroup |
body |
object |
A consistency group. |
remove_volumes (Optional) |
body |
string |
One or more volume UUIDs, separated by commas, to remove from the volume group or consistency group. |
description (Optional) |
body |
string |
The consistency group description. |
add_volumes (Optional) |
body |
string |
One or more volume UUIDs, separated by commas, to add to the volume group or consistency group. |
name (Optional) |
body |
string |
The name of the object. |
Request Example¶
{
"consistencygroup": {
"name": "my_cg",
"description": "My consistency group",
"add_volumes": "volume-uuid-1,volume-uuid-2",
"remove_volumes": "volume-uuid-8,volume-uuid-9"
}
}
Consistency group snapshots (DEPRECATED)¶
Lists all, lists all with details, shows details for, creates, and deletes consistency group snapshots.
Deletes a consistency group snapshot.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
cgsnapshot_id |
path |
string |
The ID of the consistency group snapshot. |
Shows details for a consistency group snapshot.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
cgsnapshot_id |
path |
string |
The ID of the consistency group snapshot. |
Response Parameters¶
Name |
In |
Type |
Description |
---|---|---|---|
cgsnapshot |
body |
object |
A consistency group snapshot object. |
status (Optional) |
body |
string |
The |
description |
body |
string |
The consistency group snapshot description. |
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 |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
id |
body |
string |
The UUID of the object. |
name |
body |
string |
The consistency group snapshot name. |
Response Example¶
{
"cgsnapshot": {
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814444",
"status": "available",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my-cg1",
"description": "my first consistency group"
}
}
Lists all consistency group snapshots with details.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
---|---|---|---|
cgsnapshots |
body |
object |
A collection of |
status (Optional) |
body |
string |
The |
description |
body |
string |
The consistency group snapshot description. |
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 |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
id |
body |
string |
The UUID of the object. |
name |
body |
string |
The consistency group snapshot name. |
Response Example¶
{
"cgsnapshots": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814444",
"status": "available",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my-cg1",
"description": "my first consistency group"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"consistencygroup_id": "aed36625-a6d7-4681-ba59-c7ba3d18dddd",
"status": "error",
"created_at": "2015-09-16T09:31:15.000000",
"name": "my-cg2",
"description": "Edited description"
}
]
}
Lists all consistency group snapshots.
Response codes¶
Success¶
Code |
Reason |
---|---|
200 - OK |
Request was successful. |
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 |
---|---|---|---|
cgsnapshots |
body |
object |
A collection of |
id |
body |
string |
The UUID of the object. |
name |
body |
string |
The consistency group snapshot name. |
Response Example¶
{
"cgsnapshots": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"name": "my-cg1"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"name": "my-cg2"
}
]
}
Creates a consistency group snapshot.
Response codes¶
Success¶
Code |
Reason |
---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
cgsnapshot |
body |
object |
A consistency group snapshot object. |
name (Optional) |
body |
string |
The name of the snapshot. Default is |
consistencygroup_id |
body |
string |
The UUID of the consistency group. |
description (Optional) |
body |
string |
The consistency group snapshot description. |
Request Example¶
{
"cgsnapshot": {