Block Storage API V3 (CURRENT)

Note

The URL for most API methods includes a {project_id} placeholder that represents the caller’s project ID. As of v3.67, the project_id is optional in the URL, and the following are equivalent:

  • GET /v3/{project_id}/volumes

  • GET /v3/volumes

In both instances, the actual project ID used by the API method is the one in the caller’s keystone context. For that reason, including a project ID in the URL is redundant.

The v3.67 microversion is only used as an indicator that the API accepts a URL without a {project_id} segment, and this applies to all requests regardless of the microversion in the request. For example, an API node serving v3.67 or greater will accept a URL without a {project_id} segment even if the request asks for v3.0. Likewise, it will accept a URL containing a {project_id} segment even if the request asks for v3.67.

API versions

GET
/

List All 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

GET
/v3/

Show API v3 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:

  • CURRENT: this is the preferred version of the API to use

  • DEPRECATED: a deprecated version of the API that is slated for removal

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)

GET
/v3/{project_id}/extensions

List Known API 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, 2015-08-27T09:49:58-05:00.

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

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

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.

PUT
/v3/{project_id}/types/{volume_type_id}

Update a volume type

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 volume_type object.

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 volume_type object.

is_public

body

boolean

Whether the volume type is publicly visible.

extra_specs (Optional)

body

object

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

description

body

string

The volume type description.

name

body

string

The name of the volume type.

id

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"
        }
    }
}
POST
/v3/{project_id}/types/{volume_type_id}/extra_specs

Create or update extra specs for volume type

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"
    }
}
GET
/v3/{project_id}/types/{volume_type_id}/extra_specs

Show all extra specifications for volume type

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"
    }
}
GET
/v3/{project_id}/types/{volume_type_id}/extra_specs/{key}

Show extra specification for volume type

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"
}
PUT
/v3/{project_id}/types/{volume_type_id}/extra_specs/{key}

Update extra specification for volume type

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"
}
DELETE
/v3/{project_id}/types/{volume_type_id}/extra_specs/{key}

Delete extra specification for volume type

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.

GET
/v3/{project_id}/types/{volume_type_id}

Show volume type detail

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 volume_type object.

is_public

body

boolean

Whether the volume type is publicly visible.

extra_specs (Optional)

body

object

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

description

body

string

The volume type description.

name

body

string

The name of the volume type.

id

body

string

The UUID of the volume type.

os-volume-type-access:is_public

body

boolean

Whether the volume type is publicly visible.

qos_specs_id (Optional)

body

string

The QoS specifications ID.

Response Example

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "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"
        }
    }
}
GET
/v3/{project_id}/types/default

Show default volume type

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 volume_type object.

is_public

body

boolean

Whether the volume type is publicly visible.

extra_specs (Optional)

body

object

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

description

body

string

The volume type description.

name

body

string

The name of the volume type.

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"
        }
    }
}
DELETE
/v3/{project_id}/types/{volume_type_id}

Delete a volume type

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.

GET
/v3/{project_id}/types

List all volume types

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response Parameters

Name

In

Type

Description

volume_types

body

array

The list of volume types. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

extra_specs (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
        }
    ]
}
POST
/v3/{project_id}/types

Create a volume type

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 volume_type object.

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 volume_type object.

is_public

body

boolean

Whether the volume type is publicly visible.

extra_specs (Optional)

body

object

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

description

body

string

The volume type description.

name

body

string

The name of the volume type.

id

body

string

The UUID of the volume type.

os-volume-type-access:is_public

body

boolean

Whether the volume type is publicly visible.

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"
    }
}
GET
/v3/{project_id}/types/{volume_type_id}/encryption

Show an encryption type

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, 2015-08-27T09:49:58-05:00.

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

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

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, 2015-08-27T09:49:58-05:00.

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

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

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"
}
GET
/v3/{project_id}/types/{volume_type_id}/encryption/{key}

Show encryption specs item

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"
}
DELETE
/v3/{project_id}/types/{volume_type_id}/encryption/{encryption_id}

Delete an encryption type

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.

POST
/v3/{project_id}/types/{volume_type_id}/encryption

Create an 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:

  • luks - relies on Linux Unified Key Setup (recommended)

  • plain - relies on dm-crypt

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"
    }
}
PUT
/v3/{project_id}/types/{volume_type_id}/encryption/{encryption_id}

