Block Storage API V3 (CURRENT)

Block Storage API V3 (CURRENT)

GET
/

List All Api Versions

Lists information for all Block Storage API versions.

Normal response codes: 300

Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400), unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404), conflict(409)

Request

Response

Example List Api Versions: JSON request

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

API versions

GET
/v3

Show API v3 details

Shows details for Block Storage API v3.

Normal response codes: 200

Error response codes: 203

Request

Response Parameters

Name In Type Description
location body string Full URL to a service or server.

Response Example

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

API extensions (extensions)

GET
/v3/{project_id}/extensions

List Known API extensions

Lists Block Storage API extensions.

Normal response codes: 200

Error response codes: 300

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.

Response Parameters

Name In Type Description
updated body string The date and time stamp when the extension was last updated.
description (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": "http://docs.openstack.org/block-service/ext/scheduler-hints/api/v3",
            "alias": "OS-SCH-HNT",
            "description": "Pass arbitrary key/value pairs to the scheduler."
        },
        {
            "updated": "2011-06-29T00:00:00+00:00",
            "name": "Hosts",
            "links": [],
            "namespace": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://docs.openstack.org/volume/ext/extended_services/api/v3",
            "alias": "os-extended-services",
            "description": "Extended services support."
        },
        {
            "updated": "2012-06-19T00:00:00+00:00",
            "name": "ExtendedSnapshotAttributes",
            "links": [],
            "namespace": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://docs.openstack.org/volume/ext/services/api/v3",
            "alias": "os-services",
            "description": "Services support."
        }
    ]
}

Volume types (types)

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

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

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_type_id path string The UUID for an existing volume type.
volume_type body object A volume_type object.
name body string The name of the volume type.
description (Optional) body string The volume type description.
is_public (Optional) body boolean Whether the volume type is publicly visible.
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.

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
volume_type body object A volume_type object.
is_public (Optional) body boolean Whether the volume type is publicly visible.
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
description (Optional) body string The volume type description.
name body string The name of the volume type.

Response Example

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

Update extra specs for volume type

Updates the extra specifications that are assigned to a volume type.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_type_id path string The UUID for an existing volume type.
volume_type body object A volume_type object.
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.

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
volume_type body object A volume_type object.
is_public (Optional) body boolean Whether the volume type is publicly visible.
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
description (Optional) body string The volume type description.
name body string The name of the volume type.

Response Example

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

Show volume type detail

Shows details for a volume type.

Normal response codes: 200

Request

Name In Type Description
volume_type_id 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 body object A volume_type object.
is_public (Optional) body boolean Whether the volume type is publicly visible.
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
description (Optional) body string The volume type description.
name body string The name of the volume type.

Response Example

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

Delete a volume type

Deletes a volume type.

Normal response codes: 202

Request

Name In Type Description
volume_type_id path string The UUID for an existing volume type.
project_id path string The UUID of the project in a multi-tenancy cloud.
GET
/v3/{project_id}/types

List all volume types

Lists volume types.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort (Optional) query string Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is 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
volume_types body array The list of volume types. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
name body string The name of the volume type.

Response Example

{
    "volume_types": [
        {
            "name": "SSD",
            "qos_specs_id": null,
            "extra_specs": {
                "volume_backend_name": "lvmdriver-1"
            },
            "os-volume-type-access:is_public": true,
            "is_public": true,
            "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
            "description": null
        },
        {
            "name": "SATA",
            "qos_specs_id": null,
            "extra_specs": {
                "volume_backend_name": "lvmdriver-1"
            },
            "os-volume-type-access:is_public": true,
            "is_public": true,
            "id": "8eb69a46-df97-4e41-9586-9a40a7533803",
            "description": null
        }
    ]
}
POST
/v3/{project_id}/types

Create a volume type

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.

Normal response codes: 200

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.
name body string The name of the volume type.
is_public (Optional) body boolean Whether the volume type is publicly visible.
description (Optional) body string The volume type description.

Request Example

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

Response Parameters

Name In Type Description
volume_type body object A volume_type object.
is_public (Optional) body boolean Whether the volume type is publicly visible.
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
description (Optional) body string The volume type description.
name body string The name of the volume type.
id body string The UUID of the volume type.
os-volume-type-access:is_public (Optional) body boolean Make type accessible to the public.

Response Example

{
    "volume_type": {
        "name": "test_type",
        "extra_specs": {},
        "os-volume-type-access:is_public": true,
        "is_public": true,
        "id": "6d0ff92a-0007-4780-9ece-acfe5876966a",
        "description": "test_type_desc"
    }
}
GET
/v3/{project_id}/types/{volume_type_id}/encryption

Show an encryption type

Show an encryption type.

To show an encryption type for an existing volume type.

Normal response codes: 200

Request

Name In Type Description
volume_type_id 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
encryption body object The encryption information.
volume_type_id body string The UUID of the volume type.
encryption_id body string The UUID of the encryption.
key_size (Optional) body integer Size of encryption key, in bits. 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": 128,
    "provider": "nova.volume.encryptors.luks.LuksEncryptor",
    "deleted_at": null,
    "cipher": "aes-xts-plain64"
}
GET
/v3/{project_id}/types/{volume_type_id}/encryption/{encryption_id}

Delete an encryption type

Delete an encryption type.

To delete an encryption type for an existing volume type.

Normal response codes: 202

Request

Name In Type Description
volume_type_id 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
/v3/{project_id}/types/{volume_type_id}/encryption

Create an encryption type

Creates an encryption type.

To create an encryption type for an existing volume type.

Normal response codes: 200

Request

Name In Type Description
volume_type_id 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": 128,
        "provider": "nova.volume.encryptors.luks.LuksEncryptor",
        "control_location":"front-end",
        "cipher": "aes-xts-plain64"
    }
}

Response Parameters

Name In Type Description
encryption body object The encryption information.
volume_type_id body string The UUID of the volume type.
encryption_id body string The UUID of the encryption.
key_size (Optional) body integer Size of encryption key, in bits. 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": 128,
        "provider": "nova.volume.encryptors.luks.LuksEncryptor",
        "cipher": "aes-xts-plain64"
    }
}
POST
/v3/{project_id}/types/{volume_type_id}/encryption/{encryption_id}

Update an encryption type

Update an encryption type.

To update an encryption type for an existing volume type.

Normal response codes: 200

Request

Name In Type Description
volume_type_id 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": "cinder.keymgr.conf_key_mgr.ConfKeyManager",
        "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": "cinder.keymgr.conf_key_mgr.ConfKeyManager",
        "control_location":"back-end"
    }
}

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

Add private volume type access to project

Adds private volume type access to a project.

Normal response codes: 202

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 (Optional) path string The ID of Volume Type to be accessed by project.

Request Example

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

Remove private volume type access from project

Removes private volume type access from a project.

Normal response codes: 202

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 (Optional) path string The ID of Volume Type to be accessed by project.

Request Example

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

List private volume type access detail

Lists project IDs that have access to private volume type.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_type (Optional) path string The ID of Volume Type to be accessed by project.

Response Parameters

Name In Type Description
project_id body string The UUID of the project.

Response Example

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

Volumes (volumes)

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

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

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

Volume statuses

Status Description
creating The volume is being created.
available The volume is ready to attach to an instance.
reserved The volume is reserved for attaching or shelved.
attaching The volume is attaching to an instance.
detaching The volume is detaching from an instance.
in-use The volume is attached to an instance.
maintenance The volume is locked and being migrated.
deleting The volume is being deleted.
awaiting-transfer The volume is awaiting for transfer.
error A volume creation error occurred.
error_deleting A volume deletion error occurred.
backing-up The volume is being backed up.
restoring-backup A backup is being restored to the volume.
error_backing-up A backup error occurred.
error_restoring A backup restoration error occurred.
error_extending An error occurred while attempting to extend a volume.
downloading The volume is downloading an image.
uploading The volume is being uploaded to an image.
retyping The volume is changing type to another volume type.
extending The volume is being extended.
GET
/v3/{project_id}/volumes/detail

List accessible volumes with details

Lists all Block Storage volumes, with details, that the project can access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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 body string The volume migration status.
attachments body array Instance attachment information. If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID. Otherwise, this list is empty.
links body array The volume links.
availability_zone (Optional) body string The name of the availability zone.
os-vol-host-attr:host body string Current back-end of the volume.
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.

os-volume-replication:extended_status (Optional) body string The volume replication status managed by the driver of backend storage.
replication_status body string The volume replication status.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
id body string The UUID of the volume.
size body integer The size of the volume, in gibibytes (GiB).
user_id body string The UUID of the user.
os-vol-tenant-attr:tenant_id body string The tenant ID which the volume belongs to.
os-vol-mig-status-attr:migstat body string The status of this volume migration (None means that a migration is not currently in progress).
metadata body object One or more metadata key and value pairs for the snapshot, if any.
status body string The volume status.
description (Optional) body string The backup description or null.
multiattach (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
consistencygroup_id body string The UUID of the consistency group.
os-vol-mig-status-attr:name_id body string The volume ID that this volume name on the back- end is based on.
name body string The volume name.
bootable body string Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

os-volume-replication:driver_data (Optional) body string The name of the volume replication driver.
volumes body array A list of volume objects.
volume_type (Optional) path string The ID of Volume Type to be accessed by project.

Response Example

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

Create a volume

Creates a volume.

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

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.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume body object A volume object.
size body integer The size of the volume, in gibibytes (GiB).
availability_zone (Optional) body string The name of the availability zone.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
description (Optional) body string The backup description or null.
multiattach (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
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.
name body string The volume name.
imageRef (Optional) body string The UUID of the image from which you want to create the volume. Required to create a bootable volume.
volume_type (Optional) path string The ID of Volume Type to be accessed by project.
metadata body object One or more metadata key and value pairs for the snapshot, if any.
consistencygroup_id body string The UUID of the consistency group.
OS-SCH-HNT:scheduler_hints (Optional) body object The dictionary of data to send to the scheduler.

Request Example

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

Response Parameters

Name In Type Description
migration_status body string The volume migration status.
attachments body array Instance attachment information. If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID. Otherwise, this list is empty.
links body array The volume links.
availability_zone (Optional) body string The name of the availability zone.
encrypted body boolean If true, this volume is encrypted.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

replication_status body string The volume replication status.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
id body string The UUID of the volume.
size body integer The size of the volume, in gibibytes (GiB).
user_id body string The UUID of the user.
metadata body object 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 (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
volume body object A volume object.
consistencygroup_id body string The UUID of the consistency group.
name body string The volume name.
bootable body string Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volume_type (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/v3/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                "rel": "self"
            },
            {
                "href": "http://23.253.248.171:8776/bab7d5c60cd041a0a36f7c4b6e1dd978/volumes/6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "encrypted": false,
        "created_at": "2015-11-29T03:01:44.000000",
        "description": null,
        "updated_at": null,
        "volume_type": "lvmdriver-1",
        "name": "test-volume-attachments",
        "replication_status": "disabled",
        "consistencygroup_id": null,
        "source_volid": null,
        "snapshot_id": null,
        "multiattach": false,
        "metadata": {},
        "id": "6edbc2f4-1507-44f8-ac0d-eed1d2608d38",
        "size": 2
    }
}
GET
/v3/{project_id}/volumes

List accessible volumes

Lists summary information for all Block Storage volumes that the project can access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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.
links body array The volume links.
name body string The volume name.

Response Example

{
    "volumes": [
        {
            "id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
            "links": [
                {
                    "href": "http://localhost:8776/v3/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                    "rel": "bookmark"
                }
            ],
            "name": "vol-004"
        },
        {
            "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
            "links": [
                {
                    "href": "http://localhost:8776/v3/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel": "bookmark"
                }
            ],
            "name": "vol-003"
        }
    ]
}
GET
/v3/{project_id}/volumes/{volume_id}

Show a volume’s details

Shows details for a volume.

Preconditions

  • The volume must exist.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.

Response Parameters

Name In Type Description
migration_status body string The volume migration status.
attachments body array Instance attachment information. If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID. Otherwise, this list is empty.
links body array The volume links.
availability_zone (Optional) body string The name of the availability zone.
os-vol-host-attr:host body string Current back-end of the volume.
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.

os-volume-replication:extended_status (Optional) body string The volume replication status managed by the driver of backend storage.
replication_status body string The volume replication status.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
id body string The UUID of the volume.
size body integer The size of the volume, in gibibytes (GiB).
user_id body string The UUID of the user.
os-vol-tenant-attr:tenant_id body string The tenant ID which the volume belongs to.
os-vol-mig-status-attr:migstat body string The status of this volume migration (None means that a migration is not currently in progress).
metadata body object One or more metadata key and value pairs for the snapshot, if any.
status body string The volume status.
description (Optional) body string The backup description or null.
multiattach (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
volume body object A volume object.
consistencygroup_id body string The UUID of the consistency group.
os-vol-mig-status-attr:name_id body string The volume ID that this volume name on the back- end is based on.
name body string The volume name.
bootable body string Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

os-volume-replication:driver_data (Optional) body string The name of the volume replication driver.
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/v3/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "os-vol-host-attr:host": "ip-10-168-107-25",
        "source_volid": null,
        "snapshot_id": null,
        "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "description": "Super volume.",
        "name": "vol-002",
        "created_at": "2013-02-25T02:40:21.000000",
        "volume_type": "None",
        "os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
        "size": 1,
        "os-volume-replication:driver_data": null,
        "os-volume-replication:extended_status": null,
        "metadata": {
            "contents": "not junk"
        }
    }
}
PUT
/v3/{project_id}/volumes/{volume_id}

Update a volume

Updates a volume.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
volume body object A volume object.
description (Optional) body string The backup description or null.
name (Optional) body string The volume name.
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Request Example

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

Response Parameters

Name In Type Description
migration_status body string The volume migration status.
attachments body array Instance attachment information. If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID. Otherwise, this list is empty.
links body array The volume links.
availability_zone (Optional) body string The name of the availability zone.
encrypted body boolean If true, this volume is encrypted.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

replication_status body string The volume replication status.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
id body string The UUID of the volume.
size body integer The size of the volume, in gibibytes (GiB).
user_id body string The UUID of the user.
metadata body object 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 (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
volume body object A volume object.
consistencygroup_id body string The UUID of the consistency group.
name body string The volume name.
bootable body string Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volume_type (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/v3/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "encrypted": false,
        "created_at": "2015-11-29T03:01:44.000000",
        "description": "This is yet, another volume.",
        "updated_at": null,
        "volume_type": "lvmdriver-1",
        "name": "vol-003",
        "replication_status": "disabled",
        "consistencygroup_id": null,
        "source_volid": null,
        "snapshot_id": null,
        "multiattach": false,
        "metadata": {
            "contents": "not junk"
        },
        "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "size": 1
    }
}
DELETE
/v3/{project_id}/volumes/{volume_id}

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

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
cascade (Optional) path boolean Remove any snapshots along with the volume. Default=False.
force (Optional) body boolean

Indicates whether to force deletes a volume even if the volume is in deleting or error_deleting. Default is false.

New in version 3.23

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

Create metadata for volume

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

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
metadata body object One or more metadata key and value pairs that are associated with the volume.

Request Example

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

Response Parameters

Name In Type Description
metadata body object One or more metadata key and value pairs that are associated with the volume.

Response Example

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

Show a volume’s metadata

Shows metadata for a volume.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.

Response Parameters

Name In Type Description
metadata body object One or more metadata key and value pairs that are associated with the volume.

Response Example

{
    "metadata": {}
}
PUT
/v3/{project_id}/volumes/{volume_id}/metadata

Update a volume’s metadata

Replaces all the volume’s metadata with the key-value pairs in the request.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
metadata body object One or more metadata key and value pairs that are associated with the volume.

Request Example

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

Response Parameters

Name In Type Description
metadata body object One or more metadata key and value pairs that are associated with the volume.

Response Example

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

Show a volume’s metadata for a specific key

Shows metadata for a volume for a specific key.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
key path string The metadata key name for the metadata that you want to see.

Response Parameters

Name In Type Description
meta body object The metadata key and value pair for the volume.

Response Example

{
  "meta": {
    "name": "test"
  }
}
DELETE
/v3/{project_id}/volumes/{volume_id}/metadata/{key}

Delete a volume’s metadata

Deletes metadata for a volume.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
key path string The metadata key name for the metadata that you want to remove.
PUT
/v3/{project_id}/volumes/{volume_id}/metadata/{key}

Update a volume’s metadata for a specific key

Update metadata for a volume for a specific key.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
key path string The metadata key name for the metadata that you want to update.
meta body object The metadata key and value pair for the volume.

Request Example

{
  "meta": {
    "name": "new_name"
  }
}

Response Parameters

Name In Type Description
meta body object The metadata key and value pair for the volume.

Response Example

{
  "meta": {
    "name": "new_name"
  }
}
GET
/v3/{project_id}/volumes/summary

Get volumes summary

Display volumes summary with total number of volumes and total size in GB

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
all_tenants (Optional) path string Shows details for all projects.

Response Parameters

Name In Type Description
volume-summary body object Dictionary of volume-summary objects.
total_size body integer Total size of volumes in GB.
total_count body integer Total number of volumes.
metadata body object

The dictionary of lists contains all the volumes’ metadata, classified by metadata key.

New in version 3.36

Response Example

{
  "volume-summary": {
    "total_size": 4,
    "total_count": 4,
    "metadata": {
            "key1": ["value1", "value2"],
            "key2": ["value2"]
        }
  }
}

Volume actions (volumes, action)

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

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

Extend a volume size

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

Preconditions

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

Postconditions

  • If the request is processed successfully, the volume status will change to extending while the volume size is being extended.
  • Upon successful completion of the extend operation, the volume status will go back to its original value.
  • Starting with microversion 3.42, when extending the size of an attached volume, the Block Storage service will notify the Compute service that an attached volume has been extended. The Compute service will asynchronously process the volume size change for the related server instance. This can be monitored using the GET /servers/{server_id}/os-instance-actions API in the Compute service.

Troubleshooting

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

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-extend body object The os-extend action.
new_size body integer

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

Note

Some volume backends require the storage to be in some multiple value rather than incremental. For example, the EMC ScaleIO backend requires storage in multiples of 8GB. There is a known limitation such that a request to extend the size of a volume for these backends will be rounded up to the nearest multiple but the actual physical size of the storage will not be reflected back in the API for the volume size. For example, a request to extend the size of an 8GB ScaleIO-backed volume to 9GB will actually result in 16GB of physical storage but only 9GB will be reflected in the API and counted for quota usage.

Request Example

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

Reset a volume’s statuses

Administrator only. Resets the status, attach status, revert to snapshot, and migration status for a volume. Specify the os-reset_status action in the request body.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-reset_status body object The os-reset_status action.
status body string The volume status.
migration_status (Optional) body string The volume migration status.
attach_status (Optional) body string The volume attach status.

Request Example

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

Revert volume to snapshot

Revert a volume to its latest snapshot, this API only support reverting a detached volume.

Normal response codes: 202

Error response codes: 400, 404

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id body string The UUID of the volume.
revert body object The revert action.
snapshot_id body string The UUID of the snapshot. The API reverts the volume with this snapshot.

Request Example

{
    "revert": {
        "snapshot_id": "5aa119a8-d25b-45a7-8d1b-88e127885635"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Set image metadata for a volume

Sets the image metadata for a volume. Specify the os-set_image_metadata action in the request body.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-set_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.

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

Remove image metadata from a volume

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

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-unset_image_metadata body object The os-unset_image_metadata action. This action removes the key-value pairs from the image metadata.
key body string The metadata key name for the metadata that you want to remove.

Request Example

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

Show image metadata for a volume

Shows image metadata for a volume.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-vol-image-meta (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
/v3/{project_id}/volumes/{volume_id}/action

Attach volume to a server

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

Preconditions

  • Volume status must be available.
  • You should set instance_uuid or host_name.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-attach body object The os-attach action.
instance_uuid (Optional) body string The UUID of the attaching instance.
mountpoint body string The attaching mount point.
host_name (Optional) body string The name of the attaching host.

Request Example

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

Detach volume from server

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

Preconditions

  • Volume status must be in-use.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-detach body object The os-detach action.
attachment_id (Optional) body string The ID of the attachment.

Request Example

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

Unmanage a volume

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

Preconditions

  • Volume status must be available.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-unmanage body object The os-unmanage action. This action removes the specified volume from Cinder management.

Request Example

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

Force detach a volume

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

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

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-force_detach body object The os-force_detach action.
attachment_id (Optional) body string The ID of the attachment.
connector (Optional) body object The connector object.

Request Example

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

Retype a volume

Change type of existing volume. Specify the os-retype action in the request body.

Change the volume type of existing volume, Cinder may migrate the volume to proper volume host according to the new volume type.

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

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-retype body object The os-retype action.
new_type body string The new volume type that volume is changed with.
migration_policy (Optional) body string

Specify if the volume should be migrated when it is re-typed. Possible values are on-demand or never. If not specified, the default is never.

Note

If the volume is attached to a server instance and will be migrated, then by default policy only users with the administrative role should attempt the retype operation.

Request Example

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

Force delete a volume

Attempts force-delete of volume, regardless of state. Specify the os-force_delete action in the request body.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-force_delete body string The os-force_delete action.

Request Example

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

Update a volume’s bootable status

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

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-set_bootable body object The 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"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

Upload volume to image

Uploads the specified volume to image service.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume_id path string The UUID of the volume.
os-volume_upload_image body object The os-volume_upload_image action. This action uploads the specified volume to image service.
image_name body string The name for the new image.
force (Optional) body boolean Enables or disables upload of a volume that is attached to an instance. Default=False.
disk_format (Optional) body string Disk format for the new image. Default is raw.
container_format (Optional) body string Container format for the new image. Default is bare.
visibility (Optional) body string The visibility property of the new image. Default is private.
protected (Optional) body boolean Whether the new image is protected. Default=False.

Request Example

{
  "os-volume_upload_image":{
    "image_name": "test",
    "force": false,
    "disk_format": "raw",
    "container_format": "bare",
    "visibility": "private",
    "protected": false
  }
}

Response Parameters

Name In Type Description
os-volume_upload_image body object The os-volume_upload_image action. This action uploads the specified volume to image service.
status body string The volume status.
image_name body string The name for the new image.
disk_format (Optional) body string Disk format for the new image. Default is raw.
container_format (Optional) body string Container format for the new image. Default is bare.
visibility (Optional) body string The visibility property of the new image. Default is private.
protected (Optional) body boolean Whether the new image is protected. Default=False.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

image_id body string The uuid for the new image.
display_description body string The volume description.
id body string The UUID of the volume.
size body integer The size of the volume, in gibibytes (GiB).
volume_type body string The associated volume type for the volume.

Response Example

{
  "os-volume_upload_image": {
    "status": "uploading",
    "container_format": "bare",
    "image_name": "test",
    "visibility": "private",
    "updated_at": "2017-06-05T08:44:28.000000",
    "image_id": "de75b74e-7f0d-4b59-a263-bd87bfc313bd",
    "display_description": null,
    "id": "3a81fdac-e8ae-4e61-b6a2-2e14ff316f19",
    "size": 1,
    "disk_format": "raw",
    "volume_type": null,
    "protected": false
  }
}

Volume manage extension (manageable_volumes)

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

POST
/v3/{project_id}/manageable_volumes

Manage an existing volume

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

The caller must specify a reference to an existing storage volume in the ref parameter in the request. Although each storage driver might interpret this reference differently, the driver should accept a reference structure that contains either a source-id or source-name element, if possible.

The API chooses the size of the volume by rounding up the size of the existing storage volume to the next gibibyte (GiB).

Prior to microversion 3.16 host field was required, with the possibility of defining the cluster it is no longer required, but we must have either a host or a cluster field but we cannot have them both with values.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume body object A volume object.
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 volume name.
host (Optional) body string The OpenStack Block Storage host where the existing resource resides. Optional only if cluster field is provided.
cluster (Optional) body string The OpenStack Block Storage cluster where the resource resides. Optional only if host field is provided.
ref body object A reference to the existing volume. The internal structure of this reference depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver.
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Request Example

{
    "volume": {
        "host": "geraint-VirtualBox",
        "ref": {
            "source-name": "existingLV",
            "source-id": "1234"
        },
        "name": "New Volume",
        "availability_zone": "az2",
        "description": "Volume imported from existingLV",
        "volume_type": null,
        "bootable": true,
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}
{
    "volume": {
        "host": null,
        "cluster": "cluster@backend",
        "ref": {
            "source-name": "existingLV",
            "source-id": "1234"
        },
        "name": "New Volume",
        "availability_zone": "az2",
        "description": "Volume imported from existingLV",
        "volume_type": null,
        "bootable": true,
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}
GET
/v3/{project_id}/manageable_volumes

List summary of volumes available to manage

Search a volume backend and list summary of volumes which are available to manage.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort (Optional) query string Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).
offset (Optional) query integer Used in conjunction with limit to return a slice of items. offset is where to start in the list.
limit (Optional) query integer Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional) query string The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
host path string The name of the host that hosts the storage back end.

Response

Name In Type Description
manageable-volumes body list A list of manageable volumes.
safe_to_manage body boolean If the resource can be managed or not.
reference body object Some information for the resource.
source-name body string The resource’s name.
size body integer The size of the volume, in gibibytes (GiB).

Response Example

{
  "manageable-volumes": [
    {
      "safe_to_manage": false,
      "reference": {
        "source-name": "volume-3a81fdac-e8ae-4e61-b6a2-2e14ff316f19"
      },
      "size": 1
    },
    {
      "safe_to_manage": true,
      "reference": {
        "source-name": "lvol0"
      },
      "size": 1
    }
  ]
}
GET
/v3/{project_id}/manageable_volumes/detail

List detail of volumes available to manage

Search a volume backend and list detail of volumes which are available to manage.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort (Optional) query string Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).
offset (Optional) query integer Used in conjunction with limit to return a slice of items. offset is where to start in the list.
limit (Optional) query integer Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional) query string The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
host (Optional) query string Filter the service list result by host name of the service.

Response

Name In Type Description
manageable-volumes body list A list of manageable volumes.
cinder_id (Optional) body string The UUID of the snapshot in Cinder.
safe_to_manage body boolean If the resource can be managed or not.
reason_not_safe (Optional) body string The reason why the resource can’t be managed.
reference body object Some information for the resource.
source-name body string The resource’s name.
size body integer The size of the volume, in gibibytes (GiB).
extra_info (Optional) body string More information about the resource.

Response Example

{
  "manageable-volumes": [
    {
      "cinder_id": "9ba5bb53-4a18-4b38-be06-992999da338d",
      "reason_not_safe": "already managed",
      "reference": {
        "source-name": "volume-9ba5bb53-4a18-4b38-be06-992999da338d"
      },
      "safe_to_manage": false,
      "size": 1,
      "extra_info": null
    },
    {
      "cinder_id": null,
      "reason_not_safe": null,
      "reference": {
        "source-name": "lvol0"
      },
      "safe_to_manage": true,
      "size": 1,
      "extra_info": null
    }
  ]
}

Volume snapshots (snapshots)

A snapshot is a point-in-time copy of the data that a volume contains.

When you create, list, or delete snapshots, these status values are possible:

Snapshot statuses

Status Description
creating The snapshot is being created.
available The snapshot is ready to use.
backing-up The snapshot is being backed up.
deleting The snapshot is being deleted.
error A snapshot creation error occurred.
deleted The snapshot has been deleted.
unmanaging The snapshot is being unmanaged.
restoring The snapshot is being restored to a volume.
error_deleting A snapshot deletion error occurred.
GET
/v3/{project_id}/snapshots/detail

List snapshots and details

Lists all Block Storage snapshots, with details, that the project can access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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
status body string The status for the snapshot.
os-extended-snapshot-attributes:progress body integer 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.
user_id body string

The UUID of the user.

New in version 3.41

volume_id body string The UUID of the volume.
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 UUID of the volume transfer.
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Response Example

{
    "snapshots": [
        {
            "status": "available",
            "metadata": {
                "name": "test"
            },
            "os-extended-snapshot-attributes:progress": "100%",
            "name": "test-volume-snapshot",
            "user_id": "40c2102f4a554b848d96b14f3eec39ed",
            "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"
        }
    ]
}
POST
/v3/{project_id}/snapshots

Create a snapshot

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

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot body object A snapshot object.
volume_id body string The UUID of the volume.
name body string The name of the snapshot.
description (Optional) body string The backup description or null.
force (Optional) body boolean Indicates whether to backup, even if the volume is attached. Default is false.
metadata (Optional) body object One or more metadata key and value pairs for the snapshot.

Request Example

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

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 snapshot.
snapshot body object A snapshot object.
user_id body string

The UUID of the user.

New in version 3.41

volume_id body string The UUID of the volume.
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.

Response Example

{
    "snapshot": {
        "status": "creating",
        "description": "Daily backup",
        "created_at": "2013-02-25T03:56:53.081642",
        "metadata": {},
        "updated_at": "2013-02-25T03:58:53.081642",
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "size": 1,
        "user_id": "40c2102f4a554b848d96b14f3eec39ed",
        "id": "ffa9bc5e-1172-4021-acaf-cdcd78a9584d",
        "name": "snap-001"
    }
}
GET
/v3/{project_id}/snapshots

List accessible snapshots

Lists all Block Storage snapshots, with summary information, that the project can access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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
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.
user_id body string

The UUID of the user.

New in version 3.41

volume_id body string The UUID of the volume.
metadata body object One or more metadata key and value pairs for the snapshot, if any.
id body string The UUID of the volume transfer.
size body integer The size of the volume, in gibibytes (GiB).

Response Example

{
    "snapshots": [
        {
            "status": "available",
            "metadata": {
                "name": "test"
            },
            "name": "test-volume-snapshot",
            "user_id": "40c2102f4a554b848d96b14f3eec39ed",
            "volume_id": "173f7b48-c4c1-4e70-9acc-086b39073506",
            "created_at": "2015-11-29T02:25:51.000000",
            "size": 1,
            "updated_at": "2015-11-20T05:36:40.000000",
            "os-extended-snapshot-attributes:progress": "100%",
            "os-extended-snapshot-attributes:project_id": "0892d23df5c5471da88299517a412b90",
            "id": "b1323cda-8e4b-41c1-afc5-2fc791809c8c",
            "description": "volume snapshot"
        }
    ]
}
GET
/v3/{project_id}/snapshots/{snapshot_id}/metadata

Show a snapshot’s metadata

Shows metadata for a snapshot.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.

Response Parameters

Name In Type Description
status body string The status for the snapshot.
os-extended-snapshot-attributes:progress body integer 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 object A snapshot object.
volume_id body string The UUID of the volume.
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 UUID of the volume transfer.
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Response Example

{
    "metadata": {
        "name": "test"
    }
}
POST
/v3/{project_id}/snapshots/{snapshot_id}/metadata

Create a snapshot’s metadata

Updates metadata for a snapshot.

Creates or replaces metadata items that match keys. Does not modify items that are not in the request.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Request Example

{
    "metadata": {
        "key": "v3"
    }
}

Response Parameters

Name In Type Description
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Response Example

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

Update a snapshot’s metadata

Replaces all the snapshot’s metadata with the key-value pairs in the request.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Request Example

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

Response Parameters

Name In Type Description
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Response Example

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

Show a snapshot’s details

Shows details for a snapshot.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.

Response Parameters

Name In Type Description
status body string The status for the snapshot.
os-extended-snapshot-attributes:progress body integer 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 object A snapshot object.
user_id body string

The UUID of the user.

New in version 3.41

volume_id body string The UUID of the volume.
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 UUID of the volume transfer.
metadata body object One or more metadata key and value pairs for the snapshot, if any.

Response Example

{
    "snapshot": {
        "status": "available",
        "os-extended-snapshot-attributes:progress": "100%",
        "description": "Daily backup",
        "created_at": "2013-02-25T04:13:17.000000",
        "metadata": {},
        "user_id": "40c2102f4a554b848d96b14f3eec39ed",
        "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"
    }
}
PUT
/v3/{project_id}/snapshots/{snapshot_id}

Update a snapshot

Updates a snapshot.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
snapshot body object A snapshot object.
description (Optional) body string The backup description or null.
name body string The name of the Volume Transfer.

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 object A snapshot object.
id body string The UUID of the volume transfer.
size body integer The size of the volume, in gibibytes (GiB).
volume_id body string The UUID of the volume.
user_id body string

The UUID of the user.

New in version 3.41

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

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",
        "user_id": "40c2102f4a554b848d96b14f3eec39ed",
        "volume_id": "2402b902-0b7a-458c-9c07-7435a826f794"
    }
}
DELETE
/v3/{project_id}/snapshots/{snapshot_id}

