You can call the CreateCluster operation to create a Container Service for Kubernetes (ACK) cluster. ACK clusters include ACK managed clusters, ACK dedicated clusters, ACK Serverless clusters, ACK Edge clusters, ACK clusters that support sandboxed containers, and registered clusters. For more information about how to create different types of ACK clusters, see the following usage notes.
Operation description
This topic describes all request parameters for creating a Container Service for Kubernetes (ACK) cluster. For more information about how to call the API to create each type of ACK cluster, refer to the following topics:
- Call the API to create an ACK managed cluster
- Call the API to create an ACK dedicated cluster
- Call the API to create an ACK Serverless cluster
- Call the API to create an ACK Edge cluster
- Call the API to create an ACK Basic cluster that supports sandboxed containers
- Call the API to create an ACK Pro cluster that supports sandboxed containers
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action
policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resources
is used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
Operation | Access level | Resource type | Condition key | Associated operation |
---|---|---|---|---|
cs:CreateCluster | create |
|
| none |
Request syntax
POST /clusters HTTP/1.1
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
body | object | No | The request body parameters. | |
name | string | Yes | The cluster name. The name must be 1 to 63 characters in length, and can contain digits, letters, and hyphens (-). The name cannot start with a hyphen (-). | cluster-demo |
region_id | string | Yes | The ID of the region in which the cluster is deployed. | cn-beijing |
cluster_type | string | Yes |
| Kubernetes |
cluster_spec | string | No | After you set
| ack.pro.small |
kubernetes_version | string | No | 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 that run earlier Kubernetes versions, use the ACK API. For more information about the Kubernetes versions supported by ACK, see Support for Kubernetes versions. | 1.16.9-aliyun.1 |
runtime | runtime | No | The container runtime. The default container runtime is Docker. containerd and Sandboxed-Container are also supported. For more information about how to select a proper container runtime, see Comparison among Docker, containerd, and Sandboxed-Container. | |
vpcid | string | No | The virtual private cloud (VPC) in which you want to deploy the cluster. This parameter is required. | vpc-2zeik9h3ahvv2zz95**** |
pod_vswitch_ids | array | No | If you select Terway as the network plug-in, you must allocate vSwitches to pods. For each vSwitch that allocates IP addresses to worker nodes, you must select a vSwitch in the same zone to allocate IP addresses to pods. Note
We recommend that you select pod vSwitches whose subnet masks that do not exceed 19 bits in length. The maximum subnet mask length of a pod vSwitch is 25 bits. If you select a pod vSwitch whose subnet mask exceeds 25 bits in length, the IP addresses that can be allocated to pods may be insufficient.
| |
string | No | If you select Terway as the network plug-in, you must allocate vSwitches to pods. For each vSwitch that allocates IP addresses to worker nodes, you must select a vSwitch in the same zone to allocate IP addresses to pods. Note
We recommend that you select pod vSwitches whose subnet mask lengths are no longer than 19 bits. The maximum subnet mask length of a pod vSwitch is 25 bits. If you select a pod vSwitch whose subnet mask length is longer than 25 bits, the IP addresses that can be allocated to pods may be insufficient.
| vsw-2ze97jwri7cei0mpw**** | |
container_cidr | string | No | The pod CIDR block. You can specify 10.0.0.0/8, 172.16-31.0.0/12-16, 192.168.0.0/16, or their subnets as the pod CIDR block. The pod CIDR block cannot overlap with the CIDR block of the VPC in which the cluster is deployed and the CIDR blocks of existing clusters in the VPC. You cannot modify the pod CIDR block after you create the cluster. For more information about how to plan the network of an ACK cluster, see Plan the network of an ACK cluster. Note
This parameter is required if the cluster uses the Flannel plug-in.
| 172.20.0.0/16 |
service_cidr | string | Yes | The Service CIDR block. Valid values: 10.0.0.0/16-24, 172.16-31.0.0/16-24, and 192.168.0.0/16-24. The Service CIDR block cannot overlap with the VPC CIDR block (10.1.0.0/21) or the CIDR blocks of existing clusters in the VPC. You cannot modify the Service CIDR block after the cluster is created. By default, the Service CIDR block is set to 172.19.0.0/20. | 172.21.0.0/20 |
security_group_id | string | No | The ID of an existing security group. You must specify this parameter or the | sg-bp1bdue0qc1g7k**** |
is_enterprise_security_group | boolean | No | 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.
Default value: | true |
snat_entry | boolean | No | Specifies whether to configure SNAT rules for the VPC in which your cluster is deployed. Valid values:
Note
If this feature is disabled when you create the cluster, you can also manually enable this feature after you create the cluster. For more information, see Enable an existing ACK cluster to access the Internet.
Default value: | true |
endpoint_public_access | boolean | No | 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. Valid values:
Default value: | true |
ssh_flags | boolean | No | Specifies whether to enable SSH logon. If this parameter is set to true, you can log on to master nodes in an ACK dedicated cluster over the Internet. This parameter does not take effect for ACK managed clusters. Valid values:
Default value: | true |
timezone | string | No | The time zone of the cluster. | Asia/Shanghai |
node_cidr_mask | string | No | 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. This parameter takes effect only if the cluster uses the Flannel plug-in. Default value: | 25 |
user_ca | string | No | The custom Certificate Authority (CA) certificate used by the cluster. | -----BEGIN CERTIFICATE-----**** |
user_data | string | No | The user data of nodes. | IyEvdXNyL2Jpbi9iYXNoCmVjaG8gIkhlbGxvIEFD**** |
cluster_domain | string | No | 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. | cluster.local |
node_name_mode | string | No | The custom node name. A custom node name consists of a prefix, a node IP address, and a suffix.
For example, if the node IP address is 192.168.0.55, the prefix is aliyun.com, the IP substring length is 5, and the suffix is test, the node name will aliyun.com00055test. | aliyun.com00055test |
custom_san | string | No | The custom subject alternative names (SANs) for the API server certificate to accept requests from specified IP addresses or domain names. Separate multiple IP addresses and domain names with commas (,). | cs.aliyun.com |
encryption_provider_key | string | No | The ID of the Key Management Service (KMS) key that is used to encrypt the system disk. For more information, see What is KMS? Note
The key can be used only in ACK Pro clusters.
| 0fe64791-55eb-4fc7-84c5-c6c7cdca**** |
service_account_issuer | string | No | Service accounts provide identities for pods when pods communicate with the For more information about | kubernetes.default.svc |
api_audiences | string | No | Service accounts provide identities for pods when pods communicate with the For more information about | kubernetes.default.svc |
image_id | string | No | The custom image. By default, the image provided by ACK is used. You can select a custom image to replace the default image. For more information, see Use a custom image to create an ACK cluster. | m-bp16z7xko3vvv8gt**** |
rds_instances | array | No | The ApsaraDB RDS instances. The pod CIDR block and node CIDR block are added to the whitelists of the ApsaraDB RDS instances. We recommend that you add the pod CIDR block and node CIDR block to the whitelists of the ApsaraDB RDS instances in the ApsaraDB RDS console. If the RDS instances are not in the Running state, new nodes cannot be added to the cluster. | |
string | No | The ApsaraDB RDS instances. The pod CIDR block and node CIDR block are added to the whitelists of the ApsaraDB RDS instances. We recommend that you add the pod CIDR block and node CIDR block to the whitelists of the ApsaraDB RDS instances in the ApsaraDB RDS console. If the RDS instances are not in the Running state, new nodes cannot be added to the cluster. | rm-2zev748xi27xc**** | |
tags | array | No | The labels that you want to add to nodes. You must add labels based on the following rules:
| |
tag | No | The labels that you want to add to nodes. You must add labels based on the following rules:
| ||
addons | array | No | The components that you want to install in the cluster. When you create a cluster, you can configure the Network plug-in: required. The Flannel and Terway plug-ins are supported. Select one of the plug-ins for the cluster.
Volume plug-in: optional. Only the 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 ACK event centers to store and query events and configure alerts. You can use the Logstores that are associated with ACK event centers free of charge within 90 days. For more information, see Create and use an event center. To enable the event center feature, specify the event center component in the following format: [{"name":"ack-node-problem-detector","config":"{"sls_project_name":"your_sls_project_name"}"}]. | |
addon | No | The component that you want to install in the cluster. When you create a cluster, you can configure the | ||
taints | array | No | The taints that you want to add to nodes. Taints can be used together with tolerations to avoid scheduling pods to specific nodes. For more information, see taint-and-toleration. | |
taint | No | The taint. Taints can be used together with tolerations to avoid scheduling pods to specific nodes. For more information, see taint-and-toleration. | ||
cloud_monitor_flags | boolean | No | Specifies whether to install the CloudMonitor agent. Valid values:
Default value: | true |
platform | string | No | The OS distribution that is used. Valid values:
Default value: | CentOS |
os_type | string | No | The type of OS. Valid values:
Default value: | Linux |
soc_enabled | boolean | No | Specifies whether to enable security hardening based on Multi-Level Protection Scheme (MLPS). For more information, see ACK security hardening based on MLPS. Valid values:
Default value: | false |
security_hardening_os | boolean | No | Specifies whether to enable Alibaba Cloud Linux Security Hardening. Valid values:
Default value: | false |
cis_enableddeprecated | boolean | No | This parameter is deprecated. Use security_hardening_os instead. | false |
cpu_policy | string | No | The CPU management policy of nodes in the node pool. The following policies are supported if the Kubernetes version of the cluster is 1.12.6 or later:
Default value: | none |
proxy_mode | string | No | The kube-proxy mode. Valid values:
Default value: | ipvs |
node_port_range | string | No | The node port range. Valid values: 30000 to 65535. Default value: | 30000~32767 |
master_vswitch_ids | array | No | The IDs of the vSwitches that are specified for master nodes. You can specify up to three vSwitches. We recommend that you specify three vSwitches in different zones to ensure high availability. The number of vSwitches must be the same as the value of the | |
string | No | The IDs of the vSwitches that are specified for master nodes. You can specify up to three vSwitches. We recommend that you specify three vSwitches in different zones to ensure high availability. The number of vSwitches must be the same as the value of the | vsw-2ze3ds0mdip0hdz8i**** | |
key_pair | string | No | The name of the key pair. You must specify this parameter or the | secrity-key |
login_password | string | No | The password for SSH logon. You must specify this parameter or | Hello@1234 |
master_count | long | No | The number of master nodes. Valid values: Default value: | 3 |
master_instance_types | array | No | The instance types of master nodes. For more information, see Overview of instance families. | |
string | No | The instance types of master nodes. The number of instance types must be the same as the value of the | ecs.n4.xlarge | |
master_system_disk_category | string | No | The system disk type of master nodes. Valid values:
Default value: | cloud_ssd |
master_system_disk_size | long | No | The system disk size of master nodes. Valid values: 40 to 500. Unit: GiB. Default value: | 120 |
master_system_disk_performance_level | string | No | The performance level (PL) of the system disk that you want to use for master nodes. This parameter takes effect only for ESSDs. For more information about the relationship between disk PLs and disk sizes, see ESSDs . | PL1 |
master_system_disk_snapshot_policy_id | string | No | The ID of the automatic snapshot policy that is used by the system disk specified for master nodes. | sp-2zej1nogjvovnz4z**** |
master_instance_charge_type | string | No | The billing method of master nodes. Valid values:
Default value: | PrePaid |
master_period_unit | string | No | The billing cycle of the master nodes in the cluster. This parameter is required if master_instance_charge_type is set to Valid value: | Month |
master_period | long | No | The subscription duration of master nodes. This parameter takes effect and is required only when Valid values: 1, 2, 3, 6, 12, 24, 36, 48, and 60. Default value: 1. | 1 |
master_auto_renew | boolean | No | Specifies whether to enable auto-renewal for master nodes. This parameter takes effect only when
Default value: | true |
master_auto_renew_period | long | No | The auto-renewal duration. This parameter takes effect and is required only when the subscription billing method is selected for master nodes. Valid values: 1, 2, 3, 6, and 12. Default value: 1. | 1 |
num_of_nodesdeprecated | long | No | The number of worker nodes. Valid values: 0 to 100. | 3 |
vswitch_ids | array | No | The vSwitches for nodes in the cluster. This parameter is required if you create an ACK managed cluster that does not contain nodes. | |
string | No | The vSwitches for nodes in the cluster. This parameter is required if you create an ACK managed cluster that does not contain nodes. | vsw-2ze3ds0mdip0hdz8i**** | |
worker_vswitch_idsdeprecated | array | No | The vSwitches for worker nodes. Each worker node is allocated a vSwitch.
| |
string | No | The vSwitches for worker nodes. You can specify 1 to 20 vSwitches. We recommend that you select vSwitches in different zones to ensure high availability.
| vsw-2ze3ds0mdip0hdz8i**** | |
worker_instance_typesdeprecated | array | No | The instance configurations of worker nodes. | |
string | No | The instance types of worker nodes. You must specify at least one instance type. For more information, see Overview of ECS instance families. Note
The instance types are listed in descending order of priority. If the system fails to create worker nodes with the instance type of the highest priority, the system attempts to create worker nodes with the instance type of the next highest priority.
| ecs.n4.large | |
worker_system_disk_categorydeprecated | string | No | The system disk type of worker nodes. For more information, see Overview of Block Storage. Valid values:
Default value: | cloud_efficiency |
worker_system_disk_sizedeprecated | long | No | The system disk size of worker nodes. Unit: GiB. Valid values: 40 to 500. The value of this parameter must be at least 40 and greater than or equal to the image size. Default value: | 120 |
worker_system_disk_snapshot_policy_iddeprecated | string | No | The ID of the automatic snapshot policy that is used by the system disk specified for worker nodes. | sp-2zej1nogjvovnz4z**** |
worker_system_disk_performance_leveldeprecated | string | No | If the system disk is an ESSD, you can specify the PL of the ESSD. For more information, see Enterprise SSDs. Valid values:
| PL1 |
worker_data_disksdeprecated | array<object> | No | The configurations of the data disks that you want to mount to worker nodes. The configurations include the disk type and disk size. | |
object | No | The configurations of data disks. | ||
category | string | Yes | The data disk type. | cloud_essd |
encrypted | string | No | Specifies whether to encrypt the data disk. Valid values:
Default value: | true |
size | string | Yes | The data disk size. Valid values: 40 to 32767. Unit: GiB. | 120 |
performance_level | string | No | The PL of the data disk. This parameter takes effect only for ESSDs. You can specify a higher PL if you increase the size of a data disk. For more information, see Enterprise SSDs. | PL1 |
worker_instance_charge_typedeprecated | string | No | The billing method of worker nodes. Valid values:
Default value: PostPaid. | PrePaid |
worker_period_unitdeprecated | string | No | The billing cycle of worker nodes. This parameter is required if worker_instance_charge_type is set to Set the value to | Month |
worker_perioddeprecated | long | No | The subscription duration of worker nodes. This parameter takes effect and is required only when Valid values: 1, 2, 3, 6, 12, 24, 36, 48, and 60. Default value: 1. | 1 |
worker_auto_renewdeprecated | boolean | No | Specifies whether to enable auto-renewal for worker nodes. This parameter takes effect and is required only when
Default value: | true |
worker_auto_renew_perioddeprecated | long | No | The auto-renewal duration. This parameter takes effect and is required only when the subscription billing method is selected for worker nodes. Valid values: 1, 2, 3, 6, and 12. | 1 |
instances | array | No | The existing ECS instances that are specified as worker nodes for the cluster. Note
This parameter is required if you create worker nodes on existing ECS instances.
| |
string | No | The existing ECS instances that are specified as worker nodes for the cluster. Note
This parameter is required if you create worker nodes on existing ECS instances.
| i-2ze4zxnm36vq00xn**** | |
format_disk | boolean | No | Specifies whether to mount a data disk to a node that is created based on an existing ECS instance. Valid values:
Default value: How data disks are mounted:
| false |
keep_instance_name | boolean | No | Specifies whether to retain the names of existing ECS instances that are used in the cluster. Valid values:
Default value: | true |
service_discovery_types | array | No | The type of service discovery that is implemented in the
By default, this parameter is not specified. | |
string | No | The type of service discovery that is implemented in the
By default, this parameter is not specified. | PrivateZone | |
nat_gateway | boolean | No | Specifies whether to create a NAT gateway and configure SNAT rules if you create an ACK Serverless cluster. Valid values:
Default value: | true |
zone_iddeprecated | string | No | The ID of the zone to which the cluster belongs. This parameter takes effect only for ACK Serverless clusters. If you create an ACK Serverless cluster, you must specify | cn-beiji**** |
zone_ids | array | No | List of availability zone IDs in the region where the cluster resides. This parameter is specific to ACK managed clusters.
When creating an ACK managed cluster, if | |
string | No | Availability Zone ID of the region where the cluster belongs, a virtual switch will be automatically created in this zone. | cn-beijing-h | |
profile | string | No | If you set
| Default |
logging_type | string | No | Enables Simple Log Service for the cluster. This parameter takes effect only for ACK Serverless clusters. Valid value: | SLS |
controlplane_log_ttl | string | No | The retention period of control plane logs in days. | 30 |
controlplane_log_project | string | No | 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-xxx |
controlplane_log_components | array | No | The list of control plane components for which you want to enable log collection. By default, the logs of kube-apiserver, kube-controller-manager, and kube-scheduler are collected. | |
string | No | The control plane component for which you want to enable log collection. By default, the logs of kube-apiserver, kube-controller-manager, and kube-scheduler are collected. | ["apiserver","kcm","scheduler"] | |
deletion_protection | boolean | No | Specifies whether to enable cluster deletion protection. If this option is enabled, the cluster cannot be deleted in the ACK console or by calling API operations. Valid values:
Default value: | true |
disable_rollbackdeprecated | boolean | No | Specifies whether to perform a rollback when the cluster fails to be created. Valid values:
Default value: | true |
timeout_mins | long | No | Specifies the timeout period of cluster creation. Unit: minutes. Default value: | 60 |
image_type | string | No | The type of OS distribution that you want to use. To specify the node OS, we recommend that you use this parameter. Valid values:
Default value: | AliyunLinux |
load_balancer_spec | string | No | The specification of the Server Load Balancer (SLB) instance. Valid values:
Default value: | slb.s2.small |
enable_rrsa | boolean | No | Specifies whether to enable the RAM Roles for Service Accounts (RRSA) feature. | true |
resource_group_id | string | No | The ID of the resource group to which the cluster belongs. You can use resource groups to isolate clusters. | rg-acfm3mkrure**** |
charge_type | string | No | The billing method of the cluster. The following resources are billed on a subscription basis: ECS instances in node pools. The internal-facing SLB instance associated with the API server. Valid values: PrePaid: subscription. PostPaid: pay-as-you-go. Default value: PostPaid. | 1 |
period_unit | string | No | The billing cycle. This parameter is required if charge_type is set to PrePaid. Set the value to Month. Subscription clusters are billed only on a monthly basis. | Month |
period | long | No | The subscription duration of the instance. This parameter takes effect and is required only when you set charge_type to PrePaid. Valid values: 1, 2, 3, 6, 12, 24, 36, 48, and 60. Default value: 1. | FY2023 |
auto_renew | boolean | No | Specifies whether to enable auto-renewal, which takes effect only when the Possible values:
Default value: | true |
auto_renew_period | long | No | Renewal period, which takes effect only when Prepaid and Auto-Renewal are selected. When | 1 |
ip_stack | string | No | The IP stack of the cluster. | Optional value: ipv4 (Single stack) or ipv6 (Dual Stack) Default value: IPV4 |
access_control_list | array | No | The network access control list (ACL) of the SLB instance associated with the API server if the cluster is a registered cluster. | |
string | No | The ACL rule of the SLB instance associated with the API server if the cluster is a registered cluster. | 192.168.1.0/24 | |
nodepools | array | No | The list of node pools. | |
nodepool | No | The node pool configurations. | ||
load_balancer_id | string | No | Specifies the CLB instance ID for accessing the APIServer. When this parameter is set, an APIServer CLB will no longer be automatically created. | lb-wz9t256gqa3vbouk**** |
Response parameters
Examples
Sample success responses
JSON
format
{
"cluster_id": "cb95aa626a47740afbf6aa099b650****",
"request_id": "687C5BAA-D103-4993-884B-C35E4314A1E1",
"task_id": "T-5a54309c80282e39ea00002f"
}
Examples
Sample success responses
JSON
format
{
"cluster_id": "cb95aa626a47740afbf6aa099b650****",
"task_id": "T-5a54309c80282e39ea00002f",
"request_id": "687C5BAA-D103-4993-884B-C35E4314A1E1"
}
XML
format
<cluster_id>cb95aa626a47740afbf6aa099b650****</cluster_id>
<task_id>T-5a54309c80282e39ea00002f</task_id>
<request_id>687C5BAA-D103-4993-884B-C35E4314A1E1</request_id>
Error codes
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation |
---|---|---|
2024-09-13 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2024-09-11 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2024-09-04 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2024-04-22 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2024-04-19 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2023-08-21 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2023-08-08 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2022-09-23 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2022-08-02 | The internal configuration of the API is changed, but the call is not affected | View Change Details |
2021-11-24 | The internal configuration of the API is changed, but the call is not affected | View Change Details |