• Elastic Volume Service

evs
  1. Help Center
  2. Elastic Volume Service
  3. API Reference
  4. OpenStack Cinder API v3
  5. EVS Disk
  6. Creating EVS Disks

Creating EVS Disks

Function

This API is used to create one or multiple EVS disks.

URI

  • URI format

    POST /v3/{project_id}/volumes

  • Parameter description

    Parameter

    Mandatory

    Description

    project_id

    Yes

    Specifies the project ID.

Request

  • Parameter description

    Parameter

    Type

    Mandatory

    Description

    volume

    map<string,string>

    Yes

    Specifies the EVS disk to be created.

    availability_zone

    string

    Yes

    Specifies the AZ where you want to create the disk. If the AZ does not exist, the disk will fail to create.

    NOTE:

    For details about how to obtain the AZ, see Querying Information About All AZs.

    source_volid

    string

    No

    Specifies the ID of the source EVS disk. If this parameter is specified, a new EVS disk is cloned from the source EVS disk. Currently, this function is not supported.

    description

    string

    No

    Specifies the EVS disk description. The value can contain a maximum of 255 bytes.

    snapshot_id

    string

    No

    Specifies the ID of a snapshot. If this parameter is specified, the EVS disk is created from the snapshot.

    size

    int

    Yes

    Specifies the EVS disk size, in GB.

    • If the EVS disk is created using an image, the disk size must be greater than or equal to the image size.
    • If the EVS disk is created from a snapshot, the disk size must be greater than or equal to the snapshot size.

    name

    string

    No

    Specifies the EVS disk name. The value can contain a maximum of 255 bytes.

    imageRef

    string

    No

    Specifies the ID of an image. If this parameter is specified, the EVS disk is created from an image.

    NOTE:

    BMS system disks cannot be created from BMS images.

    volume_type

    string

    No

    Specifies the EVS disk type.

    Currently, the value can be SSD, SAS, SATA, co-p1, or uh-l1.
    • SSD: specifies the ultra-high I/O disk type.
    • SAS: specifies the high I/O disk type.
    • SATA: specifies the common I/O disk type.
    • co-p1: specifies the high I/O (performance-optimized I) disk type.
    • uh-l1: specifies the ultra-high I/O (latency-optimized) disk type.

      EVS disks of the co-p1 and uh-l1 types are used exclusively for HPC ECSs and SAP HANA ECSs.

    If the specified EVS disk type is not available in the AZ, the disk will fail to create.

    NOTE:
    • If the EVS disk is created from a snapshot, the volume_type field must be the same as that of the snapshot''''s source disk.

    metadata

    map<string, string>

    No

    Specifies the EVS disk metadata. The length of the key or value in the metadata cannot exceed 255 bytes.

    For details about metadata, see the Parameters in the metadata field table. The table lists some fields. You can also specify other fields based on the disk creation requirements.

    NOTE:

    Parameter values under metadata cannot be null.

    source_replica

    string

    No

    If this parameter is specified, the disk is created from a disk clone. Currently, this function is not supported.

    consistencygroup_id

    string

    No

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

    shareable

    string

    No

    Specifies whether the EVS disk is shareable. The value can be true (sharable) or false (not sharable). This is an extended attribute.

    NOTE:

    This field is no longer used. Use multiattach.

    multiattach

    boolean

    No

    Specifies a shared disk. The default value is false.

    NOTE:

    Specifying either two of the source_volid, snapshot_id, and imageRef fields is not supported.

  • Parameters in the metadata field

    Parameter

    Type

    Mandatory

    Description

    __system__encrypted

    string

    No

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

    If this parameter does not exist, the disk will not be encrypted by default.

    __system__cmkid

    string

    No

    Specifies the parameter that describes the encryption CMK ID in metadata. This parameter is used together with __system__encrypted for encryption. The length of cmkid is fixed at 36 bytes.

    NOTE:

    For details about how to obtain the CMK ID, see section Querying the List of CMKs in the Key Management Service API Reference.

    hw:passthrough

    string

    No

    • If this parameter is set to true, the disk device type will be SCSI, which allows ECS OSs to directly access the underlying storage media and supports SCSI reservation commands.
    • If this parameter is set to false, the disk device type will be VBD, which supports only simple SCSI read/write commands.
    • If this parameter does not exist, the disk device type will be VBD, the default type.
      NOTE:

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

    full_clone

    string

    No

    If the EVS disk is created from a snapshot and linked cloning needs to be used, set this parameter to 0.

    NOTE:

    The preceding table provides only some parameters in metadata for your reference. You can also specify other fields based on the disk creation requirements.

    • 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.
  • Example request
    {
        "volume": {
            "name": "openapi_vol01", 
            "imageRef": "027cf713-45a6-45f0-ac1b-0ccc57ac12e2", 
            "availability_zone": "xxx", 
            "description": "create for api test", 
            "volume_type": "SATA", 
            "metadata": {
                "volume_owner": "openapi"
            }, 
            "consistencygroup_id": null, 
            "source_volid": null, 
            "snapshot_id": null, 
            "multiattach": false, 
            "source_replica": null, 
            "size": 40
        }, 
        "OS-SCH-HNT:scheduler_hints": {
            "dedicated_storage_id": "eddc1a3e-4145-45be-98d7-bf6f65af9767"
        }
    }

Response

  • Parameter description

    Parameter

    Type

    Description

    volume

    map<string, string>

    Specifies the created EVS disk.

    id

    string

    Specifies the EVS disk ID.

    links

    array

    Specifies the URI of the EVS disk.

    name

    string

    Specifies the EVS disk name.

    status

    string

    Specifies the EVS disk status. For details, see EVS Disk Status.

    attachments

    array

    Specifies the attachment information.

    availability_zone

    string

    Specifies the AZ to which the EVS disk belongs.

    bootable

    string

    Specifies whether the EVS disk is bootable.

    encrypted

    boolean

    Specifies whether the disk is encrypted.

    created_at

    string

    Specifies the time when the EVS disk was created.

    description

    string

    Specifies the EVS disk description.

    volume_type

    string

    Specifies the EVS disk type.

    replication_status

    string

    Specifies the disk replication status.

    consistencygroup_id

    string

    Specifies the ID of the consistency group accommodating the EVS disk.

    source_volid

    string

    Specifies the source disk ID.

    snapshot_id

    string

    Specifies the snapshot ID.

    metadata

    map<string, string>

    Specifies the metadata.

    size

    int

    Specifies the EVS disk size.

    user_id

    string

    Reserved

    updated_at

    string

    Specifies the time when the EVS disk information was updated.

    shareable

    boolean

    Specifies whether the EVS disk is shareable.

    multiattach

    boolean

    Specifies whether the EVS disk is shareable.

  • Example response
    {
        "volume": {
            "attachments": [ ], 
            "availability_zone": "xxx", 
            "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", 
            "multiattach": false, 
            "size": 40, 
            "snapshot_id": null, 
            "source_volid": null, 
            "status": "creating", 
            "updated_at": null, 
            "user_id": "39f6696ae23740708d0f358a253c2637", 
            "volume_type": "SATA"
        }
    }

    or

    {
        "error": {
            "message": "XXXX", 
            "code": "XXX"
        }
    }

    In the preceding example, error indicates a general error, for example, badRequest or itemNotFound. An example is provided as follows:

    {
        "badRequest": {
            "message": "XXXX", 
            "code": "XXX"
        }
    }

Returned Values

  • Normal

    202

Error Codes

For details, see Error Codes.