Update an encryption type

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:

  • luks - relies on Linux Unified Key Setup (recommended)

  • plain - relies on dm-crypt

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.

POST
/v3/{project_id}/types/{volume_type}/action

Add private volume type access to project

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"
    }
}
POST
/v3/{project_id}/types/{volume_type}/action

Remove private volume type access from project

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"
    }
}
GET
/v3/{project_id}/types/{volume_type}/os-volume-type-access

List private volume type access detail

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

PUT
/v3/default-types/{project-id}

Create or update a default volume type

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"
    }
}
GET
/v3/default-types/{project-id}

Show a default volume type

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
/v3/default-types/

List default volume types

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"
        }
    ]
}
DELETE
/v3/default-types/{project-id}

Delete a default volume type

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.

GET
/v3/{project_id}/volumes/detail

List accessible volumes with details

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False.

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 consumes_quota field. Resources that don’t use quotas are usually temporary internal resources created to perform an operation. Default is to not filter by it. Filtering by this option may not be always possible in a cloud, see List Resource Filters to determine whether this filter is available in your cloud.

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 host@backend#pool.

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, 2015-08-27T09:49:58-05:00.

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

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

replication_status

body

string

The volume replication status.

snapshot_id (Optional)

body

string

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

id

body

string

The UUID of the volume.

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 metadata object. Contains one or more metadata key and value pairs that are associated with the volume.

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, 2015-08-27T09:49:58-05:00.

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

volumes

body

array

A list of volume objects.

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 null if the driver doesn’t use the field or if it hasn’t created it yet. Only returned for administrators.

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. true means only is iSCSI initiator running on host doesn’t support manual scans, false means never use locks, and null means to always use locks. Look at os-brick’s guard_connection context manager. Default=True.

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
        }
    ]
}
POST
/v3/{project_id}/volumes

Create a volume

Creates a volume.

To create a bootable volume, include the UUID of the image from which you want to create the volume in the imageRef attribute in the request body.

Since the Train release, every volume must have a volume type. It is optional to specify a volume type as part of your Create a volume request. If you do not specify one, a default volume type will be supplied for you. This type may vary according to what project you are in and how the operator has configured the Block Storage service. Use the Show default volume type request to determine your effective default volume type.

Preconditions

  • You must have enough volume storage quota remaining to create a volume of size requested.

Asynchronous Postconditions

  • With correct permissions, you can see the volume status as available through API calls.

  • With correct access, you can see the created volume in the storage system that OpenStack Block Storage manages.

Troubleshooting

  • If volume status remains creating or shows another error status, the request failed. Ensure you meet the preconditions then investigate the storage back end.

  • Volume is not created in the storage system that OpenStack Block Storage manages.

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

project_id

path

string

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

volume

body

object

A volume object.

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 cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

metadata (Optional)

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, 2015-08-27T09:49:58-05:00.

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

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

replication_status

body

string

The volume replication status.

snapshot_id (Optional)

body

string

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

id

body

string

The UUID of the volume.

size

body

integer

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

user_id

body

string

The UUID of the user.

metadata

body

object

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

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

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, 2015-08-27T09:49:58-05:00.

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

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 null if the driver doesn’t use the field or if it hasn’t created it yet. Only returned for administrators.

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. true means only is iSCSI initiator running on host doesn’t support manual scans, false means never use locks, and null means to always use locks. Look at os-brick’s guard_connection context manager. Default=True.

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
    }
}
GET
/v3/{project_id}/volumes

List accessible volumes

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False.

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 consumes_quota field. Resources that don’t use quotas are usually temporary internal resources created to perform an operation. Default is to not filter by it. Filtering by this option may not be always possible in a cloud, see List Resource Filters to determine whether this filter is available in your cloud.

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

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
        }
    ]
}
GET
/v3/{project_id}/volumes/{volume_id}

Show a volume’s details

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 host@backend#pool.

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, 2015-08-27T09:49:58-05:00.

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

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

replication_status

body

string

The volume replication status.

snapshot_id (Optional)

body

string

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

id

body

string

