Creating an ECS

Function

This API is used to create ECS.

This API does not support automatic rollback after creating an ECS failed. If automatic rollback is required, call the API POST /v1/{project_id}/cloudservers. For details, see Creating an ECS.

URI

POST /v2.1/{project_id}/servers

Table 1 describes the parameters in the URI.

**Table 1** 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.

Alias of the API for creating ECSs: /v2/{project_id}/os-volumes_boot

This calling mode can only be used in OpenStack client.

Constraints

When using this API to create an ECS, you cannot bind an EIP to the ECS during the creation process. To do so, see Creating an ECS.
Parameter port in the three network parameters (port, uuid, and fixed_ip) has the highest priority. If parameter fixed_ip is set, you must specify the UUID.
A file injection failure will result in the ECS creation failure.
The following restrictions apply when you create ECSs using an image:
1. You cannot create an ECS on a specified host.
2. If a tenant backs up a disk in an ECS, the disk can be deleted only after the tenant deletes all the snapshots of the disk.
3. The flavors with different resource types cannot be adjusted if you adjust the specifications of an ECS created using an image.
Native APIs /v2/{project_id}/servers and /v2.1/{project_id}/servers provided by the cloud platform is developed based on and compatible with the community-version native OpenStack API.
Compared with the community-version native API, this API has the following restrictions when you create an ECS using a specified image:
- Community-version native OpenStack API: creates an ECS using the local disk by default.
- Native API provided by the cloud platform: creates an ECS using the shared storage as the system disk.
Specifically, when you use the native API to create an ECS:
1. You can query information about the disks attached to the ECS.
2. The ECS system disk uses the EVS disk quota.
3. You cannot query ECSs created based on a specified image using the image filtering function.
When you create an ECS with a specified disk, ensure that the disk and the ECS are in the same AZ.
The device_name field configured in block_device_mapping_v2 during the ECS creation does not take effect. The system generates a device name by default.
ECSs cannot be created in networks with provider:network_type set to geneve.

provider:network_type being set to geneve indicates the internal high-speed network for BMSs.
If your ECS is remotely logged in using a key, use the key_name parameter. If your ECS is remotely logged in using a password, use the adminPass parameter. Linux ECSs support user_data for injection. Windows ECSs support admin_pass for injection.

Request

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.
os:scheduler_hints	No	Object	Specifies the ECS scheduling information. For details, see Table 8. This parameter is not available for BMSs.

