edit-icon download-icon

Create a cluster

Last Updated: Apr 09, 2018


Create a cluster with a specified number of new nodes.

Request information

Request line (RequestLine)

  1. POST /clusters HTTP/1.1

Request line parameter (URI Param)


Special request header (RequestHead)

None. See Public request headers.

Request body (RequestBody)

  1. {
  2. "password": "password of the root account to log on to the Elastic Compute Service (ECS) instance",
  3. "region_id": "region ID",
  4. "instance_type": "ECS instance type",
  5. "name": "cluster name",
  6. "size": "number of nodes",
  7. "network_mode": "Virtual Private Cloud (VPC)",
  8. "vpc_id": "VPC ID",
  9. "vswitch_id": "VSwitch ID",
  10. "subnet_cidr": "container Classless Inter-Domain Routing (CIDR) block such as",
  11. "data_disk_category": "disk category",
  12. "data_disk_size": "disk size",
  13. "need_slb": "whether or not to create Server Load Balancer instance for the cluster",
  14. "ecs_image_id": "operating system image",
  15. "io_optimized": "whether or not to be I/O optimized",
  16. "release_eip_flag": "whether or not to release Elastic IP (EIP) after configuring the cluster"
  17. "rds_instances": "RDS instance ID"
  18. }

Request body explanation

Name Type RequiredDescription
namestringYesThe cluster name, which can contain uppercase English letters, lowercase English letters, Chinese characters, numbers, and hyphens (-).
sizeintegerYesThe number of ECS instances in the cluster.
instance_typestringYesThe ECS instance type code. For more information, see Instance type families.
network_modestringYesThe network mode of the cluster. Currently, only VPC is supported.
subnet_cidrstringYesThe CIDR block that can be used by the cluster, for example, This field needs to be configured only when the network mode is VPC.
vpc_id stringYesThe VPC ID. This field needs to be configured only when the network mode is VPC. For more information, see VPC overview.
vswitch_idstringYesThe VSwitch ID of the VPC. This field needs to be configured only when the network mode is VPC.
passwordstringYesThe password of the root account.
data_disk_categorystringYesThe disk category used by ECS. For more information, see Disk category.
data_disk_sizenumberYesThe disk size shared by nodes.
ecs_image_idstringNoThe ID of the system image used by ECS. For more information, see View image list.
io_optimizedstringNoDetermined according to the ECS instance rule. Optional values: none or optimized. We recommend that you pass in optimized because currently only VPC is supported as the network mode.
need_slbboolNoWhether or not to create the default simple routing Server Load Balancer instance for the cluster. The default value is true.
release_eip_flagboolNoWhether or not to release EIP after configuring the cluster. The default value is false.
rds_instancesarrayNoWhether or not to add the IP address of the ECS instance to the RDS instance whitelist.

ecs_image_id list

See View image list to obtain the ecs_image_id list. To customize the ECS image ID of the cluster, make sure the ECS image meets the following requirements:

  • Operating system: Ubuntu or CentOS.
  • The Linux Kernel version is equal to or later than 3.18, which is used to support overlayfs and overlay network.
  • The /etc/docker/key.json file is deleted from the image.

Response information

Response line (ResponseLine)

  1. HTTP/1.1 202 Accepted

Special response header (ResponseHead)

None. See Public response headers.

Response body (ResponseBody)

  1. {
  2. "cluster_id":"string",
  3. "request_id":"string",
  4. "task_id":"string"
  5. }


Request example

  1. POST /clusters HTTP/1.1
  2. <Public request headers>
  3. {
  4. "password": "TestPwd124",
  5. "region_id": "cn-beijing",
  6. "instance_type": "ecs.n1.small",
  7. "name": "my-test-cluster",
  8. "size": 1,
  9. "network_mode": "vpc",
  10. "vpc_id":"vpc-xxxx",
  11. "vswitch_id":"vsw-xxxx",
  12. "subnet_cidr":"",
  13. "data_disk_category": "cloud_ssd",
  14. "data_disk_size": 40,
  15. "need_slb":true,
  16. "ecs_image_id":"centos_7_04_64_20G_alibase_201701015",
  17. "io_optimized":"true",
  18. "release_eip_flag":false
  19. }

Return example

  1. HTTP/1.1 202 Accepted
  2. <Public response header>
  3. {
  4. "cluster_id": "cb95aa626a47740afbf6aa099b650d7ce",
  5. "request_id": "687C5BAA-D103-4993-884B-C35E4314A1E1",
  6. "task_id": "T-5a54309c80282e39ea00002f"
  7. }
Thank you! We've received your feedback.