CreateInstances

1. API Description

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

Prerequisites

• Query stock: call DescribeAvailableResources to check available resources.

• Query key pairs: call DescribeKeyPairs to check information on key pair ID.

• 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	ChargeType	Instance pricing model . PREPAID :subscription POSTPAID :pay-as-you-go Only PREPAID is supported currently.If you need POSTPAID ,contact us.
instanceTypeId	Yes	String	Instance model ID. To view specific values,you can call DescribeInstanceTypes .
internetChargeType	Yes	InternetChargeType	Network pricing model.
instanceChargePrepaid	No	ChargePrepaid	Details of the monthly subscription,including the purchase period,auto-renewal.It is required if the instanceChargeType is PREPAID .
imageId	No	String	Valid image ID. To obtain valid image ID,you can call DescribeImages ,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.
resourceGroupId	No	String	Resource group ID where the instances reside
instanceName	No	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	No	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. 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] .
amount	No	Integer	The number of instances to be purchased. Value range:[1,100].Default value:1. Value range: [1, 100] Default value: 1
password	No	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 keyId .
keyId	No	String	SSH key pair ID. Your SSH key pair contains several public keys that can be placed on your server.You can access your instance with the private key.Call DescribeKeyPairs to obtain key pair information. SSH key pairs and passwords cannot to set at the same time.SSH key pairs are not supported for Windows operating system. For example: key-YWD2QFOl You must and can only pass the value of either password or keyId .
internetMaxBandwidthOut	No	Integer	Public network bandwidth cap(Mbps). Default value:1 Mbps. The parameter value differs with different instance models. Value range: [1, +) Default value: 1
trafficPackageSize	No	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. Value range: [0.0, +)
subnetId	No	String	Subnet ID. Call DescribeVpcSubnets to check information on subnets created.
raidConfig	No	RaidConfig	Disk array configuration.
partitions	No	Array of Partition	Disk partition configuration. If the operating system is not installed,the partition cannot be set.
nic	No	Nic	NIC configuration.
ipxeUrl	No	String	iPXE URL. Pass in the value and install your OS via IPMI. You can choose to install OS using Netboot.See Deploy a Custom Image Using iPXE for more details.
userData	No	String	User Data. You can specify user data during instance installation. When the instance is launched for the first time, the user data is passed to the server as text and executed. The maximum supported data size is 32 KB.
enablePrimaryIPv6	No	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 . Default value: true
clusterId	No	String	Bandwidth cluster ID.
marketingOptions	No	MarketingInfo	Information on marketing campaigns.
tags	No	TagAssociation	Bound tags when creating resources. Tag keys must be unique.
enableGatewayMode	No	Boolean	Whether to enable Gateway Mode. Enables the host-bound IPs to act as a gateway for downstream traffic. Only elastic IPs are supported. Additional configuration on the host is required; when disabled, standard routing mode applies. Note: Gateway mode is not supported by default. Please contact Console Support if you need to enable this feature.

3. Output Parameters

Parameter Name	Type	Description
requestId	String	The unique request ID, which is returned for each request. RequestId is required for locating a problem.
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.uery 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.

4. Code Example

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


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

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
404	INVALID_ZONE_NOT_FOUND	Zone not found.
400	INVALID_PARAMETER_VALUE_RAID_DISK_SEQUENCE_RANGE	The disk sequence number in custom RAID configuration exceeds the number of disks supported by the instance type.
404	INVALID_SUBNET_NOT_FOUND	Subnet not found.
404	INVALID_INSTANCE_TYPE_NOT_FOUND	Instance type not found.
400	INVALID_PARAMETER_VALUE_RAID_DISK_SEQUENCE_DUPLICATE	Duplicated disk sequence number in the custom RAID configuration.
400	INVALID_PARAMETER_INSTANCE_LOGIN_CONFLICT	Password login and SSH key login cannot be specified at the same time.
400	INVALID_PARTITION_MALFORMED	Invalid file type or path format.
404	INVALID_IMAGE_NOT_FOUND	Image not found.
400	INVALID_PARAMETER_NIC_NAME_MALFORMED	Invalid public or private NIC name.
400	INVALID_INSTANCE_TYPE_RAID_NOT_SUPPORT	RAID level not supported for current instance model.
400	INVALID_RAID_CONFIG_FAST_CUSTOM_CONFLICT	Custom RAID and rapid RAID cannot be specified at the same time.
403	INVALID_CHARGE_TYPE_NOT_SUPPORT	The current account does not support the specified pricing model.
403	OPERATION_DENIED_INSTANCE_QUOTA_EXCEED	The number of machine creations has exceeded the total quota for the current Team.
400	INVALID_PARAMETER_SSH_KEY_DUPLICATE	Invalid SSH key pair; duplicate values exist.
400	INVALID_INSTANCE_TYPE_QUICK_RAID_NOT_SUPPORT	Rapid RAID not supported. Please customize RAID settings.
400	INVALID_PARAMETER_NIC_NAME_CONFLICT	Public NIC name and private NIC name cannot be the same.
400	INVALID_PARAMETER_VALUE_PASSWORD_MALFORMED	Invalid password.
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_SUBNET_PRIVATE_IP_INSUFFICIENT	Insufficient private IP addresses in the subnet to assign to the created instances.
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_PARAMETER_SSH_KEY_MALFORMED	Invalid SSH key format. Usually start with rsa .
400	INVALID_PARTITION_DUPLICATE_FILE_PATH	Duplicated file path or drive letters of the partition.
400	INVALID_PARAMETER_VALUE_RAID_DISK_MISMATCH	Disk quantity does not meet the RAID level requirement in custom RAID configuration.
400	INVALID_PARAMETER_INSTANCE_NAME_EXCEED	Invalid instance name format.
403	INVALID_PARTITION_IMAGE_NOT_SET	Custom partition are only supported for specific operating system.
400	INVALID_PARAMETER_HOSTNAME_EXCEED	Invalid hostname length. The specified hostname exceeds the maximum length.
400	INVALID_SUBNET_ZONE_MISMATCH	The subnet is not in the specified availability zone.
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_HOSTNAME_MALFORMED	Invalid hostname format.