Delete a snapshot

Deletes a snapshot.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
GET
/v3/{project_id}/snapshot/{snapshot_id}/metadata/{key}

Show a snapshot’s metadata for a specific key

Shows metadata for a snapshot for a specific key.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
key path string The metadata key name for the metadata that you want to see.

Response Parameters

Name In Type Description
meta body object The metadata key and value pair for the snapshot.

Response Example

{
  "meta": {
    "name": "test"
  }
}
DELETE
/v3/{project_id}/snapshots/{snapshot_id}/metadata/{key}

Delete a snapshot’s metadata

Deletes metadata for a snapshot.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
key path string The metadata key name for the metadata that you want to remove.
PUT
/v3/{project_id}/snapshots/{snapshot_id}/metadata/{key}

Update a snapshot’s metadata for a specific key

Update metadata for a snapshot for a specific key.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
key path string The metadata key name for the metadata that you want to update.
meta body object The metadata key and value pair for the snapshot.

Request Example

{
  "meta": {
    "name": "new_name"
  }
}

Response Parameters

Name In Type Description
meta body object The metadata key and value pair for the snapshot.

Response Example

{
  "meta": {
    "name": "new_name"
  }
}

Snapshot actions (snapshots, action)

Administrator only. Resets status for a snapshot.

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

Reset a snapshot’s status

Resets the status. Specify the os-reset_status action in the request body.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot_id path string The UUID of the snapshot.
os-reset_status body object The os-reset_status action.
status body string The status for the snapshot.

Request Example

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

Snapshot manage extension (manageable_snapshots)

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

POST
/v3/{project_id}/manageable_snapshots

Manage an existing snapshot

Creates a snapshot by using existing storage rather than allocating new storage.

The caller must specify a reference to an existing storage volume in the ref parameter in the request. Although each storage driver might interpret this reference differently, the driver should accept a reference structure that contains either a source-id or source-name element, if possible.

The API chooses the size of the snapshot by rounding up the size of the existing snapshot to the next gibibyte (GiB).

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
snapshot body object A snapshot object.
description (Optional) body string The backup description or null.
metadata (Optional) body object One or more metadata key and value pairs for the snapshot.
name (Optional) body string The name of the snapshot. Default is None.
ref body object A reference to the existing volume. The internal structure of this reference depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver.
volume_id body string The UUID of the volume.

Request Example

{
  "snapshot": {
    "description": null,
    "metadata": null,
    "ref": {
      "source-name": "lvol0"
    },
    "name": null,
    "volume_id": "7c064b34-1e4b-40bd-93ca-4ac5a973661b"
  }
}
GET
/v3/{project_id}/manageable_snapshots

List summary of snapshots available to manage

Search a volume backend and list summary of snapshots which are available to manage.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort (Optional) query string Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).
offset (Optional) query integer Used in conjunction with limit to return a slice of items. offset is where to start in the list.
limit (Optional) query integer Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional) query string The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
host (Optional) query string Filter the service list result by host name of the service.

Response

Name In Type Description
manageable-snapshots body list A list of manageable snapshots.
source_reference body object The snapshot’s origin volume information.
safe_to_manage body boolean If the resource can be managed or not.
reference body object Some information for the resource.
source-name body string The resource’s name.
size body integer The size of the volume, in gibibytes (GiB).

Response Example

{
  "manageable-snapshots": [
    {
      "source_reference": {
        "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
      },
      "safe_to_manage": true,
      "reference": {
        "source-name": "lvol0"
      },
      "size": 1
    },
    {
      "source_reference": {
        "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
      },
      "safe_to_manage": false,
      "reference": {
        "source-name": "_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
      },
      "size": 1
    }
  ]
}
GET
/v3/{project_id}/manageable_snapshots/detail

List detail of snapshots available to manage

Search a volume backend and list detail of snapshots which are available to manage.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort (Optional) query string Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is asc (ascending) or desc (descending).
offset (Optional) query integer Used in conjunction with limit to return a slice of items. offset is where to start in the list.
limit (Optional) query integer Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional) query string The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
host (Optional) query string Filter the service list result by host name of the service.

Response

Name In Type Description
manageable-snapshots body list A list of manageable snapshots.
cinder_id (Optional) body string The UUID of the snapshot in Cinder.
source_reference body object The snapshot’s origin volume information.
safe_to_manage body boolean If the resource can be managed or not.
reason_not_safe (Optional) body string The reason why the resource can’t be managed.
reference body object Some information for the resource.
source-name body string The resource’s name.
size body integer The size of the volume, in gibibytes (GiB).
extra_info (Optional) body string More information about the resource.

Response Example

{
  "manageable-snapshots": [
    {
      "cinder_id": null,
      "reason_not_safe": null,
      "reference": {
        "source-name": "lvol0"
      },
      "source_reference": {
        "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"},
      "safe_to_manage": true,
      "size": 1,
      "extra_info": null
    },
    {
      "cinder_id": "d0c84570-a01f-4579-9789-5e9f266587cd",
      "reason_not_safe": "already managed",
      "reference": {
        "source-name":"_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
      },
      "source_reference": {
        "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
      },
      "safe_to_manage": false,
      "size": 1,
      "extra_info": null
    }
  ]
}

Volume transfer

Transfers a volume from one user to another user.

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

Accept a volume transfer

Accepts a volume transfer.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
transfer_id path string The unique identifier for a volume transfer.
auth_key body string The authentication key for the volume transfer.

Request Example

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

Response Parameters

Name In Type Description
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.
POST
/v3/{project_id}/os-volume-transfer

Create a volume transfer

Creates a volume transfer.

Normal response codes: 202

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.

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

List volume transfers for a project

Lists volume transfers.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.

Response Parameters

Name In Type Description
volume_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",
            "created_at": "2017-06-20T05:48:49.000000",
            "links": [
                {
                    "href": "http://localhost/v3/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",
            "created_at": "2017-06-20T05:48:49.000000",
            "links": [
                {
                    "href": "http://localhost/v3/firstproject/volumes/2",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/2",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}
GET
/v3/{project_id}/os-volume-transfer/{transfer_id}

Show volume transfer detail

Shows details for a volume transfer.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
transfer_id path string The unique identifier for a volume transfer.

Response Parameters

Name In Type Description
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volume_id body string The UUID of the volume.
id body string The UUID of the volume transfer.
links body array Links for the volume transfer.
name 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/v3/firstproject/volumes/1",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/1",
                "rel": "bookmark"
            }
        ]
    }
}
DELETE
/v3/{project_id}/os-volume-transfer/{transfer_id}

Delete a volume transfer

Deletes a volume transfer.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
transfer_id path string The unique identifier for a volume transfer.
GET
/v3/{project_id}/os-volume-transfer/detail

List volume transfers and details

Lists volume transfers, with details.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.

Response Parameters

Name In Type Description
transfers body array List of transfer details.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volume_id body string The UUID of the volume.
id body string The UUID of the volume transfer.
links body array Links for the volume transfer.
name 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/v3/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/v3/firstproject/volumes/2",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/2",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}

Attachments

Lists all, lists all with details, shows details for, creates, and deletes attachment.

Note

Everything except for Complete attachment is new as of the 3.27 microversion. Complete attachment is new as of the 3.44 microversion.

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

Delete attachment

Deletes an attachment.

Available starting in the 3.27 microversion.