**Table 3** **server** parameters
Parameter	Mandatory	Type	Description
imageRef	No	String	Specifies the ECS image ID or URL. Example image ID: 3b8d6fef-af77-42ab-b8b7-5a7f0f0af8f2 Example image URL: http://glance.openstack.example.com/images/3b8d6fef-af77-42ab-b8b7-5a7f0f0af8f2 If you use a specified disk as the system disk to create an ECS, this parameter is not required. If you do not use a disk to create an ECS, you must set a valid UUID. Otherwise, the API will return error code 400.
flavorRef	Yes	String	Specifies the flavor ID or URL. For example: c3.2xlarge
name	Yes	String	Specifies the ECS name. The value options are as follows: The parameter value consists of 1 to 128 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 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, lower-case letters, and hyphens (-). Underscores (_) are converted into hyphens (-) by default. NOTE: ECS hostnames comply with RFC952 and RFC1123 naming rules. It is recommended that you configure hostnames using digits, lowercase letters, and hyphens (-). Underscores (_) are converted into hyphens (-) by default.
metadata	No	Map<String,String>	Specifies the ECS metadata. For details, see Table 4. The key contains 1 to 255 characters. The value contains 0 to 255 characters.
adminPass	No	String	Specifies the initial login password of the administrator account for logging in to an ECS using password authentication. The Linux administrator is root, and the Windows administrator is Administrator.
block_device_mapping_v2	No	Array of objects	Indicates the V2 API for specifying the ECS storage device. This is an extended attribute. This is the storage resource API of the new version. You are not allowed to create ECSs in batches when the volume is specified. For details, see Table 5. This parameter is not available for BMSs.
config_drive	No	String	Specifies the config_drive disk to be attached to the ECS during the ECS creation for transferring information to the ECS. This is an extended attribute. This function is not supported.
security_groups	No	Array of objects	Specifies the security group that the ECS belongs to. This parameter is an extended attribute. The default parameter value is default. This parameter is valid when you create an ECS on a specified network. For an existing port, the requested security groups are invalid. For details, see Table 6.
networks	Yes	Array of objects	Specifies information about the ECS NIC. This parameter is an extended attribute. This parameter must be specified if multiple tenant networks are used. For details, see Table 7.
key_name	No	String	Specifies the name of a key pair. This parameter is an extended attribute.
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 the 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 IyEvYmluL2Jhc2gKZWNobyB1c2VyX3Rlc3QgPiAvaG9tZS91c2VyLnR4dA== Windows cmVtIGNtZAplY2hvIDExMSA+IGM6XGFhYS50eHQ=
availability_zone	No	String	Specifies the AZ of a specified ECS. This is an extended attribute. This parameter is mandatory when you create an ECS.
return_reservation_id	No	Boolean	Specifies whether the reservation IDs of the ECSs created in a batch are returned. This is an extended attribute. You can query the ECSs created this time based on the returned reservation IDs. true: The reservation IDs are returned. false: The ECS information is returned. NOTE: When you create ECSs in a batch, this parameter is available.
min_count	No	Integer	Specifies the minimum number of ECSs that can be created. This is an extended attribute. The default value is 1. NOTE: When you use a specified image to create ECSs, this parameter is available.
max_count	No	Integer	Specifies the maximum number of ECSs that can be created. The default value of max_count is the same as that of min_count. Note: The max_count value must be greater than or equal to the min_count value. If both min_count and max_count are specified, the number of ECSs that can be created depends on host resources. If host resources permit, you can create a maximum number of ECSs ranging from min_count to max_count values. NOTE: When you use a specified image to create ECSs, this parameter is available.
OS-DCF:diskConfig	No	String	Specifies the disk configuration mode. The value can be AUTO or MANUAL. MANUAL: indicates that the image space of the system disk cannot be expanded. AUTO: indicates that the image space of the system disk can be automatically expanded to a value same as that specified in flavor. This function is not supported.
description	No	String	Specifies the description of an ECS, which is a null string by default. This is an extended attribute. This parameter is supported in microversion 2.19 and later. Can contain a maximum of 85 characters. Cannot contain special characters, such as < and >.

**Table 4** **metadata** field description
Parameter	Mandatory	Type	Description
admin_pass	No	String	Specifies the password of user Administrator for logging in to a Windows ECS. NOTE: This parameter is mandatory when a Windows ECS using password authentication is created.

**Table 5** **block_device_mapping_v2** parameters
Parameter	Type	Mandatory	Description
source_type	String	Yes	Specifies the source type of the volume device. Its value can be volume, image, snapshot, or blank. If you use a volume to create an ECS, set source_type to volume. If you use an image to create an ECS, set source_type to image. If you use a snapshot to create an ECS, set source_type to snapshot. If you create an empty data volume, set source_type to blank. NOTE: If source_type is snapshot and boot_index is 0, the EVS disk of this snapshot must be the system disk.
destination_type	String	No	Specifies the target type of the disk device. Its value can only be volume. volume: indicates the volume type. local: indicates the local file, which has not been supported.
guest_format	String	No	Specifies the local file system format. Its value can be swap or ext4. This function is not supported.
device_name	String	No	Specifies the disk device name. NOTE: This field has been discarded. The specified device_name does not take effect. The system generates a device name by default.
delete_on_termination	Boolean	No	Specifies whether disks are deleted when an ECS is deleted. Its default value is false. true: When an ECS is deleted, its disks are deleted. false: When an ECS is deleted, its disks are not deleted.
boot_index	String	No	Specifies whether it is a boot disk. 0 specifies a boot disk, and -1 specifies a non-boot disk. If this parameter is not specified, the default value is -1. NOTE: If source_type of the volume device is volume, there must be one boot_index whose value is 0.
uuid	String	No	If source_type is volume, the value of this parameter is the volume UUID. If source_type is snapshot, the value of this parameter is the snapshot UUID. If source_type is image, the value of this parameter is the image UUID.
volume_size	Integer	No	Specifies the volume size. The value is an integer. This parameter is mandatory when source_type is set to image or blank, and destination_type is set to volume. Unit: GB
volume_type	String	No	Specifies the volume type. This parameter is recommended when source_type is set to image and destination_type is set to volume.

