Block Storage API V2 (REMOVED)

Note

Version 2 of the Block Storage API was deprecated in the Pike release and was removed during the Xena development cycle. This document is maintained for historical purposes only.

Version 3 of the Block Storage API was introduced in the Mitaka release. Version 3.0, which is the default microversion at the /v3 endpoint, was designed to be identical to version 2. Thus, scripts using the Block Storage API v2 should be adaptable to version 3 with minimal changes.

API versions

GET
/

List Api Versions

Lists information for all Block Storage API versions.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

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.

404 - Not Found

The requested resource could not be found.

405 - Method Not Allowed

Method is not valid for this endpoint and resource.

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.

Response

Example List Api Versions: JSON request

{
    "versions": [
        {
            "status": "SUPPORTED",
            "updated": "2014-06-28T12:20:21Z",
            "links": [
                {
                    "href": "https://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://10.0.2.15:8776/v2/",
                    "rel": "self"
                }
            ],
            "min_version": "",
            "version": "",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.volume+json;version=1"
                }
            ],
            "id": "v2.0"
        },
        {
            "status": "CURRENT",
            "updated": "2016-02-08T12:20:21Z",
            "links": [
                {
                    "href": "https://docs.openstack.org/",
                    "type": "text/html",
                    "rel": "describedby"
                },
                {
                    "href": "http://10.0.2.15:8776/v3/",
                    "rel": "self"
                }
            ],
            "min_version": "3.0",
            "version": "{Current_Max_Version}",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.volume+json;version=1"
                }
            ],
            "id": "v3.0"
        }
    ]
}

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
/v2/{project_id}/backups/detail

List backups with details

Lists Block Storage backups, with details, to which the project has access.

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 projects. Admin only.

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

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

backups

body

array

A list of backup objects.

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.

Response Example

{
    "backups": [
        {
            "availability_zone": "az1",
            "container": "volumebackups",
            "created_at": "2013-04-02T10:35:27.000000",
            "description": null,
            "fail_reason": null,
            "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
            "links": [
                {
                    "href": "http://localhost:8776/v2/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "bookmark"
                }
            ],
            "name": "backup001",
            "object_count": 22,
            "size": 1,
            "status": "available",
            "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
            "is_incremental": true,
            "has_dependent_backups": false
        },
        {
            "availability_zone": "az1",
            "container": "volumebackups",
            "created_at": "2013-04-02T10:21:48.000000",
            "description": null,
            "fail_reason": null,
            "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
            "links": [
                {
                    "href": "http://localhost:8776/v2/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "bookmark"
                }
            ],
            "name": "backup002",
            "object_count": 22,
            "size": 1,
            "status": "available",
            "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
            "is_incremental": true,
            "has_dependent_backups": false
        }
    ]
}
GET
/v2/{project_id}/backups/{backup_id}

Show backup details

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

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.

Response Example

{
    "backup": {
        "availability_zone": "az1",
        "container": "volumebackups",
        "created_at": "2013-04-02T10:35:27.000000",
        "description": null,
        "fail_reason": null,
        "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
        "links": [
            {
                "href": "http://localhost:8776/v2/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                "rel": "bookmark"
            }
        ],
        "name": "backup001",
        "object_count": 22,
        "size": 1,
        "status": "available",
        "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
        "is_incremental": true,
        "has_dependent_backups": false
    }
}
DELETE
/v2/{project_id}/backups/{backup_id}

Delete 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
/v2/{project_id}/backups/{backup_id}/restore

Restore backup

Restores a Block Storage backup to an existing or new Block Storage volume.

You must specify either the UUID or name of the volume. If you specify both the UUID and name, the UUID takes priority.

If specifying volume_id the status of the volume must be available.

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

restore

body

object

A restore object.

name

body

string

The backup name.

volume_id

body

string

The UUID of the volume.

project_id

path

string

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

backup_id

path

string

The UUID for 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"
    }
}
POST
/v2/{project_id}/backups

Create backup

Creates a Block Storage backup from a volume.

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.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

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.

volume_id

body

string

The UUID of the volume.

force (Optional)

body

boolean

Indicates whether to backup, even if the volume is attached. Default is false.

backup

body

object

A backup object.

name

body

string

The backup name.

project_id

path

string

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

snapshot_id (Optional)

body

string

The UUID of the source volume snapshot.

Request Example

{
    "backup": {
        "container": null,
        "description": null,
        "name": "backup001",
        "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607",
        "incremental": true
    }
}

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.

GET
/v2/{project_id}/backups

List backups

Lists Block Storage backups to which the project has access.

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 projects. Admin only.

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

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

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.

Response Example

{
    "backups": [
        {
            "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
            "links": [
                {
                    "href": "http://localhost:8776/v2/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "bookmark"
                }
            ],
            "name": "backup001"
        },
        {
            "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
            "links": [
                {
                    "href": "http://localhost:8776/v2/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "bookmark"
                }
            ],
            "name": "backup002"
        }
    ]
}
GET
/v2/{project_id}/backups/{backup_id}/export_record

Export 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
/v2/{project_id}/backups/import_record

Import 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/v2/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
/v2/{project_id}/backups/{backup_id}/action

Force-delete 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

os-force_delete

body

string

The os-force_delete action.

project_id

path

string

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

backup_id

path

string

The UUID for a backup.

Request Example

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

Reset 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

status

body

string

The status for the backup.

os-reset_status

body

object

The os-reset_status action.

project_id

path

string

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

backup_id

path

string

The UUID for a backup.

Request Example

{
    "os-reset_status": {
        "status": "available"
    }
}

Capabilities for storage back ends (capabilities)

Shows capabilities for a storage back end.

GET
/v2/{project_id}/capabilities/{hostname}

Show 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 (Optional)

body

string

The backup description or null.

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

Consistency group snapshots

Lists all, lists all with details, shows details for, creates, and deletes consistency group snapshots.

DELETE
/v2/{project_id}/cgsnapshots/{cgsnapshot_id}

Delete 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
/v2/{project_id}/cgsnapshots/{cgsnapshot_id}

Show consistency group snapshot details

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

status (Optional)

body

string

The status of the consistency group snapshot.

description (Optional)

body

string

The backup description or null.

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

name

body

string

The name of the Volume Transfer.

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
/v2/{project_id}/cgsnapshots/detail

List 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 projects. Admin only.

Response Parameters

Name

In

Type

Description

status (Optional)

body

string

The status of the consistency group snapshot.

description (Optional)

body

string

The backup description or null.

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

name

body

string

The name of the Volume Transfer.

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
/v2/{project_id}/cgsnapshots

List 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 projects. Admin only.

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the volume transfer.

name

body

string

The name of the Volume Transfer.

Response Example

{
    "cgsnapshots": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my-cg1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my-cg2"
        }
    ]
}
POST
/v2/{project_id}/cgsnapshots

Create 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

name

body

string

The name of the Volume Transfer.

project_id

path

string

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

Request Example

{
    "cgsnapshot": {
        "consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814546",
        "name": "firstcg",
        "description": "first consistency group",
        "user_id": "6f519a48-3183-46cf-a32f-41815f814444",
        "project_id": "6f519a48-3183-46cf-a32f-41815f815555",
        "status": "creating"
    }
}

Response Parameters

Name

In

Type

Description

status (Optional)

body

string

The status of the consistency group snapshot.

description (Optional)

body

string

The backup description or null.

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

name

body

string

The name of the Volume Transfer.

Consistency groups

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
/v2/{project_id}/consistencygroups

List 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 projects. Admin only.

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

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

id

body

string

The UUID of the volume transfer.

name

body

string

The name of the Volume Transfer.

Response Example

{
    "consistencygroups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my-cg1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my-cg2"
        }
    ]
}
POST
/v2/{project_id}/consistencygroups

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

description

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

status

body

string

The status of the consistency group.

description (Optional)

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
/v2/{project_id}/consistencygroups/{consistencygroup_id}

Show consistency group 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

body

string

The UUID of the consistency group.

Response Parameters

Name

In

Type

Description

status

body

string

The status of the consistency group.

description (Optional)

body

string

The backup description or null.

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

name

body

string

The name of the Volume Transfer.

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
/v2/{project_id}/consistencygroups/create_from_src

Create 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

status

body

string

The status of the consistency group.

user_id

body

string

The UUID of the user.

description (Optional)

body

string

The backup description or null.

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

path

string

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

name

body

string

The name of the Volume Transfer.

project_id

body

string

The UUID of the project.

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
/v2/{project_id}/consistencygroups/{consistencygroup_id}/delete

Delete 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

force (Optional)

body

boolean

Indicates whether to backup, even if the volume is attached. Default is false.

project_id

path

string

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

consistencygroup_id

body

string

The UUID of the consistency group.

Request Example

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

List consistency groups with 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 projects. Admin only.

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

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 consistency group.

description (Optional)

body

string

The backup description or null.

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

name

body

string

The name of the Volume Transfer.

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
/v2/{project_id}/consistencygroups/{consistencygroup_id}/update

Update 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

remove_volumes (Optional)

body

string

One or more volume UUIDs, separated by commas, to remove from the volume consistency group.

description (Optional)

body

string

The backup description or null.

add_volumes (Optional)

body

string

One or more volume UUIDs, separated by commas, to add to the volume consistency group.

name

body

string

The name of the Volume Transfer.

project_id

path

string

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

consistencygroup_id

body

string

The UUID of the consistency group.

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

Hosts extension (os-hosts)

Administrators only, depending on policy settings.

Lists, shows hosts.

GET
/v2/{admin_project_id}/os-hosts

List all hosts

Lists all hosts summary info that is not disabled.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

admin_project_id

path

string

The UUID of the administrative project.

Response Parameters

Name

In

Type

Description

service-status

body

string

The status of the service. One of available or unavailable.

service

body

string

The name of the service which is running on the host.

zone

body

string

The availability zone name.

service-state

body

string

The state of the service. One of enabled or disabled.

host_name

body

string

The name of the host that hosts the storage backend, may take the format of host@backend.

last-update

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

For example, 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

{
    "hosts": [{
        "service-status": "available",
        "service": "cinder-backup",
        "zone": "nova",
        "service-state": "enabled",
        "host_name": "node1",
        "last-update": "2017-03-09T21:38:41.000000"
    },
    {
        "service-status": "available",
        "service": "cinder-scheduler",
        "zone": "nova",
        "service-state": "enabled",
        "host_name": "node1",
        "last-update": "2017-03-09T21:38:38.000000"
    },
    {
        "service-status": "available",
        "service": "cinder-volume",
        "zone": "nova",
        "service-state": "enabled",
        "host_name": "node1@lvm",
        "last-update": "2017-03-09T21:38:35.000000"
    }]
}
GET
/v2/{admin_project_id}/os-hosts/{host_name}

Show Host Details

Shows volume and snapshot details for a cinder-volume host.

Note: This API is meant specifically for cinder-volume hosts only. It is not valid against other Cinder service hosts or hosts where the cinder-volume service has been disabled.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

admin_project_id

path

string

The UUID of the administrative project.

host_name

path

string

The name of the host that hosts the storage back end.

Response

Name

In

Type

Description

volume_count

body

string

Total number of volumes.

total_volume_gb

body

string

The total number of gibibytes (GiB) used.

total_snapshot_gb

body

string

The total number of snapshots used.

project

body

string

The UUID of the project which the host resource belongs to. In the summary resource, the value is (total).

host

body

string

The name of the host that hosts the storage backend, may take the format of host@backend.

snapshot_count

body

integer

The total number of snapshots used.

Example Show Host Details

{
    "host": [{
            "resource": {
                "volume_count": "8",
                "total_volume_gb": "11",
                "total_snapshot_gb": "1",
                "project": "(total)",
                "host": "node1@rbd-sas",
                "snapshot_count": "1"
            }
        },
        {
            "resource": {
                "volume_count": "8",
                "total_volume_gb": "11",
                "total_snapshot_gb": "1",
                "project": "f21a9c86d7114bf99c711f4874d80474",
                "host": "node1@rbd-sas",
                "snapshot_count": "1"
            }
        }]
}

Limits (limits)

Shows absolute limits for a project.

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

GET
/v2/{project_id}/limits

Show absolute limits

Shows absolute limits for a project.

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id

path

string

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

Response Parameters

Name

In

Type

Description

totalSnapshotsUsed

body

integer

The total number of snapshots used.

maxTotalBackups

body

integer

The maximum number of backups.

maxTotalVolumeGigabytes

body

integer

The maximum total amount of volumes, in gibibytes (GiB).

limits

body

object

A list of limit objects.

maxTotalSnapshots

body

integer

The maximum number of snapshots.

maxTotalBackupGigabytes

body

integer

The maximum total amount of backups, in gibibytes (GiB).

totalBackupGigabytesUsed

body

integer

The total number of backups gibibytes (GiB) used.

maxTotalVolumes

body

integer

The maximum number of volumes.

totalVolumesUsed

body

integer

The total number of volumes used.

rate

body

array

Rate-limit volume copy bandwidth, used to mitigate slow down of data access from the instances.

totalBackupsUsed

body

integer

The total number of backups used.

totalGigabytesUsed

body

integer

The total number of gibibytes (GiB) used.

absolute

body

object

An absolute limits object.

Response Example

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

Back-end storage pools

Administrator only. Lists all back-end storage pools that are known to the scheduler service.

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

List back-end storage pools

Lists all back-end storage pools.

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.

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

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

Volume transfer

Transfers a volume from one user to another user.

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

Accept 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

auth_key

body

string

The authentication key for the volume transfer.

transfer

body

object

The volume transfer object.

transfer_id (Optional)

path

string

The unique identifier for a volume transfer.

project_id

path

string

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

Request Example

{
    "accept": {
        "auth_key": "9266c59563c84664"
    }
}

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

body

string

The name of the Volume Transfer.

Response Example

{
    "transfer": {
        "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
        "name": "first volume transfer",
        "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/1",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/1",
                "rel": "bookmark"
            }
        ]
    }
}
POST
/v2/{project_id}/os-volume-transfer

Create 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

body

string

The name of the Volume Transfer.

volume_id

body

string

The UUID of the volume.

project_id

path

string

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

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

body

string

The name of the Volume Transfer.

Response Example

{
    "transfer": {
        "id": "1a7059f5-8ed7-45b7-8d05-2811e5d09f24",
        "created_at": "2015-02-25T03:56:53.081642",
        "name": "first volume",
        "volume_id": "c86b9af4-151d-4ead-b62c-5fb967af0e37",
        "auth_key": "9266c59563c84664",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/3",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/3",
                "rel": "bookmark"
            }
        ]
    }
}
GET
/v2/{project_id}/os-volume-transfer

List volume transfers

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

body

string

The name of the Volume Transfer.

Response Example

{
    "transfers": [
        {
            "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
            "name": "first volume transfer",
            "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/1",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/1",
                    "rel": "bookmark"
                }
            ]
        },
        {
            "id": "f26c0dee-d20d-4e80-8dee-a8d91b9742a1",
            "name": "second volume transfer",
            "volume_id": "673db275-379f-41af-8371-e1652132b4c1",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/2",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/2",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}
GET
/v2/{project_id}/os-volume-transfer/{transfer_id}

Show volume transfer details

Shows details for a volume transfer.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

transfer_id (Optional)

path

string

The unique identifier for a volume transfer.

project_id

path

string

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

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

body

string

The name of the Volume Transfer.

Response Example

{
    "transfer": {
        "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
        "created_at": "2015-02-25T03:56:53.081642",
        "name": "first volume transfer",
        "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/1",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/1",
                "rel": "bookmark"
            }
        ]
    }
}
DELETE
/v2/{project_id}/os-volume-transfer/{transfer_id}

Delete 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

transfer_id (Optional)

path

string

The unique identifier for a volume transfer.

project_id

path

string

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

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

List volume transfers, with 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 projects. Admin only.

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

body

string

The name of the Volume Transfer.

Response Example

{
    "transfers": [
        {
            "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
            "created_at": "2015-02-25T03:56:53.081642",
            "name": "first volume transfer",
            "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/1",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/1",
                    "rel": "bookmark"
                }
            ]
        },
        {
            "id": "f26c0dee-d20d-4e80-8dee-a8d91b9742a1",
            "created_at": "2015-03-25T03:56:53.081642",
            "name": "second volume transfer",
            "volume_id": "673db275-379f-41af-8371-e1652132b4c1",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/2",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/2",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}

Quality of service (QoS) specifications (qos-specs)

Administrators only.

Creates, lists, shows details for, associates, disassociates, sets keys, unsets keys, and deletes quality of service (QoS) specifications.

GET
/v2/{project_id}/qos-specs/{qos_id}/disassociate_all

Disassociate QoS specification from all associations

Disassociates a QoS specification from all associations.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

project_id

path

string

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

qos_id

path

string

The ID of the QoS specification.

PUT
/v2/{project_id}/qos-specs/{qos_id}/delete_keys

Unset keys in QoS specification

Unsets keys in a QoS specification.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

keys

body

array

List of Keys.

project_id

path

string

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

qos_id

path

string

The ID of the QoS specification.

Request Example

{
    "keys": [
        "key1"
    ]
}

Response Example


GET
/v2/{project_id}/qos-specs/{qos_id}/associations

Get all associations for QoS specification

Lists all associations for a QoS specification.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

project_id

path

string

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

qos_id

path

string

The ID of the QoS specification.

Response Example

{
    "qos_specs": {
        "specs": {
            "availability": "100",
            "numberOfFailures": "0"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v2/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "self"
        },
        {
            "href": "http://23.253.228.211:8776/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "bookmark"
        }
    ]
}
GET
/v2/{project_id}/qos-specs/{qos_id}/associate

Associate QoS specification with volume type

Associates a QoS specification with 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.

qos_id

path

string

The ID of the QoS specification.

vol_type_id

path

string

The UUID for an existing volume type.

GET
/v2/{project_id}/qos-specs/{qos_id}/disassociate

Disassociate QoS specification from volume type

Disassociates a QoS specification from 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.

qos_id

path

string

The ID of the QoS specification.

vol_type_id

path

string

The UUID for an existing volume type.

GET
/v2/{project_id}/qos-specs/{qos_id}

Show QoS specification details

Shows details for a QoS specification.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

405 - Method Not Allowed

Method is not valid for this endpoint and resource.

413 - Request Entity Too Large

This operation cannot be completed.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

project_id

path

string

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

qos_id

path

string

The ID of the QoS specification.

Response Parameters

Name

In

Type

Description

name

body

string

The name of the QoS specification.

links

body

array

The QoS specification links.

id

body

string

The generated ID for the QoS specification.

qos_specs

body

object

A qos_specs object.

consumer (Optional)

body

string

The consumer type.

specs

body

object

A specs object.

Response Example

{
    "qos_specs": {
        "specs": {
            "availability": "100",
            "numberOfFailures": "0"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v2/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "self"
        },
        {
            "href": "http://23.253.228.211:8776/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "bookmark"
        }
    ]
}
PUT
/v2/{project_id}/qos-specs/{qos_id}

Set keys in QoS specification

Sets keys in a QoS specification.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

qos_specs

body

object

A qos_specs object.

specs

body

object

A specs object.

project_id

path

string

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

qos_id

path

string

The ID of the QoS specification.

Request Example

{
    "qos_specs": {
        "delay": "1"
    }
}

Response Example

{
    "qos_specs": {
        "delay": "1"
    }
}
DELETE
/v2/{project_id}/qos-specs/{qos_id}

Delete QoS specification

Deletes a QoS specification.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

project_id

path

string

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

qos_id

path

string

The ID of the QoS specification.

force (Optional)

body

boolean

Indicates whether to backup, even if the volume is attached. Default is false.

POST
/v2/{project_id}/qos-specs

Create QoS specification

Creates a QoS specification.

Specify one or more key and value pairs in the request body.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

qos_specs

body

object

A qos_specs object.

consumer (Optional)

body

string

The consumer type.

name

body

string

The name of the QoS specification.

project_id

path

string

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

Request Example

{
    "qos_specs": {
        "availability": "100",
        "name": "reliability-spec",
        "numberOfFailures": "0"
    }
}

Response Parameters

Name

In

Type

Description

name

body

string

The name of the QoS specification.

links

body

array

The QoS specification links.

id

body

string

The generated ID for the QoS specification.

qos_specs

body

object

A qos_specs object.

consumer (Optional)

body

string

The consumer type.

specs

body

object

A specs object.

GET
/v2/{project_id}/qos-specs

List QoS specs

Lists quality of service (QoS) specifications.

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_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

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

specs

body

object

A specs object.

qos_specs

body

object

A qos_specs object.

consumer (Optional)

body

string

The consumer type.

id

body

string

The generated ID for the QoS specification.

name

body

string

The name of the QoS specification.

Response Example

{
    "qos_specs": [
        {
            "specs": {
                "availability": "100",
                "numberOfFailures": "0"
            },
            "consumer": "back-end",
            "name": "reliability-spec",
            "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
        },
        {
            "specs": {
                "delay": "0",
                "throughput": "100"
            },
            "consumer": "back-end",
            "name": "performance-spec",
            "id": "ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
        }
    ]
}

Quota class set extension (os-quota-class-sets)

Administrators only, depending on policy settings.

Shows and updates quota classes for a project.

GET
/v2/{admin_project_id}/os-quota-class-sets/{quota_class_name}

Show quota classes

Shows quota class set for a project. If no specific value for the quota class resource exists, then the default value will be reported.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

quota_class_name

path

string

The name of the quota class for which to set quotas.

admin_project_id

path

string

The UUID of the administrative project.

Response Parameters

Name

In

Type

Description

backup_gigabytes

body

integer

The maximum total amount of backups, in gibibytes (GiB).

backups

body

integer

The maximum number of backups.

gigabytes

body

integer

The maximum total amount of volumes, in gibibytes (GiB).

groups

body

integer

The maximum number of groups.

per_volume_gigabytes

body

integer

The maximum amount of storage per volume, in gibibytes (GiB).

snapshots

body

integer

The maximum number of snapshots.

volumes

body

integer

The maximum number of volumes.

id

body

string

The name of the quota class set.

Response Example

{
  "quota_class_set": {
    "per_volume_gigabytes": -1,
    "volumes_lvmdriver-1": -1,
    "groups": 10,
    "gigabytes": 1000,
    "backup_gigabytes": 1000,
    "snapshots": 10,
    "gigabytes_lvmdriver-1": -1,
    "volumes": 10,
    "snapshots_lvmdriver-1": -1,
    "backups": 10,
    "id": "default"
  }
}
PUT
/v2/{admin_project_id}/os-quota-class-sets/{quota_class_name}

Update quota classes

Updates quota class set for a project. If the quota_class_name key does not exist, then the API will create one.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

admin_project_id

path

string

The UUID of the administrative project.

quota_class_name

path

string

The name of the quota class for which to set quotas.

gigabytes

body

integer

The maximum total amount of volumes, in gibibytes (GiB).

snapshots (Optional)

body

integer

The maximum number of snapshots.

volumes (Optional)

body

integer

The maximum number of volumes.

volume-type (Optional)

path

string

The ID of Volume Type to be accessed by project.

Request Example

{
  "quota_class_set": {
    "volumes_lmv": 10,
    "gigabytes_lmv": 1000,
    "snapshots_lmv": 10
  }
}

Response Parameters

Name

In

Type

Description

backup_gigabytes

body

integer

The maximum total amount of backups, in gibibytes (GiB).

backups

body

integer

The maximum number of backups.

gigabytes

body

integer

The maximum total amount of volumes, in gibibytes (GiB).

groups

body

integer

The maximum number of groups.

per_volume_gigabytes

body

integer

The maximum amount of storage per volume, in gibibytes (GiB).

snapshots

body

integer

The maximum number of snapshots.

volumes

body

integer

The maximum number of volumes.

Response Example

{
  "quota_class_set": {
    "per_volume_gigabytes": -1,
    "volumes_lvmdriver-1": -1,
    "groups": 10,
    "gigabytes": 1000,
    "backup_gigabytes": 1000,
    "snapshots": 10,
    "gigabytes_lvmdriver-1": -1,
    "volumes": 10,
    "snapshots_lvmdriver-1": -1,
    "backups": 10
  }
}

Quota sets extension (os-quota-sets)

Administrators only, depending on policy settings.

Shows, updates, and deletes quotas for a project.

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

Show quotas

Shows quotas for a project.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

project_id

path

string

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

admin_project_id

path

string

The UUID of the administrative project.

usage (Optional)

query

boolean

Set to usage=true to show quota usage. Default is false.

Response Parameters

Name

In

Type

Description

quota_set

body

object

A quota_set object.

id

body

string

The UUID of the project.

volumes

body

integer

The number of volumes that are allowed for each project.

volumes_{volume_type}

body

integer

The number of volumes that are allowed for each project and the specified volume type.

snapshots

body

integer

The number of snapshots that are allowed for each project.

snapshots_{volume_type}

body

integer

The number of snapshots that are allowed for each project and the specified volume type.

backups

body

integer

The number of backups that are allowed for each project.

groups

body

integer

The number of groups that are allowed for each project.

per_volume_gigabytes

body

integer

The size (GB) of volumes in request that are allowed for each volume.