The UUID of the volume.

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 metadata object. Contains one or more metadata key and value pairs that are associated with the volume.

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

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, 2015-08-27T09:49:58-05:00.

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

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. true means only is iSCSI initiator running on host doesn’t support manual scans, false means never use locks, and null means to always use locks. Look at os-brick’s guard_connection context manager. Default=True.

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 null if the driver doesn’t use the field or if it hasn’t created it yet. Only returned for administrators.

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
    }
}
PUT
/v3/{project_id}/volumes/{volume_id}

Update a volume

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

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, 2015-08-27T09:49:58-05:00.

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

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

replication_status

body

string

The volume replication status.

snapshot_id (Optional)

body

string

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

id

body

string

The UUID of the volume.

size

body

integer

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

user_id

body

string

The UUID of the user.

metadata

body

object

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

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

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, 2015-08-27T09:49:58-05:00.

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

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 null if the driver doesn’t use the field or if it hasn’t created it yet. Only returned for administrators.

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. true means only is iSCSI initiator running on host doesn’t support manual scans, false means never use locks, and null means to always use locks. Look at os-brick’s guard_connection context manager. Default=True.

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
    }
}
DELETE
/v3/{project_id}/volumes/{volume_id}

Delete a volume

Deletes a volume.

Preconditions

  • Volume status must be available, in-use, error, error_restoring, error_extending, error_managing, and must not be migrating, attached, awaiting-transfer, belong to a group, have snapshots or be disassociated from snapshots after volume transfer.

  • The cascade option can be passed in the request if you want all snapshots of this volume to be deleted automatically, which should allow the volume deletion to succeed.

  • You cannot delete a volume that is in a migration.

Asynchronous Postconditions

  • The volume is deleted in volume index.

  • The volume managed by OpenStack Block Storage is deleted in storage node.

Troubleshooting

  • If volume status remains in deleting or becomes error_deleting the request failed. Ensure you meet the preconditions then investigate the storage back end.

  • The volume managed by OpenStack Block Storage is not deleted from the storage system.

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

New in version 3.23

POST
/v3/{project_id}/volumes/{volume_id}/metadata

Create metadata for volume

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"
    }
}
GET
/v3/{project_id}/volumes/{volume_id}/metadata

Show a volume’s metadata

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": {}
}
PUT
/v3/{project_id}/volumes/{volume_id}/metadata

Update a volume’s 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"
    }
}
GET
/v3/{project_id}/volumes/{volume_id}/metadata/{key}

Show a volume’s metadata for a specific key

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"
    }
}
DELETE
/v3/{project_id}/volumes/{volume_id}/metadata/{key}

Delete a volume’s metadata

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.

PUT
/v3/{project_id}/volumes/{volume_id}/metadata/{key}

Update a volume’s metadata for a specific key

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"
    }
}
GET
/v3/{project_id}/volumes/summary

Get volumes summary

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

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.

POST
/v3/{project_id}/volumes/{volume_id}/action

Extend a volume size

Extends the size of a volume to a requested size, in gibibytes (GiB). Specify the os-extend action in the request body.

Preconditions

  • Prior to microversion 3.42 the volume status must be available. Starting with microversion 3.42, attached volumes with status in-use may be able to be extended depending on policy and backend volume and compute driver constraints in the cloud. Note that reserved is not a valid state for extend.

  • Sufficient amount of storage must exist to extend the volume.

  • The user quota must have sufficient volume storage.

Postconditions

  • If the request is processed successfully, the volume status will change to extending while the volume size is being extended.

  • Upon successful completion of the extend operation, the volume status will go back to its original value.

  • Starting with microversion 3.42, when extending the size of an attached volume, the Block Storage service will notify the Compute service that an attached volume has been extended. The Compute service will asynchronously process the volume size change for the related server instance. This can be monitored using the GET /servers/{server_id}/os-instance-actions API in the Compute service.

Troubleshooting

  • An error_extending volume status indicates that the request failed. Ensure that you meet the preconditions and retry the request. If the request fails again, investigate the storage back end.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

os-extend

body

object

The os-extend action.

new_size

body

integer

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

Request Example

