• Native OpenStack API

noa
  1. Help Center
  2. Native OpenStack API
  3. API Reference
  4. Cinder V3 Interfaces
  5. Volumes
  6. Create Volume

Create Volume

Function Description

This interface is used to create an empty volume.

This operation must be performed together by cinder-api, cinder-scheduler, and cinder-volume (cinder-proxy at the cascading layer). After cinder-api receives a request, it authenticates parameters in the request, applies for quotas in the corresponding tenant, and then submits the request to cinder-scheduler for host selection. cinder-scheduler filters available hosts based on the result reported by the backend periodically, the AZ information specified during volume creation, and the volume type, and selects the most appropriate host from the host list based on the weight computing method and delivers a message to the host (a specific service provided by cinder-proxy or cinder-volume). After the message is delivered to cinder-proxy or cinder-volume, the service converts the request into a specific operation on backend storage and finalizes creating a volume..

Interface Format

Method

URI

Description

POST

/v3/{project_id}/volumes

Creates a volume.

Restrictions

The source_volid parameter must be specified. The volume size you specified must be the same as that of the source volume.

Extension Description

N/A

Request Parameter

Parameter

Type

Mandatory

Description

availability_zone

String

No

Specifies the AZ where the volume is created. If the AZ does not exist, the volume fails to create. This parameter is required when you create a volume in the public cloud system.

source_volid

String

No

Specifies the ID of the existing volume, and allows you to create a volume from an existing volume.

description

String

No

Specifies the volume description. The value is a string of less than 255 characters.

snapshot_id

String

No

Specifies the snapshot ID. If this parameter is specified, the volume is created from the snapshot. This parameter is not supported in the public cloud scenario.

size

Int

Yes (If the volume is created directly or from the image, the parameter is mandatory. If the volume is created from the source volume, volume snapshot, and volume replication, the parameter is optional. If the volume is created from the source volume, the volume size must be the same as the source volume.)

Specifies the size of the volume.

name

String

No

Specifies the volume name. The value is a string of less than 255 characters.

imageRef

String

No

Specifies the ID of an image in Glance. If this parameter is specified, the volume is created from the image.

volume_type

String

No

Specifies the ID or name of the disk type.

  • The EVS disk type must be specified for the EVS service. If the disk type is not specified, the system specifies the default disk type for the created disks. When the specified disk type is not available in the AZ, the disk fails to be created.
  • During EVS disk creation from a snapshot, the value of the volume_type field must be the same as that of the source EVS disk.

metadata

Dict

No

Specifies the volume metadata. Ensure that key and value in metadata contain at most 255 characters.

source_replica

Uuid

No

If this parameter is specified, the volume is created from a volume replication. Currently, this function is not supported.

consistencygroup_id

Uuid

No

Specifies the ID of the consistency group. If this parameter is specified, the volume belongs to this consistency group. Currently, this function is not supported.

OS-SCH-HNT:scheduler_hints

Dict

No

Specifies the scheduling parameter. Currently, this function is not supported.

shareable

String

No

Extended attribute, which specifies a shareable volume. This field is no longer used. Use native parameter multiattach.

multiattach

Boolean

No

Specifies a shared volume.

NOTE:

Either two of the source_volidsnapshot_id, and imageRef fields are not supported.

  • Description of metadata fields

    Parameter

    Type

    Mandatory

    Description

    __system__encrypted

    string

    No

    Specifies the encryption function in the metadata. The value can be 0 (encryption function disabled) or 1 (encryption function enabled).

    __system__cmkid

    string

    No

    Specifies the cmkid encryption field in the metadata. This field is used together with the __system__encrypted field for encryption.

    hw:passthrough

    string

    No

    • If this parameter is set to trueDevice Type of the EVS disk is SCSI, which allows ECS OSs to directly access underlying storage media. SCSI reservation command is supported.
    • If this parameter is set to falseDevice Type of the EVS disk is VBD, that is, the Virtual Block Device, which supports only simple SCSI read and write commands.
    • If this parameter does not exist, the device type of the EVS disk is VBD by default.
    NOTE:

    If parameter shareable is set to true and parameter hw:passthrough is not specified, shared EVS disks for which Device Type is VBD are created.

    NOTE:
    • If the EVS disk is created from a snapshot, the __system__encrypted and __system__cmkid fields are not supported, and the newly created disk has the same encryption attribute as that of the source EVS disk of the snapshot.
    • If the EVS disk is created from an image, the __system__encrypted and __system__cmkid fields are not supported, and the newly created disk has the same encryption attribute as that of the image.
    • If the EVS disk is created from a snapshot, the hw:passthrough field is not supported, and the newly created disk has the same attribute as that of the source EVS disk of the snapshot.
    • If the EVS disk is created from an image, the hw:passthrough field is not supported, and the device type of newly created disk is VBD.