gigabytes

body

integer

The size (GB) of volumes and snapshots that are allowed for each project.

gigabytes_{volume_type}

body

integer

The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type.

backup_gigabytes

body

integer

The size (GB) of backups that are allowed for each project.

Response Example

{
    "quota_set": {
        "gigabytes": 5,
        "snapshots": 10,
        "volumes": 20
    }
}
PUT
/v2/{admin_project_id}/os-quota-sets/{project_id}

Update quotas

Updates quotas for a project.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

admin_project_id

path

string

The UUID of the administrative project.

project_id

path

string

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

quota_set

body

object

A quota_set object.

volumes

body

integer

The number of volumes that are allowed for each project.

volumes_{volume_type}

body

integer

The number of volumes that are allowed for each project and the specified volume type.

snapshots

body

integer

The number of snapshots that are allowed for each project.

snapshots_{volume_type}

body

integer

The number of snapshots that are allowed for each project and the specified volume type.

backups

body

integer

The number of backups that are allowed for each project.

groups

body

integer

The number of groups that are allowed for each project.

per_volume_gigabytes

body

integer

The size (GB) of volumes in request that are allowed for each volume.

gigabytes

body

integer

The size (GB) of volumes and snapshots that are allowed for each project.

gigabytes_{volume_type}

body

integer

The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type.

backup_gigabytes

body

integer

The size (GB) of backups that are allowed for each project.

Request Example

{
    "quota_set": {
        "snapshots": 45
    }
}

Response Parameters

Name

In

Type

Description

quota_set

body

object

A quota_set object.

volumes

body

integer

The number of volumes that are allowed for each project.

volumes_{volume_type}

body

integer

The number of volumes that are allowed for each project and the specified volume type.

snapshots

body

integer

The number of snapshots that are allowed for each project.

snapshots_{volume_type}

body

integer

The number of snapshots that are allowed for each project and the specified volume type.

backups

body

integer

The number of backups that are allowed for each project.

groups

body

integer

The number of groups that are allowed for each project.

per_volume_gigabytes

body

integer

The size (GB) of volumes in request that are allowed for each volume.

gigabytes

body

integer

The size (GB) of volumes and snapshots that are allowed for each project.

gigabytes_{volume_type}

body

integer

The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type.

backup_gigabytes

body

integer

The size (GB) of backups that are allowed for each project.

Response Example

{
    "quota_set": {
        "snapshots": 45
    }
}
DELETE
/v2/{admin_project_id}/os-quota-sets/{project_id}

Delete quotas

Deletes quotas for a project so the quotas revert to default values.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

project_id

path

string

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

admin_project_id

path

string

The UUID of the administrative project.

Response Example


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

Get default quotas

Gets default quotas for a project.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

project_id

path

string

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

admin_project_id

path

string

The UUID of the administrative project.

Response Parameters

Name

In

Type

Description

quota_set

body

object

A quota_set object.

id

body

string

The UUID of the project.

volumes

body

integer

The number of volumes that are allowed for each project.

volumes_{volume_type}

body

integer

The number of volumes that are allowed for each project and the specified volume type.

snapshots

body

integer

The number of snapshots that are allowed for each project.

snapshots_{volume_type}

body

integer

The number of snapshots that are allowed for each project and the specified volume type.

backups

body

integer

The number of backups that are allowed for each project.

groups

body

integer

The number of groups that are allowed for each project.

per_volume_gigabytes

body

integer

The size (GB) of volumes in request that are allowed for each volume.

gigabytes

body

integer

The size (GB) of volumes and snapshots that are allowed for each project.

gigabytes_{volume_type}

body

integer

The size (GB) of volumes and snapshots that are allowed for each project and the specified volume type.

backup_gigabytes

body

integer

The size (GB) of backups that are allowed for each project.

Response Example

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

Volume manage extension (os-volume-manage)

Creates volumes by using existing storage instead of allocating new storage.

POST
/v2/{project_id}/os-volume-manage

Manage 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).

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

description (Optional)

body

string

The backup description or null.

availability_zone (Optional)

body

string

The name of the availability zone.

bootable

body

boolean

Enables or disables the bootable attribute. You can boot an instance from a bootable volume.

volume_type (Optional)

path

string

The ID of Volume Type to be accessed by project.

name

body

string

The name of the Volume Transfer.

volume

body

object

A volume object.

host

body

string

The OpenStack Block Storage host where the existing volume resides.

ref

body

string

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

body

object

One or more metadata key and value pairs for the snapshot, if any.

project_id

path

string

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

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

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.

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 (Optional)

path

string

The ID of Volume Type to be accessed by project.

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": {
        "status": "creating",
        "user_id": "eae1472b5fc5496998a3d06550929e7e",
        "attachments": [],
        "links": [
            {
                "href": "http://10.0.2.15:8776/v2/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"
            }
        ],
        "availability_zone": "az2",
        "bootable": "false",
        "encrypted": "false",
        "created_at": "2014-07-18T00:12:54.000000",
        "description": "Volume imported from existingLV",
        "os-vol-tenant-attr:tenant_id": "87c8522052ca4eed98bc672b4c1a3ddb",
        "volume_type": null,
        "name": "New Volume",
        "source_volid": null,
        "snapshot_id": null,
        "metadata": {
            "key2": "value2",
            "key1": "value1"
        },
        "id": "23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
        "size": 0
    }
}

Volume type access (volumes)

Private volume type access to project.

By default, volumes types are public. To create a private volume type, set the is_public boolean field to false at volume type creation time. To control access to a private volume type, user needs to add a project to or remove a project from the volume type. Private volume types without projects are only accessible by users with the administrative role and context.

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

Add private volume type access

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

body

string

The ID of the project. Volume Type access to be added to this project ID.

project_id

path

string

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

volume_type

path

string

The ID of Volume Type to be accessed by project.

Request Example

{
    "addProjectAccess": {
        "project": "f270b245cb11498ca4031deb7e141cfa"
    }
}
POST
/v2/{project_id}/types/{volume_type}/action

Remove private volume type access

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

body

string

The ID of the project. Volume Type access to be added to this project ID.

project_id

path

string

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

volume_type

path

string

The ID of Volume Type to be accessed by project.

Request Example

{
    "removeProjectAccess": {
        "project": "f270b245cb11498ca4031deb7e141cfa"
    }
}
GET
/v2/{project_id}/types/{volume_type}/os-volume-type-access

List private volume type access details

Lists project IDs that have access to private volume type.

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 ID of Volume Type to be accessed by project.

Response Parameters

Name

In

Type

Description

project_id

body

string

The UUID of the project.

Response Example

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

API extensions (extensions)

GET
/v2/{project_id}/extensions

List API extensions

Lists Block Storage API extensions.

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 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 (Optional)

body

string

The backup description or null.

links

body

array

Links for the volume transfer.

namespace

body

string

Link associated to the extension.

alias

body

string

The alias for the extension. For example, “FOXNSOX”, “os- availability-zone”, “os-extended-quotas”, “os- share-unmanage” or “os-used-limits.”

name

body

string

The name of the Volume Transfer.

Response Example