{
    "os-extend": {
        "new_size": 3
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Complete extending a volume

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 os-extend_volume_completion action.

error (Optional)

body

boolean

Used to indicate that the extend operation has failed outside of cinder.

Request Example

{
    "os-extend_volume_completion": {
        "error": false
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Reset a volume’s statuses

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 os-reset_status action.

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"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Revert volume to snapshot

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 revert action.

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"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Set image metadata for a volume

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 os-set_image_metadata action.

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"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Remove image metadata from a volume

Removes image metadata, by key, from a volume. Specify the os-unset_image_metadata action in the request body and the key for the metadata key and value pair that you want to remove.

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 os-unset_image_metadata action. This action removes the key-value pairs from the image metadata.

key

body

string

The metadata key name for the metadata that you want to remove.

Request Example

{
    "os-unset_image_metadata": {
        "key": "ramdisk_id"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Show image metadata for a volume

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 os-show_image_metadata action.

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"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Attach volume to a server

Attaches a volume to a server. Specify the os-attach action in the request body.

Preconditions

  • Volume status must be available.

  • You should set instance_uuid or host_name.

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 os-attach action.

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"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Detach volume from server

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 os-detach action.

attachment_id (Optional)

body

string

The ID of the attachment.

Request Example

{
    "os-detach": {
        "attachment_id": "d8777f54-84cf-4809-a679-468ffed56cf1"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Unmanage a volume

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

Preconditions

  • Volume status must be available.

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 os-unmanage action. This action removes the specified volume from Cinder management.

Request Example

{
    "os-unmanage": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Force detach a volume

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

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

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 os-force_detach action.

attachment_id (Optional)

body

string

The ID of the attachment.

connector (Optional)

body

object

The connector object.

Request Example

{
    "os-force_detach": {
        "attachment_id": "d8777f54-84cf-4809-a679-468ffed56cf1",
        "connector": {
            "initiator": "iqn.2012-07.org.fake:01"
        }
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Retype a volume

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 os-retype action.

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 on-demand or never. If not specified, the default is never.

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"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Migrate a volume

Specify the os-migrate_volume action in the request body.

Migrates a volume to the specified host. Starting with the 3.16 microversion a cluster can be specified instead of a host.

It is generally not recommended to migrate an in-use multiattach volume if that volume has more than one active read/write attachment.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy configuration file.

Preconditions

  • The volume status must be available or in-use.

  • The volume migration_status must be None, deleting, error, or success.

  • The volume replication_status must be None, disabled or not-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 os-migrate_volume action.

host (Optional)

body

string

The target host for the volume migration. Host format is host@backend. Required before microversion 3.16.

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 available volume will change its status to maintenance preventing other operations from being performed on the volume such as attach, detach, retype, etc.

cluster (Optional)

body

string

The target cluster for the volume migration. Cluster format is cluster@backend. Starting with microversion 3.16, either cluster or host must be specified. If host is specified and is part of a cluster, the cluster is used as the target for the migration.

New in version 3.16

Request Example

{
    "os-migrate_volume": {
        "host": "node1@lvm"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Complete migration of a volume

Specify the os-migrate_volume_completion action in the request body.

Complete the migration of a volume, updating the new volume in the DB, returning the status of the new volume to that of the original volume and finally deleting the original volume.

Preconditions

  • Both the original and new volume migration_status must be None or both must be set to a non None value.

  • Additionally when set the new volume migration_status must take the form of target:VOLUME_UUID where VOLUME_UUID is the original volume UUID.

Asynchronous Postconditions

On success, the volume status will return to its original status of available or in-use and the migration_status will be success. On failure, the migration_status will be error.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

volume_id

path

string

The UUID of the volume.

project_id

path

string

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

os-migrate_volume_completion

body

object

The os-migrate_volume_completion action.

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,
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Force delete a volume

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 os-force_delete action.

Request Example

{
    "os-force_delete": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Update a volume’s bootable status

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

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 os-set_bootable action.

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"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Upload volume to image

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 os-volume_upload_image action. This action uploads the specified volume to image service.

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 os-volume_upload_image action. This action uploads the specified volume to image service.

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, 2015-08-27T09:49:58-05:00.

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

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

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
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Reserve volume

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 os-reserve action.

Request Example

{
  "os-reserve": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Unmark volume as reserved.

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 os-unreserve action.

Request Example

{
    "os-unreserve":{}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Update volume status to detaching

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 os-begin_detaching action.

Request Example

{
    "os-begin_detaching": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Roll back volume status to in-use

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 os-roll_detaching action.

Request Example

{
   "os-roll_detaching": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Terminate volume attachment

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 os-terminate_connection action.

connector

body

object

The connector object. The internal structure of connector depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver.

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"
        }
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Initialize volume attachment

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 os-initialize_connection action.

connector

body

object

The connector object. The internal structure of connector depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver.

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"
        }
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Updates volume read-only access-mode flag

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 os-update_readonly_flag action. This action enables or disables update of volume to read-only access mode.

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
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Reimage a volume

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 available or error status. When true, this parameter will allow a volume in the reserved status to be re-imaged. The ability to re-image a volume in reserved status may be restricted to administrators in some clouds. Default value is false.

os-reimage

body

object

The os-reimage action.

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.

POST
/v3/{project_id}/manageable_volumes

Manage an existing volume

Creates a Block Storage volume by using existing storage rather than allocating new storage.

The caller must specify a reference to an existing storage volume in the ref parameter in the request. Although each storage driver might interpret this reference differently, the driver should accept a reference structure that contains either a source-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 volume object.

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

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, 2015-08-27T09:49:58-05:00.

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

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, 2015-08-27T09:49:58-05:00.

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

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

volume_type

body

object

A volume_type object.

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 metadata object. Contains one or more metadata key and value pairs that are associated with the volume.

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"
    }
}
GET
/v3/{project_id}/manageable_volumes

List summary of volumes available to manage

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

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
        }
    ]
}
GET
/v3/{project_id}/manageable_volumes/detail

List detail of volumes available to manage

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

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.

GET
/v3/{project_id}/snapshots/detail

List snapshots and details

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False.

New in version 3.45

consumes_quota (Optional)

query

boolean

Filters results by consumes_quota field. Resources that don’t use quotas are usually temporary internal resources created to perform an operation. Default is to not filter by it. Filtering by this option may not be always possible in a cloud, see List Resource Filters to determine whether this filter is available in your cloud.

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, 2015-08-27T09:49:58-05:00.

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

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, 2015-08-27T09:49:58-05:00.

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

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

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
        }
    ]
}
POST
/v3/{project_id}/snapshots

Create a snapshot

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 snapshot object.

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

force (Optional)

body

boolean

Indicates whether to snapshot, even if the volume is attached. Default is false. See valid boolean values

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, 2015-08-27T09:49:58-05:00.

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

name

body

string

The name of the snapshot.

snapshot

body

object

A snapshot 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.

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, 2015-08-27T09:49:58-05:00.

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

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

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
    }
}
GET
/v3/{project_id}/snapshots

List accessible snapshots

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

consumes_quota (Optional)

query

boolean

Filters results by consumes_quota field. Resources that don’t use quotas are usually temporary internal resources created to perform an operation. Default is to not filter by it. Filtering by this option may not be always possible in a cloud, see List Resource Filters to determine whether this filter is available in your cloud.

New in version 3.65

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False.

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, 2015-08-27T09:49:58-05:00.

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

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, 2015-08-27T09:49:58-05:00.

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

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

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"
        }
    ]
}
GET
/v3/{project_id}/snapshots/{snapshot_id}/metadata

Show a snapshot’s metadata

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"
    }
}
POST
/v3/{project_id}/snapshots/{snapshot_id}/metadata

Create a snapshot’s metadata

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"
    }
}
PUT
/v3/{project_id}/snapshots/{snapshot_id}/metadata

