doc-exports/docs/ecs/api-ref/en-us_topic_0020212668.html

Creating ECSs

Function

This API is used to create one or more ECSs.

This API is an asynchronous API. After the creation request is successfully delivered, a job ID is returned. This does not mean that the creation is complete. You need to call the API by referring to Querying Job Execution Status to query the job status. The SUCCESS status indicates that the creation is successful.

Before calling this API, you need to obtain regions and endpoints.

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

  

  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.

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	Object	Definition Specifies the ECS information. For details, see Table 3. Constraints N/A Range N/A Default Value N/A
dry_run	No	Boolean	Definition Specifies whether to check the request. If this parameter is set to true, no instance is created. Constraints N/A Range true: Check the request. Check items include the 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: Send the request without checking the request body. Default Value false

Table 3 Parameters for creating an ECS

Parameter	Mandatory	Type	Description
imageRef	Yes	String	Definition Specifies the ID of the system image used for creating ECSs. The ID is in the format of a Universally Unique Identifier (UUID). You can obtain the image ID from the console or by following the instructions provided in "Querying Images" in Image Management Service API Reference. Constraints NOTE: Certain ECS flavors cannot support all public images provided on the 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. Range N/A Default Value N/A
flavorRef	Yes	String	Definition 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. Constraints N/A Range N/A Default Value N/A
name	Yes	String	Definition Specifies the ECS name. Constraints 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 1 to 59 characters. ECS hostnames comply with RFC 952 and RFC 1123 naming rules. It is recommended that you configure hostnames using digits (0 to 9), lowercase letters (a to z), and hyphens (-). Underscores (_) are converted into hyphens (-) by default. Range The parameter value consists of 1 to 128 characters, including letters, digits, underscores (_), hyphens (-), and periods (.). Default Value N/A
user_data	No	String	Definition Specifies the user data to be injected to the ECS during the creation. Text and text files can be injected. 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 IyEvYmluL2Jhc2gKZWNobyB1c2VyX3Rlc3QgPiAvaG9tZS91c2VyLnR4dA== Windows cmVtIGNtZAplY2hvIDExMSA+IGM6XGFhYS50eHQ= For more information about the user data to be injected, see "Injecting User Data into ECSs" in Elastic Cloud Server User Guide. Constraints The content of user_data must be encoded with base64. The maximum size of the content to be injected (before encoding) is 32 KB. 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. Range N/A Default Value N/A
adminPass	No	String	Definition 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 Function. Constraints 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. 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. If the key_name field is specified for an ECS that is created using an image with Cloud-Init installed, the adminPass field becomes invalid. Range The password must contain 8 to 26 characters. The password must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters (!@$%^-_=+[{}]:,./?~#*). Default Value N/A
key_name	No	String	Definition 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 (Listing SSH Key Pairs). Constraints N/A Range N/A Default Value N/A
vpcid	Yes	String	Definition 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. Constraints N/A Range N/A Default Value N/A
nics	Yes	Array of objects	Definition Specifies the NIC information of the ECS. For details, see Table 4. Constraints The value must be the ID of the subnet created in the VPC specified by vpcid and in the format of the UUID. A maximum of 12 NICs can be attached to an ECS. Range N/A Default Value N/A
publicip	No	Object	Definition 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 parameter is unavailable. Automatically assign: You need to specify the information about the EIP to be created. Use existing: You need to specify an existing EIP for your ECS. For details, see Table 1. Constraints N/A Range N/A Default Value N/A
count	No	Integer	Definition Specifies the number of instances to be created. Constraints If this parameter is not specified, the default value is 1. If the tenant quota is sufficient, the maximum value is 100. Range N/A Default Value N/A
root_volume	Yes	Object	Definition Specifies ECS system disk configurations. For details, see Table 5. Constraints N/A Range N/A Default Value N/A
data_volumes	No	Array of objects	Definition Specifies ECS data disk configurations. Each data structure represents a data disk to be created. Constraints An ECS can be attached with a maximum of 59 data disks (certain flavors support only 23 data disks). For details, see Table 6. Range N/A Default Value N/A
security_groups	No	Array of objects	Definition 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 2. Range N/A Default Value N/A
availability_zone	No	String	Definition Specifies the name of the AZ where the ECS is located. See Listing AZs. Constraints If this parameter is not specified, the system automatically selects an AZ. Range N/A Default Value N/A
batch_create_in_multi_az	No	Boolean	Definition Specifies whether ECSs can be randomly deployed in multiple AZs. Constraints This parameter is valid when availability_zone is left blank. NOTE: When ECSs are created in batches, parameter count is mandatory. Range true: The batch-created ECSs are deployed in multiple AZs. false: The batch-created ECSs are deployed in a single AZ. Default Value false
extendparam	No	Object	Definition Provides the supplementary information about the ECS to be created. For details, see Table 7. Constraints N/A Range N/A Default Value N/A
metadata	No	Object	Definition Specifies the metadata of the ECS to be created. You can use metadata to customize key-value pairs. For details about reserved key-value pairs, see Table 9. Constraints If the metadata contains sensitive data, take appropriate measures to protect the sensitive data, for example, controlling access permissions and encrypting the data. Range A maximum of 10 key-value pairs can be injected. A metadata key consists of 1 to 255 characters and can only contain uppercase letters, lowercase letters, spaces, digits, hyphens (-), underscores (_), colons (:), and periods (.). A metadata value consists of a maximum of 255 characters. Default Value N/A
os:scheduler_hints	No	Object	Definition Schedules ECSs, for example, by configuring an ECS group. For details, see Table 10. Constraints N/A Range N/A Default Value N/A
tags	No	Array of strings	Definition Specifies ECS tags. A tag is in the format of "key.value". Constraints Each ECS supports a maximum of 10 tags during the creation. The server_tags field provides the same functions as tags, but supports more keys and values, so the server_tags field is recommended. A tag key contains a maximum of 36 characters, and a tag value contains a maximum of 43 characters. Range A tag key contains a maximum of 36 characters, and a tag value contains a maximum of 43 characters. 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 (-). Default Value N/A
description	No	String	Definition Specifies the ECS description. Constraints Angle brackets (<>) are not allowed. Range A maximum of 85 characters are allowed. Default Value Empty string

Table 4 nics field description

Parameter	Mandatory	Type	Description
subnet_id	Yes	String	Definition Specifies the subnet of the ECS. Constraints The value must be the ID of the subnet created in the VPC specified by vpcid and in the format of the UUID. Range N/A Default Value N/A
ip_address	No	String	Definition 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. Range N/A Default Value N/A
binding:profile	No	Object	Definition Allows you to customize data. For details, see Table 12. Constraints This parameter can be specified only during the ECS creation. Range N/A Default Value N/A
extra_dhcp_opts	No	Array of objects	Definition Indicates extended DHCP options. For details, see Table 13. Constraints N/A Range N/A Default Value N/A
ipv6_enable	No	Boolean	Definition Specifies whether to support IPv6 addresses. Constraints N/A Range true: The NIC supports IPv6. false: The NIC does not support IPv6. Default Value false
ipv6_bandwidth	No	Object	Definition Specifies the bound shared bandwidth. For details, see ipv6_bandwidth Field Description. Constraints N/A Range N/A Default Value N/A

Table 5 root_volume field description

Parameter	Mandatory	Type	Description
volumetype	Yes	String	Definition Specifies the disk type of an ECS system disk. For details about disk types, see "Disk Types and Performance" in Elastic Volume Service User Guide. Constraints The disk type must match that provided by the system. If the specified disk type is not available in the AZ specified by availability_zone, the disk creation will fail. When the disk is created from a backup: If the type of the backup's source disk is SSD, SAS, SATA, GPSSD, ESSD, or GPSSD2, 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. Range The value can be ESSD, GPSSD2, GPSSD, SSD, SAS, or SATA. SSD: the ultra-high I/O type SAS: the high I/O type SATA: the common I/O type (end-of-sale) GPSSD: the general purpose SSD type ESSD: the extreme SSD type GPSSD2: the general purpose SSD V2 type Default Value N/A
size	No	Integer	Definition Specifies the system disk size, in GiB. 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. Range 1 to 1024 Default Value N/A
hw:passthrough	No	Boolean	Definition Specifies the device type of the EVS disks to be created. Constraints N/A Range If this parameter is set to false, VBD disks are created. If this parameter is set to true, SCSI disks are created. Default Value If this parameter is not specified or set to a non-Boolean character, VBD disks are created by default.
metadata	No	Object	Definition Specifies the metadata of the created EVS disk. For details, see metadata Field Description for Creating Disks. Constraints This parameter is used only when an encrypted disk is created. Range The length of key and value under metadata can contain no more than 255 bytes. Default Value N/A

Table 6 data_volumes field description

Parameter	Mandatory	Type	Description
volumetype	Yes	String	Definition Specifies the disk type of an ECS data disk. For details about disk types, see "Disk Types and Performance" in Elastic Volume Service User Guide. Constraints The disk type must match that provided by the system. If the specified disk type is not available in the AZ specified by availability_zone, the disk creation will fail. When the disk is created from a backup: If the type of the backup's source disk is SSD, SAS, SATA, GPSSD, ESSD, or GPSSD2, 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. Range The value can be ESSD, GPSSD2, GPSSD, SSD, SAS, or SATA. SSD: the ultra-high I/O type SAS: the high I/O type SATA: the common I/O type (end-of-sale) GPSSD: the general purpose SSD type ESSD: the extreme SSD type GPSSD2: the general purpose SSD V2 type Default Value N/A
size	Yes	Integer	Definition Specifies the data disk size, in GiB. Constraints 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. Range 10 to 32768 Default Value N/A
shareable	No	Boolean	Definition Specifies whether the disk is shared. Constraints This parameter has been discarded. Use multiattach. Range true: indicates that the created disk is a shared disk. false: indicates that the created disk is a common EVS disk. Default Value false
multiattach	No	Boolean	Definition Specifies the shared disk information. Constraints The shareable parameter is discarded. If both shareable and multiattach must be used, ensure that the values of the two parameters are the same. If this parameter is not specified, common EVS disks are created by default. Range true: indicates that the created disk is a shared disk. false: indicates that the created disk is a common EVS disk. Default Value false
hw:passthrough	No	Boolean	Definition Specifies the device type of the EVS disks to be created. Constraints N/A Range If this parameter is set to false, VBD disks are created. If this parameter is set to true, SCSI disks are created. If this parameter is not specified or set to a non-Boolean character, VBD disks are created by default. Default Value N/A
extendparam	No	Object	Definition Provides the disk information. For details, see Table 6. Constraints N/A Range N/A Default Value N/A
data_image_id	No	String	Definition Specifies ID of the data image. The value is in UUID format. Constraints If data disks are created using a data disk image, this parameter is mandatory and it does not support metadata. Range N/A Default Value N/A
metadata	No	Object	Definition Specifies the metadata of the created EVS disk. For details, see metadata Field Description for Creating Disks. Constraints The length of key and value under metadata can contain no more than 255 bytes. This parameter is used only when an encrypted disk is created. If data disks are created using a data disk image, this parameter cannot be used. Range N/A Default Value N/A

Table 7 security_options field description

Parameter	Mandatory	Type	Description
tpm_enabled	Yes	Boolean	Definition Specifies whether to enable TPM. Constraints Currently, the following instance types support TPM: Pi5e. Range true: Enable TPM. false: Disable TPM. Default Value false

Response

Parameter	Type	Description
job_id	String	Definition Specifies the returned job ID after delivering the job. You can query the job progress using this ID. For details about how to query the job execution status based on job_id, see Job Status Management. Range N/A
serverIds	Array of strings	Definition Specifies ECS IDs. NOTE: You can query ECS details by ECS ID. If the system returns a 404 error, the ECS is being created, or creating the ECS failed. Range N/A

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

Example Request

• Create a pay-per-use ECS with 2 vCPUs, 16 GiB of memory, private image imageid_123, SSD disks attached, and 10 Mbit/s of bandwidth-billed EIP bound. Use the key pair for login authentication.

  POST https://{endpoint}/v1/{project_id}/cloudservers
  
  {
      "server": {
          "availability_zone":"az1-dc1",
          "name": "newserver", 
          "imageRef": "imageid_123", 
          "root_volume": {
              "volumetype": "SSD"
          }, 
          "data_volumes": [
              {
                  "volumetype": "SSD", 
                  "size": 100
              }, 
              {
                  "volumetype": "SSD", 
                  "size": 100,
                  "multiattach": true,
                  "hw:passthrough": true
              }
          ], 
          "flavorRef": "m3.large.8", 
          "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": {
              "eip": {
                  "iptype": "5_bgp",
                  "bandwidth": {
                      "size": 10, 
                      "sharetype": "PER"
                  }
              }
          }, 
          "key_name": "sshkey-123", 
          "count": 1 
      }
  }

• Use a full-ECS image with an encrypted system disk and two data disks to create an ECS. For the two data disks to be restored, one uses default settings, and the other uses the changed settings, SSD, 100 GiB. Also, attach a 50 GiB SSD disk to the ECS.

  POST https://{endpoint}/v1/{project_id}/cloudservers
  
  {
      "server": {
          "availability_zone":"az1-dc1", 
          "name": "wholeImageServer", 
          "imageRef": "ff49b1f1-3e3e-4913-89c6-a026041661e8", 
          "root_volume": {
              "volumetype": "SSD",
              "metadata": {
                   "__system__encrypted": "1",
                   "__system__cmkid": "83cdb52d-9ebf-4469-9cfa-e7b5b80da846"
               }
          }, 
          "data_volumes": [
              {
                  "volumetype": "SSD", 
                  "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"
      }
  }

• 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/{project_id}/cloudservers
  
  {
      "dry_run": true,
      "server": {
          "availability_zone":"az1-dc1",
          "name": "newserver", 
          "imageRef": "1189efbf-d48b-46ad-a823-94b942e2a000", 
          "root_volume": {
              "volumetype": "SSD"
          }, 
          "data_volumes": [
              {                 
                   "volumetype": "SSD",                  
                   "size": 100,                 
                   "multiattach": true,                 
                   "hw:passthrough": true             
              }
          ], 
          "flavorRef": "s3.xlarge.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", 
          "count": 1
      }
  }

Example Response

{
    "job_id": "ff808082739334d80173941567f21d4f",
    "serverIds": [
        "118258c5-0c6a-4e73-8b51-8d1ea3272e1b"
    ]
}

Or

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

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Codes.

Parent topic: Lifecycle Management