{
    "extensions": [
        {
            "updated": "2013-04-18T00:00:00+00:00",
            "name": "SchedulerHints",
            "links": [],
            "namespace": "https://docs.openstack.org/block-service/ext/scheduler-hints/api/v2",
            "alias": "OS-SCH-HNT",
            "description": "Pass arbitrary key/value pairs to the scheduler."
        },
        {
            "updated": "2011-06-29T00:00:00+00:00",
            "name": "Hosts",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/hosts/api/v1.1",
            "alias": "os-hosts",
            "description": "Admin-only host administration."
        },
        {
            "updated": "2011-11-03T00:00:00+00:00",
            "name": "VolumeTenantAttribute",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/volume_tenant_attribute/api/v1",
            "alias": "os-vol-tenant-attr",
            "description": "Expose the internal project_id as an attribute of a volume."
        },
        {
            "updated": "2011-08-08T00:00:00+00:00",
            "name": "Quotas",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/quotas-sets/api/v1.1",
            "alias": "os-quota-sets",
            "description": "Quota management support."
        },
        {
            "updated": "2011-08-24T00:00:00+00:00",
            "name": "TypesManage",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/types-manage/api/v1",
            "alias": "os-types-manage",
            "description": "Types manage support."
        },
        {
            "updated": "2013-07-10T00:00:00+00:00",
            "name": "VolumeEncryptionMetadata",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/os-volume-encryption-metadata/api/v1",
            "alias": "os-volume-encryption-metadata",
            "description": "Volume encryption metadata retrieval support."
        },
        {
            "updated": "2012-12-12T00:00:00+00:00",
            "name": "Backups",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/backups/api/v1",
            "alias": "backups",
            "description": "Backups support."
        },
        {
            "updated": "2013-07-16T00:00:00+00:00",
            "name": "SnapshotActions",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/snapshot-actions/api/v1.1",
            "alias": "os-snapshot-actions",
            "description": "Enable snapshot manager actions."
        },
        {
            "updated": "2012-05-31T00:00:00+00:00",
            "name": "VolumeActions",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/volume-actions/api/v1.1",
            "alias": "os-volume-actions",
            "description": "Enable volume actions\n    "
        },
        {
            "updated": "2013-10-03T00:00:00+00:00",
            "name": "UsedLimits",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/used-limits/api/v1.1",
            "alias": "os-used-limits",
            "description": "Provide data on limited resources that are being used."
        },
        {
            "updated": "2012-05-31T00:00:00+00:00",
            "name": "VolumeUnmanage",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/volume-unmanage/api/v1.1",
            "alias": "os-volume-unmanage",
            "description": "Enable volume unmanage operation."
        },
        {
            "updated": "2011-11-03T00:00:00+00:00",
            "name": "VolumeHostAttribute",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/volume_host_attribute/api/v1",
            "alias": "os-vol-host-attr",
            "description": "Expose host as an attribute of a volume."
        },
        {
            "updated": "2013-07-01T00:00:00+00:00",
            "name": "VolumeTypeEncryption",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/volume-type-encryption/api/v1",
            "alias": "encryption",
            "description": "Encryption support for volume types."
        },
        {
            "updated": "2013-06-27T00:00:00+00:00",
            "name": "AvailabilityZones",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/os-availability-zone/api/v1",
            "alias": "os-availability-zone",
            "description": "Describe Availability Zones."
        },
        {
            "updated": "2013-08-02T00:00:00+00:00",
            "name": "Qos_specs_manage",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/qos-specs/api/v1",
            "alias": "qos-specs",
            "description": "QoS specs support."
        },
        {
            "updated": "2011-08-24T00:00:00+00:00",
            "name": "TypesExtraSpecs",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/types-extra-specs/api/v1",
            "alias": "os-types-extra-specs",
            "description": "Type extra specs support."
        },
        {
            "updated": "2013-08-08T00:00:00+00:00",
            "name": "VolumeMigStatusAttribute",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/volume_mig_status_attribute/api/v1",
            "alias": "os-vol-mig-status-attr",
            "description": "Expose migration_status as an attribute of a volume."
        },
        {
            "updated": "2012-08-13T00:00:00+00:00",
            "name": "CreateVolumeExtension",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/image-create/api/v1",
            "alias": "os-image-create",
            "description": "Allow creating a volume from an image in the Create Volume API."
        },
        {
            "updated": "2014-01-10T00:00:00-00:00",
            "name": "ExtendedServices",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/extended_services/api/v2",
            "alias": "os-extended-services",
            "description": "Extended services support."
        },
        {
            "updated": "2012-06-19T00:00:00+00:00",
            "name": "ExtendedSnapshotAttributes",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1",
            "alias": "os-extended-snapshot-attributes",
            "description": "Extended SnapshotAttributes support."
        },
        {
            "updated": "2012-12-07T00:00:00+00:00",
            "name": "VolumeImageMetadata",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/volume_image_metadata/api/v1",
            "alias": "os-vol-image-meta",
            "description": "Show image metadata associated with the volume."
        },
        {
            "updated": "2012-03-12T00:00:00+00:00",
            "name": "QuotaClasses",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/quota-classes-sets/api/v1.1",
            "alias": "os-quota-class-sets",
            "description": "Quota classes management support."
        },
        {
            "updated": "2013-05-29T00:00:00+00:00",
            "name": "VolumeTransfer",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/volume-transfer/api/v1.1",
            "alias": "os-volume-transfer",
            "description": "Volume transfer management support."
        },
        {
            "updated": "2014-02-10T00:00:00+00:00",
            "name": "VolumeManage",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/os-volume-manage/api/v1",
            "alias": "os-volume-manage",
            "description": "Allows existing backend storage to be 'managed' by Cinder."
        },
        {
            "updated": "2012-08-25T00:00:00+00:00",
            "name": "AdminActions",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/admin-actions/api/v1.1",
            "alias": "os-admin-actions",
            "description": "Enable admin actions."
        },
        {
            "updated": "2012-10-28T00:00:00-00:00",
            "name": "Services",
            "links": [],
            "namespace": "https://docs.openstack.org/volume/ext/services/api/v2",
            "alias": "os-services",
            "description": "Services support."
        }
    ]
}

Volume 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
/v2/{project_id}/snapshots/detail

List snapshots with details

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

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 projects. Admin only.

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 (Optional)

body

string

The backup description or null.

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 Volume Transfer.

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.

snapshots_links

body

array

List of links related to the extension.

Response Example

{
    "snapshots": [
        {
            "status": "available",
            "metadata": {
                "name": "test"
            },
            "os-extended-snapshot-attributes:progress": "100%",
            "name": "test-volume-snapshot",
            "volume_id": "173f7b48-c4c1-4e70-9acc-086b39073506",
            "os-extended-snapshot-attributes:project_id": "bab7d5c60cd041a0a36f7c4b6e1dd978",
            "created_at": "2015-11-29T02:25:51.000000",
            "size": 1,
            "id": "b1323cda-8e4b-41c1-afc5-2fc791809c8c",
            "description": "volume snapshot",
            "updated_at": "2015-12-11T07:24:57Z"
        }
    ],
    "snapshots_links": [
        {
            "href": "https://10.43.176.164:8776/v3/d55fb90e300b436cb2714a17137be023/snapshots?limit=1&marker=2e0cd28e-d7a2-4cdb-87e6-cd37c417c06d",
            "rel": "next"
        }
    ]
}
POST
/v2/{project_id}/snapshots

Create snapshot

Creates a volume snapshot, which is a point-in-time, complete copy of a volume. You can create a volume from a snapshot.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

snapshot

body

string

A partial representation of a snapshot used in the creation process.

volume_id

body

string

The UUID of the volume.

force (Optional)

body

boolean

Indicates whether to backup, even if the volume is attached. Default is false.

description (Optional)

body

string

The backup description or null.

name

body

string

The name of the Volume Transfer.

project_id

path

string

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

Request Example

{
    "snapshot": {
        "name": "snap-001",
        "description": "Daily backup",
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "force": true
    }
}

Response Parameters

Name

In

Type

Description

status

body

string

The status for the snapshot.

description (Optional)

body

string

The backup description or null.

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 Volume Transfer.

snapshot

body

string

A partial representation of a snapshot used in the creation process.

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

GET
/v2/{project_id}/snapshots

List snapshots

Lists all Block Storage snapshots, with summary information, that the project can access.

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 projects. Admin only.

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

offset (Optional)

query

integer

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

marker (Optional)

query

string

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

Response Parameters

Name

In

Type

Description

status

body

string

The status for the snapshot.

description (Optional)

body

string

The backup description or null.

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 Volume Transfer.

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.

snapshots_links

body

array

List of links related to the extension.

Response Example

{
    "snapshots": [
        {
            "status": "available",
            "metadata": {
                "name": "test"
            },
            "name": "test-volume-snapshot",
            "volume_id": "173f7b48-c4c1-4e70-9acc-086b39073506",
            "created_at": "2015-11-29T02:25:51.000000",
            "size": 1,
            "id": "b1323cda-8e4b-41c1-afc5-2fc791809c8c",
            "description": "volume snapshot",
            "updated_at": "2015-12-11T07:24:57Z"
        }
    ],
    "snapshots_links": [
        {
            "href": "https://10.43.176.164:8776/v3/d55fb90e300b436cb2714a17137be023/snapshots?limit=1&marker=2e0cd28e-d7a2-4cdb-87e6-cd37c417c06d",
            "rel": "next"
        }
    ]
}
GET
/v2/{project_id}/snapshots/{snapshot_id}/metadata

Show snapshot 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 (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.

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": {
        "name": "test"
    }
}
POST
/v2/{project_id}/snapshots/{snapshot_id}/metadata

Create snapshot 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

metadata

body

object

One or more metadata key and value pairs for the snapshot, if any.

project_id

path

string

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

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.

Request Example

{
    "metadata": {
        "key": "v2"
    }
}

Response Example

