You can call the CreateCluster operation to create a Container Service for Kubernetes (ACK) managed cluster. You can create one or more node pools when you create an ACK managed cluster.
Debugging
Request syntax
POST /clusters HTTP/1.1
Content-Type:application/json
{
"name" : "String",
"region_id" : "String",
"cluster_type" : "String",
"cluster_spec" : "String",
"kubernetes_version" : "String",
"resource_group_id" : "String",
"vpcid" : "String",
"vswitch_ids" : [ "String" ],
"pod_vswitch_ids" : [ "String" ],
"container_cidr" : "String",
"service_cidr" : "String",
"security_group_id" : "String",
"is_enterprise_security_group" : Boolean,
"node_cidr_mask" : "String",
"snat_entry" : Boolean,
"endpoint_public_access" : Boolean,
"load_balancer_spec" : "String",
"timezone" : "String",
"proxy_mode" : "String",
"enable_rrsa" : Boolean,
"tags" : [ {
"key" : "String",
"value" : "String"
} ],
"cluster_domain" : "String",
"custom_san" : "String",
"service_account_issuer" : "String",
"api_audiences" : "String",
"encryption_provider_key" : "String",
"timeout_mins" : Long,
"disable_rollback" : Boolean,
"deletion_protection" : Boolean,
"addons" : [ {
"name" : "String",
"config" : "String",
"disabled" : Boolean
} ],
"controlplane_log_ttl" : "String",
"controlplane_log_project" : "String",
"controlplane_log_components" : [ "String" ],
"nodepools" : [ {
"auto_scaling" : {
"enable" : Boolean,
"max_instances" : Long,
"min_instances" : Long,
"type" : "String",
"is_bond_eip" : Boolean,
"eip_internet_charge_type" : "String",
"eip_bandwidth" : Long
},
"kubernetes_config" : {
"cms_enabled" : Boolean,
"cpu_policy" : "String",
"labels" : [ {
"key" : "String",
"value" : "String"
} ],
"runtime" : "String",
"runtime_version" : "String",
"taints" : [ {
"key" : "String",
"value" : "String",
"effect" : "String"
} ],
"user_data" : "String"
},
"nodepool_info" : {
"name" : "String",
"resource_group_id" : "String"
},
"scaling_group" : {
"auto_renew" : Boolean,
"auto_renew_period" : Long,
"data_disks" : [ {
"category" : "String",
"size" : Long,
"encrypted" : "String",
"auto_snapshot_policy_id" : "String"
} ],
"image_id" : "String",
"instance_charge_type" : "String",
"instance_types" : [ "String" ],
"key_pair" : "String",
"login_password" : "String",
"period" : Long,
"period_unit" : "String",
"platform" : "String",
"rds_instances" : [ "String" ],
"spot_strategy" : "String",
"spot_price_limit" : [ {
"instance_type" : "String",
"price_limit" : "String"
} ],
"scaling_policy" : "String",
"security_group_id" : "String",
"security_group_ids" : [ "String" ],
"system_disk_category" : "String",
"system_disk_size" : Long,
"tags" : [ {
"key" : "String",
"value" : "String"
} ],
"vswitch_ids" : [ "String" ],
"multi_az_policy" : "String",
"on_demand_base_capacity" : Long,
"on_demand_percentage_above_base_capacity" : Long,
"spot_instance_pools" : Long,
"spot_instance_remedy" : Boolean,
"compensate_with_on_demand" : Boolean,
"internet_charge_type" : "String",
"internet_max_bandwidth_out" : Long
},
"tee_config" : {
"tee_enable" : Boolean
},
"management" : {
"enable" : Boolean,
"auto_repair" : Boolean,
"upgrade_config" : {
"auto_upgrade" : Boolean,
"surge" : Long,
"surge_percentage" : Long,
"max_unavailable" : Long
}
},
"count" : Long
} ]
}
Request parameters
Table 1. Request body parameters
Category | Parameter | Type | Required | Example | Description |
Basic configurations | name | String | Yes | cluster-demo | The cluster name. The name must be 1 to 63 characters in length, and can contain digits, letters, hyphens (-), and underscores (_). It cannot start with an underscore (_). |
region_id | String | Yes | cn-beijing | The ID of the region in which you want to deploy the cluster. | |
cluster_type | String | Yes | ManagedKubernetes | The cluster type is
| |
cluster_spec | String | No | ack.pro.small | The type of ACK managed cluster. Valid values:
Default value: For more information, see Overview of ACK Pro clusters. | |
kubernetes_version | String | No | 1.28.9-aliyun.1 | The Kubernetes version of the cluster. The Kubernetes versions supported by ACK are the same as the Kubernetes versions supported by open source Kubernetes. We recommend that you specify the latest Kubernetes version. If you do not specify this parameter, the latest Kubernetes version is used. You can create clusters of the latest two Kubernetes versions in the ACK console. If you want to create clusters of earlier Kubernetes versions, use the API. For more information about the Kubernetes versions supported by ACK, see Support for Kubernetes versions. | |
runtime | Array of runtime | No | {"name": "containerd", "version": "1.6.20"} | The name of the container runtime. The following types of runtime are supported by ACK.
Default value: | |
resource_group_id | String | No | rg-acfm3mkrure**** | The ID of the resource group to which the cluster belongs. You can use this parameter to isolate different clusters. | |
charge_type | String | No | PostPaid | The billing method of the cluster. The following resources are billed on a subscription basis: The internal-facing Server Load Balancer (SLB) instance of the cluster API server. Note A change was made to this parameter on October 15, 2024. For more information, see [Product announcement] Changes to the parameter behavior of the CreateCluster operation. Valid values:
Default value: | |
period | Long | No | 1 | The subscription duration. The subscription duration. This parameter takes effect and is required only when you set Valid values: 1, 2, 3, 6, 12, 24, 36, 48, and 60. Default value: 1. Note A change was made to this parameter on October 15, 2024. For more information, see [Product announcement] Changes to the parameter behavior of the CreateCluster operation. | |
period_unit | String | No | Month | The billing cycle. This parameter is required if Set the value to Note A change was made to this parameter on October 15, 2024. For more information, see [Product announcement] Changes to the parameter behavior of the CreateCluster operation. | |
auto_renew | boolean | No | true | Specifies whether to enable auto-renewal for the cluster. This parameter takes effect only when you set
Default value: Note A change was made to this parameter on October 15, 2024. For more information, see [Product announcement] Changes to the parameter behavior of the CreateCluster operation. | |
auto_renew_period | long | No | 1 | The auto-renewal cycle of the cluster. This parameter takes effect and is required only when Default value: 1. Note A change was made to this parameter on October 15, 2024. For more information, see [Product announcement] Changes to the parameter behavior of the CreateCluster operation. | |
Network parameters | vpcid | String | Yes | vpc-2zeik9h3ahvv2zz95**** | The ID of the virtual private cloud (VPC) in which you want to deploy the cluster. |
vswitch_ids | Array of String | Yes | ["vsw-2ze48rkq464rsdts1****"] | The IDs of vSwitches. You can specify one to five vSwitches. | |
pod_vswitch_ids | Array of String | No | ["vsw-2ze97jwri7cei0mpw****"] | If you select Terway as the network plug-in, you must allocate vSwitches to pods. Each pod vSwitch corresponds to a vSwitch of a worker node. The vSwitch of the pod and the vSwitch of the worker node must be in the same zone. Important We recommend that you set the subnet mask of the CIDR block of a pod vSwitch to no longer than 19 bits, but the subnet mask must not exceed 25 bits. Otherwise, the cluster network has only a limited number of IP addresses that can be allocated to the pods. As a result, the cluster may not function as expected. | |
container_cidr | String | No | 172.20.0.0/16 | The CIDR block of pods. This CIDR block cannot overlap with the CIDR block of the VPC in which the cluster is deployed. If the VPC is automatically created by the system, the default CIDR block of pods is 172.16.0.0/16. Important
| |
service_cidr | String | Yes | 172.21.0.0/20 | The CIDR block of Services. This CIDR block cannot overlap with the CIDR block of pods or the CIDR block of the VPC in which the cluster is deployed. If the VPC is automatically created by the system, the default CIDR block of Services is 172.19.0.0/20. | |
security_group_id | String | No | sg-bp1bdue0qc1g7k**** | The ID of an existing security group. You need to choose between this parameter and the | |
is_enterprise_security_group | Boolean | No | true | Specifies whether to create an advanced security group. This parameter takes effect only if Note To use a basic security group, make sure that the sum of the number of nodes in the cluster and the number of pods that use Terway does not exceed 2,000. Therefore, we recommend that you specify an advanced security group for a cluster that uses Terway as the network plug-in.
Default value: | |
node_cidr_mask | String | No | 25 | The maximum number of IP addresses that can be assigned to each node. This number is determined by the specified pod CIDR block. This parameter takes effect only if the cluster uses the Flannel plug-in. Default value: | |
snat_entry | Boolean | No | true | Specifies whether to configure SNAT rules for the VPC where your cluster is deployed.
If your applications require access to the Internet, we recommend that you set the value to true. Default value: false. Note If this feature is disabled when you create the cluster, you can manually enable this feature after the cluster is created. For more information, see Enable an existing ACK cluster to access the Internet. | |
endpoint_public_access | Boolean | No | true | Specifies whether to enable Internet access for the cluster. You can use an elastic IP address (EIP) to expose the API server. This way, you can access the cluster over the Internet.
Default value: | |
load_balancer_spec | String | No | slb.s2.small | The specification of the Server Load Balancer (SLB) instance that is created for the cluster API server. Valid values:
Default value: | |
Advanced settings | timezone | String | No | Asia/Shanghai | The time zone of the cluster. For more information, see Time zones. |
proxy_mode | String | No | ipvs | The kube-proxy mode. Valid values:
Default value: | |
enable_rrsa | Boolean | No | true | Specifies whether to enable the RAM Roles for Service Accounts (RRSA) feature. | |
tags | Array of tag | No | [{"key": "env", "value": "prod"}] | The labels that you want to add to the cluster. A label contains the following information:
| |
cluster_domain | String | No | cluster.local | The domain name of the cluster. The domain name can contain one or more parts that are separated by periods (.). Each part cannot exceed 63 characters in length, and can contain lowercase letters, digits, and hyphens (-). Each part must start and end with a lowercase letter or digit. | |
custom_san | String | No | cs.aliyun.com | Specifies custom subject alternative names (SANs) for the API server certificate to accept requests from specified IP addresses or domain names. Multiple IP addresses and domain names are separated by commas (,). | |
service_account_issuer | String | No | kubernetes.default.svc | Service accounts provide identities for pods when pods communicate with the For more information about | |
api_audiences | String | No | kubernetes.default.svc | Service accounts provide identities for pods when pods communicate with the For more information about | |
encryption_provider_key | String | No | 0fe64791-55eb-4fc7-84c5-c6c7cdca**** | The ID of a key that is managed by Key Management Service (KMS). The key is used to encrypt data stored in Secrets. For more information, see What is Key Management Service? Note This feature supports only ACK Pro clusters. | |
timeout_mins | Long | No | 60 | Specifies the timeout period of cluster creation. Unit: minutes. Default value: | |
disable_rollback | Boolean | No | true | Specifies whether to perform a rollback when the cluster fails to be created. Valid values:
Default value: | |
deletion_protection | Boolean | No | true | Specifies whether to enable deletion protection for the cluster. If deletion protection is enabled, the cluster cannot be deleted in the ACK console or by calling API operations. Valid values:
Default value: | |
Component configurations | addons | Array of addon | No | [{"name": "terway-eniip","config": ""}, {"name": "logtail-ds","config": "{\"IngressDashboardEnabled\":\"true\",\"sls_project_name\":\"your_sls_project_name\"}"}, {"name":"nginx-ingress-controller","config":"{\"IngressSlbNetworkType\":\"internet\"}"}] | The components that you want to install in the cluster. When you create a cluster, you can set the
Network plug-in: required. Supported network plug-ins are Flannel and Terway. Select one of the plug-ins for the cluster.
Volume plug-in: optional. Supported volume plug-in is Specify the Simple Log Service component: optional. We recommend that you enable Simple Log Service. If Simple Log Service is disabled, you cannot use the cluster auditing feature.
Ingress controller: optional. By default, the
Event center: optional. By default, the event center feature is enabled. You can use Kubernetes event centers to store and query events, and configure alerting based on events. You can use the Logstores that are associated with Kubernetes event centers for free within 90 days. For more information, see Create and use an event center. To enable the Kubernetes event center, specify the component in the following format: [{"name":"ack-node-problem-detector","config":"{\"sls_project_name\":\"your_sls_project_name\"}"}]. |
controlplane_log_ttl | String | No | 30 | The interval at which the logs of control plane components are collected. Valid values: 1 to 3000. Unit: days. Default value: | |
controlplane_log_project | String | No | k8s-log-xxx | The Simple Log Service project that is used to store the logs of control plane components. You can use an existing project or create one. If you choose to create a Simple Log Service project, the created project is named in the k8s-log-{ClusterID} format. | |
controlplane_log_components | Array of String | No | ["apiserver","kcm","scheduler","ccm"] | The list of control plane components for which you want to enable log collection. By default, the logs of the API server, KCM, scheduler, and cloud controller manager (CCM) are collected. | |
Node pool configurations | nodepools | Array of nodepool | No | The parameters of node pools. |
Response syntax
HTTP/1.1 200
Content-Type:application/json
{
"cluster_id" : "String",
"request_id" : "String",
"task_id" : "String"
}
Response parameters
Table 2. Response body parameters
Parameter | Type | Example | Description |
cluster_id | String | cb95aa626a47740afbf6aa099b650**** | The cluster ID. |
request_id | String | 687C5BAA-D103-4993-884B-C35E4314A1E1 | The request ID. |
task_id | String | T-5a54309c80282e39ea00002f | The task ID. |
Example: Create an ACK managed cluster
Sample requests
POST /clusters
<Common request headers>
{
"name":"managed Kubernetes cluster", // The name of the cluster. #required
"region_id":"cn-zhangjiakou", // The ID of the region where the cluster is deployed. #required
"cluster_type":"ManagedKubernetes", // The type of cluster. #required
"cluster_spec":"ack.pro.small", // The type of ACK managed cluster. ack.pro.small: ACK Pro cluster. ack.standard: ACK Basic cluster.
"kubernetes_version":"1.28.9-aliyun.1", // The Kubernetes version of the cluster. Only the latest three versions are available.
"resource_group_id":"rg-acfm3mkrure****",
"vpcid":"vpc-8vbh3b9a2f38urhls****", // The ID of the VPC in which you want to deploy the cluster. #required
"vswitch_ids":[ // The IDs of vSwitches that you want to use for the cluster. #required
"vsw-8vbmoffowsztjaawj****"
],
"pod_vswitch_ids":[ // Set this parameter if the cluster has Terway installed because each pod in the cluster uses a separate IP address.
"vsw-8vbo5fwyqiw0bbtlq****"
],
"container_cidr":"172.20.0.0/16", // The CIDR block of pods. #required. This parameter is optional if the cluster uses Terway as the network plug-in.
"service_cidr":"172.21.0.0/20", // The CIDR block of Services. #required
"security_group_id":"sg-8vb7grbyvlb10j0i****", // The existing security group that you want to use for the cluster. You must set the security_group_id or is_enterprise_security_group parameter.
"is_enterprise_security_group":true, // Specifies whether to create an advanced security group. You must set the security_group_id or is_enterprise_security_group parameter.
"node_cidr_mask":"25", // The maximum number of IP addresses that can be assigned to each node. This number is determined by the subnet mask of the specified CIDR block.
"snat_entry":true, // Specifies whether to configure SNAT rules for the VPC in which you want to deploy the cluster to enable Internet access for the cluster.
"endpoint_public_access":true, // Specifies whether to enable Internet access for the cluster.
"load_balancer_spec":slb.s2.small,
"timezone":"Asia/Shanghai", // The time zone of the cluster.
"proxy_mode":"ipvs", // The kube-proxy mode. Valid values: iptables and ipvs.
"enable_rrsa":true,
"tags":[ // The labels that you want to add to the cluster. The labels are applied to the ACK cluster, ECS instances, and nodes in the cluster.
{
"key":"tag-k",
"value":"tag-v"
}
],
"cluster_domain":"cluster.local", // The domain name of the cluster. Default value: cluster.local.
"custom_san":"cs.aliyuncs.com", // The custom SANs for the API server certificate.
"service_account_issuer":"kubernetes.default.svc", // Service account token volume projection. service_account_issuer is the issuer of the service account token, which corresponds to the iss field in the token payload.
"api_audiences":"kubernetes.default.svc", // Service account token volume projection. api-audiences are valid identifiers of tokens. Audiences are used to validate tokens at the API server side.
"encryption_provider_key":"8734596c-c0d6-4a63-a76e-fe72c7b0****", // The ID of the key that is managed by KMS. The key is used to encrypt Secrets in your cluster.
"timeout_mins":60, // The timeout period of cluster creation.
"disable_rollback":true, // Specifies whether to perform a rollback when the cluster fails to be created.
"deletion_protection":true, // Specifies whether to enable deletion protection for the cluster.
"addons":[ // The configurations of the components that you want to install in the cluster.
{
"name":"flannel" // To install the Terway plug-in, replace the value with {"name":"terway-eniip"}.
},
{
"name":"csi-plugin"
},
{
"name":"csi-provisioner"
},
{
"name":"logtail-ds",
"config":"{\"IngressDashboardEnabled\":\"true\"}"
},
{
"name":"ack-node-problem-detector",
"config":"{\"sls_project_name\":\"\"}"
},
{
"name":"nginx-ingress-controller", // The name of the component.
"config":"{\"IngressSlbNetworkType\":\"internet\"}", // The configuration of the component.
"disabled": true // Specifies whether to disable automatic installation.
},
{
"name":"arms-prometheus"
}
],
"controlplane_log_ttl" : "30",
"controlplane_log_project" : "k8s-log-xxx",
"controlplane_log_components" : ["apiserver","kcm","scheduler"],
"nodepools" : [ {
"auto_scaling" : {
"enable" : true,
"max_instances" : 10,
"min_instances" : 1,
"type" : "cpu"
},
"kubernetes_config" : {
"cms_enabled" : true,
"cpu_policy" : "none",
"labels" : [ {
"key" : "env",
"value" : "prod"
} ],
"runtime" : "containerd",
"runtime_version" : "1.6.20",
"taints" : [ {
"key" : "key",
"value" : "value",
"effect" : "NoSchedule"
} ],
"user_data" : "dGhpcyBpcyBhIGV4YW1wbGU=",
"node_name_mode" : "aliyun.com00055test"
},
"nodepool_info" : {
"name" : "cluster-demo",
"resource_group_id" : "rg-acfmyvw3wjmb****",
"type" : "ess"
},
"scaling_group" : {
"auto_renew" : true,
"auto_renew_period" : 1,
"data_disks" : [ {
"category" : "cloud_ssd",
"size" : 40,
"encrypted" : "true",
"auto_snapshot_policy_id" : "sp-2zej1nogjvovnz4z****",
"performance_level" : "PL1"
} ],
"image_id" : "aliyun_2_1903_x64_20G_alibase_20200529.vhd",
"instance_charge_type" : "PrePaid",
"instance_types" : [ "ecs.d1ne.2xlarge" ],
"key_pair" : "np-key-name",
"login_password" : "Hello1234",
"period" : 1,
"period_unit" : "Month",
"platform" : "AliyunLinux",
"rds_instances" : [ "rds-****" ],
"spot_strategy" : "NoSpot",
"spot_price_limit" : [ {
"instance_type" : "ecs.c6.large",
"price_limit" : "0.39"
} ],
"scaling_policy" : "release",
"security_group_id" : "sg-wz9a8g2mt6x5llu0****",
"security_group_ids" : [ "sg-wz9a8g2mt6x5llu0****" ],
"system_disk_category" : "cloud_efficiency",
"system_disk_size" : 120,
"system_disk_performance_level" : "PL1",
"tags" : [ {
"key" : "node-k-1",
"value" : "node-v-1"
} ],
"vswitch_ids" : [ "vsw-wz9mfnhmssud6eicu****" ],
"multi_az_policy" : "COST_OPTIMIZED",
"on_demand_base_capacity" : 0,
"on_demand_percentage_above_base_capacity" : 20,
"spot_instance_pools" : 5,
"spot_instance_remedy" : false,
"compensate_with_on_demand" : true,
"internet_charge_type" : "PayByTraffic",
"internet_max_bandwidth_out" : 5,
"image_type" : "AliyunLinux",
"deploymentset_id" : "ds-bp1d19mmbsv3jf6xxxxx",
"desired_size" : 0
},
"tee_config" : {
"tee_enable" : true
},
"management" : {
"enable" : false,
"auto_repair" : false,
"upgrade_config" : {
"auto_upgrade" : false,
"surge" : 0,
"surge_percentage" : 0,
"max_unavailable" : 1
}
},
"count" : 1,
"interconnect_mode" : "basic",
"interconnect_config" : {
"cen_id" : "cen-ey9k9nfhz0f*******",
"ccn_id" : "ccn-qm5i0i0q9yi*******",
"ccn_region_id" : "cn-shanghai",
"bandwidth" : 10,
"improved_period" : "1"
},
"max_nodes" : 10
} ]
}
Sample success responses
XML format
<cluster_id>cb95aa626a47740afbf6aa099b65****</cluster_id>
<task_id>687C5BAA-D103-4993-884B-C35E4314A1E1</task_id>
<request_id>T-5a54309c80282e39ea00002f</request_id>
JSON format
{
"cluster_id": "cb95aa626a47740afbf6aa099b65****",
"request_id": "687C5BAA-D103-4993-884B-C35E4314A1E1",
"task_id": "T-5a54309c80282e39ea00002f"
}
Error codes
For a list of error codes, see Service error codes.