Response Parameter

Parameter

Type

Mandatory

Description

id

Uuid

Yes

Specifies the volume ID.

links

List(Dict)

Yes

Specifies the volume URI description.

name

String

No

Specifies the volume name.

status

String

Yes

Specifies the volume status.

attachments

List

No

Specifies the volume attachment information.

availability_zone

String

Yes

Specifies the AZ to which the volume belongs.

bootable

String

No

Specifies whether the bootable attribute is enabled.

encrypted

Boolean

No

Specifies whether the volume is encrypted.

created_at

String

Yes

Specifies the date and time when the volume was created.

description

String

No

Specifies the volume description.

volume_type

String

Yes

Specifies the volume type.

replication_status

String

Yes

Specifies the volume replication status.

consistencygroup_id

String

No

Specifies the ID of the consistency group to which the volume belongs.

source_volid

String

No

Specifies the source volume ID.

snapshot_id

String

No

Specifies the snapshot ID.

metadata

Dict

Yes

Specifies the metadata of the volume.

size

Int

Yes

Specifies the size of the volume.

user_id

String

Yes

Specifies the user ID.

updated_at

String

No

Specifies the date and time when the volume was updated.

shareable

Boolean

Yes

Specifies whether the volume is sharable.

multiattach

Boolean

Yes

Specifies whether the volume is sharable.

Request Example

POST https://volume.localdomain.com:8776/v3/5dd0b0056f3d47b6ab4121667d35621a/volumes
{
"OS-SCH-HNT:scheduler_hints": {
"host": "az1.dc1",
"resource_type": "normal"
},
"volume": {
"status": "creating",
"user_id": null,
"name": "openapi_vol01",
"imageRef": "027cf713-45a6-45f0-ac1b-0ccc57ac12e2",
"availability_zone": "eu-de-01",
"description": "create for api test",
"attach_status": "detached",
"volume_type": "SATA",
"metadata": {
"volume_owner": "openapi"
},
"consistencygroup_id": null,
"source_volid": null,
"snapshot_id": null,
"shareable": "false",
"multiattach": false,
"project_id": null,
"source_replica": null,
"size": 40
}
}

Response Example

{
    "volume": {
        "attachments": [],
        "availability_zone": "eu-de-01",
        "bootable": "false",
        "consistencygroup_id": null,
        "created_at": "2016-05-25T02:38:40.392463",
        "description": "create for api test",
        "encrypted": false,
        "id": "8dd7c486-8e9f-49fe-bceb-26aa7e312b66",
        "links": [
            {
                "href": "https://volume.localdomain.com:8776/v2/5dd0b0056f3d47b6ab4121667d35621a/volumes/8dd7c486-8e9f-49fe-bceb-26aa7e312b66",
                "rel": "self"
            },
            {
                "href": "https://volume.localdomain.com:8776/5dd0b0056f3d47b6ab4121667d35621a/volumes/8dd7c486-8e9f-49fe-bceb-26aa7e312b66",
                "rel": "bookmark"
            }
        ],
        "metadata": {
            "volume_owner": "openapi"
        },
        "name": "openapi_vol01",
        "replication_status": "disabled",
        "shareable": false,
        "multiattach": false,
        "size": 40,
        "snapshot_id": null,
        "source_volid": null,
        "status": "creating",
        "updated_at": null,
        "user_id": "39f6696ae23740708d0f358a253c2637",
        "volume_type": "SATA"
    }
}

Error Code

See section Processing Return Code.