**Table 6** **security_groups** parameters
Parameter	Mandatory	Type	Description
name	No	String	Specifies the security group name or UUID.

**Table 7** **networks** parameters
Parameter	Mandatory	Type	Description
port	No	String	Specifies the network port UUID. This parameter must be set when the network UUID is not specified.
uuid	No	String	Specifies the network UUID. This parameter must be set when the network port is not specified.
fixed_ip	No	String	Specifies the fixed IP address. Parameter port in the three network parameters (port, uuid, and fixed_ip) has the highest priority. If parameter fixed_ip is set, you must specify the UUID.

**Table 8** **os:scheduler_hints** parameters
Parameter	Mandatory	Type	Description
group	No	String	Specifies the anti-affinity group. The value is in UUID format. NOTE: Ensure that the ECS group uses the anti-affinity policy.
different_host	No	Array of strings	The function has not been supported, and this field is reserved.
same_host	No	Array of strings	The function has not been supported, and this field is reserved.
cidr	No	String	The function has not been supported, and this field is reserved.
build_near_host_ip	No	String	The function has not been supported, and this field is reserved.

Response

Table 9 describes the response parameters.

**Table 9** Response parameters
Parameter	Type	Description
server	Object	Specifies ECS information. For details, see Table 10.

**Table 10** **server** field description
Parameter	Type	Description
id	String	Specifies the ECS ID in UUID format.
links	Array of objects	Specifies the URI of the ECS. For details, see Table 11.
security_groups	Array of objects	Specifies the security groups to which the ECS belongs. For details, see Table 12.
OS-DCF:diskConfig	String	Specifies the disk configuration mode. MANUAL: indicates that the image space of the system disk cannot be expanded. AUTO: indicates that the image space of the system disk can be automatically expanded to a value same as that specified in flavor.
reservation_id	String	Specifies a filtering criteria to query the created ECSs. NOTE: When you create ECSs in a batch, this parameter is available.
adminPass	String	Specifies the password of user Administrator for logging in to a Windows ECS.

**Table 11** **links** field description
Parameter	Type	Description
rel	String	Specifies the shortcut link marker name.
href	String	Provides the corresponding shortcut link.

**Table 12** **security_groups** field description
Parameter	Type	Description
name	String	Specifies the security group name or UUID.

Example Request

Use an image with the extended attribute block_device_mapping_v2 parameters set to create an ECS and use the key pair for login authentication.

POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers

{ 
    "server": { 
        "flavorRef": "s3.xlarge.2", 
        "name": "wjvm48", 
        "metadata": { 
            "name": "name_xx1", 
            "id": "id_xxxx1" 
        }, 
        "block_device_mapping_v2": [{ 
            "source_type": "image", 
            "destination_type": "volume", 
            "uuid": "b023fe17-11db-4efb-b800-78882a0e394b", 
            "delete_on_termination": "False", 
            "boot_index": "0",
            "volume_type": "SAS",
            "volume_size": "40"
        }], 
        "security_groups": [{ 
            "name": "name_xx5_sg" 
        }], 
        "networks": [{ 
            "uuid": "fd40e6f8-942d-4b4e-a7ae-465287b02a2c", 
            "port": "e730a11c-1a19-49cc-8797-cee2ad67af6f", 
            "fixed_ip": "10.20.30.137" 
        }], 
        "key_name": "test", 
        "user_data": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==", 
        "availability_zone":"az1-dc1"
    } 
}

Use a snapshot with the extended attribute block_device_mapping_v2 parameters set to create an ECS. Set boot_index to 0 and set the EVS disk corresponding to the snapshot to a system disk.

POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers

{
    "server":{
        "name":"wjvm48",
        "availability_zone":"az1-dc1",
        "block_device_mapping_v2": [
            {
                "source_type":"snapshot",
                "boot_index":"0",
                "uuid":"df51997d-ee35-4fb3-a372-e2ac933a6565", //Specifies the snapshot ID, which is returned by the API for creating a snapshot.
                "destination_type":"volume"
            }
        ],
        "flavorRef":"s3.xlarge.2",
        "max_count":1,
        "min_count":1,
        "networks": [
            {
                "uuid":"79a68cef-0936-4e21-b1f4-b800ecb70246"
            }
        ] 
    } 
}

Use a volume with the block_device_mapping_v2 parameters set to create an ECS.

POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers

{ 
    "server": { 
        "flavorRef": "s3.xlarge.2", 
        "name": "wjvm48", 
        "metadata": { 
            "name": "name_xx1", 
            "id": "id_xxxx1" 
        }, 
        "block_device_mapping_v2": [{ 
            "source_type": "volume", 
            "destination_type": "volume", 
            "uuid": "bd7e4f86-b004-4745-bea2-a55b1085f107", 
            "delete_on_termination": "False", 
            "boot_index": "0", 
            "volume_type": "dsware",
            "volume_size": "40"
        }], 
        "security_groups": [{ 
            "name": "name_xx5_sg" 
        }], 
        "networks": [{ 
            "uuid": "fd40e6f8-942d-4b4e-a7ae-465287b02a2c", 
            "port": "e730a11c-1a19-49cc-8797-cee2ad67af6f", 
            "fixed_ip": "10.20.30.137" 
        }], 
        "key_name": "test", 
        "user_data": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==", 
        "availability_zone":"az1-dc1"
    } 
}

Use an imageRef to create an ECS. For security purposes, store the passwords in ciphertext in configuration files or environment variables.

POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers

{ 
    "server": { 
        "flavorRef": "s3.xlarge.2", 
        "name": "wjvm48", 
        "metadata": { 
            "name": "name_xx1", 
            "id": "id_xxxx1" 
        }, 
        "adminPass": "$ADMIN_PASS",
        "imageRef": "6b344c54-d606-4e1a-a99e-a7d0250c3d14",
        "security_groups": [{ 
            "name": "name_xx5_sg" 
        }], 
        "networks": [{ 
            "uuid": "fd40e6f8-942d-4b4e-a7ae-465287b02a2c",
            "port": "e730a11c-1a19-49cc-8797-cee2ad67af6f",
            "fixed_ip": "10.20.30.137" 
        }], 
        "key_name": "test", 
        "user_data": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==", 
        "availability_zone":"az1-dc1"
    } 
}

Create at least two and at most three ECSs in a batch.

POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers

{
    "server": {
        "availability_zone":"az1.dc1",
        "name": "test",
        "imageRef": "10ff4f01-35b6-4209-8397-359cb4475fa0",
        "flavorRef": "s3.xlarge.2",
        "return_reservation_id": "true",
        "networks": [
            {
                "uuid": "51bead38-d1a3-4d08-be20-0970c24b7cab"
            }
        ],
        "min_count": "2",
        "max_count": "3"
    }
}

Example response

Creating an ECS

{
    "server": {
        "security_groups": [
            {
                "name": "name_xx5_sg"
            }
        ],
        "OS-DCF:diskConfig": " MANUAL",
        "id": "567c1557-0eca-422c-bfce-149d6b8f1bb8",
        "links": [
            {
                "href": "http://xxx/v2/dc4059e8e7994f2498b514ca04cdaf44/servers/567c1557-0eca-422c-bfce-149d6b8f1bb8",
                "rel": "self"
            },
            {
                "href": "http://xxx/dc4059e8e7994f2498b514ca04cdaf44/servers/567c1557-0eca-422c-bfce-149d6b8f1bb8",
                "rel": "bookmark"
            }
        ],
        "adminPass": "*********"
    }
}

Creating ECSs in a batch: