• Elastic Cloud Server

ecs
  1. Help Center
  2. Elastic Cloud Server
  3. API Reference
  4. Extension ECS APIs
  5. Lifecycle Management
  6. Creating ECSs

Creating ECSs

Function Description

This interface is used to create one or more ECSs.

Background for Setting the Login Authentication Mode

Logging in to an ECS can be authenticated using either a key pair or password. For security purposes, you are advised to use key pair authentication.

  • Key pair

    A key pair is used for ECS login authentication.

    Method of calling APIs: Use the key_name field to specify the key file used for logging in to the ECS.

  • Password

    If you choose the initial password for authentication in an ECS, you can log in to an ECS using the username and its initial password. The initial password of user root is used for authentication in Linux, while that of user Administrator is used for authentication in Windows.

    Methods of calling APIs:

    • Method 1 (recommended): Use the adminPass field to specify the initial login password of user Administrator. For details about how to use the adminPass field, see Table 3.
      NOTE:

      In this method, the user_data field is invalid for the Linux ECSs with Cloud-Init installed.

    • Method 2:
      • For Linux ECSs with Cloud-Init installed, use the user_data field to inject data. For details, see Table 3.
      • For Windows ECSs with Cloudbase-Init installed, use admin_pass in the metadata field to inject data. For details, see Table 13.
      • For the ECSs without Cloud-Init or Cloudbase-Init installed, use the adminPass field to inject data. For details, see Table 3.

URI

POST /v1/{project_id}/cloudservers

Table 1 describes the parameters in the URI.
Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

Request

Request parameters

Table 2 describes the request parameters.

Table 2 Request parameters

Parameter

Mandatory

Type

Description

server

Yes

Dict

Specifies the ECS information. For details, see Table 3.

Table 3 Parameters for creating an ECS

Parameter

Mandatory

Type

Description

imageRef

Yes

String

Specifies the ID of the system image used for creating ECSs. The ID is in Universally Unique Identifier (UUID) format.

NOTE:
  • Certain ECS flavors cannot support all public images provided on the public cloud platform. To obtain the images supported by an ECS flavor, log in to the management console, view the images displayed on the Create ECS page, and obtain the image IDs on the Image Management Service page.
  • If the creation fails, modify the parameter settings.

flavorRef

Yes

String

Specifies the ID of the system flavor. For details about the available flavors, see Instances and Application Scenarios in the Elastic Cloud Server User Guide.

name

Yes

String

Specifies the ECS name.

Value requirements:

  • Consists of 1 to 64 characters, including letters, digits, underscores (_), hyphens (-), periods (.).
  • If more than one ECS is to be created (the count value is greater than 1), the system automatically adds a hyphen followed by a four-digit incremental number, such as -0000, to the end of each ECS name. In this case, the ECS name contains a maximum of 59 characters.
    NOTE:

    ECS hostnames comply with RFC952 and RFC1123 naming rules. It is recommended that you configure hostnames using digits, letters (case sensitive), and hyphens (-). Underscores (_) are converted into hyphens (-) by default.

user_data

No

String

Specifies the user data to be injected during the ECS creation process. Text, text files, and gzip files can be injected.

Constraints:

  • The content to be injected must be encoded with base64. The maximum size of the content to be injected (before encoding) is 32 KB.
  • If key_name is not specified, the data injected by user_data is the password of user root for logging in to the ECS by default.
  • This parameter can be used to inject the user-defined initial password for user root when you create a Linux ECS using password authentication. For details, see Background for Setting the Login Authentication Mode.
Password complexity requirements:
  • Consists of 8 to 26 characters.
  • Contains at least three of the following character types: uppercase letters, lowercase letters, numerals, and special characters !@$%^-_=+[{}]:,./?.

adminPass

No

String

Specifies the initial login password of the administrator account for logging in to an ECS using password authentication. The Linux administrator is root, and the Windows administrator is Administrator. For details, see Background for Setting the Login Authentication Mode.

Password complexity requirements:
  • Consists of 8 to 26 characters.
  • The password must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters (!@$%^-_=+[{}]:,./?).
  • The password cannot contain the username or the username in reverse.
  • The Windows ECS password cannot contain the username, the username in reverse, or more than two consecutive characters in the username.

key_name

No

String

Specifies the name of the SSH key used for logging in to the ECS.

vpcid

Yes

String

Specifies the ID of the VPC to which the ECS belongs. The value is in the format of the UUID.

nics

Yes