Normal response codes: 200

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
attachment_id path string The ID of the attachment.
GET
/v3/{project_id}/attachments/{attachment_id}

Show attachment details

Shows details for an attachment.

Available starting in the 3.27 microversion.

Normal response codes: 200

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
attachment_id path string The ID of the attachment.

Response Parameters

Name In Type Description
status body string The status of the attachment.
detached_at (Optional) body string The time when attachment is detached.
connection_info body object The connection info used for server to connect the volume.
attached_at (Optional) body string The time when attachment is attached.
attach_mode (Optional) body string The attach mode of attachment, read-only (‘ro’) or read-and-write (‘rw’), default is ‘ro’.
instance (Optional) body string The UUID of the attaching instance.
volume_id body string The UUID of the volume which the attachment belongs to.
id body string The ID of attachment.

Response Example

{
    "attachment": {
        "status": "attaching",
        "detached_at": "2015-09-16T09:28:52.000000",
        "connection_info": {},
        "attached_at": "2015-09-16T09:28:52.000000",
        "attach_mode": "ro",
        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
    }
}
GET
/v3/{project_id}/attachments/detail

List attachments with details

Lists all attachments with details. Since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Available starting in the 3.27 microversion.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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
status body string The status of the attachment.
detached_at (Optional) body string The time when attachment is detached.
connection_info body object The connection info used for server to connect the volume.
attached_at (Optional) body string The time when attachment is attached.
attach_mode (Optional) body string The attach mode of attachment, read-only (‘ro’) or read-and-write (‘rw’), default is ‘ro’.
instance (Optional) body string The UUID of the attaching instance.
volume_id body string The UUID of the volume which the attachment belongs to.
id body string The ID of attachment.

Response Example

{
    "attachments": [
        {
            "status": "attaching",
            "detached_at": "2015-09-16T09:28:52.000000",
            "connection_info": {},
            "attached_at": "2015-09-16T09:28:52.000000",
            "attach_mode": "ro",
            "instance": "31c79baf-b59e-469c-979f-1df4ecb6eea7",
            "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
            "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
        }
    ]
}
GET
/v3/{project_id}/attachments

List attachments

Lists all attachments, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Available starting in the 3.27 microversion.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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
status body string The status of the attachment.
instance (Optional) body string The UUID of the attaching instance.
volume_id body string The UUID of the volume which the attachment belongs to.
id body string The ID of attachment.

Response Example

{
  "attachments": [
    {
      "status": "attaching",
      "instance": "31c79baf-b59e-469c-979f-1df4ecb6eea7",
      "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c",
      "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d"
    }
  ]
}
POST
/v3/{project_id}/attachments

Create attachment

Creates an attachment.

Available starting in the 3.27 microversion.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
attachment body object An attachment object.
instance_uuid body string The UUID of the attaching instance.
connector (Optional) body object The connector object.
volume_uuid body string The UUID of the volume which the attachment belongs to.

Request Example

{
    "attachment": {
        "instance_uuid": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
        "connector": {
            "initiator": "iqn.1993-08.org.debian: 01: cad181614cec",
            "ip": "192.168.1.20",
            "platform": "x86_64",
            "host": "tempest-1",
            "os_type": "linux2",
            "multipath": false,
            "mountpoint": "/dev/vdb",
            "mode": "ro"
        },
        "volume_uuid": "462dcc2d-130d-4654-8db1-da0df2da6a0d"
    }
}

Response Parameters

Name In Type Description
attachment body object An attachment object.
status body string The status of the attachment.
detached_at (Optional) body string The time when attachment is detached.
connection_info body object The connection info used for server to connect the volume.
attached_at (Optional) body string The time when attachment is attached.
attach_mode (Optional) body string The attach mode of attachment, read-only (‘ro’) or read-and-write (‘rw’), default is ‘ro’.
instance (Optional) body string The UUID of the attaching instance.
volume_id body string The UUID of the volume which the attachment belongs to.
id body string The ID of attachment.

Response Example

{
    "attachment": {
        "status": "attaching",
        "detached_at": "2015-09-16T09:28:52.000000",
        "connection_info": {},
        "attached_at": "2015-09-16T09:28:52.000000",
        "attach_mode": "ro",
        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
    }
}
PUT
/v3/{project_id}/attachments/{attachment_id}

Update an attachment

Update a reserved attachment record with connector information and set up the appropriate connection_info from the driver.

Available starting in the 3.27 microversion.

Normal response codes: 200

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
attachment_id path string The ID of the attachment.
attachement body object An attachment object.
connector body object The connector object. The internal structure of connector depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver.

Request Example

{
    "attachment": {
        "connector": {
            "initiator": "iqn.1993-08.org.debian: 01: cad181614cec",
            "ip": "192.168.1.20",
            "platform": "x86_64",
            "host": "tempest-1",
            "os_type": "linux2",
            "multipath": false,
            "mountpoint": "/dev/vdb",
            "mode": "ro"
        }
    }
}

Response Parameters

Name In Type Description
attachment body object An attachment object.
status body string The status of the attachment.
detached_at (Optional) body string The time when attachment is detached.
connection_info body object The connection info used for server to connect the volume.
attached_at (Optional) body string The time when attachment is attached.
attach_mode (Optional) body string The attach mode of attachment, read-only (‘ro’) or read-and-write (‘rw’), default is ‘ro’.
instance (Optional) body string The UUID of the attaching instance.
volume_id body string The UUID of the volume which the attachment belongs to.
id body string The ID of attachment.

Response Example

{
    "attachment": {
        "status": "attaching",
        "detached_at": "2015-09-16T09:28:52.000000",
        "connection_info": {},
        "attached_at": "2015-09-16T09:28:52.000000",
        "attach_mode": "ro",
        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
    }
}
POST
/v3/{project_id}/attachments/{attachment_id}/action

Complete attachment

Complete an attachment for a cinder volume.

Available starting in the 3.44 microversion.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
attachment_id path string The ID of the attachment.

Request Example

{
    "os-complete": {
    }
}

Back-end storage pools

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

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

List all back-end storage pools

Lists all back-end storage pools. Since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
detail (Optional) query boolean Indicates whether to show pool details or only pool names in the response. Set to true to show pool details. Set to false to show only pool names. Default is false.

Response Parameters

Name In Type Description
pools body array List of storage pools.
updated body string The date and time stamp when the extension was last updated.
QoS_support body boolean The quality of service (QoS) support.
name body string The name of the Volume Transfer.
total_capacity body string The total capacity for the back-end volume, in GBs. A valid value is a string, such as unknown, or an integer.
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 or QoS_support.
free_capacity body string The amount of free capacity for the back-end volume, in GBs. A valid value is a string, such as unknown, or an integer.
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": 1024,
                "free_capacity": 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": 512,
                "free_capacity": 200,
                "volume_backend_name": "pool2",
                "reserved_percentage": 0,
                "driver_version": "1.0.1",
                "storage_protocol": "iSER",
                "QoS_support": true
            }
        }
    ]
}

Backups (backups)

A backup is a full copy of a volume stored in an external service. The service can be configured. The only supported service is Object Storage. A backup can subsequently be restored from the external service to either the same volume that the backup was originally taken from or to a new volume. Backup and restore operations can only be carried out on volumes that are in an unattached and available state.

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_restoring A backup restoration error occurred.

If an error occurs, you can find more information about the error in the fail_reason field for the backup.

GET
/v3/{project_id}/backups/detail

List backups with detail

Lists Block Storage backups, with details, to which the project has access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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
backups body array A list of backup objects.
status body string The backup status. Refer to Backup statuses table for the possible status value.
object_count body integer The number of objects in the backup.
fail_reason body string If the backup failed, the reason for the failure. Otherwise, null.
description (Optional) body string The backup description or null.
links body array Links for the backup.
availability_zone (Optional) body string The name of the availability zone.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

name body string The backup name.
has_dependent_backups (Optional) body boolean If this value is true, the backup depends on other backups.
volume_id body string The UUID of the volume.
container (Optional) body string The container name or null.
size body integer The size of the volume, in gibibytes (GiB).
id body string The UUID of the backup.
is_incremental (Optional) body boolean Indicates whether the backup mode is incremental. If this value is true, the backup mode is incremental. If this value is false, the backup mode is full.
data_timestamp body string The time when the data on the volume was first saved. If it is a backup from volume, it will be the same as created_at for a backup. If it is a backup from a snapshot, it will be the same as created_at for the snapshot.
snapshot_id (Optional) body string The UUID of the source volume snapshot.
os-backup-project-attr:project_id body string

The UUID of the owning project.

New in version 3.18

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/v3/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,
            "os-backup-project-attr:project_id": "2c67a14be9314c5dae2ee6c4ec90cf0b",
            "size": 1,
            "status": "available",
            "updated_at": "2013-04-02T10:35:27.000000",
            "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/v3/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,
            "os-backup-project-attr:project_id": "2c67a14be9314c5dae2ee6c4ec90cf0b",
            "size": 1,
            "status": "available",
            "updated_at": "2013-04-02T10:21:48.000000",
            "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
            "is_incremental": true,
            "has_dependent_backups": false
        }
    ]
}
GET
/v3/{project_id}/backups/{backup_id}

Show backup detail

Shows details for a backup.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
backup_id path string The UUID for a backup.

Response Parameters

Name In Type Description
backup body object A backup object.
status body string The backup status. Refer to Backup statuses table for the possible status value.
object_count body integer The number of objects in the backup.
container (Optional) body string The container name or null.
description (Optional) body string The backup description or null.
links body array Links for the backup.
availability_zone (Optional) body string The name of the availability zone.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

name body string The backup name.
has_dependent_backups (Optional) body boolean If this value is true, the backup depends on other backups.
volume_id body string The UUID of the volume.
fail_reason body string If the backup failed, the reason for the failure. Otherwise, null.
size body integer The size of the volume, in gibibytes (GiB).
backup body object A backup object.
id body string The UUID of the backup.
is_incremental (Optional) body boolean Indicates whether the backup mode is incremental. If this value is true, the backup mode is incremental. If this value is false, the backup mode is full.
data_timestamp body string The time when the data on the volume was first saved. If it is a backup from volume, it will be the same as created_at for a backup. If it is a backup from a snapshot, it will be the same as created_at for the snapshot.
snapshot_id (Optional) body string The UUID of the source volume snapshot.
os-backup-project-attr:project_id body string

The UUID of the owning project.

New in version 3.18

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/v3/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,
        "os-backup-project-attr:project_id": "2c67a14be9314c5dae2ee6c4ec90cf0b",
        "size": 1,
        "updated_at": "2013-04-20T05:30:19.000000",
        "data_timestamp": "2013-04-20T05:30:19.000000",
        "snapshot_id": null,
        "status": "available",
        "updated_at": "2013-04-02T10:35:27.000000",
        "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
        "is_incremental": true,
        "has_dependent_backups": false
    }
}
DELETE
/v3/{project_id}/backups/{backup_id}

Delete a backup

Deletes a backup.

Normal response codes: 202

Error response codes: Bad Request(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
backup_id path string The UUID for a backup.
POST
/v3/{project_id}/backups/{backup_id}/restore

Restore a backup

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

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

Normal response codes: 202

Error response codes: Bad Request(400), Request Entity Too Large(413)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
backup_id path string The UUID for a backup.
restore body object A restore object.
name (Optional) body string The volume name.
volume_id (Optional) body string The UUID of the volume to which you want to restore a backup.

Request Example

{
    "restore": {
        "name": "vol-01",
        "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607"
    }
}

Response Parameters

Name In Type Description
restore body object A restore object.
backup_id path string The UUID for a backup.
volume_id body string The UUID of the volume.
volume_name body string The volume name.

Response Example

{
    "restore": {
        "backup_id": "2ef47aee-8844-490c-804d-2a8efe561c65",
        "volume_id": "795114e8-7489-40be-a978-83797f2c1dd3",
        "volume_name": "volume01",
    }
}
POST
/v3/{project_id}/backups

Create a backup

Creates a Block Storage backup from a volume.

Normal response codes: 202

Error response codes: Bad Request(400), Internal Server Error(500)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
backup body object A backup object.
volume_id body string The UUID of the volume that you want to back up.
container (Optional) body string The container name or null.
description (Optional) body string The backup description or null.
incremental (Optional) body boolean The backup mode. A valid value is true for incremental backup mode or false for full backup mode. Default is false.
force (Optional) body boolean Indicates whether to backup, even if the volume is attached. Default is false.
name (Optional) body string The name of the Volume Backup.
snapshot_id body string The UUID of the source volume snapshot. The API creates a new volume snapshot with the same size as the source volume snapshot.
metadata (Optional) body object

The backup metadata key value pairs.

New in version 3.43

Request Example

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

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

Update a backup

Update a Block Storage backup. This API is available since v3.9.

Normal response codes: 202

Error response codes: Bad Request(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
backup_id path string The UUID for a backup.
backup body object A backup object.
description (Optional) body string The backup description or null.
name (Optional) body string The name of the Volume Backup.
metadata (Optional) body object

The backup metadata key value pairs.

New in version 3.43

Request Example

{
    "backup":{
        "name":"test",
        "metadata": {
            "key": "value"
        },
        "description": "this is a backup"
    }
}

Response Parameters

Name In Type Description
backup body object A backup object.
id body string The UUID of the backup.
links body array Links for the backup.
name body string The backup name.

Response Example

{
    "backup": {
        "id": "fad41a83-203d-4998-9d3b-444fd5da5aba",
        "links": [
            {
                "href": "http://10.3.150.25:8776/v3/a7090a26bc554d93aa845a4d41808251/backups/fad41a83-203d-4998-9d3b-444fd5da5aba",
                "rel": "self"
            }, {
                "href": "http://10.3.150.25:8776/a7090a26bc554d93aa845a4d41808251/backups/fad41a83-203d-4998-9d3b-444fd5da5aba",
                "rel": "bookmark"
            }
        ],
        "name": "test",
        "metadata": {
            "key": "value"
        }
    }
}
GET
/v3/{project_id}/backups

List backups for project

Lists Block Storage backups to which the project has access, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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.
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": [
        {
            "status": "available",
            "object_count": 0,
            "container": null,
            "name": "volume-backup",
            "links": [
                {
                    "href": "http://localhost:8776/v3/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "created_at": "2017-06-20T05:30:19.000000",
            "description": null,
            "updated_at": "2017-06-20T05:30:19.000000",
            "data_timestamp": "2017-06-20T05:30:19.000000",
            "has_dependent_backups": false,
            "snapshot_id": null,
            "volume_id": "0b38d3f5-68fb-41db-9a99-337a96fdfa96",
            "fail_reason": null,
            "is_incremental": false,
            "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
            "size": 1
        },
        {
            "status": "available",
            "object_count": 0,
            "container": null,
            "name": "volume-backup",
            "links": [
                {
                    "href": "http://localhost:8776/v3/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "created_at": "2017-06-20T05:30:19.000000",
            "description": null,
            "updated_at": "2017-06-20T05:30:19.000000",
            "data_timestamp": "2017-06-20T05:30:19.000000",
            "has_dependent_backups": false,
            "snapshot_id": null,
            "volume_id": "0b38d3f5-68fb-41db-9a99-337a96fdfa96",
            "fail_reason": null,
            "is_incremental": false,
            "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
            "size": 1
        }
    ]
}
GET
/v3/{project_id}/backups/{backup_id}/export_record

Export a backup

Export information about a backup.

Normal response codes: 200

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
backup_id path string The UUID for a backup.

Response Parameters

Name In Type Description
backup_service body string The service used to perform the backup.
backup_url body string The backup encoded metadata.

Response Example

{
    "backup-record": {
        "backup_service": "cinder.backup.drivers.swift",
        "backup_url": "eyJzdGF0"
    }
}
POST
/v3/{project_id}/backups/{backup_id}/import_record

Import a backup

Import information about a backup.

Normal response codes: 201

Error response codes: badRequest(400), serviceUnavailable(503)

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.

Request Example

{
    "backup-record": {
        "backup_service": "cinder.backup.drivers.swift",
        "backup_url": "eyJzdGF0"
    }
}

Response Parameters

Name In Type Description
id body string The UUID of the backup.
links body array Links for the backup.
name body string The backup name.

Response Example

{
    "backup": {
        "id": "deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
        "links": [
            {
                "href": "http://localhost:8776/v3/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
                "rel": "bookmark"
            }
        ],
        "name": null
    }
}

Backup actions (backups, action)

Force-deletes a backup and reset status for a backup.

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

Force-delete a backup

Force-deletes a backup. Specify the os-force_delete action in the request body.

This operations deletes the backup and any backup data.

The backup driver returns the 405 status code if it does not support this operation.

Normal response codes: 202

Error response codes: itemNotFound(404), badMethod(405)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
backup_id path string The UUID for a backup.
os-force_delete body string The os-force_delete action.

Request Example

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

Reset a backup’s status

Reset a backup’s status. Specify the os-reset_status action in the request body.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
backup_id path string The UUID for a backup.
os-reset_status body object The os-reset_status action.
status body string The status for the backup.

Request Example

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

Capabilities for storage back ends (capabilities)

Shows capabilities for a storage back end.

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

Show all back-end capabilities

Shows capabilities for a storage back end on the host. The hostname takes the form of hostname@volume_backend_name.

Normal response codes: 200

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 Link associated to the extension.
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 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.json file to grant permissions for these actions to limit roles.

GET
/v3/{project_id}/consistencygroups

List project’s consistency groups

Lists consistency groups.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort (Optional) query string Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is 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.
marker (Optional) query string The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response Parameters

Name In Type Description
consistencygroups body array A list of consistency groups.
id body string The UUID of the 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
/v3/{project_id}/consistencygroups

Create a consistency group

Creates a consistency group.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
consistencygroup body object A consistency group.
description body string The consistency group description.
availability_zone (Optional) body string The name of the availability zone.
volume_types body string The list of volume types separated by commas. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type. For information about how to use volume types to create multiple-storage back ends, see Configure multiple-storage back ends.
name (Optional) body string The consistency group name.

Request Example

{
    "consistencygroup": {
        "name": "firstcg",
        "description": "first consistency group",
        "volume_types": "type1,type2",
        "availability_zone": "az0"
    }
}

Response

Name In Type Description
consistencygroup body object A consistency group.
status body string The status of the consistency group.
description (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
/v3/{project_id}/consistencygroups/{consistencygroup_id}

Show a consistency group’s details

Shows details for a consistency group.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
consistencygroup_id path string The ID of the consistency group.

Response Parameters

Name In Type Description
status body string The status of the consistency group.
description (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
/v3/{project_id}/consistencygroups/create_from_src

Create a consistency group from source

Creates a consistency group from source.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
consistencygroup-from-src body object The consistency group from source object.
status body string The status of the consistency group.
user_id body string The UUID of the user.
description (Optional) body string The 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 body string The UUID of the project.
name body string The name of the Volume Transfer.

Request Example

{
    "consistencygroup-from-src": {
        "name": "firstcg",
        "description": "first consistency group",
        "cgsnapshot_id": "6f519a48-3183-46cf-a32f-41815f813986",
        "source_cgid": "6f519a48-3183-46cf-a32f-41815f814546",
        "user_id": "6f519a48-3183-46cf-a32f-41815f815555",
        "project_id": "6f519a48-3183-46cf-a32f-41815f814444",
        "status": "creating"
    }
}
POST
/v3/{project_id}/consistencygroups/{consistencygroup_id}/delete

Delete a consistency group

Deletes a consistency group.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
consistencygroup_id path string The ID of the consistency group.
consistencygroup body object A consistency group.
force (Optional) body boolean Indicates whether to backup, even if the volume is attached. Default is false.

Request Example

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

List consistency groups and details

Lists consistency groups with details.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort (Optional) query string Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is 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.
marker (Optional) query string The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response Parameters

Name In Type Description
consistencygroups body array A list of consistency groups.
status body string The status of the consistency group.
description (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
/v3/{project_id}/consistencygroups/{consistencygroup_id}/update

Update a consistency group

Updates a consistency group.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
consistencygroup_id path string The ID of the consistency group.
consistencygroup body object A consistency group.
remove_volumes (Optional) body string One or more volume UUIDs, separated by commas, to remove from the volume group or consistency group.
description (Optional) body string The backup description or null.
add_volumes (Optional) body string One or more volume UUIDs, separated by commas, to add to the volume group or consistency group.
name body string The name of the Volume Transfer.

Request Example

{
    "consistencygroup": {
        "name": "my_cg",
        "description": "My consistency group",
        "add_volumes": "volume-uuid-1,volume-uuid-2",
        "remove_volumes": "volume-uuid-8,volume-uuid-9"
    }
}

Consistency group snapshots

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

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

Delete a consistency group snapshot

Deletes a consistency group snapshot.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
cgsnapshot_id path string The ID of the consistency group snapshot.
GET
/v3/{project_id}/cgsnapshots/{cgsnapshot_id}

Show consistency group snapshot detail

Shows details for a consistency group snapshot.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
cgsnapshot_id path string The ID of the consistency group snapshot.

Response Parameters

Name In Type Description
cgsnapshot body object A consistency group snapshot object.
status (Optional) body string The status of the consistency group snapshot.
description (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 consistency group snapshot name.

Response Example

{
    "cgsnapshot": {
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814444",
        "status": "available",
        "created_at": "2015-09-16T09:28:52.000000",
        "name": "my-cg1",
        "description": "my first consistency group"
    }
}
GET
/v3/{project_id}/cgsnapshots/detail

List all consistency group snapshots with details

Lists all consistency group snapshots with details.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.

Response Parameters

Name In Type Description
cgsnapshots body object A collection of cgsnapshot objects.
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 consistency group snapshot name.

Response Example

{
    "cgsnapshots": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814444",
            "status": "available",
            "created_at": "2015-09-16T09:28:52.000000",
            "name": "my-cg1",
            "description": "my first consistency group"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "consistencygroup_id": "aed36625-a6d7-4681-ba59-c7ba3d18dddd",
            "status": "error",
            "created_at": "2015-09-16T09:31:15.000000",
            "name": "my-cg2",
            "description": "Edited description"
        }
    ]
}
GET
/v3/{project_id}/cgsnapshots

List all consistency group snapshots

Lists all consistency group snapshots.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.

Response Parameters

Name In Type Description
cgsnapshots body object A collection of cgsnapshot objects.
id body string The UUID of the volume transfer.
name body string The consistency group snapshot name.

Response Example

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

Create a consistency group snapshot

Creates a consistency group snapshot.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
cgsnapshot body object A consistency group snapshot object.
name (Optional) body string The name of the snapshot. Default is None.
consistencygroup_id body string The UUID of the consistency group.
description (Optional) body string The backup description or null.

Request Example

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

Response Parameters

Name In Type Description
status (Optional) body string The 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 consistency group snapshot name.

Services (os-services)

Administrator only. Lists all Cinder services, enables or disables a Cinder service, freeze or thaw the specified cinder-volume host, failover a replicating cinder-volume host.

GET
/v3/{project_id}/os-services

List All Cinder Services

Lists all Cinder services. Provides details why any services were disabled.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
host (Optional) query string Filter the service list result by host name of the service.
binary (Optional) query string Filter the service list result by binary name of the service.

Response Parameters

Name In Type Description
services body array A list of service objects.
binary body string The binary name of the service.
disabled_reason body string The reason for disabling a service.
host body string The name of the host.
state body string The state of the service. One of up or down.
status body string The status of the service. One of available or unavailable.
frozen (Optional) body boolean The host is frozen or not. Only in cinder-volume service.
updated_at body string The date and time stamp when the extension was last updated.
zone body string The availability zone name.
cluster (Optional) body string

The cluster name. Only in cinder-volume service.

New in version 3.7

replication_status (Optional) body string The volume service replication status. Only in cinder-volume service.
active_backend_id (Optional) body string The ID of active storage backend. Only in cinder-volume service.

Response Example

{
    "services": [{
        "status": "enabled",
        "binary": "cinder-scheduler",
        "zone": "nova",
        "state": "up",
        "updated_at": "2017-06-29T05:50:35.000000",
        "host": "devstack",
        "disabled_reason": null
    },
    {
        "status": "enabled",
        "binary": "cinder-backup",
        "zone": "nova",
        "state": "up",
        "updated_at": "2017-06-29T05:50:42.000000",
        "host": "devstack",
        "disabled_reason": null
    },
    {
        "status": "enabled",
        "binary": "cinder-volume",
        "zone": "nova",
        "frozen": false,
        "state": "up",
        "updated_at": "2017-06-29T05:50:39.000000",
        "cluster": null,
        "host": "devstack@lvmdriver-1",
        "replication_status": "disabled",
        "active_backend_id": null,
        "disabled_reason": null
    }]
}
PUT
/v3/{project_id}/os-services/disable

Disable a Cinder Service

Disables a Cinder service. Specify the service by its host name and binary name.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
host (Optional) query string Filter the service list result by host name of the service.
binary (Optional) query string Filter the service list result by binary name of the service.

Request Example

{
    "binary": "cinder-volume",
    "host": "devstack@lvmdriver-1"
}

Response Parameters

Name In Type Description
disabled body boolean The service is disabled or not.
status body string The status of the service. One of available or unavailable.
host body string The name of the host.
service body string The service name. Deprecated. Keeping service key for API compatibility.
binary body string The binary name of the service.

Response Example

{
    "disabled": true,
    "status": "disabled",
    "host": "devstack@lvmdriver-1",
    "service": "",
    "binary": "cinder-volume"
}
PUT
/v3/{project_id}/os-services/disable-log-reason

Log Disabled Cinder Service Information

Logs information to the Cinder service table about why a Cinder service was disabled.

Specify the service by its host name and binary name.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
binary body string The binary name of the service.
host body string The name of the host.
disabled_reason body string The reason for disabling a service.

Request Example

{
    "binary": "cinder-volume",
    "host": "devstack@lvmdriver-1",
    "disabled_reason": "test"
}

Response

Name In Type Description
disabled body boolean The service is disabled or not.
status body string The status of the service. One of available or unavailable.
host body string The name of the host.
service body string The service name. Deprecated. Keeping service key for API compatibility.
binary body string The binary name of the service.
disabled_reason body string The reason for disabling a service.

Response Example

{
    "disabled": true,
    "status": "disabled",
    "host": "devstack@lvmdriver-1",
    "service": "",
    "binary": "cinder-volume",
    "disabled_reason": "test"
}
PUT
/v3/{project_id}/os-services/enable

Enable a Cinder Service

Enables a Cinder service. Specify the service by its host name and binary name.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
binary body string The binary name of the service.
host body string The name of the host.

Request Example

{
    "binary": "cinder-volume",
    "host": "devstack@lvmdriver-1"
}

Response Parameters

Name In Type Description
disabled body boolean The service is disabled or not.
status body string The status of the service. One of available or unavailable.
host body string The name of the host.
service body string The service name. Deprecated. Keeping service key for API compatibility.
binary body string The binary name of the service.
disabled_reason body string The reason for disabling a service.

Response Example

{
    "disabled": false,
    "status": "enabled",
    "host": "devstack@lvmdriver-1",
    "service": "",
    "binary": "cinder-volume",
    "disabled_reason": null
}
PUT
/v3/{project_id}/os-services/get-log

Get Current Log Levels for Cinder Services

Get current log levels for services, supported since v3.32. Filter the services by binary, server name and prefix for the log path.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
binary (Optional) body string The binary name of the service.
server (Optional) body string The name of the host.
prefix (Optional) body string The prefix for the log path we are querying, for example cinder. or sqlalchemy.engine. When not present or the empty string is passed all log levels will be retrieved.

Request Example

{
    "binary": "cinder-volume",
    "server": "devstack@lvmdriver-1",
    "prefix": "cinder.volume"
}

Response Parameters

Name In Type Description
log_levels body array The list of log levels.
binary body string The binary name of the service.
host body string The name of the host.
levels body object The current log level that queried.

Response Example

{
    "log_levels": [{
        "binary": "cinder-api",
        "host": "devstack",
        "levels": {
            "cinder.volume.api": "DEBUG"
        }
    }, {
        "binary": "cinder-scheduler",
        "host": "devstack",
        "levels": {
            "cinder.volume.api": "DEBUG"
        }
    }, {
        "binary": "cinder-backup",
        "host": "devstack",
        "levels": {}
    }, {
        "binary": "cinder-volume",
        "host": "devstack@lvmdriver-1",
        "levels": {
            "cinder.volume.api": "DEBUG"
        }
    }]
}
PUT
/v3/{project_id}/os-services/set-log

Set Log Levels of Cinder Services Dynamically

Set log levels of services dynamically, supported since v3.32. Filter the services by binary, server name and prefix for the log path.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
binary (Optional) body string The binary name of the service.
server (Optional) body string The name of the host.
prefix (Optional) body string The prefix for the log path we are querying, for example cinder. or sqlalchemy.engine. When not present or the empty string is passed all log levels will be retrieved.
levels body string The log level to set, case insensitive, accepted values are INFO, WARNING, ERROR and DEBUG.

Request Example

{
    "binary": "cinder-volume",
    "server": "devstack@lvmdriver-1",
    "prefix": "cinder.volume",
    "level": "ERROR"
}
PUT
/v3/{project_id}/os-services/freeze

Freeze a Cinder Backend Host

Freeze and disable the specified cinder-volume host, and set Disabled Reason of Cinder service table to frozen.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
host body string The name of the host.

Request Example

{
    "host": "devstack@rbd-sas"
}
PUT
/v3/{project_id}/os-services/thaw

Thaw a Cinder Backend Host

Thaw and enable the specified cinder-volume host, and clean Disabled Reason of Cinder service table.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
host body string The name of the host.

Request Example

{
    "host": "devstack@rbd-sas"
}
PUT
/v3/{project_id}/os-services/failover_host

Failover a Cinder Backend Host

Failover a replicating cinder-volume host. Since Cinder Volume API Version 3.26, you can use failover in request URL instead of failover_host, and the cluster name in request body is supported.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
host body string The name of the host.
backend_id (Optional) body string ID of backend to failover to. Default is None.
cluster (Optional) body string

The cluster name. Only in cinder-volume service.

New in version 3.7

Request Example

{
    "host": "devstack@lvmdriver-1",
    "backend_id": null
}

Generic volume groups

Generic volume groups enable you to create a group of volumes and manage them together.

How is generic volume groups different from consistency groups? Currently consistency groups in cinder only support consistent group snapshot. It cannot be extended easily to serve other purposes. A project may want to put volumes used in the same application together in a group so that it is easier to manage them together, and this group of volumes may or may not support consistent group snapshot. Generic volume group is introduced to solve this problem. By decoupling the tight relationship between the group construct and the consistency concept, generic volume groups can be extended to support other features in the future.

GET
/v3/{project_id}/groups

List groups

Lists groups. Since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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
groups body array A collections of groups.
id body string The UUID of the volume transfer.
name body string The group name.

Response Example

{
    "groups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my_group1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my_group2"
        }
    ]
}
POST
/v3/{project_id}/groups

Create group

Creates a group.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group body object A group object.
description (Optional) body string The backup description or null.
availability_zone (Optional) body string The name of the availability zone.
group_type body object A group_type object.
volume_types body array The list of volume types. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
name body string The group name.

Request Example

{
    "group": {
        "name": "first_group",
        "description": "first group",
        "group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
        "volume_types": [
            "4e9e6d23-eed0-426d-b90a-28f87a94b6fe",
            "c4daaf47-c530-4901-b28e-f5f0a359c4e6"
        ],
        "availability_zone": "az0",
    }
}
GET
/v3/{project_id}/groups/{group_id}

Show group details

Shows details for a group.

Normal response codes: 200

Error response codes: itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_id path string The ID of the group.

Response Parameters

Name In Type Description
group body object A group object.
status body string The status of the generic 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.

group_type body object A group_type object.
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 group name.
replication_status (Optional) body string The group replication status. Introduced with API microversion 3.38.

Response Example

{
    "group": {
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "status": "available",
        "availability_zone": "az1",
        "created_at": "2015-09-16T09:28:52.000000",
        "name": "first_group",
        "description": "my first group",
        "group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
        "volume_types": [
            "c4daaf47-c530-4901-b28e-f5f0a359c4e6"
        ],
        "group_snapshot_id": None,
        "source_group_id": None
    }
}
POST
/v3/{project_id}/groups/action

Create group from source

Creates a group from source.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
create-from-src body object The create from source action.
description (Optional) body string The backup description or null.
group_snapshot_id body string The ID of the group snapshot.
source_group_id body string The UUID of the source group.
name body string The group name.

Request Example

{
    "create-from-src": {
        "name": "first_group",
        "description": "first group",
        "group_snapshot_id": "6f519a48-3183-46cf-a32f-41815f813986",
        "source_group_id": None
    }
}
POST
/v3/{project_id}/groups/{group_id}/action

Delete group

Deletes a group.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_id path string The ID of the group.
delete body object The delete action.
delete-volumes (Optional) body boolean If set to true, allows deletion of a group as well as all volumes in the group.

Request Example

{
    "delete": {
        "delete-volumes": False
    }
}
GET
/v3/{project_id}/groups/detail

List groups with details

Lists groups with details, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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
groups body array A collections of groups.
status body string The status of the generic 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.

group_type body object A group_type object.
volume_types body array The list of volume types. In an environment with multiple-storage back ends, the scheduler determines where to send the volume based on the volume type. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
id path string The ID of the group.
name body string The name of the Volume Transfer.

Response Example

{
    "groups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "status": "available",
            "availability_zone": "az1",
            "created_at": "2015-09-16T09:28:52.000000",
            "name": "my_group1",
            "description": "my first group",
            "group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
            "volume_types": [
                "4e9e6d23-eed0-426d-b90a-28f87a94b6fe",
                "a3d55d15-eeb1-4816-ada9-bf82decc09b3"
            ]
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "status": "error",
            "availability_zone": "az2",
            "created_at": "2015-09-16T09:31:15.000000",
            "name": "my_group2",
            "description": "Edited description",
            "group_type": "f8645498-1323-47a2-9442-5c57724d2e3c",
            "volume_types": [
                "c4daaf47-c530-4901-b28e-f5f0a359c4e6"
            ]
        }
    ]
}
PUT
/v3/{project_id}/groups/{group_id}

Update group

Updates a group.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_id path string The ID of the group.
group body object A group object.
remove_volumes (Optional) body string One or more volume UUIDs, separated by commas, to remove from the volume group or consistency group.
description (Optional) body string The backup description or null.
add_volumes (Optional) body string One or more volume UUIDs, separated by commas, to add to the volume group or consistency group.
name body string The group name.

Request Example

{
    "group": {
        "name": "my_group",
        "description": "My group",
        "add_volumes": "volume-uuid-1,volume-uuid-2",
        "remove_volumes": "volume-uuid-8,volume-uuid-9"
    }
}
POST
/v3/{project_id}/groups/{group_id}/action

Reset group status

Resets the status for a group. Specify the reset_status action in the request body.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id body string The UUID of the project.
group_id path string The ID of the group.
reset_status body object The reset_status action.
status (Optional) body string The status of the consistency group snapshot.

Request Example

{
    "reset_status": {
        "status": "available"
    }
}

Group replication

Lists targets, enables, disables, and fails over group replication.

Available since API microversion 3.38.

POST
/v3/{project_id}/groups/{group_id}/action

List replication targets

Lists replication targets for a group.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_id path string The ID of the group.

Request Example

{
    "list_replication_targets": {
    }
}

Response Parameters

Name In Type Description
backend_id body string ID of failover target backend.
unique_key (Optional) body string Vendor specific key-values. Only returned if administrator.

Response Example

{
    "replication_targets": {
        "backend_id": "vendor-id-1",
        "unique_key": "value1"
    }
}
POST
/v3/{project_id}/groups/{group_id}/action

Enable group replication

Enable replication for a group.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_id path string The ID of the group.

Request Example

{
    "enable_replication": {
    }
}
POST
/v3/{project_id}/groups/{group_id}/action

Disable group replication

Disable replication for a group.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_id path string The ID of the group.

Request Example

{
    "disable_replication": {
    }
}
POST
/v3/{project_id}/groups/{group_id}/action

Failover replication

Failover a replicated group.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_id path string The ID of the group.
allow_attached_volume body boolean Whether to allow failover if any volumes are ‘in-use’.
secondary_backend_id body string ID of failover target backend.

Request Example

{
    "failover_replication": {
        "allow_attached_volume": true,
        "secondary_backend_id": "vendor-id-1"
    }
}

Group snapshots

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

DELETE
/v3/{project_id}/group_snapshots/{group_snapshot_id}

Delete group snapshot

Deletes a group snapshot.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_snapshot_id path string The ID of the group snapshot.
GET
/v3/{project_id}/group_snapshots/{group_snapshot_id}

Show group snapshot details

Shows details for a group snapshot.

Normal response codes: 200

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_snapshot_id path string The ID of the group snapshot.

Response Parameters

Name In Type Description
group_snapshot body object The group snapshot.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

group_id body string The UUID of the source group.
id body string The ID of the group snapshot.
name (Optional) body string The group snapshot name.
status (Optional) body string The status of the generic group snapshot.
description (Optional) body string The group snapshot description.

Response Example

{
    "group_snapshot": {
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "group_id": "6f519a48-3183-46cf-a32f-41815f814444",
        "status": "available",
        "created_at": "2015-09-16T09:28:52.000000",
        "name": "my_group_snapshot1",
        "description": "my first group snapshot"
    }
}
GET
/v3/{project_id}/group_snapshots/detail

List group snapshots with details

Lists all group snapshots with details. Since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort_key (Optional) query string

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

New in version 3.29

sort_dir (Optional) query string

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

New in version 3.29

limit (Optional) query integer

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

New in version 3.29

offset (Optional) query integer

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

New in version 3.29

marker (Optional) query string

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

New in version 3.29

Response Parameters

Name In Type Description
group_snapshots body array A collection of group snapshots.
id body string The ID of the group snapshot.
name (Optional) body string The group snapshot name.
status (Optional) body string The status of the generic group snapshot.
description (Optional) body string The group snapshot description.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

group_id (Optional) body string The ID of the group.

Response Example

{
    "group_snapshots": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "group_id": "6f519a48-3183-46cf-a32f-41815f814444",
            "status": "available",
            "created_at": "2015-09-16T09:28:52.000000",
            "name": "my_group_snapshot1",
            "description": "my first group snapshot"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "group_id": "aed36625-a6d7-4681-ba59-c7ba3d18dddd",
            "status": "error",
            "created_at": "2015-09-16T09:31:15.000000",
            "name": "my_group_snapshot2",
            "description": "Edited description"
        }
    ]
}
GET
/v3/{project_id}/group_snapshots

List group snapshots

Lists all group snapshots, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort_key (Optional) query string

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

New in version 3.29

sort_dir (Optional) query string

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

New in version 3.29

limit (Optional) query integer

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

New in version 3.29

offset (Optional) query integer

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

New in version 3.29

marker (Optional) query string

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

New in version 3.29

Response Parameters

Name In Type Description
group_snapshots body array A collection of group snapshots.
id body string The ID of the group snapshot.
name (Optional) body string The group snapshot name.

Response Example

{
    "group_snapshots": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my_group_snapshot1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my_group_snapshot2"
        }
    ]
}
POST
/v3/{project_id}/group_snapshots

Create group snapshot

Creates a group snapshot.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_snapshot body object The group snapshot.
name (Optional) body string The group snapshot name.
description (Optional) body string The group snapshot description.
group_id (Optional) body string The ID of the group.

Request Example

{
    "group_snapshot": {
        "group_id": "6f519a48-3183-46cf-a32f-41815f814546",
        "name": "first_group_snapshot",
        "description": "first group snapshot",
    }
}

Response Parameters

Name In Type Description
group_snapshot body object The group snapshot.
id body string The ID of the group snapshot.
name (Optional) body string The group snapshot name.
status (Optional) body string The status of the generic group snapshot.
description (Optional) body string The group snapshot description.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

group_id (Optional) body string The ID of the group.

Response Example

{
    "group_snapshot": {
        "id": "6f519a48-3183-46cf-a32f-41815f816666",
        "name": "first_group_snapshot",
        "status": "creating",
        "group_type_id": "58737af7-786b-48b7-ab7c-2447e74b0ef4",
        "created_at": "2017-06-20T07:44:47.000000",
        "group_id": "d5577983-23be-47e3-b98b-bf604e5af421",
        "description": null
    }
}
POST
/v3/{project_id}/group_snapshots/{group_snapshot_id}/action

Reset group snapshot status

Resets the status for a group snapshot. Specifies the reset_status action in the request body.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id body string The UUID of the project.
group_snapshot_id path string The ID of the group snapshot.
reset_status body object The reset_status action.
status (Optional) body string The status of the generic group snapshot.

Request Example

{
    "reset_status": {
        "status": "available"
    }
}

Group types

PUT
/v3/{project_id}/group_types/{group_type_id}

Update group type

Updates a group type.

To create a generic volume group, you must specify a group type.

Normal response codes: 200

Error response codes: badRequest(400), forbidden(403), itemNotFound(404), conflict(409), computeFault(500)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_type_id (Optional) path string The UUID for an existing group type.
group_type body object A group_type object.
name (Optional) body string The group type name.
description (Optional) body string The group type description.

Request Example

{
    "group_type": {
        "name": "grp-type-001",
        "description": "group type 0001",
        "is_public": true,
    }
}

Response Parameters

Name In Type Description
group_type body object A group_type object.
id body string The group type ID.
is_public (Optional) body boolean Whether the group is publicly visible.
group_specs (Optional) body object A set of key and value pairs that contains the specifications for a group type.
description (Optional) body string The group type description.
name (Optional) body string The group type name.

Response Example

{
    "group_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "grp-type-001",
        "description": "group type 001",
        "is_public": "true",
        "group_specs": {
            "consistent_group_snapshot_enabled": "<is> False"
        }
    }
}
GET
/v3/{project_id}/group_types/{group_type_id}

Show group type details

Shows details for a group type.

Normal response codes: 200

Error response codes: itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_type_id (Optional) path string The UUID for an existing group type.

Response Parameters

Name In Type Description
group_type body object A group_type object.
id body string The group type ID.
name (Optional) body string The group type name.
is_public (Optional) body boolean Whether the group is publicly visible.
group_specs (Optional) body object A set of key and value pairs that contains the specifications for a group type.
description (Optional) body string The group type description.

Response Example

{
    "group_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "grp-type-001",
        "description": "group type 001",
        "is_public": "true",
        "group_specs": {
            "consistent_group_snapshot_enabled": "<is> False"
        }
    }
}
DELETE
/v3/{project_id}/group_types/{group_type_id}

Delete group type

Deletes a group type.

Normal response codes: 202

Error response codes: badRequest(400), forbidden(403), itemNotFound(404)

Request

Name In Type Description
group_type_id (Optional) path string The UUID for an existing group type.
project_id path string The UUID of the project in a multi-tenancy cloud.
GET
/v3/{project_id}/group_types

List group types

Lists group types.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
sort (Optional) query string Comma-separated list of sort keys and optional sort directions in the form of < key > [: < direction > ]. A valid direction is 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
group_types body array The list of group types.
id body string The group type ID.
group_specs body object A set of key and value pairs that contains the specifications for a group type.
name (Optional) body string The group type name.

Response Example

{
    "group_types": [
        {
            "group_specs": {
                "consistent_group_snapshot_enabled": "<is> False"
            },
            "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
            "name": "group_type1"
        },
        {
            "group_specs": {},
            "id": "8eb69a46-df97-4e41-9586-9a40a7533803",
            "name": "group_type2"
        }
    ]
}
POST
/v3/{project_id}/group_types

Create group type

Creates a group type.

To create a generic volume group, you must specify a group type.

Normal response codes: 202

Error response codes: badRequest(400), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_type body object A group_type object.
name (Optional) body string The group type name.
description (Optional) body string The group type description.
group_specs (Optional) body object A set of key and value pairs that contains the specifications for a group type.

Request Example

{
    "group_type": {
        "name": "grp-type-001",
        "description": "group type 0001",
        "is_public": True,
        "group_specs": {
            "consistent_group_snapshot_enabled": "<is> False"
        }
    }
}

Response Parameters

Name In Type Description
group_type body object A group_type object.
id body string The group type ID.
is_public (Optional) body boolean Whether the group is publicly visible.
group_specs (Optional) body object A set of key and value pairs that contains the specifications for a group type.
description (Optional) body string The group type description.
name (Optional) body string The group type name.

Response Example

{
    "group_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "grp-type-001",
        "description": "group type 001",
        "is_public": "true",
        "group_specs": {
            "consistent_group_snapshot_enabled": "<is> False"
        }
    }
}

Group type specs

POST
/v3/{project_id}/group_types/{group_type_id}/group_specs

Create group specs for a group type

Create group specs for a group type, if the specification key already exists in group specs, this API will update the specification as well.

Normal response codes: 202

Error response codes: badRequest(400), forbidden(403), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_type_id path string The UUID for an existing group type.
group_specs body object A set of key and value pairs that contains the specifications for a group type.

Request Example

{
    "group_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}

Response Parameters

Name In Type Description
group_specs body object A set of key and value pairs that contains the specifications for a group type.

Response Example

{
    "group_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
GET
/v3/{project_id}/group_types/{group_type_id}/group_specs

List group specs for a group type

List all the group specs for a group type,

Normal response codes: 200

Error response codes: itemNotFound(404), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_type_id path string The UUID for an existing group type.

Response Parameters

Name In Type Description
group_specs body object A set of key and value pairs that contains the specifications for a group type.

Response Example

{
    "group_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
GET
/v3/{project_id}/group_types/{group_type_id}/group_specs/{spec_id}

Show one specific group spec for a group type

Show a group spec for a group type,

Normal response codes: 200

Error response codes: itemNotFound(404), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_type_id path string The UUID for an existing group type.
spec_id path string The id (key) of the group specification.

Response Parameters

Name In Type Description
spec body string The value of the group specification corresponding to the specified key.

Response Example

{
    "key1": "value1"
}
PUT
/v3/{project_id}/group_types/{group_type_id}/group_specs/{spec_id}

Update one specific group spec for a group type

Update a group spec for a group type,

Normal response codes: 202

Error response codes: itemNotFound(404), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_type_id path string The UUID for an existing group type.
spec_id path string The id (key) of the group specification.
spec body string The value of the group specification corresponding to the specified key.

Response Parameters

Name In Type Description
spec body string The value of the group specification corresponding to the specified key.

Response Example

{
    "key1": "value1"
}
DELETE
/v3/{project_id}/group_types/{group_type_id}/group_specs/{spec_id}

Delete one specific group spec for a group type

Delete a group spec for a group type,

Normal response codes: 202

Error response codes: itemNotFound(404), forbidden(403)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
group_type_id path string The UUID for an existing group type.
spec_id path string The id (key) of the group specification.

Hosts extension (os-hosts)

Administrators only, depending on policy settings.

Lists, shows hosts.

GET
/v3/{admin_project_id}/os-hosts

List all hosts for a project

Lists all hosts summary info that is not disabled.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
admin_project_id path string The UUID of the administrative project.

Response Parameters

Name In Type Description
hosts body object A OpenStack Block Storage host.
service-status body string The status of the service. One of 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.
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
/v3/{admin_project_id}/os-hosts/{host_name}

Show Host Details for a project

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.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
admin_project_id path string The UUID of the administrative project.
host_name path string The name of the host that hosts the storage back end.

Response

Name In Type Description
host body object The OpenStack Block Storage host where the existing volume resides.
volume_count body integer Total number of volumes.
total_volume_gb body integer The total number of gibibytes (GiB) used.
total_snapshot_gb body integer The total number of snapshots used.
project body string The Project ID 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.
snapshot_count body integer The total number of snapshots used.

Response Example

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

Limits (limits)

Shows absolute limits for a project.

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

GET
/v3/{project_id}/limits

Show absolute limits for project

Shows absolute limits for a project.

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

Normal response codes: 200

Error response codes: 203

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.

Response Parameters

Name In Type Description
limits body object A list of limit objects.
rate body array Rate-limit volume copy bandwidth, used to mitigate slow down of data access from the instances.
absolute body object An absolute limits object.
totalSnapshotsUsed body integer The total number of snapshots used.
maxTotalBackups body integer The maximum number of backups.
maxTotalVolumeGigabytes body integer The maximum total amount of volumes, in gibibytes (GiB).
maxTotalSnapshots body integer The maximum number of snapshots.
maxTotalBackupGigabytes body integer The maximum total amount of backups, in gibibytes (GiB).
totalBackupGigabytesUsed body integer The total number of backups gibibytes (GiB) used.
maxTotalVolumes body integer The maximum number of volumes.
totalVolumesUsed body integer The total number of volumes used.
totalBackupsUsed body integer The total number of backups used.
totalGigabytesUsed body integer The total number of gibibytes (GiB) used.

Response Example

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

Messages

Lists all, shows, and deletes messages.

DELETE
/v3/{project_id}/messages/{message_id}

Delete message

Deletes a message.

Normal response codes: 202

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
message_id path string The UUID of the message.
GET
/v3/{project_id}/messages/{message_id}

Show message details

Shows details for a message.

Normal response codes: 200

Error response codes: badRequest(400), itemNotFound(404)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
message_id path string The UUID of the message.

Response Parameters

Name In Type Description
message body string The translated readable message corresponding to event_id.
request_id body string The id of the request during which the message was created.
links (Optional) body array Links for the message.
message_level body string The level of the message, possible value is only ‘ERROR’ now.
event_id body string The id of the event to this message, this id could eventually be translated into user_message.
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.

guaranteed_until (Optional) body string The expire time of the message, this message could be be deleted after this time.
resource_uuid (Optional) body string The UUID of the resource during whose operation the message was created.
id body integer The ID for the message.
resource_type (Optional) body string The resource type corresponding to resource_uuid.
user_message body string The translated readable message corresponding to event_id.

Response Example

{
    "message": {
        "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
        "links": [
            {
                "href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "bookmark"
            }
        ],
        "message_level": "ERROR",
        "event_id": "VOLUME_000002",
        "created_at": "2014-10-28T00:00:00-00:00",
        "guaranteed_until": "2014-10-28T00:00:00-00:00",
        "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4cacf",
        "id": "c506cd4b-9048-43bc-97ef-0d7dec369b42",
        "resource_type": "VOLUME",
        "user_message": "No storage could be allocated for this volume request."
    }
}
GET
/v3/{project_id}/messages

List messages

Lists all messages, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request.

Normal response codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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
messages body string A collection of user messages.
request_id body string The id of the request during which the message was created.
links (Optional) body array Links for the message.
message_level body string The level of the message, possible value is only ‘ERROR’ now.
event_id body string The id of the event to this message, this id could eventually be translated into user_message.
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.

guaranteed_until (Optional) body string The expire time of the message, this message could be be deleted after this time.
resource_uuid (Optional) body string The UUID of the resource during whose operation the message was created.
id body integer The ID for the message.
resource_type (Optional) body string The resource type corresponding to resource_uuid.
user_message body string The translated readable message corresponding to event_id.

Response Example

{
    "messages": [{
        "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
        "links": [
            {
                "href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "bookmark"
            }
        ],
        "message_level": "ERROR",
        "event_id": "VOLUME_000002",
        "created_at": "2014-10-28T00:00:00-00:00",
        "guaranteed_until": "2014-10-28T00:00:00-00:00",
        "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4cacf",
        "id": "c506cd4b-9048-43bc-97ef-0d7dec369b42",
        "resource_type": "VOLUME",
        "user_message": "No storage could be allocated for this volume request."
    },{
        "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
        "links": [
            {
                "href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "bookmark"
            }
        ],
        "message_level": "ERROR",
        "event_id": "VOLUME_000002",
        "created_at": "2014-10-28T00:00:00-00:00",
        "guaranteed_until": "2014-10-28T00:00:00-00:00",
        "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4df4e",
        "id": "c506cd4b-9048-43bc-97ef-0d7dec36d5gt",
        "resource_type": "VOLUME",
        "user_message": "No storage could be allocated for this volume request."
    }]
}

Resource Filters

Lists all resource filters, available since microversion 3.33.

GET
/v3/{project_id}/resource_filters

List resource filters

List filters.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
resource (Optional) query string Filter for resource name.

Response Parameters

Name In Type Description
resource_filters body array A collection of resource filters.
filters body array The resource filter array.
resource body string Resource which the filters will be applied to.

Response Example

{
    "resource_filters": [
        {
            "filters": [
                "name",
                "status",
                "image_metadata", "bootable",
                "migration_status"
            ],
            "resource": "volume"
        },
        {
            "filters": [
                "name",
                "status",
                "volume_id"
            ],
            "resource": "snapshot"
        }
    ]
}

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

Administrators only, depending on policy settings.

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

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

Disassociate a QoS specification from all associations

Disassociates a QoS specification from all associations.

Normal response codes: 202

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
/v3/{project_id}/qos-specs/{qos_id}/delete_keys

Unset keys in a QoS specification

Unsets keys in a QoS specification.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
qos_id path string The ID of the QoS specification.
keys body array List of Keys. For example, CryptsetupEncryptor, LuksEncryptor or NoOpEncryptor.

Request Example

{
    "keys": [
        "key1"
    ]
}
GET
/v3/{project_id}/qos-specs/{qos_id}/associations

Get all associations for a QoS specification

Lists all associations for a QoS specification.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
qos_id path string The ID of the QoS specification.

Response

Name In Type Description
qos_specs body object A qos_specs object.
specs body object A specs object.
consumer body string The consumer type.
name body string The name of the QoS specification.
id body string The generated ID for the QoS specification.
links body array The QoS specification links.

Response Example

{
    "qos_specs": {
        "specs": {
            "availability": "100",
            "numberOfFailures": "0"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v3/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
/v3/{project_id}/qos-specs/{qos_id}/associate

Associate QoS specification with a volume type

Associates a QoS specification with a volume type.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
qos_id path string The ID of the QoS specification.
vol_type_id query string A volume type ID.
GET
/v3/{project_id}/qos-specs/{qos_id}/disassociate

Disassociate QoS specification from a volume type

Disassociates a QoS specification from a volume type.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
qos_id path string The ID of the QoS specification.
vol_type_id query string A volume type ID.
GET
/v3/{project_id}/qos-specs/{qos_id}

Show a QoS specification details

Shows details for a QoS specification.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
qos_id path string The ID of the QoS specification.

Response Parameters

Name In Type Description
qos_specs body object A qos_specs object.
specs body object A specs object.
consumer (Optional) body string The consumer type.
name body string The name of the QoS specification.
id body string The generated ID for the QoS specification.
links body array The QoS specification links.

Response Example

{
    "qos_specs": {
        "specs": {
            "availability": "100",
            "numberOfFailures": "0"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v3/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
/v3/{project_id}/qos-specs/{qos_id}

Set keys in a QoS specification

Sets keys in a QoS specification.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
qos_id path string The ID of the QoS specification.
qos_specs body object A qos_specs object.

Request Example

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

Response

Name In Type Description
qos_specs body object A qos_specs object.

Response Example

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

Delete a QoS specification

Deletes a QoS specification.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
qos_id path string The ID of the QoS specification.
force (Optional) query boolean To delete a QoS specification even if it is in- use, set to true. Default is false.
POST
/v3/{project_id}/qos-specs

Create a QoS specification

Creates a QoS specification.

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

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
qos_specs body object A qos_specs object.
name body string The name of the QoS specification.

Request Example

{
    "qos_specs": {
        "name": "reliability-spec",
    }
}

Response Parameters

Name In Type Description
qos_specs body object A qos_specs object.
name body string The name of the QoS specification.
links body array The QoS specification links.
id body string The generated ID for the QoS specification.
consumer (Optional) body string The consumer type.
specs body object A specs object.
GET
/v3/{project_id}/qos-specs

List QoS Specifications

Lists quality of service (QoS) specifications.

Normal response codes: 200

Error response codes: 300

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
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.
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
qos_specs body object A qos_specs object.
specs body object A 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
/v3/{admin_project_id}/os-quota-class-sets/{quota_class_name}

Show quota classes for a project

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

Normal response codes: 200

Error response codes: 403, 404

Request

Name In Type Description
quota_class_name path string The name of the quota class for which to set quotas.
admin_project_id path string The UUID of the administrative project.

Response Parameters

Name In Type Description
quota_class_set body object A quota_class_set object.
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 size (GB) of volumes that are allowed for each volume.
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
/v3/{admin_project_id}/os-quota-class-sets/{quota_class_name}

Update quota classes for a project

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

Normal response codes: 200

Error response codes: 400, 403, 404

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
quota_class_set body object A quota_class_set object.
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 size (GB) of volumes that are allowed for each volume.
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
/v3/{admin_project_id}/os-quota-sets/{project_id}

Show quotas for a project

Shows quotas for a project.

Normal response codes: 200

Request

Name In Type Description
admin_project_id path string The UUID of the administrative project.
project_id path string The UUID of the tenant in a multi-tenancy cloud.
usage (Optional) query boolean Show project’s quota usage information. Default is false.

Response Parameters

Name In Type Description
quota_set body object A quota_set object.
id body string The QoS set ID.
volumes body integer The number of volumes that are allowed for each project.
volumes_{volume_type} body integer The number of volumes that are allowed for each project and the specified volume type.
snapshots body integer The number of snapshots that are allowed for each project.
snapshots_{volume_type} body integer The number of snapshots that are allowed for each project and the specified volume type.
backups body integer The number of backups that are allowed for each project.
groups body integer The number of groups that are allowed for each project.
per_volume_gigabytes body integer The size (GB) of volumes that are allowed for each volume.
gigabytes body integer The size (GB) of volumes and snapshots that are allowed for each project.
gigabytes_{volume_type} body integer The size (GB) of volumes and snapshots that are allowed for each project and the specifed volume type.
backup_gigabytes body integer The size (GB) of backups that are allowed for each project.

Response Example

{
    "quota_set": {
        "id": "a7090a26bc554d93aa845a4d41808251",
        "volumes": 10,
        "volumes_ceph": -1,
        "volumes_lvm-thin": -1,
        "volumes_lvmdriver-1": -1,
        "snapshots": 10,
        "snapshots_ceph": -1,
        "snapshots_lvm-thin": -1,
        "snapshots_lvmdriver-1": -1,
        "backups": 10,
        "groups": 10,
        "per_volume_gigabytes": -1,
        "gigabytes": 1000,
        "gigabytes_ceph": -1,
        "gigabytes_lvm-thin": -1,
        "gigabytes_lvmdriver-1": -1,
        "backup_gigabytes": 1000
    }
}
GET
/v3/{admin_project_id}/os-quota-sets/{project_id}?{usage}=True

Show quota usage for a project

Shows quota usage for a project.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the tenant in a multi-tenancy cloud.
admin_project_id path string The UUID of the administrative project.
usage (Optional) query boolean Show project’s quota usage information. Default is false.

Response Parameters

Name In Type Description
quota_set body object A quota_set object.
id body string The QoS set ID.
volumes body object The volume usage information for this project, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.
volumes_{volume_type} body object The volume usage information for this project and this volume type, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.
snapshots body object The snapshot usage information for this project, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.
snapshots_{volume_type} body object The snapshot usage information for this project and this volume type, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.
backups body object The backup usage information for this project, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.
groups body object The group usage information for this project, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.
per_volume_gigabytes body object The size (GB) usage information for each volume, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled and only limit is meaningful here.
gigabytes body object The size (GB) usage information of volumes and snapshots for this project, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.
gigabytes_{volume_type} body object The size (GB) usage information of volumes and snapshots for this project and this volume type, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.
backup_gigabytes body object The size (GB) usage information of backup for this project, including in_use, limit, reserved and allocated attributes. Note: allocated attribute is available only when nested quota is enabled.

Response Example

{
    "quota_set": {
        "id": "a7090a26bc554d93aa845a4d41808251",
        "volumes": {
            "reserved": 0,
            "allocated": 0,
            "limit": 10,
            "in_use": 0
        },
        "volumes_lvmdriver-1": {
            "reserved": 0,
            "allocated": 0,
            "limit": -1,
            "in_use": 0
        },
        "snapshots": {
            "reserved": 0,
            "allocated": 0,
            "limit": 10,
            "in_use": 0
        },
        "snapshots_lvmdriver-1": {
            "reserved": 0,
            "allocated": 0,
            "limit": -1,
            "in_use": 0
        },
        "backups": {
            "reserved": 0,
            "allocated": 0,
            "limit": 10,
            "in_use": 0
        },
        "groups": {
            "reserved": 0,
            "allocated": 0,
            "limit": 10,
            "in_use": 0
        },
        "per_volume_gigabytes": {
            "reserved": 0,
            "allocated": 0,
            "limit": -1,
            "in_use": 0
        },
        "gigabytes": {
            "reserved": 0,
            "allocated": 0,
            "limit": 1000,
            "in_use": 0
        },
        "gigabytes_lvmdriver-1": {
            "reserved": 0,
            "allocated": 0,
            "limit": 1000,
            "in_use": 0
        },
        "backup_gigabytes": {
            "reserved": 0,
            "allocated": 0,
            "limit": 1000,
            "in_use": 0
        }
    }
}
PUT
/v3/{admin_project_id}/os-quota-sets/{project_id}

Update quotas for a project

Updates quotas for a project.

Normal response codes: 200

Request

Name In Type Description
admin_project_id path string The UUID of the administrative project.
project_id path string The UUID of the tenant 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 that are allowed for each volume.
gigabytes body integer The size (GB) of volumes and snapshots that are allowed for each project.
gigabytes_{volume_type} body integer The size (GB) of volumes and snapshots that are allowed for each project and the specifed volume type.
backup_gigabytes body integer The size (GB) of backups that are allowed for each project.
skip_validation (Optional) body boolean If set to false, the quota value can’t be set lower than the in_use quota. Default is True.

Request Example

{
    "quota_set":{
        "groups": 11,
        "volumes": 5,
        "volumes_ceph": 3,
        "backups": 4
    },
    "skip_validation": false
}

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 that are allowed for each volume.
gigabytes body integer The size (GB) of volumes and snapshots that are allowed for each project.
gigabytes_{volume_type} body integer The size (GB) of volumes and snapshots that are allowed for each project and the specifed volume type.
backup_gigabytes body integer The size (GB) of backups that are allowed for each project.

Response Example

{
    "quota_set": {
        "volumes": 10,
        "volumes_ceph": -1,
        "volumes_lvm-thin": -1,
        "volumes_lvmdriver-1": -1,
        "snapshots": 10,
        "snapshots_ceph": -1,
        "snapshots_lvm-thin": -1,
        "snapshots_lvmdriver-1": -1,
        "backups": 10,
        "groups": 10,
        "per_volume_gigabytes": -1,
        "gigabytes": 1000,
        "gigabytes_ceph": -1,
        "gigabytes_lvm-thin": -1,
        "gigabytes_lvmdriver-1": -1,
        "backup_gigabytes": 1000
    }
}
DELETE
/v3/{admin_project_id}/os-quota-sets/{project_id}

Delete quotas for a project

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

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the tenant in a multi-tenancy cloud.
admin_project_id path string The UUID of the administrative project.
GET
/v3/{admin_project_id}/os-quota-sets/{project_id}/defaults

Get default quotas for a project

Gets default quotas for a project.

Normal response codes: 200

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
admin_project_id path string The UUID of the administrative project.

Response Parameters

Name In Type Description
quota_set body object A quota_set object.
id body string The QoS set ID.
volumes body integer The number of volumes that are allowed for each project.
volumes_{volume_type} body integer The number of volumes that are allowed for each project and the specified volume type.
snapshots body integer The number of snapshots that are allowed for each project.
snapshots_{volume_type} body integer The number of snapshots that are allowed for each project and the specified volume type.
backups body integer The number of backups that are allowed for each project.
groups body integer The number of groups that are allowed for each project.
per_volume_gigabytes body integer The size (GB) of volumes that are allowed for each volume.
gigabytes body integer The size (GB) of volumes and snapshots that are allowed for each project.
gigabytes_{volume_type} body integer The size (GB) of volumes and snapshots that are allowed for each project and the specifed volume type.
backup_gigabytes body integer The size (GB) of backups that are allowed for each project.

Response Example

{
    "quota_set": {
        "id": "a7090a26bc554d93aa845a4d41808251",
        "volumes": 10,
        "volumes_ceph": -1,
        "volumes_lvm-thin": -1,
        "volumes_lvmdriver-1": -1,
        "snapshots": 10,
        "snapshots_ceph": -1,
        "snapshots_lvm-thin": -1,
        "snapshots_lvmdriver-1": -1,
        "backups": 10,
        "groups": 10,
        "per_volume_gigabytes": -1,
        "gigabytes": 1000,
        "gigabytes_ceph": -1,
        "gigabytes_lvm-thin": -1,
        "gigabytes_lvmdriver-1": -1,
        "backup_gigabytes": 1000
    }
}

Workers (workers)

POST
v3/{project_id}/workers/cleanup

Cleanup services

Request cleanup of services with optional filtering. This API is only available with microversion 3.24 or later.

Normal response codes: 202

Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
cluster (Optional) body string The OpenStack Block Storage cluster where the resource resides. Optional only if host field is provided.
host body string The name of the service which is running on the host.
binary body string The binary name of the service.
is-up (Optional) body boolean Filter by up/down status.
disabled (Optional) body boolean Filter by disabled status.
resource-id (Optional) body string The UUID of a resource to cleanup.
resource-type (Optional) body string The resource type corresponding to resource_uuid.

Request Example

{
    "cluster": "test",
    "disabled": "True",
    "host": "127.0.0.1",
    "is_up": "True",
    "binary": "cinder-volume",
    "resource_id": "b122f668-d15a-40f8-af21-38d218796ab8",
    "resource_type": "Volume"
}

Response Parameters

Name In Type Description
host body string The name of the service which is running on the host.
binary body string The binary name of the service.
id (Optional) body string UUID for the cleanup service.
cluster_name (Optional) body string The OpenStack Block Storage cluster where the resource resides. Optional only if host field is provided.

Response Example

{
    "cleaning": [
        {
            "id": "dd233343-er34-fr43-54ss-vfdfft433fdf",
            "host": "127.0.0.1",
            "binary": "cinder-volume",
            "cluster_name": "test"
        }
    ],
    "unavailable": []
}
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.