• Elastic Cloud Server

ecs
  1. Help Center
  2. Elastic Cloud Server
  3. API Reference
  4. OpenStack Nova APIs
  5. Lifecycle Management
  6. Creating an ECS

Creating an ECS

Function Description

This interface is used to create an ECS.

URI

POST /v2/{project_id}/servers

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.

NOTE:

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

This calling mode can only be used in OpenStack Client.

Constraints

  1. Parameter port in the three network parameters (portuuid, and fixed_ip) has the highest priority. If parameter fixed_ip is set, you must specify the UUID.
  2. A file injection failure will result in the ECS creation failure.
  3. 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 only be deleted 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.
  4. Native API /v2/{project_id}/servers provided by the public cloud platform is developed based on and compatible with the community-version native OpenStack API.
    Compared with the community-version native API, native API /v2/{tenant_id}/servers 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 public 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.
  5. In the  system, an ECS at the backend of a disk must be created in the same  where the disk is located.
  6. 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.
  7. ECSs cannot be created in networks with provider:network_type set to geneve.
    NOTE:

    provider:network_type being geneve indicates the internal high-speed network for BMSs.

  8. During the ECS creation, multiple ports cannot belong to the same network only when the global configuration item allow_duplicate_networks is enabled.
  9. When you create an ECS using an image that supports Cloud-Init or Cloudbase-Init, only key_name can be configured. (Parameter adminPass is invalid.) For a Linux ECS, its password can be injected only using user_data. For a Windows ECS, its password can be injected only using metadata adminPass.
  10. When you create an ECS using an image that does not support Cloud-Init or Cloudbase-Init, adminPass and key_name can be configured.

Request

Request parameters

Table 2 describes the request parameters.

Table 2 Request parameters

Parameter

Type

Mandatory

Description

server

Dict

Yes

Specifies the ECS information.

See Table 3.

os:scheduler_hints

Dict

No

Specifies the ECS scheduling information.

See Table 8.

This parameter is not available in the BMS scenario.

Table 3 server parameters

Parameter

Type

Mandatory

Description

imageRef

String

No

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 the system volume to create an ECS, this parameter is not required. If you do not use a volume to create an ECS, you must set imageRef to a valid UUID. Otherwise, the API will return error code 400.
NOTE:
  • The ECSs with certain flavors do not 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

String

Yes

Specifies the flavor ID or URL.

name

String

Yes

Specifies the ECS name.

The value contains 1 to 255 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.

metadata

Dict

No

Specifies the ECS metadata. For details, see Table 4.

  • The key contains 1 to 255 characters.
  • The value contains 0 to 255 characters.

adminPass

String

No

This parameter is invalid because password injection is implemented using Cloud-Init.

block_device_mapping_v2

List(Dict)

No

Specifies the V2 interface for specifying the ECS storage device.

This is an extended attribute.

This is the storage resource interface of the new version. Users cannot create ECSs in batches when the volume is specified. For details, see Table 5. This parameter is not available in the BMS scenario.

config_drive

String

No

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

List(Dict)

No

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

List(Dict)

Yes

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.

If multiple groups of network parameters are specified, ensure that the parameters of each group belong to the same VPC.

key_name

String

No

Specifies the name of a key pair. This parameter is an extended attribute.

user_data

String

No

Specifies the user data. This parameter is an extended attribute. The character string contains 1 to 65,534 characters and must be encrypted using Base64.

availability_zone

String

No

Specifies the AZ of the ECS. This is an extended attribute.

This parameter is mandatory when you create an ECS. In the BMS scenario, only the AZ can be specified.

return_reservation_id

Bool

No

Specifies whether the reservation IDs of the ECSs created in batches are returned. 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 batches, this parameter is available.

min_count

Int

No

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

max_count

Int

No

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

OS-DCF:diskConfig

String

No

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

String

No

Specifies the description of an ECS, which is a null string by default. This is an extended attribute.

  • Can contain a maximum of 85 characters.
  • Cannot contain special characters, such as < and >.
NOTE:
  • The V2 interface does not support this parameter.
  • The V2.1 interface supports this parameter. In such a case, add a key-value pair to the request header. The key is consistently X-OpenStack-Nova-API-Version, and the value is the microversion. When the value is 2.26, this parameter is valid.
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.

Example: cloud.1234

NOTE:

This parameter is mandatory when a Windows ECS with 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 volumeimagesnapshot, 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.

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

Yes

Specifies the current type of the disk device.

Its value can only be volume.

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 volume device name.

The name is a character string containing 1 to 255 characters, and must conform to the regular expression (^/dev/x{0,1}[a-z]{0,1}d{0,1})([a-z]+)[0-9]*$, for example, /dev/vda. The value set by the user cannot take effect, and the system will generate a value by default.

delete_on_termination

Bool

No

Specifies whether disks are deleted when an ECS is deleted.

Its default value is false.

boot_index

String

No

Specifies whether it is a boot disk. 0 specifies a boot disk, and -1 specifies a non-boot disk.

NOTE:

If source_type of the volume device is volume, there must be one boot_index whose value is 0.

uuid

String

Yes

Specifies the UUID of the volume or snapshot.

When the value of source_type is image, it indicates the UUID of the image.

volume_size

Int

No

Specifies the volume size.

The value is an integer.

This parameter is mandatory when source_type is set to image and dest is set to volume.

Unit: GB

volume_type

String

No

Specifies the volume type. This parameter is mandatory when source is set to image and dest is set to volume.

Table 6 security_groups parameters

Parameter

Type

Mandatory

Description

name

String

No