List data structure

Specifies the NIC information of the ECS. For details, see Table 4.

Constraints:

  • The network of the NIC must belong to the VPC specified by vpcid.
  • A maximum of 12 NICs can be attached to an ECS.

publicip

No

Dictionary data structure

Specifies the elastic IP address of the ECS. The elastic IP address can be configured in the following three ways:

  • Not configured (delete this field)
  • Automatically assigned. You need to specify the information about the new elastic IP address.
  • Use existing one. You need to specify the information about the elastic IP address that has been created.

For details, see Table 5.

count

No

Integer

Specifies the number of ECSs to be created.

Constraints:

  • If this parameter is not specified, the default value is 1.
  • If the quota is sufficient, the maximum value is 500.

root_volume

Yes

Dictionary data structure

Specifies ECS system disk configurations.

For details, see Table 6.

data_volumes

No

List data structure

Specifies the configuration of the ECS's data disks. Each data structure represents a data disk to be created.

Constraints: Currently, a maximum of 23 data disks can be attached to a new ECS.

For details, see Table 7.

security_groups

No

List data structure

Specifies the security groups of the ECS.

Constraints: If this parameter is left blank, the default security group is bound to the ECS by default.

For details, see Table 8.

availability_zone

Yes

String

Specifies the name of the AZ where the ECS is located.

extendparam

No

Dictionary data structure

Provides the supplementary information about the ECS to be created.

For details, see Table 12.

metadata

No

Dictionary data structure

Specifies the metadata of ECS to be created.

This parameter is mandatory when a Windows ECS with password authentication is created. For details, see Table 13.

NOTE:

This field does not allow users to write data. It is mandatory when the ECS is to be created using a Windows image.

os:scheduler_hints

No

Dictionary data structure

Specifies ECS scheduling.

For details, see Table 14.

tags

No

List data structure

Specifies the tags of an ECS.

A tag is in the format of "key.value", where the maximum lengths of key and value are 36 and 43 characters, respectively.

When adding a tag to an ECS, ensure that the tag complies with the following requirements:

  • The key of the tag can contain only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-).
  • The value of the tag can contain only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-).
NOTE:
  • When you create ECSs, one ECS supports up to 10 tags.

description

No

String

Specifies the description of an ECS, which is a null string by default.

  • Can contain a maximum of 85 characters.
  • Cannot contain special characters, such as < and >.
Table 4 nics field description

Parameter

Mandatory

Type

Description

subnet_id

Yes

String

Specifies the NIC information of the ECS.

The value must be the ID of the network created in the VPC specified by vpcid and in the format of the UUID.

ip_address

No

String

Specifies the IP address of the NIC used by the ECS. The value is an IPv4 address.

Constraints:

  • If this parameter is left blank or set to "", an unused IP address in the subnet of this network is automatically assigned as the IP address of the NIC.
  • If this parameter is specified, its value must be an unused IP address in the network segment of the subnet in this network.

binding:profile

No

Dictionary data structure

Allows you to customize data. Configure this parameter when creating a HANA ECS.

For details, see Table 15.

extra_dhcp_opts

No

List data structure

Indicates extended DHCP options.

For details, see Table 16.

Table 5 publicip field description

Parameter

Mandatory

Type

Description

id

No

String

Specifies the ID of the elastic IP address assigned to the ECS to be created. The value is in UUID format.

Constraints: Only elastic IP addresses in the DOWN state can be assigned.

eip

No

Dictionary data structure

Specifies the configuration parameter for creating an elastic IP address that will be automatically assigned to the ECS.

For details, see Table 9.

NOTE:

You can configure either but not both of id and eip in the publicip field.

Table 6 root_volume field description

Parameter

Mandatory

Type

Description

volumetype

Yes

String

Specifies the ECS system disk type. The disk type must match the available disk type.

  • SATA: common I/O disk type
  • SAS: high I/O disk type
  • SSD: ultra-high I/O disk type
  • co-p1: high I/O (performance-optimized I) disk type
  • uh-l1: ultra-high I/O (latency-optimized) disk type
NOTE:

For HANA, HL1, and HL2 ECSs, use co-p1 and uh-l1 disks. For other ECSs, do not use co-p1 or uh-l1 disks.

size

No

Integer

Specifies the system disk size, in GB. The value range is 1 to 1024.

Constraints:

  • The system disk size must be greater than or equal to the minimum system disk size supported by the image (min_disk attribute of the image).
  • If this parameter is not specified or is set to 0, the default system disk size is the minimum value of the system disk in the image (min_disk attribute of the image).
    NOTE:

    To obtain the minimum system disk size (min_disk) of an image, click the image on the management console for its details. Alternatively, call the native OpenStack API for querying details about an image. For details, see section "Querying Image Details (Native OpenStack)" in Image Management Service API Reference.

Table 7 data_volumes field description

Parameter

Mandatory

Type

Description

volumetype

Yes

String

Specifies the disk type of the ECS data disk. The disk type must be matched with the system disk type.

Enumerated values of the disk type:

  • SATA: common I/O disk type
  • SAS: high I/O disk type
  • SSD: ultra-high I/O disk type
  • co-p1: high I/O (performance-optimized I) disk type
  • uh-l1: ultra-high I/O (latency-optimized) disk type
NOTE:

For HANA, HL1, and HL2 ECSs, use co-p1 and uh-l1 disks. For other ECSs, do not use co-p1 or uh-l1 disks.

size

Yes

Integer

Specifies the data disk size, in GB. The value range is 10 to 32768.

shareable

No

Boolean

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

NOTE:

This field has been deprecated. Use multiattach.

multiattach

No

Boolean

Specifies the shared disk information.

  • true: indicates that the created disk is a shared disk.
  • false: indicates that the created disk is a common EVS disk.
NOTE:

The shareable field is not used any more. If both shareable and multiattach must be used, ensure that the values of the two fields are the same. If this parameter is not specified, common EVS disks are created by default.

hw:passthrough

No

Boolean

Indicates whether the data volume uses a SCSI lock.

If yes, set the field value to true. Otherwise, do not fill in this field.

NOTE:

This parameter is of boolean type. If a non-boolean character is imported, the parameter value is set to false.

Table 8 security_groups field description

Parameter

Mandatory

Type

Description

id

No

String

Specifies the ID of the security group to which an ECS is to be added. The configuration will take effect on the NICs of the ECS. The ID of an existing security group in UUID format must be specified. If this parameter is left blank, the system will not create a security group.

Table 9 eip field description

Parameter

Mandatory

Type

Description

iptype

Yes

String

Specifies the elastic IP address type.

Enumerated value of the IP address type: 5_bgp (indicates dynamic BGP)

bandwidth

Yes

Dictionary data structure

Specifies the bandwidth of the elastic IP address.

For details, see Table 10.

Table 10 bandwidth field description

Parameter

Mandatory

Type

Description

size

Yes

Integer

Specifies the bandwidth (Mbit/s). The value range is 1 to 1000.

sharetype

Yes

String

Specifies the bandwidth sharing type.

Enumerated values: PER (indicates exclusive bandwidth) and WHOLE (indicates sharing)

chargemode

Yes

String

Specifies the bandwidth billing mode.

  • If the field value is traffic, the ECS service is billed by traffic.
  • If the field value is others, the ECS creation will fail.
Table 11 extendparam field description for creating disks

Parameter

Mandatory

Type

Description

snapshotId

No

String

Specifies the snapshot ID or ID of the original data disk contained in the full-ECS image.

Application scenarios:

This parameter is used if an ECS is created using a full-ECS image, and the image contains one or more data disks.

Intended usage:

When an ECS is created using a full-ECS image, the system automatically restores data from the data disk (if any) in the image. However, the disk type will be restored to the default settings: common I/O, VBD, and non-shared. The snapshotID parameter allows you to specify the disk type for the original data disk after restoration.

NOTE:
  • You are advised to set snapshotID for each original data disk. Otherwise, the original data disks without snapshotID specified will use the default settings.
  • If you are required to change a disk size, ensure that the changed disk size is greater than or equal to the size of the original data disk. Otherwise, restoring data of the original data disk will fail.

Working rules:

snapshotId uniquely identifies an original data disk contained in a full-ECS image. You can use snapshotId to obtain the information of the original data disk for data restoration.

To obtain a snapshot ID, do as follows:

Log in to the management console, choose Elastic Volume Service > Snapshot. Then, use the name of the original data disk to find the snapshot ID.

Usage:

See Example 2.

Table 12 extendparam field description for creating ECSs

Parameter

Mandatory

Type

Description

regionID

No

String

Specifies the ID of the region where the ECS resides.

support_auto_recovery

No

Boolean

Specifies whether automatic recovery is enabled on the ECS.

  • true: enables this function.
  • false: disables this function.
