Help Center/ Cloud Container Engine/ API Reference (Kuala Lumpur Region)/ APIs/ Cluster Management/ Creating a Cluster

Updated on 2024-10-22 GMT+08:00

View PDF

Creating a Cluster

Function

This API is used to create an empty cluster, which has only master nodes but no worker nodes. After creating a cluster by calling this API, you can add nodes by creating nodes.

The URL for cluster management is in the format of **https://Endpoint/uri, in which uri indicates the resource path, that is, the path for API access.
By default, ICAgent is not installed when you call this API to create a cluster. If you need to install ICAgent, add "cluster.install.addons.external/install":"[{"addonTemplateName":"icagent"}]" to annotations in the request body. ICAgent will be automatically installed during cluster creation. ICAgent is an O&M data collection agent used by Application Performance Management (APM). It runs on each server to collect data from probes in real time. ICAgent is the prerequisite for achieving application O&M. If ICAgent is not installed, the application O&M functions cannot be used.

Constraints

Before calling the CCE API to create a cluster, ensure that the following conditions are met:

A VPC is available.
CIDR blocks have been properly set for containers and Services. They are not editable after cluster creation, unless you create a new cluster.
An agency has been correctly created and is not deleted. If the agency verification fails, the cluster fails to be created. You can log in to the CCE console. If no agency is created, the system prompts you to create one. If an agency has been created, no message is displayed.
By default, an account can create a maximum of five clusters in each region. If you need to create more clusters, you can submit an application to increase the quota.

URI

POST /api/v3/projects/{project_id}/clusters

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the value, see How to Obtain Parameters in the API URI.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Message body type (format).
X-Auth-Token	Yes	String	Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. For details, see Obtaining a User Token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
kind	Yes	String	API type. The value is fixed at Cluster or cluster and cannot be changed.
apiVersion	Yes	String	API version. The value is fixed at v3 and cannot be changed.
metadata	Yes	ClusterMetadata object	Basic information about a cluster. Metadata is a collection of attributes.
spec	Yes	ClusterSpec object	Detailed description of the cluster. CCE creates or updates objects by defining or updating spec.
status	No	ClusterStatus object	Cluster status and job ID of the cluster creation job.

**Table 4** ClusterMetadata
Parameter	Mandatory	Type	Description
name	Yes	String	Cluster name. Enter 4 to 128 characters, starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed.
uid	No	String	Cluster ID, which uniquely identifies a cluster. This ID is automatically generated after a cluster is created. Only the automatically generated ID will take effect.
alias	No	String	Alias of a cluster name displayed on the CCE console, and the name can be changed. Enter 4 to 128 characters, starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed. A cluster alias must be unique. In the request body for creating or updating a cluster, if the cluster alias is not specified or set to null, the cluster name will be used as the cluster alias. In the response body for obtaining a cluster, the cluster alias is returned. If it is not configured, the cluster name will be returned.
annotations	No	Map<String,String>	Cluster annotations, in the format of key-value pairs. "annotations": { "key1" : "value1", "key2" : "value2" } NOTE: annotations: Does not label or select objects. The metadata in annotations may be small or large, structured or unstructured, and may include characters that are not allowed in labels. This field is not stored in the database and is used only to specify the add-ons to be installed in the cluster. Install ICAgent during cluster creation by adding the key-value pair "cluster.install.addons.external/install":"[{"addonTemplateName":"icagent"}]".
labels	No	Map<String,String>	Cluster labels, in the format of key-value pairs. NOTE: The value of this field is automatically generated by the system and is used by the frontend to identify the features supported by the cluster during the upgrade. Customized values are invalid.
creationTimestamp	No	String	Time when the cluster was created.
updateTimestamp	No	String	Time when the cluster was updated.

**Table 5** ClusterSpec
Parameter	Mandatory	Type	Description
category	No	String	Cluster type. Options: CCE: CCE cluster CCE cluster supports hybrid deployment of VMs and BMSs, and heterogeneous nodes such as GPU and NPU nodes, allowing you to run your containers in a secure and stable container runtime environment based on a high-performance network model.
type	No	String	Master node architecture: VirtualMachine: x86
flavor	Yes	String	Cluster specifications. Specifications of clusters of 1.15 or later versions can be changed after they are created. For details, see Modifying Cluster Specifications. Options: cce.s1.small: a small-scale CCE cluster with one master node and a maximum of 50 worker nodes cce.s1.medium: a medium-scale CCE cluster with one master node and a maximum of 200 worker nodes cce.s2.small: a small-scale CCE cluster with three master nodes and a maximum of 50 worker nodes cce.s2.medium: a medium-scale CCE cluster with three master nodes and a maximum of 200 worker nodes cce.s2.large: a large-scale CCE cluster with three master nodes and a maximum of 1,000 worker nodes cce.s2.xlarge: an ultra-large-scale CCE cluster with three master nodes and a maximum of 2,000 worker nodes NOTE: The fields in the parameters are described as follows: s1: specifies a cluster with one master node. If the master node is faulty, the cluster will become unavailable, but running workloads in the cluster are not affected. s2: specifies an HA cluster with three master nodes. If one of the master nodes is faulty, the cluster is still available. small: specifies that a cluster can manage a maximum of 50 worker nodes. medium: specifies that a cluster can manage a maximum of 200 worker nodes. large: specifies that a cluster can manage a maximum of 1,000 worker nodes. xlarge: specifies that a cluster can manage a maximum of 2,000 worker nodes.
version	No	String	Cluster version, which mirrors the baseline version of the Kubernetes community. The latest version is recommended. You can create clusters of two latest versions on the CCE console. To learn which cluster versions are available, log in to the CCE console, create a cluster, and check the Cluster Version parameter. You can call APIs to create clusters of other versions. However, these cluster versions will be gradually terminated. For details about the support policy, see the CCE announcement. NOTE: If not specified, a cluster of the latest version will be created. If a baseline cluster version is specified but the R version is not specified, a cluster of the latest R version will be created by default. It is a good practice not to specify the R version.
platformVersion	No	String	CCE cluster platform version, indicating the internal version under the cluster version (version). Platform versions are used to trace iterations in a major cluster version. They are unique within a major cluster version and recounted when the major cluster version changes. This parameter cannot be customized. When you create a cluster, the latest corresponding platform version is automatically selected. The format of platformVersion is cce.X.Y. X: internal feature version, indicating changes in features, patches, or OS support in the cluster version. The value starts from 1 and increases monotonically. Y: patch version of an internal feature version. It is used only for software package update after the feature version is brought online. No other modification is involved. The value starts from 0 and increases monotonically.
description	No	String	Cluster description, for example, which purpose the cluster is intended to serve. By default, this field is left unspecified. To modify cluster description after the cluster is created, call the API for updating cluster information or go to the cluster details page on the CCE console. Only UTF-8 encoding is supported.
customSan	No	Array of strings	Custom SAN field in the server certificate of the cluster API server, which must comply with the SSL and X509 format specifications. Duplicate names are not allowed. Must comply with the IP address and domain name formats. Example: SAN 1: DNS Name=example.com SAN 2: DNS Name=www.example.com SAN 3: DNS Name=example.net SAN 4: IP Address=93.184.216.34
ipv6enable	No	Boolean	Whether the cluster supports IPv6 addresses. This field is supported in clusters of v1.15 and later versions.
hostNetwork	Yes	HostNetwork object	Node networking parameters, including VPC and subnet ID. This field is mandatory because nodes in a cluster communicate with each other by using a VPC.
containerNetwork	Yes	ContainerNetwork object	Container networking parameters, including the container network model and container CIDR block.
serviceNetwork	No	ServiceNetwork object	Service CIDR block, including IPv4 CIDR blocks.
authentication	No	Authentication object	Configurations of the cluster authentication mode.
billingMode	No	Integer	Billing mode of a cluster. 0: pay-per-use Defaults to pay-per-use.
masters	No	Array of MasterSpec objects	Advanced configurations of master nodes
kubernetesSvcIpRange	No	String	Service CIDR blocks for Kubernetes clusterIPs. This field is available only for clusters of v1.11.7 and later. If this parameter is not specified during cluster creation, the default value 10.247.0.0/16 will be used. This parameter is deprecated. Use serviceNetwork instead. The new field contains the IPv4 CIDR blocks.
clusterTags	No	Array of ResourceTag objects	Cluster resource tags.
kubeProxyMode	No	String	Service forwarding mode. Options: iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes. ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during Service updates. It is suitable for large-sized clusters. NOTE: iptables is used by default.
az	No	String	AZ. This field is returned only for a query.
extendParam	No	ClusterExtendParam object	Extended field to decide whether the cluster will span across AZs or belong to a specified enterprise project, or whether a dedicated CCE cluster is to be created.
supportIstio	No	Boolean	Whether Istio is supported.
configurationsOverride	No	Array of PackageConfiguration objects	Whether to overwrite the default component configurations of the cluster. If a component or a parameter that is not supported by the component is specified, this configuration is ignored.

**Table 6** HostNetwork
Parameter	Mandatory	Type	Description
vpc	Yes	String	ID of the VPC used to create a master node. Obtain the public address by performing the following steps: Method 1: Log in to the VPC console, and click the name of a VPC to view the VPC ID on the displayed details page. Method 2: Use the VPC API to query the VPC ID.
subnet	Yes	String	Network ID of the subnet used to create a master node. Methods: Method 1: Log in to VPC console and click the target subnet on the Subnets tab page. You can view the network ID on the displayed page. Method 2: Use the VPC API for querying subnets. . .
SecurityGroup	No	String	Default worker node security group ID of the cluster. If specified, the cluster will be bound to the target security group. Otherwise, the system will automatically create a default worker node security group for you. The default worker node security group needs to allow access from certain ports to ensure normal communications.

**Table 7** ContainerNetwork
Parameter	Mandatory	Type	Description
mode	Yes	String	Container network model. Select one of the following possible values: overlay_l2: an overlay_l2 network (container tunnel network) built for containers by using OpenVSwitch (OVS). vpc-router: an underlay_l2 network built for containers by using IPvlan and custom VPC routes.
cidr	No	String	Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19. If the selected CIDR block conflicts with existing ones, an error will be reported. Not editable after the cluster is created. (deprecated. A specified cidrs will make cidr invalid.)
cidrs	No	Array of ContainerCIDR objects	List of container CIDR blocks. In clusters of v1.21 or later, the cidrs field is used. When the cluster network type is vpc-router, you can configure a maximum of 20 container CIDR blocks. In cluster versions earlier than v1.21, if the cidrs field is used, the first CIDR element in the array is used as the container CIDR block. The configuration cannot be modified after the cluster is created.

**Table 8** ContainerCIDR
Parameter	Mandatory	Type	Description
cidr	Yes	String	Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, and 192.168.0.0/16-19

**Table 9** EniNetwork
Parameter	Mandatory	Type	Description
eniSubnetId	Yes	String	IPv4 subnet ID of ENI subnet. (IPv6 is not supported and is being discarded.) You can obtain it in either of the following ways: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the IPv4 subnet ID on the displayed page. Method 2: Use the VPC API for querying subnets.
eniSubnetCIDR	No	String	ENI subnet CIDR (being discarded)
subnets	Yes	Array of NetworkSubnet objects	List of IPv4 subnet IDs

**Table 10** NetworkSubnet
Parameter	Mandatory	Type	Description
subnetID	Yes	String	IPv4 subnet ID of the subnet for creating master nodes. Currently, IPv6 is not supported. You can obtain it in either of the following ways: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the IPv4 subnet ID on the displayed page. Method 2: Use the VPC API for querying subnets.

**Table 11** ServiceNetwork
Parameter	Mandatory	Type	Description
IPv4CIDR	No	String	Value range of the Kubernetes clusterIP IPv4 CIDR blocks. If this parameter is not specified during cluster creation, the default value 10.247.0.0/16 will be used.

**Table 12** Authentication
Parameter	Mandatory	Type	Description
mode	No	String	Cluster authentication mode. Clusters of Kubernetes v1.11 or earlier support x509, rbac, and authenticating_proxy. Defaults to x509. Clusters of Kubernetes v1.13 or later support rbac and authenticating_proxy. Defaults to rbac.
authenticatingProxy	No	AuthenticatingProxy object	Configuration related to the authenticating_proxy mode. This field is mandatory when the authentication mode is authenticating_proxy.

**Table 13** AuthenticatingProxy
Parameter	Mandatory	Type	Description
ca	No	String	X509 CA certificate (Base64-encoded) configured in authenticating_proxy mode. This field is mandatory when the cluster authentication mode is authenticating_proxy. Maximum size: 1 MB
cert	No	String	Client certificate issued by the X509 CA certificate configured in authenticating_proxy mode, which is used for authentication from kube-apiserver to the extended API server. (The value must be Base64-encoded.) This field is mandatory when the cluster authentication mode is authenticating_proxy.
privateKey	No	String	Private key of the client certificate issued by the X509 CA certificate configured in authenticating_proxy mode, which is used for authentication from kube-apiserver to the extended API server. The private key used by the Kubernetes cluster does not support password encryption. Use an unencrypted private key. (The value must be Base64-encoded.) This field is mandatory when the cluster authentication mode is authenticating_proxy.

**Table 14** MasterSpec
Parameter	Mandatory	Type	Description
availabilityZone	No	String	AZ

**Table 15** ResourceTag
Parameter	Mandatory	Type	Description
key	No	String	Key. Cannot be null. Max characters: 128. Use letters, digits, and spaces in UTF-8 format. Can contain the following special characters: _.:/=+-@. Cannot start with _sys_.
value	No	String	Value. Can be null but not the default. Max characters: 255. Use letters, digits, and spaces in UTF-8 format. Can contain the following special characters: _.:/=+-@.

**Table 16** ClusterExtendParam
Parameter	Mandatory	Type	Description
clusterAZ	No	String	AZ of master nodes in a cluster. multi_az: (Optional) The cluster will span across AZs. Multiple AZs can be configured only for a cluster with multiple master nodes is used. AZ of the dedicated cloud computing pool: The cluster will be deployed in the AZ of Dedicated Cloud (DeC). It is mandatory for dedicated CCE clusters.
dssMasterVolumes	No	String	Whether the system and data disks of a master node use dedicated distributed storage. If this parameter is omitted or left unspecified, EVS disks are used by default. This parameter is mandatory for dedicated CCE clusters. It is in the following format: <rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType> Field description: rootVol is the system disk. dataVol is the data disk. dssPoolID indicates the ID of the DSS storage pool. volType indicates the storage volume type of the DSS storage pool, such as SAS and SSD. Example: c950ee97-587c-4f24-8a74-3367e3da570f.sas;6edbc2f4-1507-44f8-ac0d-eed1d2608d38.ssd NOTE: This field cannot be configured for non-dedicated CCE clusters.
enterpriseProjectId	No	String	ID of the enterprise project that a cluster belongs to. NOTE: An enterprise project can be configured only after the enterprise project function is enabled. The enterprise project to which the cluster belongs must be the same as that to which other cloud service resources associated with the cluster belong.
kubeProxyMode	No	String	Service forwarding mode. Two modes are available: iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes. ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during Service updates. It is suitable for large-sized clusters. NOTE: This parameter has been deprecated. If this parameter and kubeProxyMode in ClusterSpec are specified at the same time, the latter is used.
clusterExternalIP	No	String	EIP of the master node
alpha.cce/fixPoolMask	No	String	Number of mask bits of the fixed IP address pool of the container network model. This field is supported only for the VPC network model (vpc-router). This parameter determines the number of container IP addresses that can be allocated to a node. The maximum number of pods that can be created on a node is decided by this parameter and maxPods set during node creation. For details, see Maximum Number of Pods That Can Be Created on a Node. For integer characters, the value ranges from 24 to 28.
decMasterFlavor	No	String	Specifications of the master node in the dedicated hybrid cluster.
dockerUmaskMode	No	String	Default UmaskMode configuration of Docker in a cluster. The value can be secure or normal. If this parameter is not specified, normal is used by default.
kubernetes.io/cpuManagerPolicy	No	String	Cluster CPU management policy. The value can be none (or null) or static. The default value is none (or null). none or null: disables pods from exclusively occupying CPUs. Select this option if you want a large pool of shareable CPU cores. static: enables pods to exclusively occupy CPUs. Select this option if your workload is sensitive to CPU cache and scheduling latency.
upgradefrom	No	String	Records of how the cluster is upgraded to the current version

**Table 17** PackageConfiguration
Parameter	Mandatory	Type	Description
name	No	String	Component name.
configurations	No	Array of ConfigurationItem objects	Component configuration item.

**Table 18** ConfigurationItem
Parameter	Mandatory	Type	Description
name	No	String	Component configuration item name.
value	No	Object	Component configuration item value.

**Table 19** ClusterStatus
Parameter	Mandatory	Type	Description
phase	No	String	Cluster status. Options: Available: The cluster is running properly. Unavailable: The cluster is exhibiting unexpected behavior. Manually delete it. ScalingUp: Nodes are being added to the cluster. ScalingDown: The cluster is being downsized to fewer nodes. Creating: The cluster is being created. Deleting: The cluster is being deleted. Upgrading: The cluster is being upgraded. Resizing: Cluster specifications are being changed. RollingBack: The cluster is being rolled back. RollbackFailed: The cluster rollback is abnormal. Hibernating: The cluster is being hibernated. Hibernation: The cluster is in hibernation. Awaking: The cluster is being woken up from hibernation. Empty: The cluster does not have any resources. This field is discarded. Error: Resources in the cluster are abnormal. Manually delete the cluster.
jobID	No	String	ID of the task associated with the cluster in the current state. Options: ID of the associated task returned when creating a cluster. You can use it to obtain the auxiliary tasks for creating a cluster. ID of the associated task returned when a cluster fails to be deleted or is deleted. If this parameter is not empty, you can use the task ID to obtain the auxiliary tasks for deleting a cluster. NOTE: Tasks are short-lived. Do not use task information in scenarios such as cluster status determination.
reason	No	String	Reason of cluster state change. This parameter is returned if the cluster is not in the Available state.
message	No	String	Detailed information about why the cluster changes to the current state. This parameter is returned if the cluster is not in the Available state.
endpoints	No	Array of ClusterEndpoints objects	Access address of kube-apiserver in the cluster.
deleteOption	No	Object	Whether to delete configurations. This parameter is contained only in the response to the deletion request.
deleteStatus	No	Object	Whether to delete the status information. This parameter is contained only in the response to the deletion request.

**Table 20** ClusterEndpoints
Parameter	Mandatory	Type	Description
url	No	String	Access address of kube-apiserver in the cluster.
type	No	String	Type of the cluster access address. Internal: address for internal network access External: address for external network access

Response Parameters

Status code: 201

**Table 21** Response body parameters
Parameter	Type	Description
kind	String	API type. The value is fixed at Cluster or cluster and cannot be changed.
apiVersion	String	API version. The value is fixed at v3 and cannot be changed.
metadata	ClusterMetadata object	Basic information about a cluster. Metadata is a collection of attributes.
spec	ClusterSpec object	Detailed description of the cluster. CCE creates or updates objects by defining or updating spec.
status	ClusterStatus object	Cluster status and job ID of the cluster creation job.

**Table 22** ClusterMetadata
Parameter	Type	Description
name	String	Cluster name. Enter 4 to 128 characters, starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed.
uid	String	Cluster ID, which uniquely identifies a cluster. This ID is automatically generated after a cluster is created. Only the automatically generated ID will take effect.
alias	String	Alias of a cluster name displayed on the CCE console, and the name can be changed. Enter 4 to 128 characters, starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed. A cluster alias must be unique. In the request body for creating or updating a cluster, if the cluster alias is not specified or set to null, the cluster name will be used as the cluster alias. In the response body for obtaining a cluster, the cluster alias is returned. If it is not configured, the cluster name will be returned.
annotations	Map<String,String>	Cluster annotations, in the format of key-value pairs. "annotations": { "key1" : "value1", "key2" : "value2" } NOTE: annotations: Does not label or select objects. The metadata in annotations may be small or large, structured or unstructured, and may include characters that are not allowed in labels. This field is not stored in the database and is used only to specify the add-ons to be installed in the cluster. Install ICAgent during cluster creation by adding the key-value pair "cluster.install.addons.external/install":"[{"addonTemplateName":"icagent"}]".
labels	Map<String,String>	Cluster labels, in the format of key-value pairs. NOTE: The value of this field is automatically generated by the system and is used by the frontend to identify the features supported by the cluster during the upgrade. Customized values are invalid.
creationTimestamp	String	Time when the cluster was created.
updateTimestamp	String	Time when the cluster was updated.

**Table 23** ClusterSpec
Parameter	Type	Description
category	String	Cluster type. Options: CCE: CCE cluster CCE cluster supports hybrid deployment of VMs and BMSs, and heterogeneous nodes such as GPU and NPU nodes, allowing you to run your containers in a secure and stable container runtime environment based on a high-performance network model.
type	String	Master node architecture: VirtualMachine: x86
flavor	String	Cluster specifications. Specifications of clusters of 1.15 or later versions can be changed after they are created. For details, see Modifying Cluster Specifications. Options: cce.s1.small: a small-scale CCE cluster with one master node and a maximum of 50 worker nodes cce.s1.medium: a medium-scale CCE cluster with one master node and a maximum of 200 worker nodes cce.s2.small: a small-scale CCE cluster with three master nodes and a maximum of 50 worker nodes cce.s2.medium: a medium-scale CCE cluster with three master nodes and a maximum of 200 worker nodes cce.s2.large: a large-scale CCE cluster with three master nodes and a maximum of 1,000 worker nodes cce.s2.xlarge: an ultra-large-scale CCE cluster with three master nodes and a maximum of 2,000 worker nodes NOTE: The fields in the parameters are described as follows: s1: specifies a cluster with one master node. If the master node is faulty, the cluster will become unavailable, but running workloads in the cluster are not affected. s2: specifies an HA cluster with three master nodes. If one of the master nodes is faulty, the cluster is still available. small: specifies that a cluster can manage a maximum of 50 worker nodes. medium: specifies that a cluster can manage a maximum of 200 worker nodes. large: specifies that a cluster can manage a maximum of 1,000 worker nodes. xlarge: specifies that a cluster can manage a maximum of 2,000 worker nodes.
version	String	Cluster version, which mirrors the baseline version of the Kubernetes community. The latest version is recommended. You can create clusters of two latest versions on the CCE console. To learn which cluster versions are available, log in to the CCE console, create a cluster, and check the Cluster Version parameter. You can call APIs to create clusters of other versions. However, these cluster versions will be gradually terminated. For details about the support policy, see the CCE announcement. NOTE: If not specified, a cluster of the latest version will be created. If a baseline cluster version is specified but the R version is not specified, a cluster of the latest R version will be created by default. It is a good practice not to specify the R version.
platformVersion	String	CCE cluster platform version, indicating the internal version under the cluster version (version). Platform versions are used to trace iterations in a major cluster version. They are unique within a major cluster version and recounted when the major cluster version changes. This parameter cannot be customized. When you create a cluster, the latest corresponding platform version is automatically selected. The format of platformVersion is cce.X.Y. X: internal feature version, indicating changes in features, patches, or OS support in the cluster version. The value starts from 1 and increases monotonically. Y: patch version of an internal feature version. It is used only for software package update after the feature version is brought online. No other modification is involved. The value starts from 0 and increases monotonically.
description	String	Cluster description, for example, which purpose the cluster is intended to serve. By default, this field is left unspecified. To modify cluster description after the cluster is created, call the API for updating cluster information or go to the cluster details page on the CCE console. Only UTF-8 encoding is supported.
customSan	Array of strings	Custom SAN field in the server certificate of the cluster API server, which must comply with the SSL and X509 format specifications. Duplicate names are not allowed. Must comply with the IP address and domain name formats. Example: SAN 1: DNS Name=example.com SAN 2: DNS Name=www.example.com SAN 3: DNS Name=example.net SAN 4: IP Address=93.184.216.34
ipv6enable	Boolean	Whether the cluster supports IPv6 addresses. This field is supported in clusters of v1.15 and later versions.
hostNetwork	HostNetwork object	Node networking parameters, including VPC and subnet ID. This field is mandatory because nodes in a cluster communicate with each other by using a VPC.
containerNetwork	ContainerNetwork object	Container networking parameters, including the container network model and container CIDR block.
serviceNetwork	ServiceNetwork object	Service CIDR block, including IPv4 CIDR blocks.
authentication	Authentication object	Configurations of the cluster authentication mode.
billingMode	Integer	Billing mode of a cluster. 0: pay-per-use Defaults to pay-per-use.
masters	Array of MasterSpec objects	Advanced configurations of master nodes
kubernetesSvcIpRange	String	Service CIDR blocks for Kubernetes clusterIPs. This field is available only for clusters of v1.11.7 and later. If this parameter is not specified during cluster creation, the default value 10.247.0.0/16 will be used. This parameter is deprecated. Use serviceNetwork instead. The new field contains the IPv4 CIDR blocks.
clusterTags	Array of ResourceTag objects	Cluster resource tags.
kubeProxyMode	String	Service forwarding mode. Options: iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes. ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during Service updates. It is suitable for large-sized clusters. NOTE: iptables is used by default.
az	String	AZ. This field is returned only for a query.
extendParam	ClusterExtendParam object	Extended field to decide whether the cluster will span across AZs or belong to a specified enterprise project, or whether a dedicated CCE cluster is to be created.
supportIstio	Boolean	Whether Istio is supported.
configurationsOverride	Array of PackageConfiguration objects	Whether to overwrite the default component configurations of the cluster. If a component or a parameter that is not supported by the component is specified, this configuration is ignored.

**Table 24** HostNetwork
Parameter	Type	Description
vpc	String	ID of the VPC used to create a master node. Obtain the public address by performing the following steps: Method 1: Log in to the VPC console, and click the name of a VPC to view the VPC ID on the displayed details page. Method 2: Use the VPC API to query the VPC ID.
subnet	String	Network ID of the subnet used to create a master node. Methods: Method 1: Log in to VPC console and click the target subnet on the Subnets tab page. You can view the network ID on the displayed page. Method 2: Use the VPC API for querying subnets. . .
SecurityGroup	String	Default worker node security group ID of the cluster. If specified, the cluster will be bound to the target security group. Otherwise, the system will automatically create a default worker node security group for you. The default worker node security group needs to allow access from certain ports to ensure normal communications.

**Table 25** ContainerNetwork
Parameter	Type	Description
mode	String	Container network model. Select one of the following possible values: overlay_l2: an overlay_l2 network (container tunnel network) built for containers by using OpenVSwitch (OVS). vpc-router: an underlay_l2 network built for containers by using IPvlan and custom VPC routes.
cidr	String	Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19. If the selected CIDR block conflicts with existing ones, an error will be reported. Not editable after the cluster is created. (deprecated. A specified cidrs will make cidr invalid.)
cidrs	Array of ContainerCIDR objects	List of container CIDR blocks. In clusters of v1.21 or later, the cidrs field is used. When the cluster network type is vpc-router, you can configure a maximum of 20 container CIDR blocks. In cluster versions earlier than v1.21, if the cidrs field is used, the first CIDR element in the array is used as the container CIDR block. The configuration cannot be modified after the cluster is created.

**Table 26** ContainerCIDR
Parameter	Type	Description
cidr	String	Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, and 192.168.0.0/16-19

**Table 27** EniNetwork
Parameter	Type	Description
eniSubnetId	String	IPv4 subnet ID of ENI subnet. (IPv6 is not supported and is being discarded.) You can obtain it in either of the following ways: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the IPv4 subnet ID on the displayed page. Method 2: Use the VPC API for querying subnets.
eniSubnetCIDR	String	ENI subnet CIDR (being discarded)
subnets	Array of NetworkSubnet objects	List of IPv4 subnet IDs

**Table 28** NetworkSubnet
Parameter	Type	Description
subnetID	String	IPv4 subnet ID of the subnet for creating master nodes. Currently, IPv6 is not supported. You can obtain it in either of the following ways: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the IPv4 subnet ID on the displayed page. Method 2: Use the VPC API for querying subnets.

**Table 29** ServiceNetwork
Parameter	Type	Description
IPv4CIDR	String	Value range of the Kubernetes clusterIP IPv4 CIDR blocks. If this parameter is not specified during cluster creation, the default value 10.247.0.0/16 will be used.

**Table 30** Authentication
Parameter	Type	Description
mode	String	Cluster authentication mode. Clusters of Kubernetes v1.11 or earlier support x509, rbac, and authenticating_proxy. Defaults to x509. Clusters of Kubernetes v1.13 or later support rbac and authenticating_proxy. Defaults to rbac.
authenticatingProxy	AuthenticatingProxy object	Configuration related to the authenticating_proxy mode. This field is mandatory when the authentication mode is authenticating_proxy.

**Table 31** AuthenticatingProxy
Parameter	Type	Description
ca	String	X509 CA certificate (Base64-encoded) configured in authenticating_proxy mode. This field is mandatory when the cluster authentication mode is authenticating_proxy. Maximum size: 1 MB
cert	String	Client certificate issued by the X509 CA certificate configured in authenticating_proxy mode, which is used for authentication from kube-apiserver to the extended API server. (The value must be Base64-encoded.) This field is mandatory when the cluster authentication mode is authenticating_proxy.
privateKey	String	Private key of the client certificate issued by the X509 CA certificate configured in authenticating_proxy mode, which is used for authentication from kube-apiserver to the extended API server. The private key used by the Kubernetes cluster does not support password encryption. Use an unencrypted private key. (The value must be Base64-encoded.) This field is mandatory when the cluster authentication mode is authenticating_proxy.

**Table 32** MasterSpec
Parameter	Type	Description
availabilityZone	String	AZ

**Table 33** ResourceTag
Parameter	Type	Description
key	String	Key. Cannot be null. Max characters: 128. Use letters, digits, and spaces in UTF-8 format. Can contain the following special characters: _.:/=+-@. Cannot start with _sys_.
value	String	Value. Can be null but not the default. Max characters: 255. Use letters, digits, and spaces in UTF-8 format. Can contain the following special characters: _.:/=+-@.

**Table 34** ClusterExtendParam
Parameter	Type	Description
clusterAZ	String	AZ of master nodes in a cluster. multi_az: (Optional) The cluster will span across AZs. Multiple AZs can be configured only for a cluster with multiple master nodes is used. AZ of the dedicated cloud computing pool: The cluster will be deployed in the AZ of Dedicated Cloud (DeC). It is mandatory for dedicated CCE clusters.
dssMasterVolumes	String	Whether the system and data disks of a master node use dedicated distributed storage. If this parameter is omitted or left unspecified, EVS disks are used by default. This parameter is mandatory for dedicated CCE clusters. It is in the following format: <rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType> Field description: rootVol is the system disk. dataVol is the data disk. dssPoolID indicates the ID of the DSS storage pool. volType indicates the storage volume type of the DSS storage pool, such as SAS and SSD. Example: c950ee97-587c-4f24-8a74-3367e3da570f.sas;6edbc2f4-1507-44f8-ac0d-eed1d2608d38.ssd NOTE: This field cannot be configured for non-dedicated CCE clusters.
enterpriseProjectId	String	ID of the enterprise project that a cluster belongs to. NOTE: An enterprise project can be configured only after the enterprise project function is enabled. The enterprise project to which the cluster belongs must be the same as that to which other cloud service resources associated with the cluster belong.
kubeProxyMode	String	Service forwarding mode. Two modes are available: iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes. ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during Service updates. It is suitable for large-sized clusters. NOTE: This parameter has been deprecated. If this parameter and kubeProxyMode in ClusterSpec are specified at the same time, the latter is used.
clusterExternalIP	String	EIP of the master node
alpha.cce/fixPoolMask	String	Number of mask bits of the fixed IP address pool of the container network model. This field is supported only for the VPC network model (vpc-router). This parameter determines the number of container IP addresses that can be allocated to a node. The maximum number of pods that can be created on a node is decided by this parameter and maxPods set during node creation. For details, see Maximum Number of Pods That Can Be Created on a Node. For integer characters, the value ranges from 24 to 28.
decMasterFlavor	String	Specifications of the master node in the dedicated hybrid cluster.
dockerUmaskMode	String	Default UmaskMode configuration of Docker in a cluster. The value can be secure or normal. If this parameter is not specified, normal is used by default.
kubernetes.io/cpuManagerPolicy	String	Cluster CPU management policy. The value can be none (or null) or static. The default value is none (or null). none or null: disables pods from exclusively occupying CPUs. Select this option if you want a large pool of shareable CPU cores. static: enables pods to exclusively occupy CPUs. Select this option if your workload is sensitive to CPU cache and scheduling latency.
upgradefrom	String	Records of how the cluster is upgraded to the current version

**Table 35** PackageConfiguration
Parameter	Type	Description
name	String	Component name.
configurations	Array of ConfigurationItem objects	Component configuration item.

**Table 36** ConfigurationItem
Parameter	Type	Description
name	String	Component configuration item name.
value	Object	Component configuration item value.

**Table 37** ClusterStatus
Parameter	Type	Description
phase	String	Cluster status. Options: Available: The cluster is running properly. Unavailable: The cluster is exhibiting unexpected behavior. Manually delete it. ScalingUp: Nodes are being added to the cluster. ScalingDown: The cluster is being downsized to fewer nodes. Creating: The cluster is being created. Deleting: The cluster is being deleted. Upgrading: The cluster is being upgraded. Resizing: Cluster specifications are being changed. RollingBack: The cluster is being rolled back. RollbackFailed: The cluster rollback is abnormal. Hibernating: The cluster is being hibernated. Hibernation: The cluster is in hibernation. Awaking: The cluster is being woken up from hibernation. Empty: The cluster does not have any resources. This field is discarded. Error: Resources in the cluster are abnormal. Manually delete the cluster.
jobID	String	ID of the task associated with the cluster in the current state. Options: ID of the associated task returned when creating a cluster. You can use it to obtain the auxiliary tasks for creating a cluster. ID of the associated task returned when a cluster fails to be deleted or is deleted. If this parameter is not empty, you can use the task ID to obtain the auxiliary tasks for deleting a cluster. NOTE: Tasks are short-lived. Do not use task information in scenarios such as cluster status determination.
reason	String	Reason of cluster state change. This parameter is returned if the cluster is not in the Available state.
message	String	Detailed information about why the cluster changes to the current state. This parameter is returned if the cluster is not in the Available state.
endpoints	Array of ClusterEndpoints objects	Access address of kube-apiserver in the cluster.
deleteOption	Object	Whether to delete configurations. This parameter is contained only in the response to the deletion request.
deleteStatus	Object	Whether to delete the status information. This parameter is contained only in the response to the deletion request.

**Table 38** ClusterEndpoints
Parameter	Type	Description
url	String	Access address of kube-apiserver in the cluster.
type	String	Type of the cluster access address. Internal: address for internal network access External: address for external network access

Example Requests

Create an HA CCE cluster of v1.19 with three master nodes and a maximum of 50 worker nodes.

/api/v3/projects/{project_id}/clusters

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "cluster"
  },
  "spec" : {
    "category" : "CCE",
    "flavor" : "cce.s2.small",
    "version" : "v1.19",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881"
    },
    "containerNetwork" : {
      "mode" : "vpc-router",
      "cidr" : "10.0.0.0/16"
    },
    "kubernetesSvcIpRange" : "10.247.0.0/16",
    "description" : "",
    "billingMode" : 0,
    "extendParam" : {
      "kubeProxyMode" : "iptables",
      "alpha.cce/fixPoolMask" : "25",
      "enterpriseProjectId" : "0"
    },
    "authentication" : {
      "mode" : "rbac"
    },
    "ipv6enable" : false
  }
}

Create an HA CCE cluster of v1.19 with three master nodes and a maximum of 50 worker nodes and install ICAgent in the cluster.

/api/v3/projects/{project_id}/clusters

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "cluster",
    "annotations" : {
      "cluster.install.addons.external/install" : "[{\"addonTemplateName\":\"icagent\"}]"
    }
  },
  "spec" : {
    "category" : "CCE",
    "flavor" : "cce.s2.small",
    "version" : "v1.19",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881"
    },
    "containerNetwork" : {
      "mode" : "vpc-router",
      "cidr" : "10.0.0.0/16"
    },
    "kubernetesSvcIpRange" : "10.247.0.0/16",
    "description" : "",
    "billingMode" : 0,
    "extendParam" : {
      "kubeProxyMode" : "iptables",
      "alpha.cce/fixPoolMask" : "25",
      "enterpriseProjectId" : "0"
    },
    "authentication" : {
      "mode" : "rbac"
    },
    "ipv6enable" : false
  }
}

Create an HA CCE cluster of v1.19 with three master nodes and a maximum of 50 worker nodes and configure the default security group for custom nodes in the cluster.

/api/v3/projects/{project_id}/clusters

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "cluster"
  },
  "spec" : {
    "category" : "CCE",
    "flavor" : "cce.s2.small",
    "version" : "v1.19",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881",
      "SecurityGroup" : "a4ef108c-2ec6-492f-a6c4-7b64e25ae490"
    },
    "containerNetwork" : {
      "mode" : "vpc-router",
      "cidr" : "10.0.0.0/16"
    },
    "kubernetesSvcIpRange" : "10.247.0.0/16",
    "description" : "",
    "billingMode" : 0,
    "extendParam" : {
      "kubeProxyMode" : "iptables",
      "alpha.cce/fixPoolMask" : "25",
      "enterpriseProjectId" : "0"
    },
    "authentication" : {
      "mode" : "rbac"
    },
    "ipv6enable" : false
  }
}

Create an HA CCE cluster of v1.25 with three master nodes and a maximum of 50 worker nodes.

/api/v3/projects/{project_id}/clusters

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "cluster"
  },
  "spec" : {
    "category" : "Turbo",
    "flavor" : "cce.s2.small",
    "version" : "v1.25",
    "type" : "VirtualMachine",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881"
    },
    "containerNetwork" : {
      "mode" : "eni"
    },
    "eniNetwork" : {
      "eniSubnetId" : "861fb11d-2f0e-4c10-a98a-166dc26e4ff7",
      "eniSubnetCIDR" : "192.168.0.0/24",
      "subnets" : [ {
        "subnetID" : "861fb11d-2f0e-4c10-a98a-166dc26e4ff7"
      } ]
    },
    "serviceNetwork" : {
      "IPv4CIDR" : "10.247.0.0/16"
    },
    "description" : "",
    "billingMode" : 0,
    "extendParam" : {
      "kubeProxyMode" : "iptables",
      "enterpriseProjectId" : "0"
    },
    "authentication" : {
      "mode" : "rbac"
    },
    "ipv6enable" : false
  }
}

Example Responses

Status code: 201

The cluster creation job is successfully delivered.

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "alias" : "cluster",
    "name" : "cluster",
    "uid" : "bce956e1-87f3-11ec-b5e5-0255ac101514",
    "creationTimestamp" : "2022-02-07 08:55:45.785425492 +0000 UTC",
    "updateTimestamp" : "2022-02-07 08:55:45.78542824 +0000 UTC",
    "annotations" : {
      "jobid" : "bd42f724-87f3-11ec-b5e5-0255ac101514",
      "resourceJobId" : "bce99f78-87f3-11ec-b5e5-0255ac101514"
    }
  },
  "spec" : {
    "category" : "CCE",
    "type" : "VirtualMachine",
    "flavor" : "cce.s2.small",
    "version" : "v1.19.10-r0",
    "platformVersion" : "cce.5.0",
    "hostNetwork" : {
      "vpc" : "030bfb19-5fa7-42ad-8a0d-c0721d268867",
      "subnet" : "ca964acf-8468-4735-8229-97940ef6c881"
    },
    "containerNetwork" : {
      "mode" : "vpc-router",
      "cidr" : "10.0.0.0/16",
      "cidrs" : [ {
        "cidr" : "10.0.0.0/16"
      } ]
    },
    "eniNetwork" : { },
    "authentication" : {
      "mode" : "rbac",
      "authenticatingProxy" : { }
    },
    "billingMode" : 0,
    "kubernetesSvcIpRange" : "10.247.0.0/16",
    "kubeProxyMode" : "iptables",
    "extendParam" : {
      "alpha.cce/fixPoolMask" : "25",
      "enterpriseProjectId" : "0",
      "kubeProxyMode" : "iptables",
      "orderID" : ""
    }
  },
  "status" : {
    "phase" : "Creating",
    "jobID" : "bd42f724-87f3-11ec-b5e5-0255ac101514"
  }
}