You can call CreateCluster to create a dedicated cluster and add a specified number of nodes to the cluster.

Notes: You must set parameters correctly. Otherwise, you may fail to create a cluster. When you create a cluster in the Container Service console, you can click Generate API Request Parameters on the Create Kubernetes Cluster page to view all parameters. For more information, see Generate API request parameters.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request headers

This operation uses the common request header only. For more information, see Common parameters.

Request syntax

POST /clusters HTTPS|HTTP

Request parameters

Parameter Type Required Example Description
region_id String Yes cn-beijing

The ID of the region where the cluster is deployed.

name String No test-cluster

The name of the cluster. The name can contain uppercase letters, lowercase letters, Chinese characters, digits, and hyphens (-).

key_pair String Yes key_pair-xxxxxx

The name of the key pair. You must set key_pair or login_password.

snat_entry Boolean Yes true

Specifies whether to enable Source Network Address Translation (SNAT).

  • If the VPC has Internet access, set this parameter to false.
  • If the VPC has no Internet access, valid values include:
    • true: configures SNAT. This enables the cluster to access the Internet.
    • false: does not configure SNAT. The prevents the cluster from accessing the Internet.
login_password String Yes Yourpasswd1234

The SSH logon password. The password must be 8 to 30 characters in length and contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. You must set login_password or key_pair.

master_system_disk_category String Yes cloud_ssd

The system disk type of master nodes. Valid values:

  • cloud_efficiency: ultra disks.
  • cloud_ssd: SSDs.
master_system_disk_size Integer Yes 120

The system disk size of a master node. Unit: GiB.

num_of_nodes Integer Yes 3

The number of worker nodes. Valid values: 0 to 100.

worker_system_disk_category String Yes cloud_efficiency

The system disk type of worker nodes.

worker_instance_types List<String> Yes ["ecs.i1.2xlarge"]

The ECS instance types of worker nodes. For more information, see Instance families.

master_instance_types List<String> Yes ["ecs.n4.xlarge","ecs.n4.xlarge","ecs.n4.xlarge"]

The ECS instance types of master nodes. For more information, see .Instance families

master_vswitch_ids List<String> Yes ["vsw-2ze4jvvvade1yk899****","vsw-2ze4jvvvade1yk899****","vsw-2ze4jvvvade1yk899****"]

The VSwitch IDs of master nodes. Specify one to three VSwitch IDs. We recommend that you specify three VSwitches in different zones to ensure high availability.

worker_system_disk_size Integer Yes 120

The system disk size of a worker node. Unit: GiB.

worker_vswitch_ids List<String> Yes ["vsw-2ze4jvvvade1yk899****"]

The VSwitch IDs of worker nodes.

cluster_type String Yes Kubernetes

The type of the cluster. Cluster types include managed Kubernetes clusters, dedicated Kubernetes clusters, serverless Kubernetes clusters, and edge clusters.

tags Array No [{"key":"tier","value":"backend"}]

The tags of the cluster.

  • key: the name of the tag.
  • value: the value of the tag.
endpoint_public_access Boolean No true

Specifies whether to enable Internet access to the API server. Valid values:

  • true: enables Internet access to the API server. Default value: true.
  • false: disables Internet access to the API server. The API server only allows internal access.
kubernetes_version String No 1.16.6-aliyun.1

The Kubernetes version. We recommend that you use the latest version.

timeout_mins Integer No 60

The timeout period in minutes during which a resource creation operation must be completed. Default value: 60.

disable_rollback Boolean No true

Specifies whether to retain all resources if the operation fails. Valid values:

  • true: retains the resources.
  • false: releases the resources.

Default value: true. We recommend that you use the default value.

ssh_flags Boolean No true

Specifies whether to enable SSH logon. Valid values:

  • true: enables SSH logon.
  • false: disables SSH logon.
cloud_monitor_flags Boolean No true

