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}/volumesGET /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
availablethrough API calls.With correct access, you can see the created volume in the storage system that OpenStack Block Storage manages.
Troubleshooting
If volume status remains
creatingor shows another error status, the request failed. Ensure you meet the preconditions then investigate the storage back end.Volume is not created in the storage system that OpenStack Block Storage manages.
The storage node needs enough free storage space to match the size of the volume creation request.
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
cascadeoption 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
deletingor becomeserror_deletingthe request failed. Ensure you meet the preconditions then investigate the storage back end.The volume managed by OpenStack Block Storage is not deleted from the storage system.
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.42the volume status must beavailable. Starting with microversion3.42, attached volumes with statusin-usemay be able to be extended depending on policy and backend volume and compute driver constraints in the cloud. Note thatreservedis not a valid state for extend.Sufficient amount of storage must exist to extend the volume.
The user quota must have sufficient volume storage.
Postconditions
If the request is processed successfully, the volume status will change to
extendingwhile the volume size is being extended.Upon successful completion of the extend operation, the volume status will go back to its original value.
Starting with microversion
3.42, when extending the size of an attached volume, the Block Storage service will notify the Compute service that an attached volume has been extended. The Compute service will asynchronously process the volume size change for the related server instance. This can be monitored using theGET /servers/{server_id}/os-instance-actionsAPI in the Compute service.
Troubleshooting
An
error_extendingvolume status indicates that the request failed. Ensure that you meet the preconditions and retry the request. If the request fails again, investigate the storage back end.
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_uuidorhost_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
statusmust beavailableorin-use.The volume
migration_statusmust beNone,deleting,error, orsuccess.The volume
replication_statusmust beNone,disabledornot-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_statusmust beNoneor both must be set to a nonNonevalue.Additionally when set the new volume
migration_statusmust take the form oftarget:VOLUME_UUIDwhere 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
availableorerror
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
statusmust beavailableTransferring 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
statusmust beavailableTransferring encrypted volumes is not supported
If the volume has snapshots, those snapshots must be
availableunlessno_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": {
"consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814546",
"name": "firstcg",
"description": "first consistency group",
"status": "creating"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
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. |
Services (os-services)¶
Administrator only. Lists all Cinder services, enables or disables a Cinder service, freeze or thaw the specified cinder-volume host, failover a replicating cinder-volume host.
Lists all Cinder services. Provides details why any services were disabled.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
host (Optional) |
query |
string |
Filter the service list result by host name of the service. |
binary (Optional) |
query |
string |
Filter the service list result by binary name of the service. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
services |
body |
array |
A list of service objects. |
binary |
body |
string |
The binary name of the service. |
disabled_reason |
body |
string |
The reason for disabling a resource. |
host |
body |
string |
The name of the host. |
state |
body |
string |
The state of the service. One of |
status |
body |
string |
The status of the service. One of |
frozen (Optional) |
body |
boolean |
The host is frozen or not. Only in |
updated_at |
body |
string |
The date and time stamp when the extension was last updated. |
zone |
body |
string |
The availability zone name. |
cluster (Optional) |
body |
string |
The cluster name. Only in New in version 3.7 |
replication_status (Optional) |
body |
string |
The volume service replication status. Only in |
active_backend_id (Optional) |
body |
string |
The ID of active storage backend. Only in |
backend_state (Optional) |
body |
string |
The state of storage backend. Only in |
Response Example¶
{
"services": [{
"status": "enabled",
"binary": "cinder-scheduler",
"zone": "nova",
"state": "up",
"updated_at": "2017-06-29T05:50:35.000000",
"host": "devstack",
"disabled_reason": null
},
{
"status": "enabled",
"binary": "cinder-backup",
"zone": "nova",
"state": "up",
"updated_at": "2017-06-29T05:50:42.000000",
"host": "devstack",
"disabled_reason": null
},
{
"status": "enabled",
"binary": "cinder-volume",
"zone": "nova",
"frozen": false,
"state": "up",
"updated_at": "2017-06-29T05:50:39.000000",
"cluster": null,
"host": "devstack@lvmdriver-1",
"replication_status": "disabled",
"active_backend_id": null,
"disabled_reason": null
}]
}
Disables a Cinder service. Specify the service by its host name and binary name.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
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. |
host |
body |
string |
The name of the host. |
binary |
body |
string |
The binary name of the service. |
Request Example¶
{
"binary": "cinder-volume",
"host": "devstack@lvmdriver-1"
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
disabled |
body |
boolean |
The service is disabled or not. |
status |
body |
string |
The status of the service. One of |
host |
body |
string |
The name of the host. |
service |
body |
string |
The service name. Deprecated. Keeping service key for API compatibility. |
binary |
body |
string |
The binary name of the service. |
Response Example¶
{
"disabled": true,
"status": "disabled",
"host": "devstack@lvmdriver-1",
"service": "",
"binary": "cinder-volume"
}
Logs information to the Cinder service table about why a Cinder service was disabled.
Specify the service by its host name and binary name.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
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. |
binary |
body |
string |
The binary name of the service. |
host |
body |
string |
The name of the host. |
disabled_reason (Optional) |
body |
string |
The reason for disabling a resource. |
Request Example¶
{
"binary": "cinder-volume",
"host": "devstack@lvmdriver-1",
"disabled_reason": "test"
}
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
disabled |
body |
boolean |
The service is disabled or not. |
status |
body |
string |
The status of the service. One of |
host |
body |
string |
The name of the host. |
service |
body |
string |
The service name. Deprecated. Keeping service key for API compatibility. |
binary |
body |
string |
The binary name of the service. |
disabled_reason |
body |
string |
The reason for disabling a resource. |
Response Example¶
{
"disabled": true,
"status": "disabled",
"host": "devstack@lvmdriver-1",
"service": "",
"binary": "cinder-volume",
"disabled_reason": "test"
}
Enables a Cinder service. Specify the service by its host name and binary name.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
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. |
binary |
body |
string |
The binary name of the service. |
host |
body |
string |
The name of the host. |
Request Example¶
{
"binary": "cinder-volume",
"host": "devstack@lvmdriver-1"
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
disabled |
body |
boolean |
The service is disabled or not. |
status |
body |
string |
The status of the service. One of |
host |
body |
string |
The name of the host. |
service |
body |
string |
The service name. Deprecated. Keeping service key for API compatibility. |
binary |
body |
string |
The binary name of the service. |
disabled_reason |
body |
string |
The reason for disabling a resource. |
Response Example¶
{
"disabled": false,
"status": "enabled",
"host": "devstack@lvmdriver-1",
"service": "",
"binary": "cinder-volume",
"disabled_reason": null
}
Get current log levels for services, supported since v3.32. Filter the services by binary, server name and prefix for the log path.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
binary (Optional) |
body |
string |
The binary name of the service. |
server (Optional) |
body |
string |
The name of the host. |
prefix (Optional) |
body |
string |
The prefix for the log path we are querying,
for example |
Request Example¶
{
"binary": "cinder-volume",
"server": "devstack@lvmdriver-1",
"prefix": "cinder.volume"
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
log_levels |
body |
array |
The list of log levels. |
binary |
body |
string |
The binary name of the service. |
host |
body |
string |
The name of the host. |
levels |
body |
object |
The current log level that queried. |
Response Example¶
{
"log_levels": [{
"binary": "cinder-api",
"host": "devstack",
"levels": {
"cinder.volume.api": "DEBUG"
}
},
{
"binary": "cinder-scheduler",
"host": "devstack",
"levels": {
"cinder.volume.api": "DEBUG"
}
},
{
"binary": "cinder-backup",
"host": "devstack",
"levels": {}
},
{
"binary": "cinder-volume",
"host": "devstack@lvmdriver-1",
"levels": {
"cinder.volume.api": "DEBUG"
}
}]
}
Set log levels of services dynamically, supported since v3.32. Filter the services by binary, server name and prefix for the log path.
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. |
401 - Unauthorized |
User must authenticate before making a request. |
403 - Forbidden |
Policy does not allow current user to do this operation. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
binary (Optional) |
body |
string |
The binary name of the service. |
server (Optional) |
body |
string |
The name of the host. |
prefix (Optional) |
body |
string |
The prefix for the log path we are querying,
for example |
levels |
body |
string |
The log level to set, case insensitive, accepted values are |
Request Example¶
{
"binary": "cinder-volume",
"server": "devstack@lvmdriver-1",
"prefix": "cinder.volume",
"level": "ERROR"
}
Freeze and disable the specified cinder-volume host, and set
Disabled Reason of Cinder service table to frozen.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
host |
body |
string |
The name of the host. |
Request Example¶
{
"host": "devstack@rbd-sas"
}
Thaw and enable the specified cinder-volume host, and clean
Disabled Reason of Cinder service table.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
host |
body |
string |
The name of the host. |
Request Example¶
{
"host": "devstack@rbd-sas"
}
Failover a replicating cinder-volume host. Since Cinder Volume API Version
3.26, you can use failover in request URL instead of failover_host,
and the cluster name in request body is supported.
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. |
401 - Unauthorized |
User must authenticate before making a request. |
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. |
host |
body |
string |
The name of the host. |
backend_id (Optional) |
body |
string |
ID of backend to failover to. Default is |
cluster (Optional) |
body |
string |
The cluster name. Only in New in version 3.7 |
Request Example¶
{
"host": "devstack@lvmdriver-1",
"backend_id": null
}
Generic volume groups (groups)¶
Generic volume groups enable you to create a group of volumes and manage them together.
How is generic volume groups different from consistency groups? Currently consistency groups in cinder only support consistent group snapshot. It cannot be extended easily to serve other purposes. A project may want to put volumes used in the same application together in a group so that it is easier to manage them together, and this group of volumes may or may not support consistent group snapshot. Generic volume group is introduced to solve this problem. By decoupling the tight relationship between the group construct and the consistency concept, generic volume groups can be extended to support other features in the future.
Lists groups. 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 |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
groups |
body |
array |
A collections of groups. |
id |
body |
string |
The UUID of the object. |
name |
body |
string |
The group name. |
Response Example¶
{
"groups": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"name": "my_group1"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"name": "my_group2"
}
]
}
Creates a group.
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. |
group |
body |
object |
A group object. |
description (Optional) |
body |
string |
The group description. |
availability_zone (Optional) |
body |
string |
The name of the availability zone. |
group_type |
body |
string |
The group type ID. |
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 |
body |
string |
The group name. |
Request Example¶
{
"group": {
"name": "first_group",
"description": "first group",
"group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
"volume_types": [
"4e9e6d23-eed0-426d-b90a-28f87a94b6fe",
"c4daaf47-c530-4901-b28e-f5f0a359c4e6"
],
"availability_zone": "az0"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
id |
path |
string |
The ID of the group. |
name |
body |
string |
The group name. |
Response Example¶
{
"group": {
"id": "6f519a48-3183-46cf-a32f-41815f816666",
"name": "first_group"
}
}
Shows details for a group.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
|---|---|
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. |
group_id |
path |
string |
The ID of the group. |
list_volume (Optional) |
path |
string |
Show volume ids in this group. Default is False. New in version 3.25 |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group |
body |
object |
A group object. |
status |
body |
string |
The status of the generic group. |
description |
body |
string |
The 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 |
group_type |
body |
string |
The group type ID. |
group_snapshot_id (Optional) |
body |
string |
The ID of the group snapshot. |
source_group_id (Optional) |
body |
string |
The UUID of the source group. |
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 |
body |
string |
The group name. |
volumes (Optional) |
body |
array |
A list of New in version 3.25 |
replication_status (Optional) |
body |
string |
The group replication status. New in version 3.38 |
project_id (Optional) |
body |
string |
The UUID of the volume group project. New in version 3.58 |
Response Example¶
{
"group": {
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"status": "available",
"availability_zone": "az1",
"created_at": "2015-09-16T09:28:52.000000",
"name": "first_group",
"description": "my first group",
"group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
"volume_types": [
"c4daaf47-c530-4901-b28e-f5f0a359c4e6"
],
"volumes": ["a2cdf1ad-5497-4e57-bd7d-f573768f3d03"],
"group_snapshot_id": null,
"source_group_id": null,
"project_id": "7ccf4863071f44aeb8f141f65780c51b"
}
}
Creates a group from source.
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. |
create-from-src |
body |
object |
The create from source action. |
description (Optional) |
body |
string |
The group description. |
group_snapshot_id |
body |
string |
The ID of the group snapshot. |
source_group_id |
body |
string |
The UUID of the source group. |
name |
body |
string |
The group name. |
Request Example¶
{
"create-from-src": {
"name": "first_group",
"description": "first group",
"group_snapshot_id": "6f519a48-3183-46cf-a32f-41815f813986",
"source_group_id": null
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
id |
path |
string |
The ID of the group. |
name |
body |
string |
The group name. |
Response Example¶
{
"group": {
"id": "6f519a48-3183-46cf-a32f-41815f816666",
"name": "first_group"
}
}
Deletes a group.
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. |
group_id |
path |
string |
The ID of the group. |
delete |
body |
object |
The delete action. |
delete-volumes (Optional) |
body |
boolean |
If set to |
Request Example¶
{
"delete": {
"delete-volumes": false
}
}
Lists groups with details, 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 |
list_volume (Optional) |
path |
string |
Show volume ids in this group. Default is False. New in version 3.25 |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
groups |
body |
array |
A collections of groups. |
status |
body |
string |
The status of the generic group. |
description |
body |
string |
The 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 |
group_type |
body |
string |
The group type ID. |
group_snapshot_id (Optional) |
body |
string |
The ID of the group snapshot. |
source_group_id (Optional) |
body |
string |
The UUID of the source group. |
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 |
path |
string |
The ID of the group. |
name (Optional) |
body |
string |
The name of the object. |
volumes (Optional) |
body |
array |
A list of New in version 3.25 |
replication_status (Optional) |
body |
string |
The group replication status. New in version 3.38 |
project_id (Optional) |
body |
string |
The UUID of the volume group project. New in version 3.58 |
Response Example¶
{
"groups": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"status": "available",
"availability_zone": "az1",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my_group1",
"description": "my first group",
"group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
"volume_types": [
"4e9e6d23-eed0-426d-b90a-28f87a94b6fe",
"a3d55d15-eeb1-4816-ada9-bf82decc09b3"
],
"volumes": ["a2cdf1ad-5497-4e57-bd7d-f573768f3d03"],
"project_id": "7ccf4863071f44aeb8f141f65780c51b"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"status": "error",
"availability_zone": "az2",
"created_at": "2015-09-16T09:31:15.000000",
"name": "my_group2",
"description": "Edited description",
"group_type": "f8645498-1323-47a2-9442-5c57724d2e3c",
"volume_types": [
"c4daaf47-c530-4901-b28e-f5f0a359c4e6"
],
"volumes": ["a2cdf1ad-5497-4e57-bd7d-f573768f3d03"],
"project_id": "7ccf4863071f44aeb8f141f65780c51b"
}
]
}
Updates a group.
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. |
group_id |
path |
string |
The ID of the group. |
group |
body |
object |
A group object. |
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 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 |
body |
string |
The group name. |
Request Example¶
{
"group": {
"name": "my_group",
"description": "My group",
"add_volumes": "volume-uuid-1,volume-uuid-2",
"remove_volumes": "volume-uuid-8,volume-uuid-9"
}
}
Resets the status for a group. Specify the 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. |
group_id |
path |
string |
The ID of the group. |
reset_status |
body |
object |
The |
status (Optional) |
body |
string |
The |
Request Example¶
{
"reset_status": {
"status": "available"
}
}
Group replication (groups, action)¶
Lists targets, enables, disables, and fails over group replication.
Available since API microversion 3.38.
Lists replication targets for a group.
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. |
group_id |
path |
string |
The ID of the group. |
Request Example¶
{
"list_replication_targets": {}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
backend_id |
body |
string |
ID of failover target backend. |
unique_key (Optional) |
body |
string |
Vendor specific key-values. Only returned if administrator. |
Response Example¶
{
"replication_targets": {
"backend_id": "vendor-id-1",
"unique_key": "value1"
}
}
Enable replication for a group.
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. |
group_id |
path |
string |
The ID of the group. |
Request Example¶
{
"enable_replication": {}
}
Disable replication for a group.
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. |
group_id |
path |
string |
The ID of the group. |
Request Example¶
{
"disable_replication": {}
}
Failover a replicated group.
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. |
group_id |
path |
string |
The ID of the group. |
allow_attached_volume |
body |
boolean |
Whether to allow failover if any volumes are ‘in-use’. See valid boolean values |
secondary_backend_id |
body |
string |
ID of failover target backend. |
Request Example¶
{
"failover_replication": {
"allow_attached_volume": true,
"secondary_backend_id": "vendor-id-1"
}
}
Group snapshots (group_snapshots)¶
Lists all, lists all with details, shows details for, creates, and deletes group snapshots.
Deletes a group snapshot.
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. |
group_snapshot_id |
path |
string |
The ID of the group snapshot. |
Shows details for a group snapshot.
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. |
group_snapshot_id |
path |
string |
The ID of the group snapshot. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_snapshot |
body |
object |
The group 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 |
group_id |
body |
string |
The UUID of the source group. |
id |
body |
string |
The ID of the group snapshot. |
name |
body |
string |
The group snapshot name. |
status |
body |
string |
The |
description |
body |
string |
The group snapshot description. |
group_type_id |
body |
string |
The group type ID. |
project_id (Optional) |
body |
string |
The UUID of the volume group snapshot project. New in version 3.58 |
Response Example¶
{
"group_snapshot": {
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"group_id": "6f519a48-3183-46cf-a32f-41815f814444",
"status": "available",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my_group_snapshot1",
"description": "my first group snapshot",
"group_type_id": "7270c56e-6354-4528-8e8b-f54dee2232c8",
"project_id": "7ccf4863071f44aeb8f141f65780c51b"
}
}
Lists all group snapshots with details. 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 New in version 3.29 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is New in version 3.29 |
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.29 |
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.29 |
offset (Optional) |
query |
integer |
Used in conjunction with New in version 3.29 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the New in version 3.29 |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_snapshots |
body |
array |
A collection of group snapshots. |
id |
body |
string |
The ID of the group snapshot. |
name |
body |
string |
The group snapshot name. |
status |
body |
string |
The |
description |
body |
string |
The 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 |
group_id |
body |
string |
The ID of the group. |
group_type_id |
body |
string |
The group type ID. |
project_id (Optional) |
body |
string |
The UUID of the volume group snapshot project. New in version 3.58 |
Response Example¶
{
"group_snapshots": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"group_id": "6f519a48-3183-46cf-a32f-41815f814444",
"status": "available",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my_group_snapshot1",
"description": "my first group snapshot",
"group_type_id": "0ef094a2-d9fd-4c79-acfd-ac60a0506b7d",
"project_id": "7ccf4863071f44aeb8f141f65780c51b"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"group_id": "aed36625-a6d7-4681-ba59-c7ba3d18dddd",
"status": "error",
"created_at": "2015-09-16T09:31:15.000000",
"name": "my_group_snapshot2",
"description": "Edited description",
"group_type_id": "7270c56e-6354-4528-8e8b-f54dee2232c8",
"project_id": "7ccf4863071f44aeb8f141f65780c51b"
}
]
}
Lists all group snapshots, 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 New in version 3.29 |
sort_key (Optional) |
query |
string |
Sorts by an attribute. A valid value is New in version 3.29 |
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.29 |
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.29 |
offset (Optional) |
query |
integer |
Used in conjunction with New in version 3.29 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the New in version 3.29 |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_snapshots |
body |
array |
A collection of group snapshots. |
id |
body |
string |
The ID of the group snapshot. |
name |
body |
string |
The group snapshot name. |
Response Example¶
{
"group_snapshots": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"name": "my_group_snapshot1"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"name": "my_group_snapshot2"
}
]
}
Creates a group snapshot.
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. |
group_snapshot |
body |
object |
The group snapshot. |
name (Optional) |
body |
string |
The group snapshot name. |
description (Optional) |
body |
string |
The group snapshot description. |
group_id |
body |
string |
The ID of the group. |
Request Example¶
{
"group_snapshot": {
"group_id": "6f519a48-3183-46cf-a32f-41815f814546",
"name": "first_group_snapshot",
"description": "first group snapshot"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_snapshot |
body |
object |
The group snapshot. |
id |
body |
string |
The ID of the group snapshot. |
name |
body |
string |
The group snapshot name. |
group_type_id |
body |
string |
The group type ID. |
Response Example¶
{
"group_snapshot": {
"id": "6f519a48-3183-46cf-a32f-41815f816666",
"name": "first_group_snapshot",
"group_type_id": "58737af7-786b-48b7-ab7c-2447e74b0ef4"
}
}
Resets the status for a group snapshot. Specifies the 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. |
group_snapshot_id |
path |
string |
The ID of the group snapshot. |
reset_status |
body |
object |
The |
status |
body |
string |
The |
Request Example¶
{
"reset_status": {
"status": "available"
}
}
Group types (group_types)¶
To create a generic volume group, you must specify a group type.
Updates a group type.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
500 - Internal Server Error |
Something went wrong with the service which prevents it from fulfilling the request. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
group_type_id |
path |
string |
The UUID for an existing group type. |
group_type |
body |
object |
A |
name (Optional) |
body |
string |
The group name. |
description (Optional) |
body |
string |
The group type description. |
is_public (Optional) |
body |
boolean |
Whether the group type is publicly visible. See valid boolean values |
Request Example¶
{
"group_type": {
"name": "grp-type-001",
"description": "group type 0001",
"is_public": true
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_type |
body |
object |
A |
id |
body |
string |
The group type ID. |
is_public |
body |
boolean |
Whether the group type is publicly visible. |
group_specs (Optional) |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
description |
body |
string |
The group type description. |
name |
body |
string |
The group type name. |
Response Example¶
{
"group_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "grp-type-001",
"description": "group type 001",
"is_public": true,
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
}
}
}
Shows details for a group type.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
|---|---|
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. |
group_type_id |
path |
string |
The UUID for an existing group type. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_type |
body |
object |
A |
id |
body |
string |
The group type ID. |
name |
body |
string |
The group type name. |
is_public |
body |
boolean |
Whether the group type is publicly visible. |
group_specs (Optional) |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
description |
body |
string |
The group type description. |
Response Example¶
{
"group_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "grp-type-001",
"description": "group type 001",
"is_public": true,
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
}
}
}
Shows details for the default group type if configured.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
Error¶
Code |
Reason |
|---|---|
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. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_type |
body |
object |
A |
id |
body |
string |
The group type ID. |
name |
body |
string |
The group type name. |
is_public |
body |
boolean |
Whether the group type is publicly visible. |
group_specs (Optional) |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
description |
body |
string |
The group type description. |
Response Example¶
{
"group_type": {
"id": "7270c56e-6354-4528-8e8b-f54dee2232c8",
"name": "group-type-test",
"description": "default group type",
"is_public": true,
"group_specs": {}
}
}
Deletes a group type.
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 |
|---|---|---|---|
group_type_id |
path |
string |
The UUID for an existing group type. |
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
Lists group types.
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 |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number
of items up to a limit value. Use the |
offset (Optional) |
query |
integer |
Used in conjunction with |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_types |
body |
array |
The list of group types. |
id |
body |
string |
The group type ID. |
group_specs (Optional) |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
name |
body |
string |
The group type name. |
is_public |
body |
boolean |
Whether the group type is publicly visible. |
description |
body |
string |
The group type description. |
Response Example¶
{
"group_types": [
{
"is_public": true,
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
},
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "group_type1",
"description": "tempest-group-type-description-1261576824"
},
{
"is_public": true,
"group_specs": {},
"id": "8eb69a46-df97-4e41-9586-9a40a7533803",
"name": "group_type2",
"description": "tempest-group-type-description-3927295731"
}
]
}
Creates a group type.
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. |
group_type |
body |
object |
A |
name |
body |
string |
The group type name. |
description (Optional) |
body |
string |
The group type description. |
is_public (Optional) |
body |
boolean |
Whether the group type is publicly visible. See valid boolean values |
group_specs (Optional) |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
Request Example¶
{
"group_type": {
"name": "grp-type-001",
"description": "group type 0001",
"is_public": true,
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
}
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_type |
body |
object |
A |
id |
body |
string |
The group type ID. |
is_public |
body |
boolean |
Whether the group type is publicly visible. |
group_specs (Optional) |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
description |
body |
string |
The group type description. |
name |
body |
string |
The group type name. |
Response Example¶
{
"group_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "grp-type-001",
"description": "group type 001",
"is_public": true,
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
}
}
}
Group type specs (group_types, group_specs)¶
Create group specs for a group type, if the specification key already exists in group specs, this API will update the specification as well.
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. |
group_type_id |
path |
string |
The UUID for an existing group type. |
group_specs |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
Request Example¶
{
"group_specs": {
"key1": "value1",
"key2": "value2"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_specs |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
Response Example¶
{
"group_specs": {
"key1": "value1",
"key2": "value2"
}
}
List all the group specs for a group type,
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. |
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. |
group_type_id |
path |
string |
The UUID for an existing group type. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
group_specs |
body |
object |
A set of key and value pairs that contains the specifications for a group type. |
Response Example¶
{
"group_specs": {
"key1": "value1",
"key2": "value2"
}
}
Show a group spec for a group type,
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. |
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. |
group_type_id |
path |
string |
The UUID for an existing group type. |
spec_id |
path |
string |
The id (key) of the group specification. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
spec |
body |
string |
The value of the group specification corresponding to the specified key. |
Response Example¶
{
"key1": "value1"
}
Update a group spec for a group type,
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. |
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. |
group_type_id |
path |
string |
The UUID for an existing group type. |
spec_id |
path |
string |
The id (key) of the group specification. |
spec |
body |
string |
The value of the group specification corresponding to the specified key. |
Request Example¶
{
"key1": "value1"
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
spec |
body |
string |
The value of the group specification corresponding to the specified key. |
Response Example¶
{
"key1": "value1"
}
Delete a group spec for a group type,
Response codes¶
Success¶
Code |
Reason |
|---|---|
202 - Accepted |
Request is accepted, but processing may take some time. |
Error¶
Code |
Reason |
|---|---|
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. |
group_type_id |
path |
string |
The UUID for an existing group type. |
spec_id |
path |
string |
The id (key) of the group specification. |
Hosts extension (os-hosts)¶
Administrators only, depending on policy settings.
Lists, shows hosts.
Lists all hosts summary info that is not disabled.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
admin_project_id |
path |
string |
The UUID of the administrative project. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
hosts |
body |
object |
A OpenStack Block Storage host. |
service-status |
body |
string |
The status of the service. One of |
service |
body |
string |
The name of the service which is running on the host. |
zone |
body |
string |
The availability zone name. |
service-state |
body |
string |
The state of the service. One of |
host_name |
body |
string |
The name of the host that hosts the storage backend,
may take the format of |
last-update |
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¶
{
"hosts": [{
"service-status": "available",
"service": "cinder-backup",
"zone": "nova",
"service-state": "enabled",
"host_name": "node1",
"last-update": "2017-03-09T21:38:41.000000"
},
{
"service-status": "available",
"service": "cinder-scheduler",
"zone": "nova",
"service-state": "enabled",
"host_name": "node1",
"last-update": "2017-03-09T21:38:38.000000"
},
{
"service-status": "available",
"service": "cinder-volume",
"zone": "nova",
"service-state": "enabled",
"host_name": "node1@lvm",
"last-update": "2017-03-09T21:38:35.000000"
}]
}
Shows volume and snapshot details for a cinder-volume host.
Note: This API is meant specifically for cinder-volume hosts only. It is not valid against other Cinder service hosts or hosts where the cinder-volume service has been disabled.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
404 - Not Found |
The requested resource could not be found. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
admin_project_id |
path |
string |
The UUID of the administrative project. |
host_name |
path |
string |
The name of the host that hosts the storage back end. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
host |
body |
object |
The OpenStack Block Storage host where the existing volume resides. |
volume_count |
body |
string |
Total number of volumes. |
total_volume_gb |
body |
string |
The total number of gibibytes (GiB) used. |
total_snapshot_gb |
body |
string |
The total number of gibibytes (GiB) used by snapshots. |
project |
body |
string |
The Project ID which the host resource belongs to.
In the summary resource, the value is |
host |
body |
string |
The name of the host that hosts the storage backend,
may take the format of |
snapshot_count |
body |
string |
The total number of snapshots used. |
Response Example¶
{
"host": [{
"resource": {
"volume_count": "8",
"total_volume_gb": "11",
"total_snapshot_gb": "1",
"project": "(total)",
"host": "node1@rbd-sas",
"snapshot_count": "1"
}
},
{
"resource": {
"volume_count": "8",
"total_volume_gb": "11",
"total_snapshot_gb": "1",
"project": "f21a9c86d7114bf99c711f4874d80474",
"host": "node1@rbd-sas",
"snapshot_count": "1"
}
}]
}
Limits (limits)¶
Shows absolute limits for a project.
An absolute limit value of -1 indicates that the absolute limit
for the item is infinite.
Shows absolute limits for a project.
An absolute limit value of -1 indicates that the absolute limit
for the item is infinite.
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¶
Name |
In |
Type |
Description |
|---|---|---|---|
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
limits |
body |
object |
A list of |
rate |
body |
array |
Rate-limit volume copy bandwidth, used to mitigate slow down of data access from the instances. |
absolute |
body |
object |
An |
totalSnapshotsUsed |
body |
integer |
The total number of snapshots used. |
maxTotalBackups |
body |
integer |
The maximum number of backups. |
maxTotalVolumeGigabytes |
body |
integer |
The maximum total amount of volumes, in gibibytes (GiB). |
maxTotalSnapshots |
body |
integer |
The maximum number of snapshots. |
maxTotalBackupGigabytes |
body |
integer |
The maximum total amount of backups, in gibibytes (GiB). |
totalBackupGigabytesUsed |
body |
integer |
The total number of backups gibibytes (GiB) used. |
maxTotalVolumes |
body |
integer |
The maximum number of volumes. |
totalVolumesUsed |
body |
integer |
The total number of volumes used. |
totalBackupsUsed |
body |
integer |
The total number of backups used. |
totalGigabytesUsed |
body |
integer |
The total number of gibibytes (GiB) used. |
Response Example¶
{
"limits": {
"rate": [],
"absolute": {
"totalSnapshotsUsed": 0,
"maxTotalBackups": 10,
"maxTotalVolumeGigabytes": 1000,
"maxTotalSnapshots": 10,
"maxTotalBackupGigabytes": 1000,
"totalBackupGigabytesUsed": 0,
"maxTotalVolumes": 10,
"totalVolumesUsed": 0,
"totalBackupsUsed": 0,
"totalGigabytesUsed": 0
}
}
}
Messages (messages)¶
Lists all, shows, and deletes messages. These are error messages generated by failed operations as a way to find out what happened when an asynchronous operation failed.
Deletes a message.
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. |
message_id |
path |
string |
The UUID of the message. |
Shows details for a message.
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. |
message_id |
path |
string |
The UUID of the message. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
message |
body |
string |
The translated readable message corresponding to |
request_id |
body |
string |
The id of the request during which the message was created. |
links (Optional) |
body |
array |
Links for the message. |
message_level |
body |
string |
The level of the message, possible value is only ‘ERROR’ now. |
event_id |
body |
string |
The id of the event to this message, this id could
eventually be translated into |
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 |
guaranteed_until (Optional) |
body |
string |
The expire time of the message, this message could be deleted after this time. |
resource_uuid (Optional) |
body |
string |
The UUID of the resource during whose operation the message was created. |
id |
body |
string |
The UUID for the message. |
resource_type (Optional) |
body |
string |
The resource type corresponding to |
user_message |
body |
string |
The translated readable message corresponding to |
Response Example¶
{
"message": {
"request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
"links": [
{
"href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
"rel": "self"
},
{
"href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
"rel": "bookmark"
}
],
"message_level": "ERROR",
"event_id": "VOLUME_000002",
"created_at": "2014-10-28T00:00:00-00:00",
"guaranteed_until": "2014-10-28T00:00:00-00:00",
"resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4cacf",
"id": "c506cd4b-9048-43bc-97ef-0d7dec369b42",
"resource_type": "VOLUME",
"user_message": "No storage could be allocated for this volume request."
}
}
Lists all messages, 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. |
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 |
|---|---|---|---|
messages |
body |
string |
A collection of user messages. |
request_id |
body |
string |
The id of the request during which the message was created. |
links (Optional) |
body |
array |
Links for the message. |
message_level |
body |
string |
The level of the message, possible value is only ‘ERROR’ now. |
event_id |
body |
string |
The id of the event to this message, this id could
eventually be translated into |
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 |
guaranteed_until (Optional) |
body |
string |
The expire time of the message, this message could be deleted after this time. |
resource_uuid (Optional) |
body |
string |
The UUID of the resource during whose operation the message was created. |
id |
body |
string |
The UUID for the message. |
resource_type (Optional) |
body |
string |
The resource type corresponding to |
user_message |
body |
string |
The translated readable message corresponding to |
Response Example¶
{
"messages": [{
"request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
"links": [
{
"href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
"rel": "self"
},
{
"href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
"rel": "bookmark"
}
],
"message_level": "ERROR",
"event_id": "VOLUME_000002",
"created_at": "2014-10-28T00:00:00-00:00",
"guaranteed_until": "2014-10-28T00:00:00-00:00",
"resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4cacf",
"id": "c506cd4b-9048-43bc-97ef-0d7dec369b42",
"resource_type": "VOLUME",
"user_message": "No storage could be allocated for this volume request."
},{
"request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
"links": [
{
"href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
"rel": "self"
},
{
"href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
"rel": "bookmark"
}
],
"message_level": "ERROR",
"event_id": "VOLUME_000002",
"created_at": "2014-10-28T00:00:00-00:00",
"guaranteed_until": "2014-10-28T00:00:00-00:00",
"resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4df4e",
"id": "c506cd4b-9048-43bc-97ef-0d7dec36d5gt",
"resource_type": "VOLUME",
"user_message": "No storage could be allocated for this volume request."
}]
}
Resource Filters (resource_filters)¶
Lists all resource filters, available since microversion 3.33.
List filters.
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. |
resource (Optional) |
query |
string |
Filter for resource name. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
resource_filters |
body |
array |
A collection of resource filters. |
filters |
body |
array |
The resource filter array. |
resource |
body |
string |
Resource which the filters will be applied to. |
Response Example¶
{
"resource_filters": [
{
"filters": [
"name",
"status",
"image_metadata", "bootable",
"migration_status"
],
"resource": "volume"
},
{
"filters": [
"name",
"status",
"volume_id"
],
"resource": "snapshot"
}
]
}
Quality of service (QoS) specifications (qos-specs)¶
Administrators only, depending on policy settings.
Creates, lists, shows details for, associates, disassociates, sets keys, unsets keys, and deletes quality of service (QoS) specifications.
Disassociates a QoS specification from all associations.
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. |
qos_id |
path |
string |
The ID of the QoS specification. |
Unsets keys in a QoS specification.
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. |
qos_id |
path |
string |
The ID of the QoS specification. |
keys |
body |
array |
List of Keys. |
Request Example¶
{
"keys": [
"key1"
]
}
Lists all associations for a QoS specification.
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. |
qos_id |
path |
string |
The ID of the QoS specification. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
qos_associations |
body |
array |
A collection of |
type |
body |
string |
The QoS association type. |
id |
body |
string |
The Qos association ID. |
name |
body |
string |
The QoS association name. |
Response Example¶
{
"qos_associations": []
}
Associates a QoS specification with 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. |
qos_id |
path |
string |
The ID of the QoS specification. |
vol_type_id |
query |
string |
A volume type ID. |
Disassociates a QoS specification from 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. |
qos_id |
path |
string |
The ID of the QoS specification. |
vol_type_id |
query |
string |
A volume type ID. |
Shows details for a QoS specification.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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. |
404 - Not Found |
The requested resource could not be found. |
405 - Method Not Allowed |
Method is not valid for this endpoint and resource. |
413 - Request Entity Too Large |
This operation cannot be completed. |
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. |
qos_id |
path |
string |
The ID of the QoS specification. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
qos_specs |
body |
object |
A |
specs |
body |
object |
A |
consumer (Optional) |
body |
string |
The consumer type. |
name |
body |
string |
The name of the QoS specification. |
id |
body |
string |
The generated ID for the QoS specification. |
links |
body |
array |
The QoS specification links. |
Response Example¶
{
"qos_specs": {
"specs": {},
"consumer": "back-end",
"name": "reliability-spec",
"id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
},
"links": [
{
"href": "http://23.253.228.211:8776/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/qos-specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
"rel": "self"
},
{
"href": "http://23.253.228.211:8776/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/qos-specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
"rel": "bookmark"
}
]
}
Sets keys in a QoS specification.
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. |
qos_id |
path |
string |
The ID of the QoS specification. |
qos_specs |
body |
object |
A |
Request Example¶
{
"qos_specs": {
"delay": "1"
}
}
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
qos_specs |
body |
object |
A |
Response Example¶
{
"qos_specs": {
"delay": "1"
}
}
Deletes a QoS specification.
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. |
qos_id |
path |
string |
The ID of the QoS specification. |
force (Optional) |
query |
boolean |
To delete a QoS specification even if it is in-
use, set to |
Creates a QoS specification.
Specify one or more key and value pairs 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. |
qos_specs |
body |
object |
A |
name |
body |
string |
The name of the QoS specification. |
Request Example¶
{
"qos_specs": {
"name": "reliability-spec"
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
qos_specs |
body |
object |
A |
name |
body |
string |
The name of the QoS specification. |
links |
body |
array |
The QoS specification links. |
id |
body |
string |
The generated ID for the QoS specification. |
consumer (Optional) |
body |
string |
The consumer type. |
specs |
body |
object |
A |
Response Example¶
{
"qos_specs": {
"specs": {},
"consumer": "back-end",
"name": "reliability-spec",
"id": "599ef437-1c99-42ec-9fc6-239d0519fef1"
},
"links": [
{
"href": "http://23.253.248.171:8776/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/qos-specs/599ef437-1c99-42ec-9fc6-239d0519fef1",
"rel": "self"
},
{
"href": "http://23.253.248.171:8776/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/qos-specs/599ef437-1c99-42ec-9fc6-239d0519fef1",
"rel": "bookmark"
}
]
}
Lists quality of service (QoS) specifications.
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. |
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 |
|---|---|---|---|
qos_specs |
body |
object |
A |
specs |
body |
object |
A |
consumer (Optional) |
body |
string |
The consumer type. |
id |
body |
string |
The generated ID for the QoS specification. |
name |
body |
string |
The name of the QoS specification. |
Response Example¶
{
"qos_specs": [
{
"consumer": "back-end",
"id": "62c17294-2e52-4877-a01f-a30388749d9d",
"name": "reliability-spec",
"specs": {}
}
]
}
Quota class set extension (os-quota-class-sets)¶
Administrators only, depending on policy settings.
Shows and updates quota classes for a project.
Shows quota class set for a project. If no specific value for the quota class resource exists, then the default value will be reported.
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. |
404 - Not Found |
The requested resource could not be found. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_class_name |
path |
string |
The name of the quota class for which to set quotas. |
admin_project_id |
path |
string |
The UUID of the administrative project. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_class_set |
body |
object |
A |
backup_gigabytes |
body |
integer |
The maximum total amount of backups, in gibibytes (GiB). |
backups |
body |
integer |
The maximum number of backups. |
gigabytes |
body |
integer |
The maximum total amount of volumes, in gibibytes (GiB). |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type. |
groups |
body |
integer |
The maximum number of groups. |
per_volume_gigabytes |
body |
integer |
The size (GB) of volumes that are allowed for each volume. |
snapshots |
body |
integer |
The maximum number of snapshots. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
volumes |
body |
integer |
The maximum number of volumes. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
id |
body |
string |
The name of the quota class set. |
Response Example¶
{
"quota_class_set": {
"backup_gigabytes": 1000,
"backups": 10,
"gigabytes": 1000,
"gigabytes___DEFAULT__": -1,
"groups": 10,
"id": "test_class",
"per_volume_gigabytes": -1,
"snapshots": 10,
"snapshots___DEFAULT__": -1,
"volumes": 10,
"volumes___DEFAULT__": -1
}
}
Updates quota class set for a project. If the quota_class_name key does not
exist, then the API will create one.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
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 |
|---|---|---|---|
admin_project_id |
path |
string |
The UUID of the administrative project. |
quota_class_name |
path |
string |
The name of the quota class for which to set quotas. |
gigabytes |
body |
integer |
The maximum total amount of volumes, in gibibytes (GiB). |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type. |
snapshots (Optional) |
body |
integer |
The maximum number of snapshots. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
volumes (Optional) |
body |
integer |
The maximum number of volumes. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
Request Example¶
{
"quota_class_set": {
"volumes": 10,
"gigabytes": 1000,
"snapshots": 10
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_class_set |
body |
object |
A |
backup_gigabytes |
body |
integer |
The maximum total amount of backups, in gibibytes (GiB). |
backups |
body |
integer |
The maximum number of backups. |
gigabytes |
body |
integer |
The maximum total amount of volumes, in gibibytes (GiB). |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type. |
groups |
body |
integer |
The maximum number of groups. |
per_volume_gigabytes |
body |
integer |
The size (GB) of volumes that are allowed for each volume. |
snapshots |
body |
integer |
The maximum number of snapshots. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
volumes |
body |
integer |
The maximum number of volumes. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
Response Example¶
{
"quota_class_set": {
"backup_gigabytes": 1000,
"backups": 10,
"gigabytes": 1000,
"gigabytes___DEFAULT__": -1,
"groups": 10,
"per_volume_gigabytes": -1,
"snapshots": 10,
"snapshots___DEFAULT__": -1,
"volumes": 10,
"volumes___DEFAULT__": -1
}
}
Quota sets extension (os-quota-sets)¶
Administrators only, depending on policy settings.
Shows, updates, and deletes quotas for a project.
Shows quotas for a project.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
admin_project_id |
path |
string |
The UUID of the administrative project. |
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
usage (Optional) |
query |
boolean |
Show project’s quota usage information.
Default is |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_set |
body |
object |
A |
id |
body |
string |
The UUID of the project. |
volumes |
body |
integer |
The number of volumes that are allowed for each project. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
snapshots |
body |
integer |
The number of snapshots that are allowed for each project. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
backups |
body |
integer |
The number of backups that are allowed for each project. |
groups |
body |
integer |
The number of groups that are allowed for each project. |
per_volume_gigabytes |
body |
integer |
The size (GB) of volumes that are allowed for each volume. |
gigabytes |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project. |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type. |
backup_gigabytes |
body |
integer |
The size (GB) of backups that are allowed for each project. |
Response Example¶
{
"quota_set": {
"backup_gigabytes": 1000,
"backups": 10,
"gigabytes": 1000,
"gigabytes___DEFAULT__": -1,
"groups": 10,
"id": "fake_tenant",
"per_volume_gigabytes": -1,
"snapshots": 10,
"snapshots___DEFAULT__": -1,
"volumes": 10,
"volumes___DEFAULT__": -1
}
}
Shows quota usage for a project.
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. |
admin_project_id |
path |
string |
The UUID of the administrative project. |
usage (Optional) |
query |
boolean |
Show project’s quota usage information.
Default is |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_set |
body |
object |
A |
id |
body |
string |
The UUID of the project. |
volumes |
body |
object |
The volume usage information for this project, including |
volumes_{volume_type} |
body |
object |
The volume usage information for this project and this volume type,
including |
snapshots |
body |
object |
The snapshot usage information for this project, including |
snapshots_{volume_type} |
body |
object |
The snapshot usage information for this project and this volume type,
including |
backups |
body |
object |
The backup usage information for this project, including |
groups |
body |
object |
The group usage information for this project, including |
per_volume_gigabytes |
body |
object |
The size (GB) usage information for each volume, including |
gigabytes |
body |
object |
The size (GB) usage information of volumes and snapshots for this project,
including |
gigabytes_{volume_type} |
body |
object |
The size (GB) usage information of volumes and snapshots for this project
and this volume type, including |
backup_gigabytes |
body |
object |
The size (GB) usage information of backup for this project, including |
Response Example¶
{
"quota_set": {
"backup_gigabytes": {
"in_use": 0,
"limit": 1000,
"reserved": 0
},
"backups": {
"in_use": 0,
"limit": 10,
"reserved": 0
},
"gigabytes": {
"in_use": 0,
"limit": 1000,
"reserved": 0
},
"gigabytes___DEFAULT__": {
"in_use": 0,
"limit": -1,
"reserved": 0
},
"groups": {
"in_use": 0,
"limit": 10,
"reserved": 0
},
"id": "fake_tenant",
"per_volume_gigabytes": {
"in_use": 0,
"limit": -1,
"reserved": 0
},
"snapshots": {
"in_use": 0,
"limit": 10,
"reserved": 0
},
"snapshots___DEFAULT__": {
"in_use": 0,
"limit": -1,
"reserved": 0
},
"volumes": {
"in_use": 0,
"limit": 10,
"reserved": 0
},
"volumes___DEFAULT__": {
"in_use": 0,
"limit": -1,
"reserved": 0
}
}
}
Updates quotas for a project.
Response codes¶
Success¶
Code |
Reason |
|---|---|
200 - OK |
Request was successful. |
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
admin_project_id |
path |
string |
The UUID of the administrative project. |
project_id |
path |
string |
The UUID of the project in a multi-tenancy cloud. |
quota_set |
body |
object |
A |
volumes |
body |
integer |
The number of volumes that are allowed for each project. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
snapshots |
body |
integer |
The number of snapshots that are allowed for each project. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
backups |
body |
integer |
The number of backups that are allowed for each project. |
groups |
body |
integer |
The number of groups that are allowed for each project. |
per_volume_gigabytes |
body |
integer |
The size (GB) of volumes that are allowed for each volume. |
gigabytes |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project. |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type. |
backup_gigabytes |
body |
integer |
The size (GB) of backups that are allowed for each project. |
Request Example¶
{
"quota_set":{
"groups": 11,
"volumes": 5,
"backups": 4
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_set |
body |
object |
A |
volumes |
body |
integer |
The number of volumes that are allowed for each project. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
snapshots |
body |
integer |
The number of snapshots that are allowed for each project. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
backups |
body |
integer |
The number of backups that are allowed for each project. |
groups |
body |
integer |
The number of groups that are allowed for each project. |
per_volume_gigabytes |
body |
integer |
The size (GB) of volumes that are allowed for each volume. |
gigabytes |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project. |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type. |
backup_gigabytes |
body |
integer |
The size (GB) of backups that are allowed for each project. |
Response Example¶
{
"quota_set": {
"backup_gigabytes": 1000,
"backups": 4,
"gigabytes": 1000,
"gigabytes___DEFAULT__": -1,
"groups": 11,
"per_volume_gigabytes": -1,
"snapshots": 10,
"snapshots___DEFAULT__": -1,
"volumes": 5,
"volumes___DEFAULT__": -1
}
}
Deletes quotas for a project so the quotas revert to default values.
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. |
admin_project_id |
path |
string |
The UUID of the administrative project. |
Gets default quotas for a project.
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. |
admin_project_id |
path |
string |
The UUID of the administrative project. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
quota_set |
body |
object |
A |
id |
body |
string |
The UUID of the project. |
volumes |
body |
integer |
The number of volumes that are allowed for each project. |
volumes_{volume_type} |
body |
integer |
The number of volumes that are allowed for each project and the specified volume type. |
snapshots |
body |
integer |
The number of snapshots that are allowed for each project. |
snapshots_{volume_type} |
body |
integer |
The number of snapshots that are allowed for each project and the specified volume type. |
backups |
body |
integer |
The number of backups that are allowed for each project. |
groups |
body |
integer |
The number of groups that are allowed for each project. |
per_volume_gigabytes |
body |
integer |
The size (GB) of volumes that are allowed for each volume. |
gigabytes |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project. |
gigabytes_{volume_type} |
body |
integer |
The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type. |
backup_gigabytes |
body |
integer |
The size (GB) of backups that are allowed for each project. |
Response Example¶
{
"quota_set": {
"backup_gigabytes": 1000,
"backups": 10,
"gigabytes": 1000,
"gigabytes___DEFAULT__": -1,
"groups": 10,
"id": "fake_tenant",
"per_volume_gigabytes": -1,
"snapshots": 10,
"snapshots___DEFAULT__": -1,
"volumes": 10,
"volumes___DEFAULT__": -1
}
}
Workers (workers)¶
Request cleanup of services with optional filtering. This API is only available with microversion 3.24 or later.
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. |
cluster_name (Optional) |
body |
string |
The OpenStack Block Storage cluster where the resource resides. Optional only if host field is provided. |
service_id (Optional) |
body |
integer |
UUID for the cleanup service. |
host |
body |
string |
The name of the service which is running on the host. |
binary |
body |
string |
The binary name of the service. |
is-up (Optional) |
body |
boolean |
Filter by up/down status. See valid boolean values |
disabled (Optional) |
body |
boolean |
Filter by disabled status. See valid boolean values |
resource-id (Optional) |
body |
string |
The UUID of a resource to cleanup. |
resource-type (Optional) |
body |
string |
The resource type corresponding to |
Request Example¶
{
"cluster_name": "test",
"disabled": true,
"host": "host1@lvmdriver",
"service_id": 1,
"is_up": true,
"binary": "cinder-volume",
"resource_id": "b122f668-d15a-40f8-af21-38d218796ab8",
"resource_type": "Volume"
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
host |
body |
string |
The name of the service which is running on the host. |
binary |
body |
string |
The binary name of the service. |
id (Optional) |
body |
integer |
UUID for the cleanup service. |
cluster_name (Optional) |
body |
string |
The OpenStack Block Storage cluster where the resource resides. Optional only if host field is provided. |
Response Example¶
{
"cleaning": [
{
"id": 1,
"host": "host1@lvmdriver",
"binary": "cinder-volume",
"cluster_name": "test"
}
],
"unavailable": []
}
Valid boolean values¶
Following is the list of valid values for boolean parameters.
[True, ‘True’, ‘TRUE’, ‘true’, ‘1’, ‘ON’, ‘On’, ‘on’, ‘YES’, ‘Yes’, ‘yes’, ‘y’, ‘t’, False, ‘False’, ‘FALSE’, ‘false’, ‘0’, ‘OFF’, ‘Off’, ‘off’, ‘NO’, ‘No’, ‘no’, ‘n’, ‘f’]
