# Creating an ECS

#### Function

This API is used to create one or more 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.

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 | Specifies the ECS information. For details, see Table 3.

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 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 flavor ID of the ECS to be created. For details about the flavors that have been released, see "ECS Specifications and Types" 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. 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 to the ECS during the 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

      cmVtIGNtZAplY2hvIDExMSA+IGM6XGFhYS50eHQ=

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

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

publicip

No

Object

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

- Do not use: In such a case, this parameter is unavailable.
- Automatically assign: The system will automatically assign an EIP to your ECS.
- Use existing: You need to specify an existing EIP for your ECS.

For details, see Table 1.

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 | Object | Specifies ECS system disk configurations. 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. If this parameter is left blank, the default security group is bound to the ECS by default. For details, see Table 2.
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. See Querying AZs.
extendparam | No | Object | Provides the supplementary information about the ECS to be created. For details, see Table 6.

metadata

No

Object

Specifies the metadata of the ECS to be created.

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

os:scheduler_hints | No | Object | Schedules ECSs, for example, by configuring an ECS group. For details, see Table 9.

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:

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

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

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.

binding:profile | No | Object | Allows you to customize data. Configure this parameter when creating a HANA ECS. For details, see Table 11.
extra_dhcp_opts | No | Array of objects | Indicates extended DHCP options. For details, see Table 12.

Table 5 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, SAS, SATA, co-p1, or uh-l1.

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

  Disks of the co-p1 and uh-l1 types are used exclusively for HPC ECSs and SAP HANA ECSs.

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

NOTE:

- When the disk is created from a backup:

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

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

- For details about disk types, see Disk Types and Disk Performance in the Elastic Volume Service User Guide.

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.

hw:passthrough

No

Boolean

Specifies the device type of the EVS disks to be created.

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

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.

Table 6 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, SAS, SATA, co-p1, or uh-l1.

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

  Disks of the co-p1 and uh-l1 types are used exclusively for HPC ECSs and SAP HANA ECSs.

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

NOTE:

- When the disk is created from a backup:

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

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

- For details about disk types, see Disk Types and Disk Performance in the Elastic Volume Service User Guide.

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

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

extendparam | No | Object | Provides the disk information. For details, see Table 5.
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

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 about how to query the task execution status based on job_id, see Task Status Management.

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

#### Example Request

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.

- Example URL request

      POST https://{endpoint}/v1/{project_id}/cloudservers

- An ECS with flavor ID m3.larger is to be created, where the image ID is imageid_123, disk type is SSD, and VPC ID is 0dae26c9-9a70-4392-93f3-87d53115d171. An example request is as follows:

      {
          "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.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": {
                  "eip": {
                      "iptype": "5_bgp",
                      "bandwidth": {
                          "size": 10,
                          "sharetype": "PER"
                      }
                  }
              },
              "key_name": "sshkey-123",
              "count": 1
          }
      }

- 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:
  - The system disk is encrypted.
  - For the two data disks to be restored, one uses default settings, and the other uses the changed settings, SSD, 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.
  An example request is as follows:

      {
          "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"
          }
      }

- An example pre-verification request body is as follows:

      {
          "dry_run": true
          "server": {
              "availability_zone":"az1-dc1",
              "name": "newserver",
              "imageRef": "1189efbf-d48b-46ad-a823-94b942e2a000",
              "root_volume": {
                  "volumetype": "SSD"
              },
              "data_volumes": [ ],
              "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": "93c82933d6b7827d3016b8771f2070873"
    }

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