Update a snapshot’s metadata

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"
    }
}
GET
/v3/{project_id}/snapshots/{snapshot_id}

Show a snapshot’s details

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, 2015-08-27T09:49:58-05:00.

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

name (Optional)

body

string

The name of the object.

snapshot

body

object

A snapshot 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.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

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
    }
}
PUT
/v3/{project_id}/snapshots/{snapshot_id}

Update a snapshot

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 snapshot object.

description (Optional)

body

string

A description for the snapshot. Default is None.

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, 2015-08-27T09:49:58-05:00.

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

name (Optional)

body

string

The name of the object.

snapshot

body

object

A snapshot object.

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
    }
}
DELETE
/v3/{project_id}/snapshots/{snapshot_id}

Delete a snapshot

Deletes a snapshot.

Preconditions:

  • Snapshot status must be available or error

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.

GET
/v3/{project_id}/snapshot/{snapshot_id}/metadata/{key}

Show a snapshot’s metadata for a specific key

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"
    }
}
DELETE
/v3/{project_id}/snapshots/{snapshot_id}/metadata/{key}

Delete a snapshot’s metadata

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.

PUT
/v3/{project_id}/snapshots/{snapshot_id}/metadata/{key}

Update a snapshot’s metadata for a specific key

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.

POST
/v3/{project_id}/snapshots/{snapshot_id}/action

Reset a snapshot’s status

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 os-reset_status action.

status

body

string

The status for the snapshot.

Request Example

{
    "os-reset_status": {
        "status": "available"
    }
}
POST
/v3/{project_id}/snapshots/{snapshot_id}/action

Update status of a snapshot

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 os-update_snapshot_status action.

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%"
    }
}
POST
/v3/{project_id}/snapshots/{snapshot_id}/action

Force delete a snapshot

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 os-force_delete action.

Request Example

{
    "os-force_delete": {}
}

Snapshot manage extension (manageable_snapshots)

Creates or lists snapshots by using existing storage instead of allocating new storage.

POST
/v3/{project_id}/manageable_snapshots

Manage an existing snapshot

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 snapshot object.

description (Optional)

body

string

A description for the snapshot. Default is None.

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

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 snapshot object.

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

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, 2015-08-27T09:49:58-05:00.

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

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, 2015-08-27T09:49:58-05:00.

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

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

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"
    }
}
GET
/v3/{project_id}/manageable_snapshots

List summary of snapshots available to manage

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

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
        }
    ]
}
GET
/v3/{project_id}/manageable_snapshots/detail

List detail of snapshots available to manage

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

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.

POST
/v3/{project_id}/os-volume-transfer/{transfer_id}/accept

Accept a volume transfer

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"
    }
}
POST
/v3/{project_id}/os-volume-transfer

Create a volume transfer

Creates a volume transfer.

Preconditions

  • The volume status must be available

  • Transferring encrypted volumes is not supported

  • If the volume has snapshots, those snapshots must be available

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

project_id

path

string

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

transfer

body

object

The volume transfer object.

name (Optional)

body

string

The name of the object.

volume_id

body

string

The UUID of the volume.

Request Example

{
    "transfer": {
        "volume_id": "c86b9af4-151d-4ead-b62c-5fb967af0e37",
        "name": "first volume"
    }
}

Response Parameters

Name

In

Type

Description

auth_key

body

string

The authentication key for the volume transfer.

links

body

array

Links for the volume transfer.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

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"
    }
}
GET
/v3/{project_id}/os-volume-transfer

List volume transfers for a project

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"
        }
    ]
}
GET
/v3/{project_id}/os-volume-transfer/{transfer_id}

Show volume transfer detail

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, 2015-08-27T09:49:58-05:00.

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

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"
    }
}
DELETE
/v3/{project_id}/os-volume-transfer/{transfer_id}

Delete a volume transfer

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.

GET
/v3/{project_id}/os-volume-transfer/detail

List volume transfers and details

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, 2015-08-27T09:49:58-05:00.

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

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.

POST
/v3/{project_id}/volume-transfers/{transfer_id}/accept

Accept a volume transfer

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"
    }
}
POST
/v3/{project_id}/volume-transfers

Create a volume transfer

Creates a volume transfer.

Preconditions

  • The volume status must be available

  • Transferring encrypted volumes is not supported

  • If the volume has snapshots, those snapshots must be available unless no_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, 2015-08-27T09:49:58-05:00.

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

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"
    }
}
GET
/v3/{project_id}/volume-transfers

List volume transfers for a project

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

New in version 3.59

sort_key (Optional)

query

string

Sorts by an attribute. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value. Deprecated in favour of the combined sort parameter.

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 desc. Deprecated in favour of the combined sort parameter.

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 limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

New in version 3.59

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

New in version 3.59

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

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"
        }
    ]
}
GET
/v3/{project_id}/volume-transfers/{transfer_id}

Show volume transfer detail

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, 2015-08-27T09:49:58-05:00.

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

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"
    }
}
DELETE
/v3/{project_id}/volume-transfers/{transfer_id}