Specifies the security group name or UUID.

Table 7 networks parameters

Parameter

Type

Mandatory

Description

port

String

No

Specifies the network port UUID.

This parameter must be set when the network UUID is not specified.

uuid

String

No

Specifies the network UUID.

This parameter must be set when the network port is not specified.

fixed_ip

String

No

Specifies the fixed IP address. Parameter port in the three network parameters (portuuid, 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

Type

Mandatory

Description

group

List(String)

No

Specifies the anti-affinity group.

The value is in UUID format.

different_host

List(String)

No

Specifies the anti-affinity with a specified ECS. The value is in UUID format.

This function is not supported.

same_host

List(String)

No

Specifies the affinity with a specified ECS. The value is in UUID format.

This function is not supported.

cidr

List(String)

No

Specifies the CIDR of the specified network segment accommodating the host to which the ECS is scheduled.

This function is not supported.

build_near_host_ip

List(String)

No

Specifies the IP address of the host when the ECS is scheduled to a host in a specified network segment.

This function is not supported.

tenancy

List(String)

No

Specifies whether the ECS is created on a Dedicated Host (DeH) or in a shared pool.

The value can be shared or dedicated.

  • shared: indicates the shared pool.
  • dedicated: indicates the DeH.

The parameter value also takes effect for ECS query operations.

dedicated_host_id

List(String)

No

Specifies the DeH ID.

This parameter takes effect only when the value of tenancy is dedicated.

If you do not specify this parameter, the system will automatically assign a DeH to a tenant to deploy ECSs.

The parameter value also takes effect for ECS query operations.

Response

Response parameters

Table 9 describes the response parameters.

Table 9 Response parameters

Parameter

Type

Description

id

String

Specifies the ECS ID in UUID format.

links

List(Dict)

Specifies the URI of the ECS.

security_groups

List(Dict)

Specifies the security group of the ECS.

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 batches, this parameter is available.

adminPass

String

Specifies the password of user Administrator for logging in to a Windows ECS.

Example 1

Creating an ECS

  • Example request

    Use an image to create an ECS through the interface block_device_mapping_v2. An example request is as follows:

    POST /v2/9c53a566cb3443ab910cf0daebca90c4/servers 
    POST /v2.1/9c53a566cb3443ab910cf0daebca90c4/servers 
    { 
        "server": { 
            "flavorRef": "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": "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": "name_xx5az2" 
        } 
    }

    Use a snapshot to create an ECS through the interface block_device_mapping_v2. An example request is as follows:

    NOTE:

    When source_type is snapshotboot_index is 0, and the EVS disk corresponding to the snapshot must be a system disk.

    POST /v2/3e530d031d004e4aa96f9c74343a4030/servers
    {
        "server":{
            "name":"wjvm48",
            "availability_zone":"name_xx5az2",
            "block_device_mapping_v2": [
                {
                    "source_type":"snapshot",
                    "boot_index":"0",
                    "uuid":"df51997d-ee35-4fb3-a372-e2ac933a6565", //Specifies the snapshot ID, which is returned when a snapshot is created.
                    "destination_type":"volume"
                }
            ],
            "flavorRef":"s3.xlarge.2",
            "max_count":1,
            "min_count":1,
            "networks": [
                {
                    "uuid":"79a68cef-0936-4e21-b1f4-b800ecb70246"
                }
            ] 
        } 
    }

    Use a volume to create an ECS through the interface block_device_mapping_v2. An example request is as follows:

    POST /v2/9c53a566cb3443ab910cf0daebca90c4/servers 
    POST /v2.1/9c53a566cb3443ab910cf0daebca90c4/servers 
    { 
        "server": { 
            "flavorRef": "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": "name_xx5az2" 
        } 
    }

    Create an ECS through the interface imageRef. An example request is as follows:

    POST /v2/9c53a566cb3443ab910cf0daebca90c4/servers 
    POST /v2.1/9c53a566cb3443ab910cf0daebca90c4/servers 
    { 
        "server": { 
            "flavorRef": "2", 
            "name": "wjvm48", 
            "metadata": { 
                "name": "name_xx1", 
                "id": "id_xxxx1" 
            }, 
            "adminPass": "name_xx1", 
            "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": "name_xx5az2" 
        } 
    }
  • Example response
    {
        "server": {
            "security_groups": [
                {
                    "name": "name_xx5_sg"
                }
            ],
            "OS-DCF:diskConfig": " MANUAL",
            "id": "567c1557-0eca-422c-bfce-149d6b8f1bb8",
            "links": [
                {
                    "href": "http://192.168.82.230:8774/v2/dc4059e8e7994f2498b514ca04cdaf44/servers/567c1557-0eca-422c-bfce-149d6b8f1bb8",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.82.230:8774/dc4059e8e7994f2498b514ca04cdaf44/servers/567c1557-0eca-422c-bfce-149d6b8f1bb8",
                    "rel": "bookmark"
                }
            ],
            "adminPass": "name_xx1"
        }
    }

Example 2

Creating ECSs in a batch

  • Example request
    {
        "server": {
            "availability_zone": "az1.dc1",
            "name": "test",
            "imageRef": "10ff4f01-35b6-4209-8397-359cb4475fa0",
            "flavorRef": "s1.medium",
            "return_reservation_id": "true",
            "networks": [
                {
                    "uuid": "51bead38-d1a3-4d08-be20-0970c24b7cab"
                }
            ],
            "min_count": "2",
            "max_count": "3"
        }
    }
  • Example response
    {
        "reservation_id": "r-3fhpjulh"
    }

Returned Values

See General Request Returned Values.