CreateInstances

1. API Description

This API is used to create one or more instances with a specified configuration.

Prerequisites

Query stock: call DescribeAvailableResources to check available resources.
Query instance model: call DescribeInstanceTypes to check specifications.
Query image: call DescribeImages to check information on image.
Cost estimation: know of bare metal cloud pricing. See Billing Method for more details.

Note

After an instance is created successfully, it will start up automatically, and the instance status will become "RUNNING".
If you create a subscription instance, the amount required will be pre-deducted. If the balance is insufficient, the request will fail. If you create a pay-as-you-go instance, please ensure your account balance is sufficient before calling this API.
Vouchers can be used for fee deduction in instance creation. See Vouchers for more details.
This API is an async API. An instance ID list is returned after the creation request is sent. However, it does not mean the creation has been completed. The status of the instance will be PENDING or CREATING during the creation. You can use DescribeInstances to query the status of the instance. If the status changes from PENDING or Creating to Running, it means that the instance has been created successfully; CREATE_FAILED means the instance has been created failed. Any operations on the instances are not allowed while creating.
A maximum of 100 instances can be created in one request.

2. Input Parameters

The following request parameter list only provides API request parameters.

Parameter Name

Required

Type

Description

zoneId

Yes

String

Zone ID to which the instances belong.

instanceChargeType

Yes

String

Instance .

PREPAID: subscription

POSTPAID: pay-as-you-go

instanceChargePrepaid

Details of the monthly subscription, including the purchase period, auto-renewal. It is required if the instanceChargeType is PREPAID.

instanceTypeId

Yes

String

Instance model ID. To view specific values, you can call .

imageId

String

Valid image ID. To obtain valid image ID, you can call , pass in instanceTypeId to retrieve the list of images supported by the current model, and then find the imageId in the response.

You can also not specify an image and install it later through IPMI. When using iPXE to install OS, pass the value of ipxeUrl, and leave imageId empty.

ipxeUrl

String

iPXE URL.

Pass in the value and install your OS via IPMI.

You can choose to install OS using Netboot. See for more details.

resourceGroupId

String

Resource group ID where the instances reside

instanceName

String

Instance name to be displayed.

Default value: instance.

This parameter can contain up to 64 characters. Only letters, numbers, - and periods (.) are supported.

If you purchase multiple instances at the same time, you can specify a pattern string [begin_number,bits].

begin_number: the starting value of an ordered number, value range: [0,99999], default value: 0.

bits: the number of digits occupied by an ordered value, value range: [1,6], default value: 6.

For example, if you purchase 1 instance and the instance name body is server_[3,3], the instance name will be server003; if you purchase 2 instances, the instance names will be server003, server004.

Note:

Spaces are not supported in the pattern string.
Multiple pattern strings are supported, such as server_[3,3]_[1,1].

hostname

String

Instance hostname.

Default value: hostname.

This parameter can contain up to 64 . characters. Only letters, numbers, - and periods (.) are supported.

If you purchase multiple instances at the same time, you can specify a pattern string [begin_number,bits].

begin_number: the starting value of an ordered number, value range: [0,99999], default value: 0.

bits: the number of digits occupied by an ordered value, value range: [1,6], default value: 6.

Note:

Spaces are not supported in the pattern string.
Multiple pattern strings are supported, such as server_[3,3]_[1,1].

amount

Integer

The number of instances to be purchased.

Value range: [1,100]. Default value: 1.

password

String

Instance password.

The parameter must be 8-16 characters, including uppercase letters, lowercase letters, numbers and special characters like 1~!@$^*-_=+. This password is also used as the password for IPMI login. Please keep it safe. You must and can only pass the value of either password or sshKeys.

sshKeys

Array of String

List of SSH keys.

If an SSH key is used to log in, password login will be disabled. Up to 5 keys are supported.

Note:

For instances of Windows and EXSi operating systems, ignore this parameter. Default value is empty. Even if this parameter is filled in, only the value of password will be passed in.

If imageId is not specified, then sshKeys will be ignored. You must and can only pass the value of either password or sshKeys.

internetChargeType

Yes

String

Network pricing model.

See for details.

internetMaxBandwidthOut

Integer

Public network bandwidth cap (Mbps).

Default value: 1 Mbps.

The parameter value differs with different instance models. See bandwidth configuration for details.

trafficPackageSize

Float

Traffic package size (TB).

The parameter is valid only when internetChargeType is ByTrafficPackage. If not passed in, the default value will be the size of the free traffic package.

subnetId

String

Subnet ID.

Call DescribeVpcSubnets to check information on subnets created.

raidConfig

Disk array configuration.

partitions

Array of

Disk partition configuration. If the operating system is not installed, the partition cannot be set.

nic

NIC configuration.

enablePrimaryIPv6

Boolean

Enable primary IPv6 or not.

If the value is false, the primary IPv6 is not enabled and the elastic IPv6 cannot be configured.

The default value is true.

3. Output Parameters

Parameter Name

Type

Description

instanceIdSet

Array of String

List of instance IDs.

The returned instance ID list does not mean the creation has been completed. The status of the instance will be PENDING or CREATING during the creation. You can call to query the status of the instance according to dataSet. If the status changes from PENDING or Creating to Running, it means that the instance has been created successfully; CREATE_FAILED means the instance has been created failed.

orderNumber

String

Number of order.

requestId

String

The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Code Example

Create a pay-as-you -go instance with the simplest parameters Assuming to create a pay-as-you-go instance in Seoul A with the model of M6C, 1 Mbps flat rate bandwidth billing method, random system-generated password, and no images installed.

POST /api/v2/bmc HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateInstances
<Common Request Params>

Request:
{
    "instanceChargeType": "POSTPAID",
    "instanceTypeId": "M6C",
    "internetChargeType": "ByBandwidth",
    "zoneId": "SEL-A"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
        "instanceIdSet": ["instanceId1"],
        "orderNumber" : "orderNumber1"
    }
}

Create two subscription instances Assuming to create two subscription instances in Seoul A with the model of M6C, named SEL-M6C-01 and SEL-M6C-02, with the password: Password-12345~, image ID: 5ace1756-2230-4d1d-8fc6-84f1897ef397, public NIC name: wan0, private NIC name: lan0, and with 10 Mbps flat rate bandwidth billing method.

POST /api/v2/bmc HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateInstances
<Common Request Params>

Request:
{
    "instanceChargeType": "PREPAID",
    "amount": 2, 
    "instanceChargePrepaid":{
        "period": 2
    },
    "instanceName": "SEL-M6C-[1,2]",
    "hostname": "SEL-M6C-[1,2]",
    "internetMaxBandwidthOut": 10,
    "password": "Password-12345~",
    "nic": {
        "wanName": "wan0",
        "lanName": "lan0"
    },
    "instanceTypeId": "M6C",
    "internetChargeType": "ByBandwidth",
    "zoneId": "SEL-A", 
    "imageId": "5ace1756-2230-4d1d-8fc6-84f1897ef397"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
        "instanceIdSet": ["instanceId3", "instanceId4"],
        "orderNumber" : "orderNumber2"
    }
}

Create two subscription instances with traffic package billing method Similar to Example 2, but the difference is that the network billing method created this time is a traffic package, and the package size is 10 TB.

POST /api/v2/bmc HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateInstances
<Common Request Params>

Request:
{
    "instanceChargeType": "PREPAID",
    "amount": 2, 
    "instanceChargePrepaid":{
        "period": 2
    },
    "instanceName": "SEL-M6C-[1,2]",
    "hostname": "SEL-M6C-[1,2]",
    "internetMaxBandwidthOut": 10,
    "password": "Password-12345~",
    "nic": {
        "wanName": "wan0",
        "lanName": "lan0"
    },
    "instanceTypeId": "M6C",
    "internetChargeType": "ByBandwidth",
    "zoneId": "SEL-A", 
    "imageId": "5ace1756-2230-4d1d-8fc6-84f1897ef397",
    "trafficPackageSize": 10 
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
        "instanceIdSet": ["instanceId5", "instanceId6"],
        "orderNumber" : "orderNumber3"
    }
}

5. Developer Resources

Zenlayer Cloud API 2.0 integrates SDKs to make it easier for you to call APIs. More programming languages will be supported.

6. Error Codes

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

HTTP Status Code

Error Code

Description

400

INVALID_PARAMETER_HOSTNAME_EXCEED

Invalid hostname length. The specified hostname exceeds the maximum length.