Delete a volume transfer

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.

GET
/v3/{project_id}/volume-transfers/detail

List volume transfers and details

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, 2015-08-27T09:49:58-05:00.

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

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.

DELETE
/v3/{project_id}/attachments/{attachment_id}

Delete attachment

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.

GET
/v3/{project_id}/attachments/{attachment_id}

Show attachment details

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"
    }
}
GET
/v3/{project_id}/attachments/detail

List attachments with details

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response Parameters

Name

In

Type

Description

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"
        }
    ]
}
GET
/v3/{project_id}/attachments

List attachments

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response Parameters

Name

In

Type

Description

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"
        }
    ]
}
POST
/v3/{project_id}/attachments

Create attachment

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 connector object.

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"
    }
}
PUT
/v3/{project_id}/attachments/{attachment_id}

Update an attachment

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 connector object. The internal structure of connector depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver.

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"
    }
}
POST
/v3/{project_id}/attachments/{attachment_id}/action

Complete attachment

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.

GET
/v3/{project_id}/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.

GET
/v3/{project_id}/scheduler-stats/get_pools

List all back-end storage pools

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 true to show pool details. Set to false to show only pool names. Default is false.

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 unknown, or a number (integer or floating point).

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 null or a string value that indicates the capabilities for each pool. For example, total_capacity_gb or QoS_support.

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 unknown, or a number (integer or floating point).

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, iSCSI or FC.

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.

GET
/v3/{project_id}/backups/detail

List backups with detail

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False.

New in version 3.45

Response Parameters

Name

In

Type

Description

backups

body

array

A list of backup objects.

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, 2015-08-27T09:49:58-05:00.

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

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

name

body

string

The backup name.

has_dependent_backups (Optional)

body

boolean

If this value is true, there are other backups depending on this backup.

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 true, the backup mode is incremental. If this value is false, the backup mode is full.

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 created_at for a backup. If it is a backup from a snapshot, it will be the same as created_at for the snapshot.

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: "rel" with the value "next" and href, whose value is a link to the next page of backups. Only appears when there are more backups than are listed in the current response.

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"
        }
    ]
}
GET
/v3/{project_id}/backups/{backup_id}

Show backup detail

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

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, 2015-08-27T09:49:58-05:00.

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

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

name

body

string

The backup name.

has_dependent_backups (Optional)

body

boolean

If this value is true, there are other backups depending on this backup.

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

id

body

string

The UUID of the backup.

is_incremental (Optional)

body

boolean

Indicates whether the backup mode is incremental. If this value is true, the backup mode is incremental. If this value is false, the backup mode is full.

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 created_at for a backup. If it is a backup from a snapshot, it will be the same as created_at for the snapshot.

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"
    }
}
DELETE
/v3/{project_id}/backups/{backup_id}

Delete a backup

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.

POST
/v3/{project_id}/backups/{backup_id}/restore

Restore 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 restore object.

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 restore object.

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"
    }
}
POST
/v3/{project_id}/backups

Create a backup

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

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 true for incremental backup mode or false for full backup mode. Default is false. See valid boolean values

force (Optional)

body

boolean

Indicates whether to backup, even if the volume is attached. Default is false. See valid boolean values

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

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"
    }
}
PUT
/v3/{project_id}/backups/{backup_id}

Update a backup

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

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

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"
    }
}
GET
/v3/{project_id}/backups

List backups for project

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

with_count (Optional)

query

boolean

Whether to show count in API response or not, default is False.

New in version 3.45

Response Parameters

Name

In

Type

Description

backups

body

array

A list of backup objects.

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: "rel" with the value "next" and href, whose value is a link to the next page of backups. Only appears when there are more backups than are listed in the current response.

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"
        }
    ]
}
GET
/v3/{project_id}/backups/{backup_id}/export_record

Export a backup

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 and backup_url.

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"
    }
}
POST
/v3/{project_id}/backups/import_record

Import a backup

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 and backup_url.

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.

POST
/v3/{project_id}/backups/{backup_id}/action

Force-delete 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 os-force_delete action.

Request Example

{
    "os-force_delete": {}
}
POST
/v3/{project_id}/backups/{backup_id}/action

Reset a backup’s status

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 os-reset_status action.

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.

