Call the CreateCluster API to create a cluster - Container Service for Kubernetes - Alibaba Cloud - Container Service for Kubernetes

Creates an ACK cluster, including ACK managed clusters, ACK Serverless clusters, ACK Edge clusters, and registered clusters. When you create a cluster, you configure cluster information, cluster components, and ACK-related cloud resources.

Operation description

Generate OpenAPI request parameters by using the console

When you call the CreateCluster operation to create a cluster, if the call fails due to incorrect request parameter combinations, you can use the console to generate the required request parameter combinations. Perform the following steps:

Log on to the Container Service for Kubernetes (ACK) console and choose Clusters in the left-side navigation pane.
On the Clusters page, click Cluster Template.
In the dialog box, select the cluster type that you want to create, click Create, and then configure the cluster information on the cluster configuration page.
After the configuration is complete, on the Confirm Configuration page, click Equivalent Code in the upper-right corner. The dialog box displays the parameter combinations required for creating the cluster. You can copy and use them.

Important Starting from July 04, 2026, some request parameters will no longer take effect. For details about the changes and replacement parameter descriptions, see Notice on changes to OpenAPI request and response parameters for ACK cluster management and OpenAPI offline.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

cs:CreateCluster

create

*Cluster

acs:cs:{#regionId}:{#accountId}:cluster/*

cs:ClusterType
cs:ClusterSpec
cs:ClusterProfile
cs:EnableSecretEncryption
cs:EnableApiServerEip
cs:EnableAddonLogtailDs
cs:EnableCoreControlPlaneComponentsLog
cs:AddonNames
cs:EnableSNAT
cs:EnableNodePoolPublicIP

None

Request syntax

POST /clusters HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	The request body parameters.	cluster-demo
access_control_list `deprecated`	array	No	[Deprecated] The access control list (ACL) of the SLB instance for the API server of a registered cluster.
	string	No	The access control list (ACL) of the SLB instance for the API server of a registered cluster.	192.168.XX.XX/24
addons	array	No	The list of cluster components. When you create a cluster, use `addons` to specify the components that you want to install. Network component: Required. Two network types are available: Flannel and Terway. Select one when you create a cluster: Flannel: [{"name":"flannel","config":""}]. Terway: [{"name": "terway-eniip","config": ""}]. Storage component: Optional. Only the `csi` type is supported: `csi`: [{"name":"csi-plugin","config": ""},{"name": "csi-provisioner","config": ""}]. Log component: Optional. We recommend that you enable this component. If you do not enable the log service, you cannot use the cluster audit feature. Use an existing `SLS Project`: [{"name": "loongcollector","config": "{"IngressDashboardEnabled":"true","sls_project_name":"your_sls_project_name"}"}]. Create a new `SLS Project`: [{"name": "loongcollector","config": "{"IngressDashboardEnabled":"true"}"}]. Ingress component: Optional. By default, the Ingress component `nginx-ingress-controller` is installed for ACK dedicated clusters. Install Ingress and enable Internet access: [{"name":"nginx-ingress-controller","config":"{"IngressSlbNetworkType":"internet"}"}]. Do not install Ingress by default: [{"name": "nginx-ingress-controller","config": "","disabled": true}]. Event Center: Optional. Enabled by default. Event Center provides the capabilities to store, query, and alert on Kubernetes events. The Logstore associated with Kubernetes Event Center is free of charge for 90 days. For more information about the free policy, see Create and use Kubernetes Event Center. Example of enabling Event Center: [{"name":"ack-node-problem-detector","config":"{"sls_project_name":"your_sls_project_name"}"}].
	addon	No	The list of cluster components. When you create a cluster, use `addons` to specify the components that you want to install.
api_audiences	string	No	A ServiceAccount is the access credential used by a pod to communicate with the cluster API server. The `api-audiences` parameter specifies the valid request `token` identities used by the `apiserver` to authenticate whether request `tokens` are valid. You can configure multiple `audiences` separated by commas (,). For more information about `ServiceAccount`, see Deploy service account token volume projection.	kubernetes.default.svc
audit_log_config	object	No	The cluster audit log configuration.
enabled	boolean	No	Specifies whether to enable the cluster audit log feature. Valid values: true: Enable the feature. false: Disable the feature.	true
sls_project_name	string	No	The SLS Project that contains the Logstore for cluster audit logs. Default value: `k8s-log-{clusterid}`. After the cluster audit log feature is enabled, a Logstore for cluster audit logs is created in the specified SLS Project.	k8s-log-c2345xxxxxxxxxxxx
auto_mode	object	No	The intelligent managed mode configuration.
enable	boolean	No	Specifies whether to enable intelligent managed mode. Valid values: true: Enable the mode. false: Disable the mode.	true
auto_renew `deprecated`	boolean	No	[Deprecated] Specifies whether to enable auto-renewal. This parameter takes effect only when `charge_type` is set to `PrePaid`. Valid values: `true`: Enable auto-renewal. `false`: Disable auto-renewal. Default value: `false`. This parameter was changed on October 15, 2024. For more information, see Notice on behavior changes of the CreateCluster parameter.	true
auto_renew_period `deprecated`	integer	No	[Deprecated] The auto-renewal epoch. This parameter takes effect only when the billing method is upfront and auto-renewal is enabled. When `PeriodUnit=Month`, valid values: {1, 2, 3, 6, 12}. Default value: 1. This parameter was changed on October 15, 2024. For more information, see Notice on behavior changes of the CreateCluster parameter.	1
charge_type `deprecated`	string	No	[Deprecated] The billing method of the CLB instance used by the API server. Default value: PostPaid. Valid values: PostPaid: pay-as-you-go. PrePaid: subscription. The subscription billing method is no longer supported for newly created CLB instances. Existing instances are not affected. Important This parameter was changed on October 15, 2024. For more information, see Notice on behavior changes of the CreateCluster parameter. Starting from December 01, 2024, newly created CLB instances no longer support the subscription billing method, and an instance fee will be charged. For more information, see Notice on billing changes for Classic Load Balancer (CLB).	PostPaid
cis_enabled `deprecated`	boolean	No	[Deprecated] For cluster control plane configuration, use the `security_hardening_os` parameter under `control_plane_config` instead. For node pool configuration, use the `security_hardening_os` parameter under `scaling_group` in `nodepool` instead.	false
client_token	string	No	The client token.	0a287651-1277-4c0d-80d2-623a4*****
cloud_monitor_flags `deprecated`	boolean	No	[Deprecated] For cluster control plane node configuration, use the `cloud_monitor_flags` parameter under `control_plane_config` instead. For node pool configuration, use the `cms_enabled` parameter under `kubernetes_config` in nodepool instead. Specifies whether to install the CloudMonitor agent on the cluster. Valid values: `true`: Install the CloudMonitor agent. `false`: Do not install the CloudMonitor agent. Default value: `false`.	false
cluster_domain	string	No	The cluster local domain name. Naming rules: A domain name consists of one or more parts separated by periods (.). Each part can be up to 63 characters long and can contain lowercase letters, digits, and hyphens (-). Each part must start and end with a lowercase letter or digit.	cluster.local
cluster_spec	string	No	After you set `cluster_type` to `ManagedKubernetes` and configure `profile`, you can further specify the cluster specification. Valid values: `ack.standard`: Basic Edition (selected by default if the value is empty) `ack.pro.small`: Pro Edition `ack.pro.xlarge`: Pro XL `ack.pro.2xlarge`: Pro 2XL `ack.pro.4xlarge`: Pro 4XL (requires contacting customer service to enable the whitelist) Pro XL, Pro 2XL, and Pro 4XL are three tiers provided by ACK Pro Provisioned Control Plane. By pre-allocating and dedicating control plane resources, these tiers ensure that API concurrency and pod scheduling capabilities remain at a consistently high level. They are suitable for AI training and inference, ultra-large-scale clusters, and mission-critical workloads. For information about the cluster management fees for Pro Edition and Provisioned Control Plane editions, see Cluster management fee.	ack.pro.small
cluster_type	string	No	Valid values: `Kubernetes`: ACK dedicated cluster. `ManagedKubernetes`: ACK managed cluster types, including ACK managed clusters (Pro and Basic editions), ACK Serverless clusters (Pro and Basic editions), ACK Edge clusters (Pro and Basic editions), and ACK Lingjun clusters (Pro Edition). `ExternalKubernetes`: registered cluster.	Kubernetes
container_cidr	string	No	The CIDR block for pods. This must be a valid private CIDR block, specifically the following CIDR blocks and their subnets: 10.0.0.0/8, 172.16-31.0.0/12-16, and 192.168.0.0/16. The CIDR block cannot overlap with the VPC CIDR block or the CIDR blocks used by existing Kubernetes clusters in the VPC. You cannot modify this CIDR block after the cluster is created. For more information about cluster network planning, see Plan the network of an ACK managed cluster. Note This parameter is required for Flannel clusters.	172.20.0.0/16
control_plane_config	object	No	The control plane configuration for ACK dedicated clusters.
auto_renew	boolean	No	Specifies whether to enable auto-renewal for control plane nodes. This parameter takes effect only when the billing method is set to `PrePaid`. Valid values: true: Enables auto-renewal. false: Disables auto-renewal. Default value: true.	true
auto_renew_period	integer	No	The auto-renewal period for control plane nodes. Valid values: {1, 2, 3, 6, 12}. Unit: months. Default value: 1.	1
charge_type	string	No	The billing method for control plane nodes. `PrePaid`: subscription. `PostPaid`: pay-as-you-go. Default value: `PostPaid`.	PostPaid
cloud_monitor_flags	boolean	No	Specifies whether to install CloudMonitor on nodes. true: Installs the CloudMonitor agent. false: Does not install the CloudMonitor agent. Default value: false.	false
cpu_policy	string	No	The node CPU management policy. static: Allows pods with certain resource characteristics on the node to be granted enhanced CPU affinity and exclusivity. none: Uses the existing default CPU affinity scheme. Default value: none.	none
deploymentset_id	string	No	The deployment set ID.	ds-bp10b35imuam5amw****
image_id	string	No	The image ID.	aliyun_3_x64_20G_alibase_20240819.vhd
image_type	string	No	The operating system image type.	AliyunLinux3
instance_metadata_options	InstanceMetadataOptions	No	The ECS instance metadata access configuration.
instance_types	array	No	The node instance types.
	string	No	The node instance type.	ecs.g6.large
key_pair	string	No	The key pair name. You must set one of key_pair and login_password.	ack
login_password	string	No	The SSH logon password. The password must be 8 to 30 characters in length and must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. You must set one of login_password and key_pair.	********
node_port_range	string	No	[Deprecated] The node service port range.	30000-32767
period	integer	No	The subscription duration for control plane nodes. This parameter is required and takes effect only when the billing method is set to `PrePaid`. Valid values: {1, 2, 3, 6, 12, 24, 36, 48, 60}. Unit: months. Default value: 1.	1
period_unit	string	No	The subscription duration unit for control plane nodes. This parameter is required and takes effect only when the billing method is set to `PrePaid`. Valid value: `Month`. Currently, only month-based billing cycles are supported.	Month
runtime	string	No	[Deprecated] The runtime name for control plane nodes. Valid values: containerd: The Containerd runtime, which is supported by all cluster versions.	containerd
security_hardening_os	boolean	No	Specifies whether to enable Alibaba Cloud OS security hardening. true: Enables Alibaba Cloud OS security hardening. false: Disables Alibaba Cloud OS security hardening. Default value: false.	false
size	integer	No	The number of control plane nodes. Valid values: `3` or `5`.	3
soc_enabled	boolean	No	Specifies whether to enable MLPS security hardening. true: Enables MLPS 2.0 security hardening. false: Disables MLPS 2.0 security hardening. Default value: false.	false
system_disk_bursting_enabled	boolean	No	Specifies whether to enable burst performance for node system cloud disks. true: Enabled. false: Disabled. This parameter is supported only when `system_disk_category` is set to `cloud_auto`.	true
system_disk_category	string	No	The node system cloud disk type. `cloud_efficiency`: ultra cloud disk. `cloud_ssd`: standard SSD. `cloud_essd`: ESSD. `cloud_auto`: ESSD AutoPL cloud disk. `cloud_essd_entry`: ESSD Entry cloud disk. Default value: `cloud_ssd`. The default value may vary by zone.	cloud_ssd
system_disk_performance_level	string	No	The performance level of the node system cloud disk. This parameter takes effect only for ESSD cloud disks. The performance level varies based on the cloud disk size. For more information, see ESSD cloud disks.	PL1
system_disk_provisioned_iops	integer	No	The provisioned read/write IOPS for node system cloud disks. Valid values: 0 to min{50,000, 1000 × capacity - baseline performance}. Baseline performance = min{1,800 + 50 × capacity, 50,000}. This parameter is supported only when `system_disk_category` is set to `cloud_auto`.	1000
system_disk_size	integer	No	The node system cloud disk size. Valid values: [40, 500]. Unit: GiB. Default value: `120`.	120
system_disk_snapshot_policy_id	string	No	The automatic snapshot policy for node system cloud disks.	sp-2zej1nogjvovnz4z****
control_plane_endpoints_config	object	No	The cluster endpoint configuration.
internal_dns_config	object	No	The internal DNS configuration for the cluster. This parameter applies to ACK managed clusters. The internal domain name is used by node-side system components such as kubelet and kube-proxy to access the API Server. If the internal domain name access is not enabled, node-side system components access the API Server through the CLB IP address.
bind_vpcs	array	No	The VPCs in which the internal DNS records of the cluster take effect.
	string	No	The VPCs in which the internal DNS records of the cluster take effect.	vpc-xxxx
load_balancers_config	array<object>	No	The cluster endpoint configuration. When this parameter is specified, the endpoint_public_access and load_balancer_id parameters do not take effect. ACK supports only automatic creation of NLB instances. To specify a CLB or NLB instance, use load_balancers_config to specify the corresponding instance ID.
	object	No	The load balancing configuration for cluster access.
endpoint_type	string	No	The endpoint type.	private
load_balancer_id	string	No	The NLB instance ID.	nlb-0ogk9aaxxxxxxx
controlplane_log_components	array	No	The list of component names that specifies which control plane components to collect logs from. By default, logs are collected from kube-apiserver, kube-controller-manager, kube-scheduler, and cloud-controller-manager.
	string	No	The list of component names that specifies which control plane components to collect logs from. By default, logs are collected from kube-apiserver, kube-controller-manager, kube-scheduler, and cloud-controller-manager.	["apiserver","kcm","scheduler"]
controlplane_log_project	string	No	The Simple Log Service project for control plane component logs. You can use an existing project for log storage, or the system automatically creates a project. If you choose automatic creation, a Simple Log Service project named `k8s-log-{ClusterID}` is created.	k8s-log-xxx
controlplane_log_ttl	string	No	The log retention period for control plane component logs, in days.	30
cpu_policy `deprecated`	string	No	[Deprecated] Use the `cpu_policy` parameter under `control_plane_config` for cluster control plane configuration, or use the `cpu_policy` parameter under `kubernetes_config` in `nodepool` for node pool configuration. The node CPU management policy. The following policies are supported for clusters of version 1.12.6 or later: `static`: Allows pods with certain resource characteristics on the node to be granted enhanced CPU affinity and exclusivity. `none`: Uses the existing default CPU affinity scheme. Default value: `none`.	none
custom_san `deprecated`	string	No	[Deprecated] Use the `extra_sans` parameter instead. The custom certificate Subject Alternative Name (SAN). Separate multiple IP addresses or domain names with commas (,).	cs.aliyun.com
deletion_protection	boolean	No	Specifies whether to enable cluster deletion protection, which prevents the cluster from being accidentally deleted in the console or by calling API operations. Valid values: `true`: Enables cluster deletion protection. The cluster cannot be deleted in the console or by calling API operations. `false`: Disables cluster deletion protection. The cluster can be deleted in the console or by calling API operations. Default value: `false`.	true
disable_rollback `deprecated`	boolean	No	[Deprecated] When cluster creation fails, no rollback is performed by default. You must manually clean up the failed cluster. Specifies whether to roll back the cluster if cluster creation fails. Valid values: `true`: Rolls back the cluster if cluster creation fails. `false`: Does not roll back the cluster if cluster creation fails. Default value: `true`.	true
enable_rrsa `deprecated`	boolean	No	[Deprecated] Use the `rrsa_config` parameter instead. Specifies whether to enable the RRSA feature. true: Enables the feature. false: Does not enable the feature.	false
encryption_provider_key	string	No	The ID of the Key Management Service (KMS) key used to encrypt cloud disks. For more information, see Key Management Service. Note This feature takes effect only in ACK Pro clusters.	0fe64791-55eb-4fc7-84c5-c6c7cdca****
endpoint_public_access	boolean	No	Specifies whether to enable public network access. An Elastic IP Address (EIP) is used to expose the API Server for public network access to the cluster. `true`: Enables public network access. `false`: Disables public network access. If you select this option, the cluster API Server cannot be accessed over the Internet. Default value: `false`.	true
extra_sans	array	No	The custom Subject Alternative Name (SAN) for the API Server certificate.
	string	No	The certificate SAN. Supports custom IP addresses or domain names.	192.168.xx.xx
format_disk `deprecated`	boolean	No	[Deprecated] Selecting existing nodes during cluster creation is not supported. To add existing nodes to a cluster, create a node pool first and call the AttachInstancesToNodePool operation. Specifies whether to mount data disks to existing instances when creating a cluster with existing instances. Valid values: `true`: Stores containers and images on data disks. Existing data on the data disks will be lost. Back up your data in advance. `false`: Does not store containers and images on data disks. Default value: `false`. Data disk mounting rules: If the ECS instance has data disks attached and the file system of the last data disk is not initialized, the system automatically formats the data disk as ext4 to store /var/lib/docker and /var/lib/kubelet. If the ECS instance has no data disks attached, no new data disks are mounted.	false
image_id `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `image_id` parameter under `control_plane_config` instead. For node pool configuration, use the `image_id` parameter under `scaling_group` in `nodepool` instead. The custom image for nodes. The system image is used by default. When a custom image is selected, it replaces the default system image. For more information, see Custom images.	m-bp16z7xko3vvv8gt****
image_type `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `image_type` parameter under `control_plane_config` instead. For node pool configuration, use the `image_type` parameter under `scaling_group` in `nodepool` instead. The operating system distribution type. We recommend that you use this field to specify the node operating system. Valid values: CentOS AliyunLinux AliyunLinux Qboot AliyunLinuxUEFI AliyunLinux3 Windows WindowsCore AliyunLinux3Arm64 ContainerOS Default value: `CentOS`.	AliyunLinux
instances `deprecated`	array	No	[Deprecated] Selecting existing nodes during cluster creation is not supported. To add existing nodes to a cluster, create a node pool first and call the AttachInstancesToNodePool operation. The list of ECS instances to use when creating a cluster with existing nodes. These instances are added to the cluster as worker nodes. Note This field is required when you create a cluster by using existing instances.
	string	No	The list of ECS instances to use when creating a cluster with existing nodes. These instances are added to the cluster as worker nodes. Note This field is required when you create a cluster by using existing instances.	i-2ze4zxnm36vq00xn****
ip_stack	string	No	The IP protocol stack of the cluster.	Valid values: ipv4 (single stack) dual (dual stack). Default value: ipv4
is_enterprise_security_group	boolean	No	Specifies whether to enable automatic creation of an advanced security group. This parameter takes effect when `security_group_id` is empty. Note When a basic security group is used, the total number of nodes and Terway pods in the cluster cannot exceed 2000. Therefore, when creating a Terway network type cluster, use an advanced security group. `true`: Creates and uses an advanced security group. `false`: Uses a basic security group. Default value: `true`.	true
keep_instance_name `deprecated`	boolean	No	[Deprecated] Selecting existing nodes during cluster creation is not supported. To add existing nodes to a cluster, create a node pool first and call the AttachInstancesToNodePool operation. Specifies whether to retain instance names when creating a cluster with existing instances. `true`: Retains the instance names. `false`: Does not retain the instance names. The names are replaced by system-generated names. Default value: `true`.	true
key_pair `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `key_pair` parameter under `control_plane_config` instead. For node pool configuration, use the `key_pair` parameter under `scaling_group` in `nodepool` instead. The name of the key pair. Mutually exclusive with `login_password`.	security-key
kubernetes_version	string	No	The cluster version, which is consistent with the Kubernetes community baseline version. Use the latest version. If you do not specify this parameter, the latest version is used by default. You can create clusters of the three most recent versions. Call the DescribeKubernetesVersionMetadata operation to query supported cluster versions. For more information about Kubernetes versions supported by ACK, see Kubernetes version release overview.	1.32.1-aliyun.1
load_balancer_id	string	No	The instance ID of the Classic Load Balancer (CLB) used for API Server access. If this parameter is specified, automatic creation of an API Server CLB is skipped. Note Make sure that the CLB instance has no other dependencies (such as listeners or backend servers). Shared and Internet-facing CLB instances are not supported.	lb-wz9t256gqa3vbouk****
load_balancer_spec `deprecated`	string	No	[Deprecated] CLB uses pay-by-usage billing. This parameter does not take effect. The load balancing specification. Valid values: slb.s1.small slb.s2.small slb.s2.medium slb.s3.small slb.s3.medium slb.s3.large Default value: `slb.s2.small`.	slb.s2.small
logging_type `deprecated`	string	No	[Deprecated] Enables the log service for the cluster. This parameter takes effect only for ACK Serverless clusters, and the value must be `SLS`.	SLS
login_password `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `login_password` parameter under `control_plane_config` instead. For node pool configuration, use the `login_password` parameter under `scaling_group` in `nodepool` instead. The SSH logon password. Mutually exclusive with `key_pair`. 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.	null
maintenance_window	maintenance_window	No	The cluster O&M window.
master_auto_renew `deprecated`	boolean	No	[Deprecated] For cluster control plane configuration, use the `auto_renew` parameter under `control_plane_config` instead. Specifies whether to enable auto-renewal for master nodes. This parameter takes effect only when `master_instance_charge_type` is set to `PrePaid`. Valid values: `true`: Enables auto-renewal. `false`: Disables auto-renewal. Default value: `true`.	true
master_auto_renew_period `deprecated`	integer	No	[Deprecated] For cluster control plane configuration, use the `auto_renew_period` parameter under `control_plane_config` instead. The auto-renewal epoch for master nodes. This parameter takes effect and is required only when the subscription billing method is selected. Valid values: {1, 2, 3, 6, 12}. Default value: 1.	1
master_count `deprecated`	integer	No	[Deprecated] For cluster control plane configuration, use the `size` parameter under `control_plane_config` instead. The number of master nodes. Valid values: `3` or `5`. Default value: `3`.	3
master_instance_charge_type `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `instance_charge_type` parameter under `control_plane_config` instead. The billing method for master nodes. Valid values: `PrePaid`: Subscription. `PostPaid`: Pay-as-you-go. Default value: `PostPaid`.	PrePaid
master_instance_types `deprecated`	array	No	[Deprecated] For cluster control plane configuration, use the `instance_types` parameter under `control_plane_config` instead. The instance types for master nodes. For more information, see Instance families.
	string	No	The instance type for a master node. The number of specified instance types must match the value of `master_count` and correspond one-to-one with the elements in `master_instance_types`. For more information, see Instance families.	ecs.n4.xlarge
master_period `deprecated`	integer	No	[Deprecated] For cluster control plane configuration, use the `unit` parameter under `control_plane_config` instead. The subscription duration for master nodes. This parameter takes effect and is required only when `master_instance_charge_type` is set to `PrePaid`. Valid values: {1, 2, 3, 6, 12, 24, 36, 48, 60}. Default value: 1.	1
master_period_unit `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `period_unit` parameter under `control_plane_config` instead. The subscription period unit for master nodes. This parameter is required when the billing method is `PrePaid`. Valid values: `Month`. Currently, only monthly billing is supported.	Month
master_system_disk_category `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `system_disk_category` parameter under `control_plane_config` instead. The system cloud disk type for master nodes. Valid values: `cloud_efficiency`: Ultra cloud disk. `cloud_ssd`: Standard SSD. `cloud_essd`: Enterprise SSD (ESSD). Default value: `cloud_ssd`. The default value may vary by zone.	cloud_ssd
master_system_disk_performance_level `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `system_disk_performance_level` parameter under `control_plane_config` instead. The performance level (PL) of the system cloud disk for master nodes. This parameter takes effect only for ESSD cloud disks. The performance level is related to the disk size. For more information, see ESSD cloud disks.	PL1
master_system_disk_size `deprecated`	integer	No	[Deprecated] For cluster control plane configuration, use the `system_disk_size` parameter under `control_plane_config` instead. The system cloud disk size for master nodes. Valid values: [40, 500]. Unit: GiB. Default value: `120`.	120
master_system_disk_snapshot_policy_id `deprecated`	string	No	[Deprecated] For cluster control plane configuration, use the `system_disk_snapshot_policy_id` parameter under `control_plane_config` instead. The ID of the automatic snapshot policy for master node system cloud disks.	sp-2zej1nogjvovnz4z****
master_vswitch_ids `deprecated`	array	No	[Deprecated] Use the `vswitch_ids` parameter instead. The list of vSwitch IDs for master nodes. The number of vSwitches must be in the range of [1, 3]. To ensure high availability, select three vSwitches distributed across different zones. The number of specified instance types must match the value of `master_count` and correspond one-to-one with the elements in `master_vswitch_ids`.
	string	No	The list of vSwitch IDs for master nodes. The number of vSwitches must be in the range of [1, 3]. To ensure high availability, select three vSwitches distributed across different zones. The number of specified instance types must match the value of `master_count` and correspond one-to-one with the elements in `master_vswitch_ids`.	vsw-2ze3ds0mdip0hdz8i****
name	string	Yes	The custom cluster name. The name can contain digits, Chinese characters, letters, and hyphens (-). It must be 1 to 63 characters in length and cannot start with a hyphen (-).	cluster-demo
nat_gateway `deprecated`	boolean	No	[Deprecated] Use the `snat_entry` parameter instead.	true
node_cidr_mask	string	No	The number of IP addresses per node, determined by specifying the network CIDR block. This parameter takes effect only for Flannel network type clusters. Default value: `26`.	25
node_name_mode `deprecated`	string	No	[Deprecated] For node pool configuration, use the `node_name_mode` parameter under `kubernetes_config` in `nodepool` instead.	null
node_port_range `deprecated`	string	No	The node service port range. Valid port range: [30000, 65535]. Default value: `30000-32767`.	30000~32767
nodepools	array	No	The list of node pools.
	nodepool	No	The node pool configuration.
num_of_nodes `deprecated`	integer	No	[Deprecated] Use the desired_size parameter under scaling_group in nodepool instead. The number of worker nodes. Valid values: 0 to 100.	3
operation_policy	object	No	The automatic O&M policy of the cluster.
cluster_auto_upgrade	object	No	The cluster auto upgrade configuration.
channel	string	No	The cluster auto upgrade frequency. Valid values: patch: Automatically upgrades to the latest available patch version within the current minor version. The new Kubernetes version does not contain breaking changes. stable: Automatically upgrades to the latest patch version of the second-latest minor version. The new Kubernetes version may involve API and feature changes, but its stability has been extensively validated. rapid: Automatically upgrades to the latest patch version of the latest minor version, allowing faster access to new features from the Kubernetes community.	stable
enabled	boolean	No	Specifies whether to enable cluster auto upgrade. true: Enabled. false: Not enabled.	true
os_type `deprecated`	string	No	[Deprecated] For cluster control plane node configuration, use the image_type parameter under control_plane_config instead. For node pool configuration, use the image_type parameter under scaling_group in nodepool instead. The operating system platform type. Valid values: Windows Linux Default value: `Linux`.	Linux
period `deprecated`	integer	No	[Deprecated] The subscription duration. This parameter takes effect and is required only when charge_type is set to PrePaid. Valid values: 1, 2, 3, 6, 12, 24, 36, 48, and 60. Default value: 1. This parameter was changed on October 15, 2024. For more information, see Notice on behavior changes of the CreateCluster API parameters.	1
period_unit `deprecated`	string	No	[Deprecated] The billing cycle. This parameter is required when the billing method is set to PrePaid. Valid values: Month. Currently, only monthly billing cycles are supported. This parameter was changed on October 15, 2024. For more information, see Notice on behavior changes of the CreateCluster API parameters.	Month
platform `deprecated`	string	No	[Deprecated] For node pool configuration, use the platform parameter under scaling_group in nodepool instead. The operating system distribution. Valid values: CentOS AliyunLinux QbootAliyunLinux Qboot Windows WindowsCore Default value: `CentOS`.	CentOS
pod_vswitch_ids `deprecated`	array	No	[Deprecated] When the Terway network plugin is selected, you must specify vSwitches for Pod IP address allocation. Each Pod vSwitch corresponds to a worker node vSwitch, and the zones of the Pod vSwitches and worker node vSwitches must be the same. Note The CIDR block mask of the Pod vSwitch should not exceed 19 and must not exceed 25. Otherwise, the number of Pod IP addresses available in the cluster network is very limited, which affects normal cluster operations.
	string	No	When the Terway network plugin is selected, you must specify vSwitches for Pod IP address allocation. Each Pod vSwitch corresponds to a worker node vSwitch, and the zones of the Pod vSwitches and worker node vSwitches must be the same. Note The CIDR block mask of the Pod vSwitch should not exceed 19 and must not exceed 25. Otherwise, the number of Pod IP addresses available in the cluster network is very limited, which affects normal cluster operations.	vsw-2ze97jwri7cei0mpw****
profile	string	No	When you set `cluster_type` to `ManagedKubernetes` for ACK managed clusters, you can further specify the cluster subtype. `Default`: ACK managed cluster, including ACK clusters (Pro and Basic editions). `Edge`: ACK Edge cluster, including ACK Edge clusters (Pro and Basic editions). `Serverless`: ACK Serverless cluster, including ACK Serverless clusters (Pro and Basic editions). `Lingjun`: ACK Lingjun cluster, available in Pro edition.	Default
proxy_mode	string	No	The kube-proxy mode. `iptables`: A mature and stable kube-proxy mode. Service discovery and load balancing for Kubernetes Services are configured by using iptables rules. Performance is moderate and affected by scale. This mode is suitable for clusters with a small number of Services. `ipvs`: A high-performance kube-proxy mode. Service discovery and load balancing for Kubernetes Services are configured by using the Linux IPVS module. This mode is suitable for clusters with a large number of Services that require high load balancing performance. `nftables`: A next-generation kube-proxy mode that implements Service discovery and load balancing based on Linux nftables. It is a modern replacement for iptables. Compared with iptables, nftables delivers better network performance, more efficient rule updates, and improved behavior in large-scale Service scenarios. Only supported for clusters running version 1.35 or later. The Kubernetes community deprecated IPVS starting from version 1.35. For new clusters, use nftables for longer-term community support. Default value: `ipvs`.	ipvs
rds_instances `deprecated`	array	No	[Deprecated] For node pool configuration, use the rds_instances parameter under scaling_group in nodepool instead. The list of ApsaraDB RDS instances to which you want to add the cluster nodes to the whitelist. Add the container Pod CIDR block and node CIDR block to the RDS whitelist directly. Setting RDS instances may fail if the instances are not in a running state.
	string	No	The list of ApsaraDB RDS instances to which you want to add the cluster nodes to the whitelist. Add the container Pod CIDR block and node CIDR block to the RDS whitelist directly. Setting RDS instances may fail if the instances are not in a running state.	rm-2zev748xi27xc****
region_id	string	Yes	The ID of the region where the cluster is deployed. For details, see Container service supported regions.	cn-beijing
resource_group_id	string	No	The ID of the resource group to which the cluster belongs. Use this parameter to isolate different resources.	rg-acfm3mkrure****
rrsa_config	object	No	The RAM Roles for Service Accounts (RRSA) feature configuration.
enabled	boolean	No	Specifies whether to enable the RRSA feature. true: Enabled. false: Not enabled.	true
runtime `deprecated`	runtime	No	The container runtime used in the cluster. Supported runtimes include containerd, sandboxed containers, and Docker. Note Kubernetes 1.24 no longer supports Docker as a built-in container runtime. For more information, see Comparison of Docker, containerd, and sandboxed container runtimes.
security_group_id	string	No	The ID of an existing security group. This parameter is mutually exclusive with `is_enterprise_security_group`. Cluster nodes are automatically added to this security group.	sg-bp1bdue0qc1g7k****
security_hardening_os `deprecated`	boolean	No	[Deprecated] For cluster control plane configuration, use the security_hardening_os parameter under control_plane_config instead. For node pool configuration, use the security_hardening_os parameter under scaling_group in nodepool instead. Specifies whether to enable Alibaba Cloud OS security hardening. Valid values: `true`: Enables Alibaba Cloud OS security hardening. `false`: Does not enable Alibaba Cloud OS security hardening. Default value: `false`.	false
service_account_issuer	string	No	A ServiceAccount is the access credential used for communication between a Pod and the cluster API Server. The `service-account-issuer` is the issuer identity in the `serviceaccount token`, which is the `iss` field in the `token payload`. For more information about `ServiceAccount`, see Deploy service account token volume projection.	kubernetes.default.svc
service_cidr	string	No	The CIDR block for Services. Valid ranges: 10.0.0.0/16-24, 172.16-31.0.0/16-24, and 192.168.0.0/16-24. The CIDR block cannot overlap with the VPC CIDR block 10.1.0.0/21 or CIDR blocks used by existing Kubernetes clusters in the VPC. This value cannot be modified after the cluster is created. Default value: 172.19.0.0/20.	172.21.0.0/20
service_discovery_types `deprecated`	array	No	[Deprecated] The service discovery type within the cluster, used to specify the service discovery method in `ACK Serverless` clusters. `CoreDNS`: Uses the Kubernetes-native standard service discovery component CoreDNS. A set of containers must be deployed in the cluster for DNS resolution. By default, two ECI instances with 0.25 Core and 512 MiB specifications are used. `PrivateZone`: Uses Alibaba Cloud PrivateZone to provide service discovery capabilities. The PrivateZone service must be activated. Default value: not enabled.
	string	No	The service discovery type within the cluster, used to specify the service discovery method in `ACK Serverless` clusters. `CoreDNS`: Uses the Kubernetes-native standard service discovery component CoreDNS. A set of containers must be deployed in the cluster for DNS resolution. By default, two ECI instances with 0.25 Core and 512 MiB specifications are used. `PrivateZone`: Uses Alibaba Cloud PrivateZone to provide service discovery capabilities. The PrivateZone service must be activated. Default value: not enabled.	PrivateZone
snat_entry	boolean	No	Settings for configuring SNAT for the VPC. Valid values: `true`: Enables automatic creation of a NAT gateway and automatic configuration of SNAT rules. Set this to `true` if nodes and applications in the cluster need to access the Internet. `false`: Does not create a NAT gateway or SNAT rules. Nodes and applications in the cluster cannot access the Internet. Note If this is not enabled during cluster creation and Internet access is required later, you can manually enable it. Default value: `false`.	false
soc_enabled `deprecated`	boolean	No	[Deprecated] For cluster control plane node configuration, use the soc_enabled parameter under control_plane_config instead. For node pool configuration, use the soc_enabled parameter under scaling_group in nodepool instead. Specifies whether to enable mlps 2.0 security hardening. For more information, see China classified protection compliance for ACK. Valid values: `true`: Enables mlps 2.0 security hardening. `false`: Does not enable mlps 2.0 security hardening. Default value: `false`.	false
ssh_flags	boolean	No	Specifies whether to enable public SSH logon. This is used to log on to the master nodes of ACK dedicated clusters. This parameter does not take effect for managed clusters. `true`: Enabled. `false`: Not enabled. Default value: `false`.	true
tags	array	No	The node tags. Tag definition rules: Tags are case-sensitive key-value pairs. You can set up to 20 tags. Tag keys cannot be duplicated and can be up to 64 characters in length. Tag values can be empty and can be up to 128 characters in length. Tag keys and tag values cannot start with "aliyun", "acs:", "https://", or "http://". For more information, see Labels and Selectors.
	tag	No	The node tags. Tag definition rules: Tags are case-sensitive key-value pairs. You can set up to 20 tags. Tag keys cannot be duplicated and can be up to 64 characters in length. Tag values can be empty and can be up to 128 characters in length. Tag keys and tag values cannot start with "aliyun", "acs:", "https://", or "http://". For more information, see Labels and Selectors.
taints `deprecated`	array	No	[Deprecated] For node pool configuration, use the taints parameter under kubernetes_config in nodepool instead. The node taint information. Taints and tolerations work together to prevent Pods from being scheduled to inappropriate nodes. For more information, see taint-and-toleration.
	taint	No	The node taint information. Taints and tolerations work together to prevent Pods from being scheduled to inappropriate nodes. For more information, see taint-and-toleration.
timeout_mins `deprecated`	integer	No	[Deprecated] By default, the system does not roll back when cluster creation fails. You must manually clean up the failed cluster. The cluster creation timeout period, in minutes. Default value: `60`.	60
timezone	string	No	The time zone used by the cluster. For more information, see Supported time zones.	Asia/Shanghai
user_ca	string	No	The custom cluster Certificate Authority (CA).	-----BEGIN CERTIFICATE-----****
user_data `deprecated`	string	No	[Deprecated] The custom node data.	IyEvdXNyL2Jpbi9iYXNoCmVjaG8gIkhlbGxvIEFD****
vpcid	string	No	The VPC used by the cluster. You must provide a VPC when creating a cluster.	vpc-2zeik9h3ahvv2zz95****
vswitch_ids	array	No	The vSwitches for cluster nodes. This parameter is required when creating a zero-node managed cluster.
	string	No	The vSwitches for cluster nodes. This parameter is required when creating a zero-node managed cluster.	vsw-2ze3ds0mdip0hdz8i****
worker_auto_renew `deprecated`	boolean	No	[Deprecated] For node pool configuration, use the auto_renew parameter under scaling_group in nodepool instead. Specifies whether to enable auto-renewal for worker nodes. This parameter takes effect only when `worker_instance_charge_type` is set to `PrePaid`. Valid values: `true`: Enables auto-renewal. `false`: Does not enable auto-renewal. Default value: `true`.	true
worker_auto_renew_period `deprecated`	integer	No	[Deprecated] For node pool configuration, use the auto_renew_period parameter under scaling_group in nodepool instead. The auto-renewal cycle for worker nodes. This parameter takes effect and is required only when the subscription billing method is selected. Valid values: 1, 2, 3, 6, and 12.	1
worker_data_disks `deprecated`	array<object>	No	[Deprecated] Use the data_disks parameter in scaling_group of nodepool instead. The combination of data cloud disk type, size, and other configurations for worker nodes.
	object	No	The data cloud disk configuration set.
category	string	Yes	The data cloud disk type.	cloud_essd
encrypted	string	No	Specifies whether to encrypt data cloud disks. Valid values: `true`: Encrypts data cloud disks. `false`: Does not encrypt data cloud disks. Default value: `false`.	true
performance_level	string	No	The performance level of node data cloud disks. This parameter takes effect only for ESSD cloud disks.	PL1
size	string	Yes	The data cloud disk size. Valid values: 40 to 32767. Unit: GiB.	120
worker_instance_charge_type `deprecated`	string	No	[Deprecated] Use the instance_charge_type parameter in scaling_group of nodepool instead. The billing method for worker nodes. Valid values: `PrePaid`: Subscription. `PostPaid`: Pay-as-you-go. Default value: pay-as-you-go.	PrePaid
worker_instance_types `deprecated`	array	No	[Deprecated] Use the instance_types parameter in scaling_group of nodepool instead. The instance configurations for worker nodes.
	string	No	The instance type for worker nodes. Specify at least one instance type. For more information, refer to Instance families. Note The priority of an instance type decreases as its position in the array increases. If an instance cannot be created based on a higher-priority instance type, the system automatically uses the next-priority instance type.	ecs.n4.large
worker_period `deprecated`	integer	No	[Deprecated] Use the period parameter in scaling_group of nodepool instead. The subscription duration for worker nodes. This parameter takes effect and is required only when `worker_instance_charge_type` is set to `PrePaid`. Valid values: {1, 2, 3, 6, 12, 24, 36, 48, 60}. Default value: 1.	1
worker_period_unit `deprecated`	string	No	[Deprecated] Use the period_unit parameter in scaling_group of nodepool instead. The billing cycle for worker nodes. This parameter is required when the billing method is `PrePaid`. Valid values: `Month`. Currently, only monthly billing cycles are supported.	Month
worker_system_disk_category `deprecated`	string	No	[Deprecated] Use the system_disk_category parameter in scaling_group of nodepool instead. The system cloud disk type for worker nodes. For more information, refer to Block storage overview. Valid values: `cloud_efficiency`: ultra cloud disk. `cloud_ssd`: standard SSD. Default value: `cloud_ssd`.	cloud_efficiency
worker_system_disk_performance_level `deprecated`	string	No	[Deprecated] Use the system_disk_performance_level parameter in scaling_group of nodepool instead. When the system cloud disk is an ESSD, you can configure the performance level (PL) of the ESSD. For more information, refer to ESSD cloud disks. Valid values: PL0 PL1 PL2 PL3	PL1
worker_system_disk_size `deprecated`	integer	No	[Deprecated] Use the system_disk_size parameter in scaling_group of nodepool instead. The system cloud disk size for worker nodes. Unit: GiB. Valid values: [40,500]. The value of this parameter must be greater than or equal to max{40, ImageSize}. Default value: `120`.	120
worker_system_disk_snapshot_policy_id `deprecated`	string	No	[Deprecated] Use the system_disk_snapshot_policy_id parameter in scaling_group of nodepool instead. The ID of the automatic snapshot policy used by the system cloud disks of worker nodes.	sp-2zej1nogjvovnz4z****
worker_vswitch_ids `deprecated`	array	No	[Deprecated] Use the vswitch_ids parameter in scaling_group of nodepool instead. The list of vSwitches used by cluster nodes. Each node corresponds to one value. When you create a managed cluster with zero nodes, the `worker_vswitch_ids` field is not required, but you must provide `vswitch_ids`.
	string	No	The list of vSwitches for worker nodes. Valid values: [1,20]. To ensure high availability, select vSwitches in different zones. When you create a managed cluster with zero nodes, the `worker_vswitch_ids` field is not required, but you must provide `vswitch_ids`.	vsw-2ze3ds0mdip0hdz8i****
zone_id `deprecated`	string	No	[Deprecated] Use the `zone_ids` parameter instead. The active zone ID of the region to which the cluster belongs. This parameter is specific to ACK managed clusters. When you create an ACK managed cluster, if `vpc_id` and `vswitch_ids` are not specified, you must specify `zone_id` for the cluster to automatically create a VPC and related network resources in this zone. If `vpc_id` and `vswitch_ids` are specified, this parameter does not take effect.	cn-beiji****
zone_ids	array	No	The IDs of multiple zones in the region to which the cluster belongs. This parameter is specific to ACK managed clusters.
	string	No	The active zone ID of the region to which the cluster belongs. vSwitches are subject to automatic creation in this zone. When you create an ACK managed cluster, if `vpc_id` and `vswitch_ids` are not specified, specify `zone_ids` for the cluster to automatically create a VPC and related network resources in multiple active zones. If `vpc_id` and `vswitch_ids` are specified, this parameter does not take effect.	cn-beijing-h

Response elements

Element	Type	Description	Example
	object	The response body.
cluster_id	string	The cluster ID.	cb95aa626a47740afbf6aa099b650****
request_id	string	The request ID.	687C5BAA-D103-4993-884B-C35E4314****
task_id	string	The task ID.	T-5a54309c80282e39ea****

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.