Specifies whether to install the CloudMonitor agent. Valid values:

  • true: installs the CloudMonitor agent.
  • false: does not install the CloudMonitor agent.
deletion_protection Boolean No true

Specifies whether to enable cluster deletion protection. If this option is enabled, the cluster cannot be deleted by operations in the console or API operations.

node_cidr_mask String No 26

The prefix length of the node CIDR block.

proxy_mode String No ipvs

The kube-proxy mode. Valid values: iptables and ipvs. Default value: iptables.

os_type String No Linux

The operating system of the nodes that run pods. For example, Linux and Windows.

platform String No CentOS

The architecture of the nodes that run pods, for example, x86.

node_port_range String No 30000-32767

The service port range of nodes. Valid values: 30000 to 65535.

master_instance_charge_type String No PrePaid

The billing method of master nodes. Valid values:

  • PrePaid: subscription.
  • PostPaid: pay-as-you-go.

Default value: PostPaid.

worker_instance_charge_type String No PrePaid

The billing method of worker nodes. Valid values:

  • PrePaid: subscription.
  • PostPaid: pay-as-you-go.

Default value: PostPaid.

master_period Integer No 1

The subscription duration of master nodes. This parameter takes effect and is required only if master_instance_charge_type is set to PrePaid. If master_period_unit is set to Month, valid values of master_period include 1, 2, 3, 6, and 12.

worker_period Integer No 1

The subscription duration of worker nodes. This parameter takes effect and is required only if worker_instance_charge_type is set to PrePaid. If worker_period_unit is set to Month, valid values of worker_period include 1, 2, 3, 6, and 12.

cpu_policy String No none

The CPU policy. For Kubernetes 1.12.6 and later, valid values of cpu_policy include static and none. Default value: none.

worker_period_unit String No Month

The unit of the subscription duration. This parameter is required if worker_instance_charge_type is set to PrePaid. A value of Month indicates that the subscription duration is measured in months.

master_auto_renew Boolean No true

Specifies whether to enable auto renewal for master nodes. This parameter takes effect only if master_instance_charge_type is set to PrePaid. Valid values:

  • true: enables auto renewal for master nodes.
  • false: disables auto renewal for master nodes.
master_auto_renew_period Integer No 6

The auto renewal period for master nodes. This parameter takes effect and is required only if master_instance_charge_type is set to PrePaid and master_auto_renew is set to true. If master_period_unit is set to Month, valid values of master_auto_renew_period include 1, 2, 3, 6, and 12.

worker_auto_renew Boolean No true

Specifies whether to enable auto renewal for worker nodes. Valid values:

  • true: enables auto renewal for worker nodes.
  • false: disables auto renewal for worker nodes.
worker_auto_renew_period Integer No 6

The auto renewal period for worker nodes. This parameter takes effect and is required only if worker_instance_charge_type is set to PrePaid and worker_auto_renew is set to true. If worker_period_unit is set to Month, valid values of worker_auto_renew_period include 1, 2, 3, 6, and 12.

master_period_unit String No Month

The unit of the subscription duration. This parameter is required if worker_instance_charge_type is set to PrePaid. A value of Month indicates that the subscription duration is measured in months.

master_count Integer No 3

The number of master nodes. Valid values: 3 and 5. Default value: 3.

runtime Json No {"name":"docker","version":"19.03.5"}

The runtime of containers. Default value: docker. Specify the runtime name and version.

worker_data_disk Boolean No true

Specifies whether to mount data disks to worker nodes. Valid values:

  • true: mounts data disks to worker nodes.
  • false: does not mount data disks to worker nodes.
vpcid String No vpc-2ze8b1o12tx3ocbzx****

Optional. The ID of the VPC. If this parameter is not specified, the system automatically creates a VPC that uses CIDR block 192.168.0.0/16.

Notes: You must specify both the vpcid and vswitch_ids parameters or leave both parameters empty.

security_group_id String No sg-2ze6ess9kho6fdn9****

