Help Center> Elastic Cloud Server> API Reference> APIs (Recommended)> Lifecycle Management> Creating ECSs
View PDF

Creating ECSs

Function

This API is used to create one or more ECSs.

The V1.1 API supports all functions (see Creating an ECS (Pay-per-Use)) provided by the V1 API. Additionally, the V1.1 API supports the creation of yearly/monthly ECSs.

This is an asynchronous API. After the ECS creation request is issued, the system will return job_id. The ECS creation is still in progress. Therefore, you need to call the API described in Querying Task Execution Status to obtain the task status. When the status changes to SUCCESS, the ECS has been created.

Logging in to an ECS can be authenticated using either a key pair or password. The login using a key pair is more secure than using a password. Therefore, key pair authentication is recommended.
  • 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. For details, see Table 2.

  • Password

    If you choose the initial password for authentication in an ECS, you can log in to the 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.

    Method of calling APIs: Use the adminPass field to specify the initial login password of the administrator account. For details about how to use the adminPass field, see Table 2. If an encrypted password is required for logging in to a Linux ECS that is created using an image with Cloud-Init installed, you can use the user_data field to inject the password. For details, see Table 2.

    If the user_data field is specified for a Linux ECS that is created using an image with Cloud-Init installed, the adminPass field becomes invalid.

  • Image password

    If you use a Linux private image to create an ECS, you can use the image password for login authentication.

    Method of calling APIs: If the image password is used, the key_name and adminPass fields do not need to be specified.

Constraints

  • Ensure that your account has sufficient balance because this API does not support coupons. If the account balance is insufficient, a pending order will be generated.
  • After creating a yearly/monthly ECS, pay for it by following the instructions provided in Paying for the Order of Yearly/Monthly Resources.
  • If you want to use coupons to pay, set isAutoPay in the request to false, and pay for the order on the official website using the coupon or following the instructions provided in Paying for the Order of Yearly/Monthly Resources.
  • If you need to view resource provisioning details in your order, see Querying Resource Provisioning Details in an Order.
  • If you need to unsubscribe from a yearly/monthly resource, see Unsubscribing from Year/Monthly Resources.

URI

  • URI format

    POST /v1.1/{project_id}/cloudservers

  • Parameter description

    Parameter

    Mandatory

    Description

    project_id

    Yes

    Specifies the project ID.

    For details about how to obtain the ID, see Obtaining a Project ID.

Request

Table 1 Request parameters

Parameter

Mandatory

Type

Description

server

Yes

Object

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

dry_run

No

Boolean

Specifies whether to check the request and create the ECS.

  • true: indicates that only the request is sent, but the ECS will not be created. Check items include mandatory parameters and request format.
    • If the check fails, the system returns an error.
    • If the check is successful, the system returns status code 202.
  • false: indicates that the request is sent and the ECS will be created if the check result is as expected.
Table 2 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.

You can obtain the image ID from the console or by following the instructions provided in "Querying Images" in Image Management Service API Reference.

flavorRef

Yes

String

Specifies the flavor ID of the ECS to be created.

For details about the flavors that have been released, see Instances in Elastic Cloud Server Service Overview.

name

Yes

String

Specifies the ECS name.

If the number (count) of ECSs to be created is 1, the ECS name consists of 1 to 64 characters, including letters, digits, underscores (_), hyphens (-), and periods (.)

If more than one ECS is to be created (the count value is greater than 1), the system supports automatic and customizable ECS naming.

For details, see How Can I Set Sequential ECS Names When Creating Multiple ECSs?

A name must comply with the following rules:

  • The parameter value 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. If you specify a number, the name of the first new ECS will start from the specified number. 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. Text and text files can be injected.

NOTE:
  • The content of user_data must be encoded with base64.
  • The maximum size of the content to be injected (before encoding) is 32 KB.

For more information about the user data to be injected, see Injecting User Data into ECSs in Elastic Cloud Server User Guide.

Examples

Before base64 encoding:

  • Linux 
    #! /bin/bash
echo user_test >> /home/user.txt
  • Windows 
    rem cmd
echo 111 > c:\aaa.txt