GET
/v3/{project_id}/capabilities/{hostname}

Show all back-end capabilities

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 OS::Storage::Capabilities::foo.

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, iSCSI or FC.

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.

PUT
/v3/{project_id}/clusters/disable

Disable cluster

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 up or down.

status

body

string

The status of the cluster. One of enabled or disabled.

replication_status (Optional)

body

string

The cluster replication status. Only included in responses if configured. One of: enabled or disabled.

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"
    }
}
PUT
/v3/{project_id}/clusters/enable

Enable cluster

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 up or down.

status

body

string

The status of the cluster. One of enabled or disabled.

replication_status (Optional)

body

string

The cluster replication status. Only included in responses if configured. One of: enabled or disabled.

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"
    }
}
GET
/v3/{project_id}/clusters/{cluster_name}

Show cluster details

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 cinder-api, cinder-scheduler, cinder-volume or cinder-backup.

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 up or down.

status

body

string

The status of the cluster. One of enabled or disabled.

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, 2015-08-27T09:49:58-05:00.

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

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

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: enabled or disabled.

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

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"
    }
}
GET
/v3/{project_id}/clusters

List clusters

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 cinder-api, cinder-scheduler, cinder-volume or cinder-backup.

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: enabled, disabled.

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 up or down.

status

body

string

The status of the cluster. One of enabled or disabled.

replication_status (Optional)

body

string

The cluster replication status. Only included in responses if configured. One of: enabled or disabled.

Response Example

{
    "clusters": [
        {
            "name": "cluster_name",
            "binary": "cinder-volume",
            "state": "up",
            "status": "enabled",
            "replication_status": "enable"
        }
    ]
}
GET
/v3/{project_id}/clusters/detail

List clusters with details

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 cinder-api, cinder-scheduler, cinder-volume or cinder-backup.

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: enabled, disabled.

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

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 up or down.

status

body

string

The status of the cluster. One of enabled or disabled.

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, 2015-08-27T09:49:58-05:00.

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

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

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: enabled or disabled.

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

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.

GET
/v3/{project_id}/consistencygroups

List project’s consistency groups

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response Parameters

Name

In

Type

Description

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"
        }
    ]
}
POST
/v3/{project_id}/consistencygroups

Create a consistency group

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, 2015-08-27T09:49:58-05:00.

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

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"
    }
}
GET
/v3/{project_id}/consistencygroups/{consistencygroup_id}

Show a consistency group’s details

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, 2015-08-27T09:49:58-05:00.

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

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"
        ]
    }
}
POST
/v3/{project_id}/consistencygroups/create_from_src

Create a consistency group from source

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"
    }
}
POST
/v3/{project_id}/consistencygroups/{consistencygroup_id}/delete

Delete a consistency group

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 false. See valid boolean values

Request Example

{
    "consistencygroup": {
        "force": false
    }
}
GET
/v3/{project_id}/consistencygroups/detail

List consistency groups and details

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 < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc. Deprecated in favour of the combined sort parameter.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response Parameters

Name

In

Type

Description

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, 2015-08-27T09:49:58-05:00.

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

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"
            ]
        }
    ]
}
PUT
/v3/{project_id}/consistencygroups/{consistencygroup_id}/update

Update a consistency group

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.

DELETE
/v3/{project_id}/cgsnapshots/{cgsnapshot_id}

Delete a consistency group snapshot

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.

GET
/v3/{project_id}/cgsnapshots/{cgsnapshot_id}

Show consistency group snapshot detail

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 status of the consistency group snapshot.

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, 2015-08-27T09:49:58-05:00.

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

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"
    }
}
GET
/v3/{project_id}/cgsnapshots/detail

List all consistency group snapshots with details

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 cgsnapshot objects.

status (Optional)

body

string

The status of the consistency group snapshot.

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, 2015-08-27T09:49:58-05:00.

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

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"
        }
    ]
}
GET
/v3/{project_id}/cgsnapshots

List all consistency group snapshots

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 cgsnapshot objects.

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"
        }
    ]
}
POST
/v3/{project_id}/cgsnapshots

Create a consistency group snapshot

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

consistencygroup_id

body

string

The UUID of the consistency group.

description (Optional)

body

string

The consistency group snapshot description.

Request Example

{
    "cgsnapshot": {