The ID of the security group to which the ECS instances in the cluster belong.

container_cidr String No 172.20.0.0/16

The CIDR block of containers. This CIDR block cannot overlap with that of the VPC. If the VPC is automatically created by the system, the CIDR block of containers is set to 172.16.0.0/16.

service_cidr String No 172.21.0.0/20

The CIDR block of services. This CIDR block cannot overlap with that of the VPC or containers. If the VPC is automatically created by the system, the CIDR block of services is set to 172.19.0.0/20.

addons Array No [{"name":"flannel"},{"name":"flexvolume"},{"name":"alicloud-disk-controller"},{"name":"logtail-ds","config":"{"IngressDashboardEnabled":"true"}"},{"name":"nginx-ingress-controller","config":"{"IngressSlbNetworkType":"internet"}"}]

The add-ons to be installed for the cluster.

  • Configure the parameters of add-ons as follows:
    • name: Required. The name of the add-on.
    • version: Optional. The default value is the latest version.
    • config: Optional.
  • Network plug-in: Select Flannel or Terway.
  • Log Service: Optional. If Log Service is disabled, the cluster audit feature is unavailable.
  • Ingress: The nginx-ingress-controller component is installed by default.
worker_data_disks Array No [{"category":"cloud","size":"40","encrypted":"false"}]

The data disk configurations of worker nodes, such as the disk type and disk size. This parameter takes effect only if worker_data_disk is set to true.

  • category: the type of the data disks. Valid values:
    • cloud: basic disks.
    • cloud_efficiency: ultra disks.
    • cloud_ssd: SSDs.
  • size: the size of a data disk. Unit: GiB.
  • encrypted: specifies whether to encrypt data disks. Valid values: true and false.
taints Array No

The taints that are added to nodes to ensure appropriate scheduling of pods. If a pod has a toleration that matches the taint on a node, this pod can be scheduled to the node.

Response parameters

Parameter Type Example Description
cluster_id String cb95aa626a47740afbf6aa099b650****

The ID of the cluster.

request_id String 687C5BAA-D103-4993-884B-C35E4314A1E1

The ID of the request.

task_id String T-5a54309c80282e39ea00002f

The ID of the task. The task ID is automatically assigned by the system and can be used to query task status.

Examples

Sample requests

POST /clusters HTTP/1.1
Common request header
{
    "cluster_type": "Kubernetes",
    "name": "test-cluster",
    "region_id": "cn-beijing",
    "snat_entry": "true",
    "key_pair": "key_pair-xxxxxx",
    "login_password": "Yourpasswd1234",
    "master_system_disk_category": "cloud_ssd",
    "master_system_disk_size": "120",
    "num_of_nodes": "3",
    "worker_system_disk_category": "cloud_efficiency",
    "worker_system_disk_size": "120",
    "master_instance_types": ["ecs.n4.xlarge","ecs.n4.xlarge","ecs.n4.xlarge"],
    "master_vswitch_ids": ["vsw-2ze4jvvvade1yk899****","vsw-2ze4jvvvade1yk899****","vsw-   2ze4jvvvade1yk899****"],
    "tags": [{"key":"tier","value":"backend"}],
    "worker_instance_types": ["ecs.i1.2xlarge"],
    "worker_vswitch_ids": ["vsw-2ze4jvvvade1yk899****"]
}

Sample success responses

XML format

<cluster_id>cb95aa626a47740afbf6aa099b650****</cluster_id>
<request_id>687C5BAA-D103-4993-884B-C35E4314A1E1</request_id>
<task_id>T-5a54309c80282e39ea00002f</task_id>

JSON format

{
    "cluster_id": "cb95aa626a47740afbf6aa099b650****",
    "request_id": "687C5BAA-D103-4993-884B-C35E4314A1E1",
    "task_id": "T-5a54309c80282e39ea00002f"
}

Error codes

For a list of error codes, visit the API Error Center.