After base64 encoding:

  • Linux 
    IyEgL2Jpbi9iYXNoDQplY2hvIHVzZXJfdGVzdCAmZ3Q7Jmd0OyAvaG9tZS91c2VyLnR4dA==
  • Windows 
    cmVtIGNtZA0KZWNobyAxMTEgJmd0OyBjOlxhYWEudHh0

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.

Password complexity requirements:
  • Consists of 8 to 26 characters.
  • Contains at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters (!@$%^-_=+[{}]:,./?).
  • 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.

Keys can be created using the key creating API (Creating and Importing an SSH Key Pair) or obtained using the SSH key query API (Querying SSH Key Pairs).

Note:

If chargeMode in the extendparam parameter of a created ECS is set to prePaid, which indicates that the ECS is billed in yearly/monthly payments, the key_name parameter must be used with the metadata parameter. For details, see metadata Field Description for Creating ECSs and example request 1.

vpcid

Yes

String

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

You can obtain the VPC ID from the management console or by following the instructions provided in Querying VPCs in Virtual Private Cloud API Reference.

nics

Yes

Array of objects

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

Note:

  • The network of the primary NIC must belong to the VPC specified by vpcid. When you create NICs, the first NIC specified is the primary NIC.
  • A maximum of 12 NICs can be attached to an ECS by default.
  • The maximum number of NICs varies depending on ECS specifications. For details, see ECS Specifications.

publicip

No

Object

Specifies the EIP bound to the ECS, which can be configured in one of the following ways:

  • Do not use: In such a case, this field is unavailable.
  • Automatically assign an EIP. You need to specify the EIP.
  • Use existing one. You need to specify an existing EIP.

For details, see publicip Field Description.

count

No

Integer

Specifies the number of ECSs to be created.

Note:

  • If this parameter is not specified, the default value is 1.
  • If chargingMode in the extendparam parameter is set to postPaid, the ECS is billed in pay-per-use payments, and a tenant can create a maximum of 500 ECSs.
  • If chargingMode in the extendparam parameter is set to prePaid, the ECS is billed in yearly/monthly payments, and a tenant can create a maximum of 100 ECSs. A maximum of 400 resources can be purchased at a time. For example, a purchased ECS includes mandatory resources, such as one cloud server and one system disk, and other optional resources, such as data disks, EIP, and bandwidth. All of these are included in 400 resources. The system will report an error when the number of resources exceeds 400.

isAutoRename

No

Boolean

Specifies whether ECS names can be duplicated. The default value is False. This parameter takes effect when the count value is greater than 1.

  • True: indicates that the names can be duplicated.
  • False: indicates that the names cannot be duplicated.

root_volume

Yes

Object

Specifies ECS system disk configurations.

The system disk and data disk created during the creation of a yearly/monthly ECS are also in yearly/monthly payments, and the period of the disks is the same as that of the ECS.

For details, see Table 4.

data_volumes

No

Array of objects

Specifies ECS data disk configurations. Each data structure represents a data disk to be created.

An ECS can be attached with a maximum of 59 data disks (certain flavors support only 23 data disks).

For details, see Table 5.

security_groups

No

Array of objects

Specifies ECS security groups.

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

For details, see security_groups Field Description.

availability_zone

Yes

String

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

See Regions and Endpoints.

extendparam

No

Object

Specifies the ECS supplementary information.

For details, see Table 9.

metadata

No

Object

Specifies the ECS metadata.

You can use metadata to customize key-value pairs.

NOTE:
  • A maximum of 10 key-value pairs can be injected.
  • A metadata key consists of 1 to 255 characters and contains only uppercase letters, lowercase letters, digits, hyphens (-), underscores (_), colons (:), and decimal points (.).
  • A metadata value consists of a maximum of 255 characters.

For details about reserved key-value pairs, see Table 11.

os:scheduler_hints

No

Object

Schedules ECSs, for example, by configuring an ECS group.

For details, see Table 12.

tags

No

Array of strings

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 (_), hyphens (-), and periods (.).
NOTE:
  • When you create ECSs, one ECS supports up to 10 tags.
  • The functions of the server_tags field newly added to the public cloud are the same as those of the tags field, but the former supports more keys and values. Therefore, the server_tags field is recommended.

server_tags

No

