Creating an ECS
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 API is an asynchronous API. After the creation request is successfully delivered, a job ID is returned. This does not mean the creation is complete. You need to call the API by referring to Querying Task Execution Status to query the job status. The SUCCESS status indicates that the creation is successful.
This API allows you to set the X-Client-Token request header in the HTTP request header to ensure the request idempotence. For details, see Idempotent Requests.
![](https://support.huaweicloud.com/intl/en-us/api-ecs/public_sys-resources/note_3.0-en-us.png)
Huawei Cloud no longer provides Windows images. This API cannot be used to create ECSs using Windows images, including public Windows images, private Windows images, shared Windows images, and Marketplace Windows images.
- 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
- When creating a yearly/monthly ECS, you can pay for it automatically or manually.
- If isAutoPay in the request is set to true, automatic payments are used. The system automatically pays for order using the supported payment methods.
- Discounts and cash coupons can be used in the following sequence:
Discounts (only one at a time) > Cash coupons (only one at a time) > Account balance (first cash balance and then available credit) or monthly settlement
- If the preceding payment methods cannot be used to accomplish the payment, the system automatically generates an unpaid order. You need to manually select a payment method on the console and pay for the order.
For details, see Automatic Payments.
- Discounts and cash coupons can be used in the following sequence:
- If isAutoPay in the request is set to false, manual payments are used. The system generates an unpaid order. You need to manually select a payment method on the console and pay for the order.
- If isAutoPay in the request is set to true, automatic payments are used. The system automatically pays for order using the supported payment methods.
- When you create a pay-per-use ECS, the system automatically uses available cash coupons.
- If you want to unsubscribe from yearly/monthly resources, see Unsubscribing from Yearly/Monthly Resources.
URI
- URI format
- 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
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. The default value is false.
|
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 "ECS Specifications and Types" in Elastic Cloud Server User Guide. |
name |
Yes |
String |
Specifies the ECS name. For details, see How Can I Set Sequential ECS Names When Creating Multiple ECSs? A name must comply with the following rules:
|
user_data |
No |
String |
Specifies the user data to be injected to the ECS during the creation. Text and text files can be injected.
NOTE:
For more information about the user data to be injected, see Injecting User Data into ECSs in the Elastic Cloud Server User Guide. Examples Before base64 encoding:
After base64 encoding:
|
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:
|
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 creation API (Creating and Importing an SSH Key Pair) or obtained using the SSH key query API (Querying SSH Key Pairs). Note: If chargingMode 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:
|
publicip |
No |
Object |
Specifies the EIP bound to the ECS, which can be configured in one of the following ways:
For details, see publicip Field Description. |
count |
No |
Integer |
Specifies the number of ECSs to be created. Note:
|
isAutoRename |
No |
Boolean |
Specifies whether the same name is allowed during batch creation. The default value is False. This parameter takes effect when the count value is greater than 1.
|
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 subscription duration of the disks is the same as that of the ECS. For details, see Table 5. |
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 6. |
security_groups |
No |
Array of objects |
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 security_groups Field Description. |
availability_zone |
No |
String |
Specifies the name of the AZ where the ECS is located.
NOTE:
If this parameter is not specified, the system automatically selects an AZ. If the ECS is created on a DeH, the ECS must be in the same AZ as the DeH. You can obtain the value of this parameter by referring to Querying AZs or Regions and Endpoints. |
batch_create_in_multi_az |
No |
Boolean |
Specifies whether ECSs can be deployed in multiple random AZs. The default value is false.
This parameter is valid when availability_zone is left blank. |
extendparam |
No |
Object |
Provides the supplementary information about the ECS to be created. For details, see Table 9. |
metadata |
No |
Map<String,String> |
Specifies the metadata of the ECS to be created. You can use metadata to customize key-value pairs.
NOTE:
For details about reserved key-value pairs, see Table 11. |
os:scheduler_hints |
No |
Object |
Specifies ECS scheduling information, for example, setting an ECS group. For details, see Table 12. |
tags |
No |
Array of strings |
Specifies ECS tags. 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:
NOTE:
|
server_tags |
No |
Array of objects |
Specifies ECS tags. For details, see server_tags Field Description.
NOTE:
|
description |
No |
String |
Specifies the description of an ECS, which is empty by default.
|
auto_terminate_time |
No |
String |
Specifies the scheduled deletion time. The value is in the format of "yyyy-MM-ddTHH:mm:ssZ" in UTC+0 and complies with ISO8601. If the value of second (ss) is not 00, the system automatically sets to the current value of minute (mm). The scheduled deletion time must be at least half an hour later than the current time. The scheduled deletion time cannot be three years later than the current time. For example, set the value to 2020-09-25T12:05:00Z.
NOTE:
Scheduled deletion is available only for pay-per-use ECSs. |
cpu_options |
No |
Object |
Specifies the CPU options. For details, see Table 7. |
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 Subnets. |
ip_address |
No |
String |
Specifies the IP address of the NIC used by the ECS. The value is an IPv4 address.
Constraints:
|
ipv6_enable |
No |
Boolean |
Specifies 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. |
allowed_address_pairs |
No |
Array of allow_address_pair objects |
Specifies the allowed IP or MAC address pairs. For details, see Table 4 (extended attribute). The IP address cannot be 0.0.0.0/0.
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
ip_address |
No |
String |
Specifies the IP address. The IP address cannot be 0.0.0.0/0. Configure an independent security group for the port if a large CIDR block (subnet mask less than 24) is configured for parameter allowed_address_pairs. |
mac_address |
No |
String |
Specifies the MAC address. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
volumetype |
Yes |
String |
Specifies the ECS system disk type, which must be one of available disk types.
The value can be SATA, SAS, GPSSD, SSD, or ESSD.
If the specified disk type is not available in the AZ, the disk will fail to be created.
NOTE:
|
size |
No |
Integer |
Specifies the system disk size in GB. The value ranges from 1 to 1024. Constraints:
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. Value: DSS (dedicated storage type) This parameter must be used together with cluster_id and cluster_id must be specified. |
cluster_id |
No |
String |
Specifies the ID of the storage pool used by an ECS system disk. |
hw:passthrough |
No |
Boolean |
Specifies the device type of the EVS disks to be created.
|
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. For details, see metadata Field Description for Creating Disks. |
iops |
No |
Integer |
Specifies the IOPS configured for an EVS disk. This parameter is mandatory only when volumetype is set to GPSSD2 or ESSD2.
NOTE:
|
throughput |
No |
Integer |
Specifies the throughput of an EVS disk. The unit is MiB/s. This parameter is mandatory when volumetype is set to GPSSD2 and cannot be configured when volumetype is set to other values.
NOTE:
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
volumetype |
Yes |
String |
Specifies the type of the ECS data disk, which must be one of available disk types.
The value can be SATA, SAS, GPSSD, SSD, or ESSD.
If the specified disk type is not available in the AZ, the disk will fail to be created.
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.
NOTE:
The shareable field is not used anymore. 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 |
Specifies the device type of the EVS disks to be created.
|
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. Value: DSS (dedicated storage type) This parameter must be used together with cluster_id and cluster_id must be specified. |
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. |
delete_on_termination |
No |
Boolean |
Specifies the policy of releasing data disks when the ECS is deleted.
The default value is false.
NOTE:
This parameter is supported only by pay-per-use and spot ECSs. |
iops |
No |
Integer |
Specifies the IOPS configured for an EVS disk. This parameter is mandatory only when volumetype is set to GPSSD2 or ESSD2.
NOTE:
|
throughput |
No |
Integer |
Specifies the throughput of an EVS disk. The unit is MiB/s. This parameter is mandatory when volumetype is set to GPSSD2 and cannot be configured when volumetype is set to other values.
NOTE:
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
hw:cpu_threads |
No |
integer |
Specifies whether to enable CPU hyper-threading. Values: 1 and 2
This parameter can be set to 1 (disabling hyper-threading) only when all of the following conditions are met:
|
Response
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. |
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
- Create a yearly/monthly ECS running CentOS 7.6 64bit, with 1 vCPU, 1 GB of memory, and 1 Mbit/s of bandwidth bound. Use the key pair for login authentication.
POST https://{endpoint}/v1.1/{project_id}/cloudservers { "server": { "availability_zone":"az1-dc1", "name": "newserver", "imageRef": "67f433d8-ed0e-4321-a8a2-a71838539e09", "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" } } }
- Create a yearly/monthly ECS running CentOS 7.6 64bit, with 1 vCPU, 1 GB of memory, and 1 Mbit/s of bandwidth bound. Use the password for login authentication. For security purposes, store the password in ciphertext in configuration files or environment variables.
POST https://{endpoint}/v1.1/{project_id}/cloudservers { "server": { "availability_zone":"az1-dc1", "name": "newserver", "adminPass": "$ADMIN_PASS", "imageRef": "67f433d8-ed0e-4321-a8a2-a71838539e09", "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" } } }
- Create a yearly/monthly ECS running CentOS 7.6 64bit, with 1 vCPU, 1 GB of memory, and 1 Mbit/s of pay-per-use EIP (billed by traffic) bound. Use the key pair for login authentication.
POST https://{endpoint}/v1.1/{project_id}/cloudservers { "server": { "availability_zone":"az1-dc1", "name": "newserver", "imageRef": "67f433d8-ed0e-4321-a8a2-a71838539e09", "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" } } }
- Create a yearly/monthly ECS running CentOS 7.6 64bit, with 1 vCPU, 1 GB of memory, and shared bandwidth bound. Use the key pair for login authentication.
POST https://{endpoint}/v1.1/{project_id}/cloudservers { "server": { "availability_zone":"az1-dc1", "name": "newserver", "imageRef": "67f433d8-ed0e-4321-a8a2-a71838539e09", "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" } } }
- Send a pre-verification request to check whether mandatory parameters are configured in the request and whether the request format is correct.
POST https://{endpoint}/v1.1/{project_id}/cloudservers { "dry_run": true, "server": { "availability_zone":"az1-dc1", "name": "server", "imageRef": "ff49b1f1-3e3e-4913-89c6-a026041661e8", "root_volume": { "volumetype": "SSD" }, "data_volumes": [ { "volumetype": "SSD", "size": 100 }, { "volumetype": "SSD", "size": 100, "multiattach": true, "hw:passthrough": true } ], "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
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot