You can call the CreateCluster operation to create a Container Service for Kubernetes (ACK) managed cluster. To create worker nodes, see Create a node pool.

Debugging

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

Request 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" ]     
}

Request parameters

Table 1. Request body parameters
Category Parameter Type Required Example Description
Basic configurations name String Yes cluster-demo

The name of the cluster.

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 type of cluster. Set the value to ManagedKubernetes to create an ACK standard cluster.

cluster_spec String No ack.pro.small

The type of the ACK managed cluster. Valid values:

  • ack.pro.small: ACK Pro cluster
  • ack.standard: ACK standard cluster

Default value: ack.standard. If you leave this parameter empty, an ACK standard cluster is created.

For more information, see Introduction to professional managed Kubernetes clusters.

kubernetes_version String No 1.22.3-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 set 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 Overview of Kubernetes versions supported by ACK.

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:
  • Elastic Compute Service (ECS) instances in node pools.
  • The internal-facing Server Load Balancer (SLB) instance of the cluster API server.
Valid values:
  • PrePaid: subscription
  • PostPaid: pay-as-you-go

Default value: PostPaid

period Long No 1

The subscription duration. The subscription duration. 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.

period_unit String No Month

The billing cycle. This parameter is required if charge_type is set to PrePaid.

Set the value to Month. Resources are billed only on a monthly basis.

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****"]

Specifies the pod vSwitches. You must set this parameter if the cluster has Terway installed because each pod in the cluster uses a separate IP address.

container_cidr String Yes 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.

Notice
  • This parameter is required if the cluster uses Flannel as the network plug-in.
  • This parameter is optional if the cluster uses Terway as the network plug-in.
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 the existing security group that is specified for the cluster. You must set this parameter or the is_enterprise_security_group parameter. Nodes in the cluster are automatically added to the specified security group.

is_enterprise_security_group Boolean No true

Specifies whether to create an advanced security group. This parameter takes effect only if you leave the security_group_id parameter empty.

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.
  • true: creates an advanced security group.
  • false: does not create an advanced security group.

Default value: true.

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:25.

snat_entry Boolean No true

Specifies whether to configure SNAT rules for the VPC in which you want to deploy the cluster

  • If the VPC can access the Internet, set the value to false.
  • If the VPC does not support Internet access, valid values are:
    • true: configures SNAT rules. This enables Internet access for the cluster.
    • false: does not configure SNAT rules. In this case, the cluster cannot access the Internet.

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 you create the cluster. For more information, see Enable an existing ACK cluster to access the Internet by using SNAT.
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.

  • true: enables Internet access.
  • false: disables Internet access. If you set this parameter to false, the API server cannot be accessed over the Internet.

Default value: true.

load_balancer_spec String No slb.s2.small

The specification of the SLB instance that is created for the cluster API server. 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

Advanced settings timezone String No Asia/Shanghai

The time zone of the cluster. For more information, see Supported time zones.

proxy_mode String No ipvs

The kube-proxy mode. Valid values:

  • iptables is a kube-proxy mode. It uses iptables rules to conduct Service discovery and load balancing. The performance of this mode is limited by the size of the cluster. This mode is suitable for clusters that run a small number of Services.
  • IPVS is a high-performance kube-proxy mode. It uses Linux IP Virtual Server (IPVS) to conduct Service discovery and load balancing. This mode is suitable for clusters that run a large number of Services. We recommend that you use this mode in scenarios where high-performance load balancing is required.

Default value: ipvs.

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:

  • key: the key of the label
  • value: the value of the label
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

A service account is used to provide an identity for pods when they communicate with the API server. service-account-issuer is the issuer of the service account token, which corresponds to the iss field in the token payload.

For more information about service accounts, see Enable service account token volume projection.

api_audiences String No kubernetes.default.svc

A service account is used to provide an identity for pods when they communicate with the API server. api-audiences are valid identifiers of tokens. Audiences are used to validate tokens at the API server side. Separate multiple audiences with commas (,).

For more information about service accounts, see Enable service account token volume projection.

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: 60

disable_rollback Boolean No true

Specifies whether to perform a rollback when the cluster fails to be created. Valid values:

  • true: performs a rollback when the cluster fails to be created
  • false: does not perform a rollback when the cluster fails to be created

Default value: true.

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:

  • true: enables deletion protection for the cluster. This way, the cluster cannot be deleted in the ACK console or by calling API operations.
  • false: disables deletion protection for the cluster. This way, the cluster can be deleted in the ACK console or by calling API operations.

Default value: false.

Component settings 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 addons parameter to install specific components.

  • name: required. This parameter specifies the name of the component.
  • config: optional. If this parameter is left empty, no configurations are required.
  • disabled: optional. It specifies whether to disable automatic installation.

Network plug-in: required. The Flannel and Terway plug-ins are supported. Select one of the plug-ins for the cluster.

  • Specify the Flannel plug-in in the following format: [{"name":"flannel","config":""}].
  • Specify the Terway plug-in in the following format: [{"name": "terway-eniip","config": ""}].

Volume plug-in: required. The Container Storage Interface (CSI) and FlexVolume plug-ins are supported.

  • Specify the CSI plug-in in the following format: [{"name":"csi-plugin","config": ""},{"name": "csi-provisioner","config": ""}].
  • Specify the FlexVolume plug-in in the following format: [{"name": "flexvolume","config": ""}].

Log Service component: optional. We recommend that you enable Log Service. If Log Service is disabled, you cannot use the cluster auditing feature.

  • To use an existing Log Service project, specify the component in the following format: [{"name": "logtail-ds","config": "{\"IngressDashboardEnabled\":\"true\",\"sls_project_name\":\"your_sls_project_name\"}"}].
  • To create a Log Service project, specify the component in the following format: [{"name": "logtail-ds","config": "{\"IngressDashboardEnabled\":\"true\"}"}].

Ingress controller: optional. By default, the nginx-ingress-controller component is installed in ACK dedicated clusters.

  • To install nginx-ingress-controller and enable Internet access, specify the Ingress controller in the following format: [{"name":"nginx-ingress-controller","config":"{\"IngressSlbNetworkType\":\"internet\"}"}].
  • If you do not want to install nginx-ingress-controller, specify the component in the following format: [{"name": "nginx-ingress-controller","config": "","disabled": true}].

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.

controlplane_log_project String No k8s-log-xxx

The 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 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.

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 ID of the cluster.

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

The ID of the request.

task_id String T-5a54309c80282e39ea00002f

The ID of the task.

Examples

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. A value of ack.pro.small indicates ACK Pro cluster. A value of ack.standard indicates ACK standard cluster. 
    "kubernetes_version":"1.18.8-aliyun.1",  // The Kubernetes version of the cluster. Only the latest two 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":[                                // The pod vSwitches. You must specify pod vSwitches if the cluster uses Terway as the network plug-in because each pod uses a separate IP address.                      
        "vsw-8vbo5fwyqiw0bbtlq****"
    ],
    "container_cidr":"172.20.0.0/16",             // The CIDR block of pods. #required. This parameter is optional 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-eni"}. 
        },
        {
            "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"]
 }

Sample 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, visit the API Error Center.