NOTE:

This parameter is of boolean type. If a non-boolean character is imported, the parameter value is set to false.

Table 13 metadata field description

Parameter

Mandatory

Type

Description

admin_pass

No

String

Specifies the password of user Administrator for logging in to a Windows ECS. For details, see Background for Setting the Login Authentication Mode.

Example: cloud.1234

NOTE:

This parameter is mandatory when a Windows ECS with password authentication is created.

Table 14 os:scheduler_hints field description

Parameter

Mandatory

Type

Description

group

No

String

Specifies an ECS group ID, which is in UUID format.

Obtain the parameter value from the console or by performing operations provided in section Querying ECS Groups.

tenancy

No

String

Creates ECSs on a dedicated or shared host.

The value of this parameter can be dedicated or shared.

dedicated_host_id

No

String

Specifies the dedicated host ID.

NOTE:

A DeH ID takes effect only when tenancy is set to dedicated.

Table 15 binding:profile field description

Parameter

Mandatory

Type

Description

disable_security_groups

No

Boolean

Indicates that a HANA ECS NIC is not added to a security group.

NOTE:
  • A primary HANA ECS NIC must be added to a security group.
  • At most one HANA ECS NIC is allowed not to add to any security group.
Table 16 extra_dhcp_opts field description

Parameter

Mandatory

Type

Description

opt_value

Yes

Int

Specifies the NIC MTU, which ranges from 1280 to 8888.

opt_name

Yes

String

Set the parameter value to 26.

Response

See Responses (Task).

Example 1

The public cloud platform provides various ECS types. The flavor name/ID varies depending on ECS types and specifications. When you use APIs to create ECSs with different specifications, the request bodies are the same. You only need to change the parameter values in the following request example based on the parameters described in Request.

An ECS with flavor ID m1.larger is to be created, where the image ID is  imageid_123, disk type is  SATA, and VPC ID is  0dae26c9-9a70-4392-93f3-87d53115d171. The request example is as follows:
{
    "server": {
        "availability_zone": "az1.dc1", 
        "name": "newserver", 
        "imageRef": "imageid_123", 
        "root_volume": {
            "volumetype": "SATA"
        }, 
        "data_volumes": [
            {
                "volumetype": "SATA", 
                "size": 100
            }, 
            {
                "volumetype": "SSD", 
                "size": 100,
                "multiattach": true,
                "hw:passthrough": "true"
            }
        ], 
        "flavorRef": "m1.larger", 
        "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", 
        "security_groups": [
            {
                "id": "507ca48f-814c-4293-8706-300564d54620"
            }
        ], 
        "nics": [
            {
                "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83", 
                "extra_dhcp_opts":[
                     {
                           "opt_value": 8888, 
                           "opt_name": "26",
                     }
                ]
            }
        ], 
        "publicip": {
            "id": "publicip_123", 
            "eip": {
                "iptype": "5_bgp",
                "bandwidth": {
                    "size": 10, 
                    "sharetype": "PER"
            }
            }
        }, 
        "key_name": "sshkey-123", 
        "count": 1, 
        "extendparam": { 
            "regionID": "region_001",
            
        }
    }
}

Example 2

An ECS is to be created using a full-ECS image, in which two data disks are contained. The disk settings of the newly created ECS are as follows:

  • For the two data disks to be restored, one uses default settings, and the other uses the changed settings, SATA, 100 GB.
  • In addition to the two data disks to be restored, a new data disk is to be attached to the ECS, and the settings of the disk are SSD, 50 GB.

The request example is as follows:

{
    "server": {
        "availability_zone": "az1.dc1", 
        "name": "wholeImageServer", 
        "imageRef": "ff49b1f1-3e3e-4913-89c6-a026041661e8", 
        "root_volume": {
            "volumetype": "SATA"
        }, 
        "data_volumes": [
            {
                "volumetype": "SATA", 
                "size": 100,
                "extendparam":{
                    "snapshotId": "ef020653-9742-4d24-8672-10af42c9702b"
                }
            }, 
            {
                "volumetype": "SSD", 
                "size": 50
            }
        ], 
        "flavorRef": "s2.large.2", 
        "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", 
        "security_groups": [
            {
                "id": "507ca48f-814c-4293-8706-300564d54620"
            }
        ], 
        "nics": [
            {
                "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83",
            }
        ],
        "key_name": "sshkey-123"
    }
}

Returned Values

See General Request Returned Values.

Error Code

See Error Code Description.