{
    "metadata": {
        "key": "v2"
    }
}
PUT
/v2/{project_id}/snapshots/{snapshot_id}/metadata

Update snapshot 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

metadata

body

object

One or more metadata key and value pairs for the snapshot, if any.

project_id

path

string

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

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.

Request Example

{
    "metadata": {
        "key": "v2"
    }
}

Response Example

{
    "metadata": {
        "key": "v2"
    }
}
GET
/v2/{project_id}/snapshots/{snapshot_id}

Show snapshot 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 (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.

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 (Optional)

body

string

The backup description or null.

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 Volume Transfer.

snapshot

body

string

A partial representation of a snapshot used in the creation process.

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.

Response Example

{
    "snapshot": {
        "status": "available",
        "os-extended-snapshot-attributes:progress": "100%",
        "description": "Daily backup",
        "created_at": "2013-02-25T04:13:17.000000",
        "metadata": {},
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
        "size": 1,
        "id": "2bb856e1-b3d8-4432-a858-09e4ce939389",
        "name": "snap-001",
        "updated_at": "2013-03-11T07:24:57Z"
    }
}
PUT
/v2/{project_id}/snapshots/{snapshot_id}

Update snapshot

Updates a snapshot.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

snapshot

body

string

A partial representation of a snapshot used in the creation process.

description (Optional)

body

string

The backup description or null.

name

body

string

The name of the Volume Transfer.

project_id

path

string

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

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.

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 (Optional)

body

string

The backup description or null.

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 Volume Transfer.

snapshot

body

string

A partial representation of a snapshot used in the creation process.

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

Response Example

{
    "snapshot": {
        "created_at": "2013-02-20T08:11:34.000000",
        "description": "This is yet, another snapshot",
        "name": "snap-002",
        "id": "4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2",
        "size": 1,
        "status": "available",
        "metadata": {},
        "volume_id": "2402b902-0b7a-458c-9c07-7435a826f794"
    }
}
DELETE
/v2/{project_id}/snapshots/{snapshot_id}

Delete snapshot

Deletes a 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.

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.

Snapshot actions (snapshots, action)

Administrator only. Resets status for a snapshot.

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

Reset 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

status

body

string

The status for the snapshot.

os-reset_status

body

object

The os-reset_status action.

project_id

path

string

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

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.

Request Example

{
    "os-reset_status": {
        "status": "available"
    }
}

Volume types (types)

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

Update volume type

Updates a volume type.

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.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

volume_type

body

object

A volume_type object.

volume_type_id (Optional)

path

string

The UUID for an existing volume type.

project_id

path

string

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

Request Example

{
    "volume_type": {
        "name": "vol-type-001",
        "description": "volume type 0001",
        "is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

Response Parameters

Name

In

Type

Description

is_public (Optional)

body

boolean

Volume type which is accessible to the public.

extra_specs

body

object

A set of key and value pairs that contains the specifications for a volume type.

description (Optional)

body

string

The backup description or null.

volume_type

body

object

A volume_type object.

name

body

string

The name of the Volume Transfer.

Response Example

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "description": "volume type 001",
        "is_public": "true",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
PUT
/v2/{project_id}/types/{volume_type_id}

Update extra specs for a volume type

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

extra_specs

body

object

A set of key and value pairs that contains the specifications for a volume type.

volume_type

body

object

A volume_type object.

volume_type_id (Optional)

path

string

The UUID for an existing volume type.

project_id

path

string

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

Request Example

{
    "volume_type": {
        "name": "vol-type-001",
        "description": "volume type 0001",
        "is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

Response Parameters

Name

In

Type

Description

is_public (Optional)

body

boolean

Volume type which is accessible to the public.

extra_specs

body

object

A set of key and value pairs that contains the specifications for a volume type.

description (Optional)

body

string

The backup description or null.

volume_type

body

object

A volume_type object.

name

body

string

The name of the Volume Transfer.

Response Example

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "description": "volume type 001",
        "is_public": "true",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
GET
/v2/{project_id}/types/{volume_type_id}

Show volume type details for v2

Shows details for a volume type.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

volume_type_id (Optional)

path

string

The UUID for an existing volume type.

project_id

path

string

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

Response Parameters

Name

In

Type

Description

is_public (Optional)

body

boolean

Volume type which is accessible to the public.

extra_specs

body

object

A set of key and value pairs that contains the specifications for a volume type.

description (Optional)

body

string

The backup description or null.

volume_type

body

object

A volume_type object.

name

body

string

The name of the Volume Transfer.

Response Example

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "description": "volume type 001",
        "is_public": "true",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
DELETE
/v2/{project_id}/types/{volume_type_id}

Delete volume type

Deletes a volume type.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

volume_type_id (Optional)

path

string

The UUID for an existing volume type.

project_id

path

string

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

GET
/v2/{project_id}/types

List all volume types for v2

Lists volume types.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

project_id

path

string

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

sort_key (Optional)

query

string

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

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

offset (Optional)

query

integer

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

marker (Optional)

query

string

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

Response Parameters

Name

In

Type

Description

volume_types

body

array

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

extra_specs

body

object

A set of key and value pairs that contains the specifications for a volume type.

name

body

string

The name of the Volume Transfer.

volume_type (Optional)

path

string

The ID of Volume Type to be accessed by project.

Response Example

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

Create volume type for v2

Creates a volume type.

To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder-volume, and they are keyed from a unique queue. They are named cinder-volume.HOST.BACKEND. For example, cinder-volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type.

For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

volume_type

body

object

A volume_type object.

project_id

path

string

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

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

is_public (Optional)

body

boolean

Volume type which is accessible to the public.

extra_specs

body

object

A set of key and value pairs that contains the specifications for a volume type.

description (Optional)

body

string

The backup description or null.

volume_type

body

object

A volume_type object.

name

body

string

The name of the Volume Transfer.

Response Example

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "description": "volume type 001",
        "is_public": "true",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
GET
/v2/{project_id}/types/{volume_type_id}/encryption

Show an encryption type for v2

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

volume_type_id (Optional)

path

string

The UUID for an existing volume type.

project_id

path

string

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

Response Parameters

Name

In

Type

Description

volume_type_id

body

string

The UUID of the 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. For example, 128 or 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
/v2/{project_id}/types/{volume_type_id}/encryption/{encryption_id}

Delete an encryption type for v2

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

volume_type_id (Optional)

path

string

The UUID for an existing volume type.

project_id

path

string

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

encryption_id

path

string

The ID of the encryption type.

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

Create an encryption type for v2

Creates 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

volume_type_id (Optional)

path

string

The UUID for an existing volume type.

project_id

path

string

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

encryption

body

object

The encryption information.

key_size (Optional)

body

integer

Size of encryption key, in bits. For example, 128 or 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.

Request Example

{
    "encryption":{
        "key_size": 256,
        "provider": "luks",
        "control_location":"front-end",
        "cipher": "aes-xts-plain64"
    }
}

Response Parameters

Name

In

Type

Description

volume_type_id

body

string

The UUID of the 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. For example, 128 or 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
/v2/{project_id}/types/{volume_type_id}/encryption/{encryption_id}

Update an encryption type for v2

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

volume_type_id (Optional)

path

string

The UUID for an existing volume type.

project_id

path

string

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

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. For example, 128 or 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.

Request Example

{
    "encryption":{
        "key_size": 64,
        "provider": "luks",
        "control_location":"back-end"
    }
}

Response Parameters

Name

In

Type

Description

encryption

body

object

The encryption information.

key_size (Optional)

body

integer

Size of encryption key, in bits. For example, 128 or 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"
    }
}

API version details

GET
/v2/

Show API v2 details

Shows details for Block Storage API v2.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Response Parameters

Name

In

Type

Description

location

body

string

Full URL to a service or server.

Response Example

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

Volume actions (volumes, action)

Extends the size of, resets statuses for, sets image metadata for, and removes image metadata from a volume. Attaches a volume to a server, detaches a volume from a server, and removes a volume from Block Storage management without actually removing the back-end storage object associated with it.

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

Extend volume size

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

Preconditions

  • Volume status must be available.

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

  • The user quota must have sufficient volume storage.

Troubleshooting

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

os-extend

body

object

The os-extend action.

new_size

body

integer

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

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Reset volume statuses

Administrator only. Resets the status, attach status, 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

status

body

string

The volume status.

migration_status (Optional)

body

string

The volume migration status. Admin only.

os-reset_status

body

object

The os-reset_status action.

attach_status (Optional)

body

string

The volume attach status.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

{
    "os-reset_status": {
        "status": "available",
        "attach_status": "detached",
        "migration_status": "migrating"
    }
}
POST
/v2/{project_id}/volumes/{volume_id}/action

Set image metadata for 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

os-set_image_metadata

body

object

The os-set_image_metadata action.

metadata

body

object

One or more metadata key and value pairs for the snapshot, if any.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

{
    "os-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 key 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
/v2/{project_id}/volumes/{volume_id}/action

Remove image metadata from 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

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.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Show image metadata for 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 key value pairs.

Response Example

{
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    }
}
POST
/v2/{project_id}/volumes/{volume_id}/action

Attach volume to server

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

Preconditions

  • Volume status must be available.

  • You should set instance_uuid or host_name.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

instance_uuid (Optional)

body

string

The UUID of the attaching instance.

mountpoint

body

string

The attaching mount point.

host_name (Optional)

body

string

The name of the attaching host.

os-attach

body

object

The os-attach action.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

{
    "os-attach": {
        "instance_uuid": "95D9EF50-507D-11E5-B970-0800200C9A66",
        "mountpoint": "/dev/vdc"
    }
}
POST
/v2/{project_id}/volumes/{volume_id}/action

Detach volume from a server

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

Preconditions

  • Volume status must be in-use.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

attachment_id (Optional)

body

string

The interface ID.

os-detach

body

object

The os-detach action.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Unmanage 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

os-unmanage

body

object

The os-unmanage action. This action removes the specified volume from Cinder management.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Force detach 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.

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

connector (Optional)

body

object

The connector object.

attachment_id (Optional)

body

string

The interface ID.

os-force_detach

body

object

The os-force_detach action.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Retype 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

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.

os-retype

body

object

The os-retype action.

volume_id

path

string

The UUID of the volume.

project_id

path

string

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

Request Example

{
    "os-retype": {
        "new_type": "dedup-tier-replicaton",
        "migration_policy": "never"
        }
}
POST
/v2/{project_id}/volumes/{volume_id}/action

Migrate volume

Specify the os-migrate_volume action in the request body.

Migrates a volume to the specified 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 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

body

string

The target host for the volume migration. Host format is host@backend.

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.

Request Example

{
    "os-migrate_volume": {
        "host": "node1@lvm"
    }
}
POST
/v2/{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
/v2/{project_id}/volumes/{volume_id}/action

Force delete 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

os-force_delete

body

string

The os-force_delete action.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Update volume bootable status

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

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.

Request Example

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

Volumes (volumes)

A volume is a detachable block storage device similar to a USB hard drive. You can attach a volume to one instance at a time.

The snapshot_id and source_volid parameters specify the ID of the snapshot or volume from which this volume originates. If the volume was not created from a snapshot or source volume, these values are null.

When you create, list, update, or delete volumes, the possible status values are:

Volume statuses

Status

Description

creating

The volume is being created.

available

The volume is ready to attach to an instance.

attaching

The volume is attaching to an instance.

detaching

The volume is detaching from an instance.

in-use

The volume is attached to an instance.

maintenance

The volume is locked and being migrated.

deleting

The volume is being deleted.

awaiting-transfer

The volume is awaiting for transfer.

error

A volume creation error occurred.

error_deleting

A volume deletion error occurred.

backing-up

The volume is being backed up.

restoring-backup

A backup is being restored to the volume.

error_backing-up

A backup error occurred.

error_restoring

A backup restoration error occurred.

error_extending

An error occurred while attempting to extend a volume.

downloading

The volume is downloading an image.

uploading

The volume is being uploaded to an image.

retyping

The volume is changing type to another volume type.

extending

The volume is being extended.

GET
/v2/{project_id}/volumes/detail

List volumes with details

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

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 projects. Admin only.

sort (Optional)

query

string

Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

limit (Optional)

query

integer

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

offset (Optional)

query

integer

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

marker (Optional)

query

string

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

Response Parameters

Name

In

Type

Description

migration_status (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.

links

body

array

Links for the volume transfer.

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.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

replication_status

body

string

The volume replication status.

snapshot_id (Optional)

body

string

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

id

body

string

The UUID of the volume transfer.

size

body

integer

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

user_id

body

string

The UUID of the user.

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

One or more metadata key and value pairs for the snapshot, if any.

status

body

string

The volume status.

volume_image_metadata (Optional)

body

object

List of image metadata entries. Only included for volumes that were created from an image, or from a snapshot of a volume originally created from an image.

description (Optional)

body

string

The backup description or null.

multiattach

body

boolean

If true, this volume can attach to more than one instance.

source_volid (Optional)

body

string

The UUID of the source volume. The API creates a new volume with the same size as the source volume 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 name of the Volume Transfer.

bootable

body

string

Enables or disables the bootable attribute. You can boot an instance from a bootable volume.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volumes

body

array

A list of volume objects.

volume_type (Optional)

path

string

The ID of Volume Type to be accessed by project.

volumes_links (Optional)

body

array

The volume links.

Response Example

{
    "volumes": [
        {
            "migration_status": null,
            "attachments": [
                {
                    "server_id": "f4fda93b-06e0-4743-8117-bc8bcecd651b",
                    "attachment_id": "3b4db356-253d-4fab-bfa0-e3626c0b8405",
                    "host_name": null,
                    "volume_id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                    "device": "/dev/vdb",
                    "id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38"
                }
            ],
            "links": [
                {
                    "href": "http://23.253.248.171:8776/v2/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                    "rel": "self"
                },
                {
                    "href": "http://23.253.248.171:8776/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "os-vol-host-attr:host": "difleming@lvmdriver-1#lvmdriver-1",
            "encrypted": false,
            "replication_status": "disabled",
            "snapshot_id": null,
            "id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
            "size": 2,
            "user_id": "32779452fcd34ae1a53a797ac8a1e064",
            "os-vol-tenant-attr:tenant_id": "bab7d5c60cd041a0a36f7c4b6e1dd978",
            "os-vol-mig-status-attr:migstat": null,
            "metadata": {
                "readonly": false,
                "attached_mode": "rw"
            },
            "status": "in-use",
            "description": null,
            "multiattach": true,
            "source_volid": null,
            "consistencygroup_id": null,
            "os-vol-mig-status-attr:name_id": null,
            "name": "test-volume-attachments",
            "bootable": "false",
            "created_at": "2015-11-29T03:01:44.000000",
            "volume_type": "lvmdriver-1"
        },
        {
            "migration_status": null,
            "attachments": [],
            "links": [
                {
                    "href": "http://23.253.248.171:8776/v2/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/173f7b48-c4c1-4e70-9acc-086b39073506",
                    "rel": "self"
                },
                {
                    "href": "http://23.253.248.171:8776/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/173f7b48-c4c1-4e70-9acc-086b39073506",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "os-vol-host-attr:host": "difleming@lvmdriver-1#lvmdriver-1",
            "encrypted": false,
            "replication_status": "disabled",
            "snapshot_id": null,
            "id": "173f7b48-c4c1-4e70-9acc-086b39073506",
            "size": 1,
            "user_id": "32779452fcd34ae1a53a797ac8a1e064",
            "os-vol-tenant-attr:tenant_id": "bab7d5c60cd041a0a36f7c4b6e1dd978",
            "os-vol-mig-status-attr:migstat": null,
            "metadata": {},
            "status": "available",
            "volume_image_metadata": {
                "kernel_id": "8a55f5f1-78f7-4477-8168-977d8519342c",
                "checksum": "eb9139e4942121f22bbc2afc0400b2a4",
                "min_ram": "0",
                "ramdisk_id": "5f6bdf8a-92db-4988-865b-60bdd808d9ef",
                "disk_format": "ami",
                "image_name": "cirros-0.3.4-x86_64-uec",
                "image_id": "b48c53e1-9a96-4a5a-a630-2e74ec54ddcc",
                "container_format": "ami",
                "min_disk": "0",
                "size": "25165824"
            },
            "description": "",
            "multiattach": false,
            "source_volid": null,
            "consistencygroup_id": null,
            "os-vol-mig-status-attr:name_id": null,
            "name": "test-volume",
            "bootable": "true",
            "created_at": "2015-11-29T02:25:18.000000",
            "volume_type": "lvmdriver-1"
        }
    ],
    "volumes_links": [{
        "href": "https://158.69.65.111/volume/v2/4ad9f06ab8654e40befa59a2e7cac86d/volumes/detail?limit=1&marker=3b451d5d-9358-4a7e-a746-c6fd8b0e1462",
        "rel": "next"
    }]
}
POST
/v2/{project_id}/volumes

Create volume

Creates a volume.

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

Preconditions

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

Asynchronous Postconditions

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

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

Troubleshooting

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

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

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

Response codes

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Request

Name

In

Type

Description

size

body

integer

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

description

body

string

The volume description.

imageRef (Optional)

body

string

The UUID of the image from which you want to create the volume. Required to create a bootable volume.

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.

name (Optional)

body

string

The volume name.

volume

body

object

A volume object.

consistencygroup_id (Optional)

body

string

The UUID of the consistency group.

volume_type (Optional)

body

string

The volume type (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.

snapshot_id (Optional)

body

string

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

OS-SCH-HNT:scheduler_hints (Optional)

body

object

The dictionary of data to send to the scheduler.

metadata (Optional)

body

object

One or more metadata key and value pairs that are associated with the volume.

project_id

path

string

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

Request Example

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

Response Parameters

Name

In

Type

Description

migration_status (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.

links

body

array

Links for the volume transfer.

availability_zone (Optional)

body

string

The name of the availability zone.

encrypted

body

boolean

If true, this volume is encrypted.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

replication_status

body

string

The volume replication status.

snapshot_id (Optional)

body

string

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

id

body

string

The UUID of the volume transfer.

size

body

integer

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

user_id

body

string

The UUID of the user.

metadata

body

object

One or more metadata key and value pairs for the snapshot, if any.

status

body

string

The volume status.

description (Optional)

body

string

The backup description or null.

multiattach

body

boolean

If true, this volume can attach to more than one instance.

source_volid (Optional)

body

string

The UUID of the source volume. The API creates a new volume with the same size as the source volume 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 name of the Volume Transfer.

bootable

body

string

Enables or disables the bootable attribute. You can boot an instance from a bootable volume.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volume_type (Optional)

path

string

The ID of Volume Type to be accessed by project.

Response Example

{
    "volume": {
        "status": "creating",
        "migration_status": null,
        "user_id": "0eea4eabcf184061a3b6db1e0daaf010",
        "attachments": [],
        "links": [
            {
                "href": "http://23.253.248.171:8776/v2/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                "rel": "self"
            },
            {
                "href": "http://23.253.248.171:8776/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "encrypted": false,
        "created_at": "2015-11-29T03:01:44.000000",
        "description": null,
        "updated_at": null,
        "volume_type": "lvmdriver-1",
        "name": "test-volume-attachments",
        "replication_status": "disabled",
        "consistencygroup_id": null,
        "source_volid": null,
        "snapshot_id": null,
        "multiattach": false,
        "metadata": {},
        "id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
        "size": 2
    }
}
GET
/v2/{project_id}/volumes

List volumes

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

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 projects. Admin only.

sort (Optional)

query

string

Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).

limit (Optional)

query

integer

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

offset (Optional)

query

integer

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

marker (Optional)

query

string

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

Response Parameters

Name

In

Type

Description

volumes

body

array

A list of volume objects.

id

body

string

The UUID of the volume transfer.

links

body

array

Links for the volume transfer.

name

body

string

The name of the Volume Transfer.

volumes_links (Optional)

body

array

The volume links.

Response Example

{
    "volumes": [
        {
            "id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
            "links": [
                {
                    "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                    "rel": "bookmark"
                }
            ],
            "name": "vol-004"
        },
        {
            "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
            "links": [
                {
                    "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel": "bookmark"
                }
            ],
            "name": "vol-003"
        }
    ],
    "volumes_links": [{
        "href": "https://158.69.65.111/volume/v2/4ad9f06ab8654e40befa59a2e7cac86d/volumes/detail?limit=1&marker=3b451d5d-9358-4a7e-a746-c6fd8b0e1462",
        "rel": "next"
    }]
}
GET
/v2/{project_id}/volumes/{volume_id}

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

links

body

array

Links for the volume transfer.

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.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

replication_status

body

string

The volume replication status.

snapshot_id (Optional)

body

string

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

id

body

string

The UUID of the volume transfer.

size

body

integer

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

user_id

body

string

The UUID of the user.

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

One or more metadata key and value pairs for the snapshot, if any.

status

body

string

The volume status.

volume_image_metadata (Optional)

body

object

List of image metadata entries. Only included for volumes that were created from an image, or from a snapshot of a volume originally created from an image.

description (Optional)

body

string

The backup description or null.

multiattach

body

boolean

If true, this volume can attach to more than one instance.

source_volid (Optional)

body

string

The UUID of the source volume. The API creates a new volume with the same size as the source volume 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 name of the Volume Transfer.

bootable

body

string

Enables or disables the bootable attribute. You can boot an instance from a bootable volume.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volume_type (Optional)

path

string

The ID of Volume Type to be accessed by project.

Response Example

{
    "volume": {
        "status": "available",
        "attachments": [],
        "links": [
            {
                "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "os-vol-host-attr:host": "ip-10-168-107-25",
        "source_volid": null,
        "snapshot_id": null,
        "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "description": "Super volume.",
        "name": "vol-002",
        "created_at": "2013-02-25T02:40:21.000000",
        "volume_type": "None",
        "os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
        "size": 1,
        "metadata": {
            "contents": "not junk"
        }
    }
}
PUT
/v2/{project_id}/volumes/{volume_id}

Update volume

Updates a volume.

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

volume

body

object

A volume object.

description (Optional)

body

string

The backup description or null.

name

body

string

The name of the Volume Transfer.

metadata (Optional)

body

object

One or more metadata key and value pairs that are associated with the volume.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Response Parameters

Name

In

Type

Description

migration_status (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.

links

body

array

Links for the volume transfer.

availability_zone (Optional)

body

string

The name of the availability zone.

encrypted

body

boolean

If true, this volume is encrypted.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

replication_status

body

string

The volume replication status.

snapshot_id (Optional)

body

string

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

id

body

string

The UUID of the volume transfer.

size

body

integer

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

user_id

body

string

The UUID of the user.

metadata

body

object

One or more metadata key and value pairs that are associated with the volume.

status

body

string

The volume status.

description (Optional)

body

string

The backup description or null.

multiattach

body

boolean

If true, this volume can attach to more than one instance.

source_volid (Optional)

body

string

The UUID of the source volume. The API creates a new volume with the same size as the source volume 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 name of the Volume Transfer.

bootable

body

string

Enables or disables the bootable attribute. You can boot an instance from a bootable volume.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volume_type (Optional)

path

string

The ID of Volume Type to be accessed by project.

Response Example

{
    "volume": {
        "status": "available",
        "migration_status": null,
        "user_id": "0eea4eabcf184061a3b6db1e0daaf010",
        "attachments": [],
        "links": [
            {
                "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "encrypted": false,
        "created_at": "2015-11-29T03:01:44.000000",
        "description": "This is yet, another volume.",
        "updated_at": null,
        "volume_type": "lvmdriver-1",
        "name": "vol-003",
        "replication_status": "disabled",
        "consistencygroup_id": null,
        "source_volid": null,
        "snapshot_id": null,
        "multiattach": false,
        "metadata": {
            "contents": "not junk"
        },
        "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "size": 1
    }
}
DELETE
/v2/{project_id}/volumes/{volume_id}

Delete volume

Deletes a volume.

Preconditions

  • Volume status must be available, in-use, error, or error_restoring.

  • You cannot already have a snapshot of the volume.

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

Asynchronous Postconditions

  • The volume is deleted in volume index.

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

Troubleshooting

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

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

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)

path

boolean

Remove any snapshots along with the volume. Default=False.

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

Create volume metadata

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

Response codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs that are associated with the volume.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Response Parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs that are associated with the volume.

Response Example

{
    "metadata": {
        "name": "metadata0"
    }
}
GET
/v2/{project_id}/volumes/{volume_id}/metadata

Show volume metadata

Shows metadata for a volume.

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
/v2/{project_id}/volumes/{volume_id}/metadata

Update volume 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

metadata

body

object

One or more metadata key and value pairs that are associated with the volume.

project_id

path

string

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

volume_id

path

string

The UUID of the volume.

Request Example

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

Response Parameters

Name

In

Type

Description

metadata

body

object

One or more metadata key and value pairs that are associated with the volume.

Response Example

{
    "metadata": {
        "name": "metadata1"
    }
}
GET
/v2/{project_id}/volumes/{volume_id}/metadata/{key}

Show volume metadata for a specific key

Shows metadata for a volume for a specific key.

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

Delete volume 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
/v2/{project_id}/volumes/{volume_id}/metadata/{key}

Update volume 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"
  }
}