Array of objects

Specifies the tags of an ECS. For details, see server_tags Field Description.

NOTE:
  • When you create ECSs, one ECS supports up to 10 tags.
  • The functions of the server_tags field newly added to the public cloud are the same as those of the tags field, but the former supports more keys and values. Therefore, the server_tags field is recommended.

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 an angle bracket < or >.
Table 3 nics field description

Parameter

Mandatory

Type

Description

subnet_id

Yes

String

Specifies the subnet of the ECS.

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

You can obtain the parameter value by calling a VPC API for Querying Subnet Details.

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

ipv6_enable

No

Boolean

Indicates whether to support IPv6 addresses.

If this parameter is set to true, the NIC supports IPv6 addresses.

ipv6_bandwidth

No

Object

Specifies the bound shared bandwidth. For details, see ipv6_bandwidth Field Description.
Table 4 root_volume field description

Parameter

Mandatory

Type

Description

volumetype

Yes

String

Specifies the ECS system disk type, which must be one of available disk types.

Currently, the value can be SSD, GPSSD, or SAS.
  • SSD: specifies the ultra-high I/O disk type.
  • GPSSD: specifies the general purpose SSD disk type.
  • SAS: specifies the high I/O disk type.

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

NOTE:

size

No

Integer

Specifies the system disk size, in GB. The value ranges from 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 "Querying Image Details (Native OpenStack)" in Image Management Service API Reference.

extendparam

No

Object

Provides the disk information.

For details, see extendparam Field Description for Creating Disks.

cluster_type

No

String

Specifies the storage type of an ECS system disk.

Enumerated values of the storage type:

  • DSS: dedicated storage type.

cluster_id

No

String

Specifies the ID of the storage pool used by an ECS system disk.

hw:passthrough

No

Boolean

Pay attention to this parameter if your ECS is SDI-compliant. If the value of this parameter is true, the created disk is of SCSI type.

NOTE:

This parameter is of boolean type. If a non-boolean character is imported, the parameter value is set to false.
Table 5 data_volumes field description

Parameter

Mandatory

Type

Description

volumetype

Yes

String

Specifies the type of the ECS data disk, which must be one of available disk types.

Currently, the value can be SSD, GPSSD, or SAS.
  • SSD: specifies the ultra-high I/O disk type.
  • GPSSD: specifies the general purpose SSD disk type.
  • SAS: specifies the high I/O disk type.

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

NOTE:

size

Yes

Integer

Specifies the data disk size, in GB. The value ranges from 10 to 32768.

When you use a data disk image to create a data disk, ensure that the value of this parameter is greater than or equal to the size of the source data disk that is used to create the data disk image.

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 discarded. 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 this parameter is set to true, the disk device type is SCSI, which allows ECS OSs to directly access the underlying storage media. SCSI reservation commands are supported.
  • If this parameter is set to false, the disk device type is VBD, which supports only simple SCSI read/write commands.
  • If this parameter does not appear, the disk device type is VBD.
NOTE:

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

extendparam

No

Object

Provides the disk information.

For details, see Table 7.

cluster_type

No

String

Specifies the storage type of an ECS data disk.

Enumerated values of the storage type:

  • DSS: dedicated storage type.

cluster_id

No

String

Specifies the ID of the storage pool used by an ECS data disk.

data_image_id

No

String

Specifies ID of the data image. The value is in UUID format.

If data disks are created using a data disk image, this parameter is mandatory and it does not support metadata.

metadata

No

Object

Specifies the EVS disk metadata. Ensure that key and value in the metadata contain at most 255 bytes.

This field is used only when an encrypted disk is created.

If data disks are created using a data disk image, this field cannot be used.

For details, see metadata Field Description for Creating Disks.

Response

Table 6 Response parameters

Parameter

Type

Description

job_id

String

Specifies the returned task ID after delivering the task. You can query the task progress using this ID. For details how to query the execution status of the task based on the task ID, see Task Status Management.

order_id

String

Specifies the order ID. This parameter is returned for the creation of a yearly/monthly ECS.

NOTE:

    If you need to view resource provisioning details in your order, see Querying Resource Provisioning Details in an Order.

serverIds

Array of strings

Specifies ECS IDs.

