• Elastic Volume Service

evs
  1. Help Center
  2. Elastic Volume Service
  3. API Reference
  4. 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}/cloudvolumes

  • 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.

    backup_id

    string

    No

    Specifies the ID of the backup that can be used to create an EVS disk. This parameter is mandatory when you use a backup to create the disk.

    availability_zone

    string

    Yes

    Specifies the AZ where you want to create the disk. If the specified AZ does not exist or is different from the AZ to which the backup belongs, the disk will fail to create.

    NOTE:

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

    description

    string

    No

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

    size

    int

    No

    Specifies the EVS disk size (GB). Its values are as follows:

    System disk: 1 GB to 1024 GB

    Data disk: 10 GB to 32768 GB

    This parameter is mandatory when you create an empty EVS disk or use an image or a snapshot to create an EVS disk. If you use an image or a snapshot to create an EVS disk, the disk size must be greater than or equal to the image or snapshot size.

    This parameter is optional when you use a backup to create an EVS disk. If this parameter is not specified, the disk size is equal to the backup size.

    NOTE:

    If the specified parameter value is a decimal, the integral part of the value is used by default when the request is sent.

    name

    string

    No

    Specifies the EVS disk name.

    • If you create EVS disks in batches, the actual disk names use this parameter value as the prefix, and each disk name has a unique four-digit number starting with a hyphen (-). For example, the disk name can be shan-0001. The value can contain a maximum of 250 bytes.
    • If you create EVS disks one by one, the name value is the EVS disk name. 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.

    imageRef

    string

    No

    Specifies the ID of the image in IMS. If you specify this parameter, the EVS disk is created from an image.

    NOTE:

    BMS system disks cannot be created from BMS images.

    volume_type

    string

    Yes

    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 high performance computing (HPC) and SAP HANA Elastic Cloud Servers (ECSs).

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

    NOTE:
    • When EVS disks are created using backups:

      If the type of the backup's source disk is SSD, SAS, or SATA, you can create disks of any of these types.

      If the type of the backup's source disk is co-p1 or uh-l1, you can create disks of any of the two types.

    • 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.

    count

    int

    No

    Specifies the number of EVS disks to be created in a batch. If this parameter is not specified, only one EVS disk is created. You can create a maximum of 100 EVS disks in a batch.

    If disks are created from a backup, batch creation is not supported, and this parameter must be set to 1.

    NOTE:

    If the specified parameter value is a decimal, the integral part of the value is used by default when the request is sent.

    shareable

    string

    No

    Specifies whether the EVS disk is shareable. The value can be true (specifies a shared disk) or false (specifies a common disk).

    NOTE:

    This field is no longer used. Use multiattach.

    metadata

    map<string, string>

    No

    Specifies the metadata of the created EVS disk. 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. Only the fields listed in this table can be specified when creating a disk.

    NOTE:

    Parameter values under metadata cannot be null.

    multiattach

    boolean

    No

    Specifies the shared EVS disk information. The default value is false.

    tags

    map<string, string>

    No

    Specifies the tags bound to the EVS disk during the disk creation.

    A maximum of 10 tags can be created for an EVS disk.

    Tag keys of a tag must be unique. Deduplication will be performed for duplicate keys. Therefore, only one tag key in the duplicate keys is valid.

    • Tag key: String type
      • Cannot be left blank.
      • Must be unique for each resource.
      • Can contain a maximum of 36 characters.
      • Can contain only digits, letters, hyphens (-), and underscores (_).
    • Tag value: String type
      • Can contain a maximum of 43 characters.
      • Can contain only digits, letters, hyphens (-), and underscores (_).

    enterprise_project_id

    string

    No

    Specifies the enterprise project ID. This ID is bound to the EVS disk during the disk creation.

    Currently, the field is not supported by EVS.

    NOTE:

    Specifying either two of the backup_id, 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 underlying storage media. SCSI reservation command is supported.
    • If this parameter is set to false, the disk device type will be VBD, that is, Virtual Block Device, 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 SCSI disks are created.
      • SCSI EVS disks cannot be created from backups, which means that the hw:passthrough value cannot be true if backup_id has been specified.

    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:

    When creating a disk, you can only specify the fields of metadata listed in the preceding table.

    • 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": {
            "backup_id": null, 
            "count": 1, 
            "availability_zone": "az1.dc1", 
            "description": "test_volume_1", 
            "size": 120, 
            "name": "test_volume_1", 
            "volume_type": "SSD", 
            "metadata": {
                "__system__encrypted": "1", 
                "__system__cmkid": "37b0d52e-c249-40d6-83cb-2b93f22445bd"
            }
        }
    }

Response

  • Parameter description

    Parameter

    Type

    Description

    job_id

    string

    Specifies the task ID.

    NOTE:

    For details about how to query the task status, see Querying Task Status.

    message

    string

    Specifies the returned error message when an error occurs.

    code

    string

    Specifies the returned error code when an error occurs.

    For details about the error code, see Error Codes.

  • Example response
    {
        "job_id": "70a599e0-31e7-49b7-b260-868f441e862b"
    }

    or

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

Returned Values

  • Normal

    200

Error Codes

For details, see Error Codes.