Prev Next

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

Version 5.0.0 — Feb 01, 2022

Prev Next