NOTE:

The details about an ECS are obtained by ECS ID. If the system returns a 404 error, the ECS is being created, or creating the ECS failed.

For details about abnormal responses, see Responses (Task).

Example Request

  • Example URL request 
    POST https://{endpoint}/v1.1/{project_id}/cloudservers
  • Example request 1 (creating a yearly/monthly ECS that is logged in using a key pair) 
    {
    "server": {
        "availability_zone":"az1-dc1", //AZ name
        "name": "newserver", 
        "imageRef": "5ef3a512-1c65-418e-8764-a4413c2f9277", 
        "root_volume": {
            "volumetype": "SSD"
        }, 
        "data_volumes": [
            {
                "volumetype": "SSD", 
                "size": 100
            }, 
            {
                "volumetype": "SSD", 
                "size": 100,
                "multiattach": true,
                "hw:passthrough": true
            }
        ], 
        "flavorRef": "s2.small.1", 
        "vpcid": "2a6f4aa6-d93e-45f5-a8cb-b030dbf8cd68", 
        "security_groups": [
            {
                "id": "6242ef48-4d35-49c8-8711-a6e54902e44a"
            }
        ], 
        "nics": [
            {
                "subnet_id": "ef039b60-6a14-42d1-963b-687b627fea08"
            }
        ], 
        "publicip": {
            "eip": {
                "iptype": "5_sbgp",
                "bandwidth": {
                    "size": 1, 
                    "sharetype": "PER"
                }
            }
        }, 
        "key_name": "id_rsa", 
        "count": 1, 
        "metadata": {
            "op_svc_userid": "f79791beca3c48159ac2553fff22e166"
        },
        "extendparam": { 
            "chargingMode": "prePaid",
            "periodType": "month",
            "periodNum": 1,
            "isAutoRenew": "true",
            "isAutoPay": "true",
            "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb"
        },
        "os:scheduler_hints": {
          "group": "cdbbfffe-ef18-47b4-a5c8-f61a984c0ecc"
        }
        
    }
}
  • Example request 2 (creating a yearly/monthly ECS that is logged in using a password) 
    {
    "server": {
        "availability_zone":"az1-dc1", //AZ name
        "name": "newserver",
        "adminPass": "P@ssw0rd123",
        "imageRef": "9b04ad7e-6d97-40bf-9d62-57873382eab0",
        "root_volume": {
            "volumetype": "SSD"
        },
        "data_volumes": [
            {
                "volumetype": "SSD",
                "size": 100
            },
            {
                "volumetype": "SSD",
                "size": 100,
                "multiattach": true,
                "hw:passthrough": true
            }
        ],
        "flavorRef": "s2.small.1",
        "vpcid": "2a6f4aa6-d93e-45f5-a8cb-b030dbf8cd68",
        "security_groups": [
            {
                "id": "6242ef48-4d35-49c8-8711-a6e54902e44a"
            }
        ],
        "nics": [
            {
                "subnet_id": "ef039b60-6a14-42d1-963b-687b627fea08"
            }
        ],
        "publicip": {
            "eip": {
                "iptype": "5_sbgp",
                "bandwidth": {
                    "size": 1,
                    "sharetype": "PER"
                }
            }
        },
        "key_name": "",
        "count": 1,
        "metadata": {},
        "extendparam": {
            "chargingMode": "prePaid",
            "periodType": "month",
            "periodNum": 1,
            "isAutoRenew": "true",
            "isAutoPay": "true",
            "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb"
        },
        "os:scheduler_hints": {
            "group": "cdbbfffe-ef18-47b4-a5c8-f61a984c0ecc"
        }
    }
}
  • Example request 3 (creating a yearly/monthly ECS with a pay-per-use EIP bound) 
    {
    "server": {
        "availability_zone":"az1-dc1", //AZ name
        "name": "newserver", 
        "imageRef": "5ef3a512-1c65-418e-8764-a4413c2f9277", 
        "root_volume": {
            "volumetype": "SSD"
        }, 
        "data_volumes": [
            {
                "volumetype": "SSD", 
                "size": 100
            }, 
            {
                "volumetype": "SSD", 
                "size": 100,
                "multiattach": true,
                "hw:passthrough": true
            }
        ], 
        "flavorRef": "s2.small.1", 
        "vpcid": "2a6f4aa6-d93e-45f5-a8cb-b030dbf8cd68", 
        "security_groups": [
            {
                "id": "6242ef48-4d35-49c8-8711-a6e54902e44a"
            }
        ], 
        "nics": [
            {
                "subnet_id": "ef039b60-6a14-42d1-963b-687b627fea08"
            }
        ], 
        "publicip": {
            "eip": {
                "iptype": "5_sbgp",
                "bandwidth": {
                    "size": 1, 
                    "sharetype": "PER",
                    "chargemode": "traffic"
                },
                "extendparam": {
                    "chargingMode": "postPaid"
                }
            }
        }, 
        "key_name": "id_rsa", 
        "count": 1, 
        "metadata": {
            "op_svc_userid": "f79791beca3c48159ac2553fff22e166"
        },
        "extendparam": { 
            "chargingMode": "prePaid",
            "periodType": "month",
            "periodNum": 1,
            "isAutoRenew": "true",
            "isAutoPay": "true",
            "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb"
        },
        "os:scheduler_hints": {
          "group": "cdbbfffe-ef18-47b4-a5c8-f61a984c0ecc"
        }
    }
}
  • Example request 4 (creating a yearly/monthly ECS with an EIP using a shared bandwidth bound) 
    {
    "server": {
        "availability_zone":"az1-dc1", //AZ name
        "name": "newserver", 
        "imageRef": "5ef3a512-1c65-418e-8764-a4413c2f9277", 
        "root_volume": {
            "volumetype": "SSD"
        }, 
        "data_volumes": [
            {
                "volumetype": "SSD", 
                "size": 100
            }, 
            {
                "volumetype": "SSD", 
                "size": 100,
                "multiattach": true,
                "hw:passthrough": true
            }
        ], 
        "flavorRef": "s2.small.1", 
        "vpcid": "2a6f4aa6-d93e-45f5-a8cb-b030dbf8cd68", 
        "security_groups": [
            {
                "id": "6242ef48-4d35-49c8-8711-a6e54902e44a"
            }
        ], 
        "nics": [
            {
                "subnet_id": "ef039b60-6a14-42d1-963b-687b627fea08"
            }
        ], 
        "publicip": {
            "eip": {
                "iptype": "5_sbgp",
                "bandwidth": {
                    "id": "a0d4b26f-699d-49a0-bcc8-6f707a925abf",
                    "sharetype": "WHOLE"
                }
            }
        }, 
        "key_name": "id_rsa", 
        "count": 1, 
        "metadata": {
            "op_svc_userid": "f79791beca3c48159ac2553fff22e166",
            "agency_name": "test"
        },
        "extendparam": { 
            "chargingMode": "prePaid",
            "periodType": "month",
            "periodNum": 1,
            "isAutoRenew": "true",
            "isAutoPay": "true",
            "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb"
        },
        "os:scheduler_hints": {
          "group": "cdbbfffe-ef18-47b4-a5c8-f61a984c0ecc"
        }
    }
}
  • Example request 6 (pre-verification request body) 
    {
    "dry_run": true
    "server": {
        "availability_zone":"az1-dc1", 
        "name": "server", 
        "imageRef": "ff49b1f1-3e3e-4913-89c6-a026041661e8", 
        "root_volume": {
            "volumetype": "SSD"
        }, 
        "data_volumes": [], 
        "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"
    }
}

Example Response

{
    "job_id": "ff808082739334d80173943ec9b42130",
    "order_id": "CS2007281506xxxxx",
    "serverIds": [
        "fe0528f0-5b1c-4c8c-9adf-e5d5047b8c17",
        "679854ae-a50d-40c9-8132-b19bf3a306a1"
    ] 
}

Or

{
    "error": {
        "code": "Ecs.0005", 
        "message": "request body is illegal."
    }
}

Or

{
    "error": {
        "message": "privateIp [%s] is not in this subnet [%s]",
        "code": "Ecs.0005",
        "details": [
            {
                "code": "Ecs.0039"
            }
        ]
    }
}

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Code Description.

Parent topic: Lifecycle Management