400

INVALID_PARAMETER_HOSTNAME_MALFORMED

Invalid hostname format.

400

INVALID_PARAMETER_INSTANCE_NAME_EXCEED

Invalid instance name length. The specified instance name exceeds the maximum length.

400

INVALID_PARAMETER_INSTANCE_NAME_EXCEED

Invalid instance name format.

403

OPERATION_FILED_INTERNET_CHARGE_TYPE_NOT_SUPPORT

Network billing method not supported in current zone.

404

INVALID_IMAGE_NOT_FOUND

Image not found.

404

INVALID_ZONE_NOT_FOUND

Zone does not exist.

404

INVALID_INSTANCE_TYPE_NOT_FOUND

Instance model not found.

403

INVALID_PARTITION_IMAGE_NOT_SET

Custom partition are only supported for specific operating system.

403

OPERATION_DENIED_INSTANCE_QUOTA_EXCEED

You are trying to create more instances than your remaining quota allows.

400

INVALID_BANDWIDTH_VALUE_EXCEED_MAXIMUM

Bandwidth exceeds the maximum limit.

400

INVALID_PARAMETER_VALUE_PASSWORD_MALFORMED

Invalid password.

400

INVALID_PARAMETER_INSTANCE_LOGIN_CONFLICT

Password login and SSH key login cannot be specified at the same time.

400

INVALID_PARAMETER_SSH_KEY_MALFORMED

Invalid SSH key format. Usually start with rsa.

400

INVALID_RAID_CONFIG_FAST_CUSTOM_CONFLICT

Custom RAID and rapid RAID cannot be specified at the same time.

400

INVALID_INSTANCE_TYPE_RAID_NOT_SUPPORT

RAID level not supported for current instance model.

400

INVALID_PARAMETER_NIC_NAME_CONFLICT

Public NIC name and private NIC name cannot be the same.

400

INVALID_PARAMETER_NIC_NAME_MALFORMED

Invalid public or private NIC name.

400

INVALID_PARTITION_SIZE_NOT_FULL

Invalid partition size. Does not reach the specified capacity.

400

INVALID_PARTITION_DUPLICATE_FILE_PATH

Duplicated file path or drive letters of the partition.

400

INVALID_PARTITION_MISSING_REQUIRED_FILE_PATH

File path (drive letter) is needed.

"c" must be included for Windows, and "/" must be included for Linux.

400

INVALID_PARTITION_MALFORMED

Invalid file type or path format.

400

INVALID_PARTITION_NO_TYPE

Invalid file type.

400

INVALID_PARTITION_INVALID_ORDER

Drive letters must be filled in alphabetical order, such as CDEFG for Windows.

400

INVALID_PARAMETER_VALUE_RAID_DISK_MISMATCH

Disk quantity does not meet the RAID level requirement in custom RAID configuration.

400

INVALID_PARAMETER_VALUE_RAID_DISK_DISORDER

Serial numbers of disks must be filled in order, such as [1,2,3], in custom RAID configuration.

400

INVALID_PARAMETER_VALUE_RAID_DISK_SEQUENCE_DUPLICATE

Duplicated disk serial numbers in custom RAID configuration.

400

INVALID_PARAMETER_VALUE_RAID_DISK_SEQUENCE_RANGE

Disk serial number exceeds disk quantity in custom RAID configuration.

400

RESOURCE_INSUFFICIENT_PRODUCT_SOLD_OUT

Resources not for sale.

403

OPERATION_DENIED_CHARGE_TYPE_NOT_SUPPORT

Pricing model not supported in current zone.

400

RESOURCES_SOLDOUT_INSTANCE_TYPE

Instance models sold out.

403

INVALID_CHARGE_TYPE_NOT_SUPPORT

Pricing model not supported. If necessary, please contact Zenlayer Support.

404

INVALID_SUBNET_NOT_FOUND

Subnet not found.

400

INVALID_SUBNET_PRIVATE_IP_INSUFFICIENT

Insufficient private IPs in subnet to assign to created instances.

400

INVALID_SUBNET_ZONE_MISMATCH

Subnet not in the current zone.

400

INVALID_PARAMETER_SSH_KEY_DUPLICATE

Invalid SSH key. Duplicated values.

Last updated 4 months ago