7.2. Creating volumes

POST /v3/{project_id}/volumes

Create a volume.

To clone a volume, pass its ID in source_volid. To create a volume from a snapshot, pass its ID in snapshot_id.

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.

Precondition: 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 another error status, the request has 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.

Source: https://docs.openstack.org/api-ref/block-storage/v3/index.html#create-a-volume

7.2.1. Request

Name In Type Description
project_id path string The UUID of the project in a multi-tenancy cloud.
volume body object A volume object.
size body integer The size of the volume, in gibibytes (GiB).
availability_zone (Optional) body string The name of the availability zone.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume unless a larger size is requested.
description (Optional) body string The volume description.
multiattach (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false. Note that support for multiattach volumes depends on the volume type being used.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
backup_id (Optional) body string

The UUID of the backup.

New in version 3.47

name (Optional) body string The volume name.
imageRef (Optional) body string The UUID of the image from which you want to create the volume. Required to create a bootable volume.
volume_type (Optional) body string The volume type (either name or ID). To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
metadata (Optional) body object One or more metadata key and value pairs to be associated with the new volume.
consistencygroup_id body string The UUID of the consistency group.
OS-SCH-HNT:scheduler_hints (Optional) body object The dictionary of data to send to the scheduler.

7.2.1.1. Example

Create a 1 GiB volume vol2 with the policy policy1:

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d '
{
  "volume": {
    "size": 1,
    "description": "Volume 2",
    "name": "vol2",
    "volume_type": "policy1"
  }
}' https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes

7.2.2. Response

Name In Type Description
migration_status (Optional) body string The volume migration status. Admin only.
attachments body array

Instance attachment information. If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID. Otherwise, this list is empty. For example:

[
  {
    'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
    'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
    'attached_at': '2019-09-30T19:30:34.000000',
    'host_name': null,
    'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
    'device': '/dev/vda',
    'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
  }
]
links body array The volume links.
availability_zone (Optional) body string The name of the availability zone.
encrypted body boolean If true, this volume is encrypted.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

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

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

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

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

replication_status body string The volume replication status.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
id body string The UUID of the volume.
size body integer The size of the volume, in gibibytes (GiB).
user_id body string The UUID of the user.
metadata body object A metadata object. Contains one or more metadata key and value pairs that are associated with the volume.
status body string The volume status.
description body string The volume description.
multiattach body boolean If true, this volume can attach to more than one instance.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume unless a larger size is requested.
volume body object A volume object.
consistencygroup_id body string The UUID of the consistency group.
name body string The volume name.
bootable body string Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

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

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

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

volume_type body string The associated volume type name for the volume.
group_id (Optional) body string The ID of the group.

7.2.2.1. Status codes

7.2.2.1.1. Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

7.2.2.2. Example

{
  "volume": {
    "status": "creating",
    "migration_status": null,
    "user_id": "eb481bff7b7c4ec6a686646957d8064b",
    "attachments": [],
    "links": [
      {
        "href": "https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329",
        "rel": "self"
      },
      {
        "href": "https://<node_IP_addr>:8776/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329",
        "rel": "bookmark"
      }
    ],
    "availability_zone": "nova",
    "bootable": "false",
    "encrypted": false,
    "created_at": "2020-03-11T12:15:14.476003",
    "description": "Volume 2",
    "updated_at": null,
    "volume_type": "policy1",
    "name": "vol2",
    "replication_status": null,
    "consistencygroup_id": null,
    "source_volid": null,
    "snapshot_id": null,
    "multiattach": false,
    "metadata": {},
    "id": "de5b7dfc-e3e8-4f14-9969-98d61af40329",
    "size": 1
  }
}