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. Otherwise, the cluster cannot be created. If a VPC is available, you do not need to create a new one. A VPC provides an isolated, configurable, manageable virtual network environment for CCE clusters.
-
Before creating a cluster, you should properly plan the container and Service CIDR blocks. After a cluster using a container tunnel network is created, you cannot modify the CIDR blocks. After a cluster using a VPC network or Cloud Native 2.0 network is created, you can only add CIDR blocks or subnet CIDR blocks to the cluster but cannot modify the existing CIDR blocks or subnet CIDR blocks. To modify the existing CIDR blocks, you need to create a new cluster. Exercise caution when performing this operation.
-
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 to see if there is any agency. 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 up to 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
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
project_id |
Yes |
String |
Details: Project ID. For details about how to obtain the value, see How to Obtain Parameters in the API URI. Constraints: None Options: Project IDs of the account Default value: N/A |
Request Parameters
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
Content-Type |
Yes |
String |
Details: The request body type or format Constraints: The GET method is not verified. Options: Default value: N/A |
X-Auth-Token |
Yes |
String |
Details: 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. Constraints: None Options: N/A Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
kind |
Yes |
String |
Details: API type Constraints: The value cannot be changed. Options: Default value: N/A |
apiVersion |
Yes |
String |
Details: API version Constraints: The value cannot be changed. Options: Default value: N/A |
metadata |
Yes |
ClusterMetadata object |
Details: Basic information about a cluster. Metadata is a collection of attributes. Constraints: None |
spec |
Yes |
CreateClusterRequestSpec object |
Details: Detailed description about a cluster. CCE creates or updates objects by defining or updating spec. Constraints: None |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
name |
Yes |
String |
Details: Cluster name Constraints: None Options: Enter 4 to 128 characters starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed. Default value: N/A |
uid |
No |
String |
Details: Cluster ID, which identifies a cluster Constraints: The value is automatically generated after the object is created. A user-defined value will not take effect. Options: N/A Default value: N/A |
alias |
No |
String |
Details: Alias of a cluster name displayed on the CCE console. The name can be changed. A cluster alias must be unique. Constraints: 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 creating a cluster or other response bodies, if the cluster alias is not configured, no value will be returned. Options: Enter 4 to 128 characters starting with a letter and not starting or ending with a hyphen (-). Only digits, letters, and hyphens (-) are allowed. Default value: N/A |
annotations |
No |
Map<String,String> |
Details: Cluster annotations in the format of key-value pairs "annotations": { "key1" : "value1", "key2" : "value2" } Constraints: This field is not stored in the database and is only used to specify the add-ons to be installed in the cluster. Options: N/A Default value: N/A
NOTE:
|
labels |
No |
Map<String,String> |
Details: Cluster labels, in the format of key-value pairs Constraints: 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. Custom values are invalid. Options: N/A Default value: N/A |
creationTimestamp |
No |
String |
Details: Time when a cluster was created Constraints: The value is automatically recorded during cluster creation and cannot be specified. Options: N/A Default value: N/A |
updateTimestamp |
No |
String |
Details: Time when a cluster was updated Constraints: The value is automatically recorded during cluster updates and cannot be specified. Options: N/A Default value: N/A |
timezone |
No |
String |
Details: Time zone of a cluster. The time zone must be included in IANA Time Zone Database. Constraints: None Options: N/A Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
category |
No |
String |
Details: Cluster type Constraints: None Options: CCE clusters support hybrid deployment of VMs and BMSs, and heterogeneous nodes such as GPU and NPU nodes, allowing you to run your containers in a secure, stable container runtime environment based on a high-performance network model. Default value: CCE when the container network is not set to eni |
type |
No |
String |
Details: Master node architecture Constraints: None Options: Default value: VirtualMachine |
flavor |
Yes |
String |
Details: Cluster specifications. Specifications of clusters of v1.15 or later can be changed after they are created. For details, see Modifying Cluster Specifications. Configure this parameter based on actual service requirements. Constraints: None Options:
Default value: N/A
NOTE:
The fields in the parameters are described as follows:
|
version |
No |
String |
Details: Cluster version, which mirrors the baseline version of the Kubernetes community. The latest commercial version is recommended. You can create clusters of the latest three versions on the CCE console. To learn which cluster versions are available, log in to the CCE console, create a cluster, and check the supported cluster versions. 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. Constraints: The value must be in the format of vX.Y[.Z[-rN]], for example, v1.30, v1.30.0, or v1.30.0-r0. Specifying either of these values will create a cluster of version 1.30. Options: N/A Default value: |
platformVersion |
No |
String |
Details: CCE cluster platform version, which is an 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. Constraints: This parameter cannot be customized, and when you create a cluster, the latest corresponding platform version is selected automatically. Options: The format of platformVersion is cce.X.Y.
Default value: N/A |
legacyVersion |
No |
String |
Details: (Deprecated) Outdated version of CCE clusters, which serves no practical purpose and is only used to showcase the cluster version and platform version combination. The version number is globally unique. For example, if the cluster version is va.b and the platformVersion is cce.X.Y, the value of legacyVersion is va.b.X-rY. Constraints: None Options: N/A Default value: N/A |
description |
No |
String |
Details: Cluster description, for example, which purpose the cluster is intended to serve. By default, this parameter is left unspecified. To modify cluster description after a cluster is created, call the API for updating a specified cluster or go to the cluster details page on the CCE console. Constraints: Only UTF-8 encoding is supported. The length must be less than or equal to 200 bytes. Options: N/A Default value: N/A |
customSan |
No |
Array of strings |
Details: Custom Subject Alternative Name (SAN) in the server certificate of a cluster API server, which must comply with the SSL and X509 standard formats Constraints: Duplicate names are not allowed. Options: Values in the IP address or domain name format Default value: N/A 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 |
Details: Whether a cluster supports IPv6 addresses. It is supported by clusters v1.15 and later. Constraints: After IPv6 is enabled, iptables is not supported. The VPC network model does not support IPv4/IPv6 dual-stack. Options: Default value: false |
hostNetwork |
Yes |
HostNetwork object |
Details: Node network parameters, including VPC and subnet ID. This field is mandatory because nodes in a cluster communicate with each other using a VPC. Constraints: None |
containerNetwork |
Yes |
ContainerNetwork object |
Details: Container networking parameters, including the container network model and container CIDR block Constraints: None |
serviceNetwork |
No |
ServiceNetwork object |
Details: Service CIDR block, including IPv4 CIDR block Constraints: None |
publicAccess |
No |
PublicAccess object |
Details: Cluster API access control Constraints: None |
authentication |
No |
Authentication object |
Details: Configurations of the cluster authentication mode Constraints: None |
billingMode |
No |
Integer |
Details: Cluster billing mode Constraints: None Options: Default value: 0 |
masters |
No |
Array of MasterSpec objects |
Details: Advanced settings of the control plane nodes in a cluster. You can specify AZs for them. Constraints: If this parameter is not specified, no value is returned. |
kubernetesSvcIpRange |
No |
String |
Details: Service CIDR blocks which kubernetes clusterIP must fall within. This parameter is available only for clusters v1.11.7 and later. If this parameter is not specified during cluster creation, the default value 10.247.0.0/16 is used. This parameter is being deprecated, so you can use serviceNetwork instead. The new field contains the IPv4 CIDR blocks. Constraints: None Options: N/A Default value: N/A |
clusterTags |
No |
Array of ResourceTag objects |
Details: Cluster resource tags Constraints: None |
kubeProxyMode |
No |
String |
Details: Service forwarding mode Constraints: None Options:
Default value: iptables is used by default. |
az |
No |
String |
Details: AZ.
NOTE:
This field will be deprecated. You are advised to configure the AZs for the control plane nodes using the masters field. Constraints: None |
extendParam |
No |
ClusterExtendParam object |
Details: Extended field to decide whether a cluster will span across AZs or belong to a specified enterprise project, or whether a dedicated CCE cluster is to be created Constraints: None |
deletionProtection |
No |
Boolean |
Details: Cluster deletion protection, which prevents the deletion of a cluster when this function is enabled Constraints: None Options: Default value: false |
configurationsOverride |
No |
Array of PackageConfiguration objects |
Details: Overrides the default component configurations in a cluster. Constraints: If you specify a component or parameter that is not supported, the configuration item will be ignored. |
clusterOps |
No |
ClusterOps object |
Details: Cluster O&M settings Constraints: None |
encryptionConfig |
No |
EncryptionConfig object |
Details: Configuration of secret encryption. Only one encryption mode can be configured. By default, the CCE-managed key is used for encryption. (Users are not aware of the key being used.) Constraints: None Options: N/A Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
mode |
Yes |
String |
Details: Container network type Constraints: Only one container network type can be selected. Options:
Default value: N/A |
cidr |
No |
String |
Details: Container CIDR block. 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19 is recommended. If the selected CIDR block conflicts with existing ones, an error will be reported. Constraints: This parameter cannot be modified after the cluster is created. (It has been deprecated. If cidrs has been configured, the specified CIDR blocks will be ignored.) Once you have created a cluster that uses a VPC network, you can add new CIDR blocks, but you are unable to modify the existing ones. If you need to adjust the CIDR blocks, you will have to create a cluster. Options: Values in IPv4 CIDR format Default value: If this parameter is left blank, a unique CIDR block is randomly allocated from 172.(16–31).0.0/16 and 10.(0 | 16 | 32 | 48 | 64 | 80 | 96 | 112).0.0/12. |
cidrs |
No |
Array of ContainerCIDR objects |
Details: List of container CIDR blocks. In clusters 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 clusters earlier than v1.21, if the cidrs field is used, the first CIDR element in the array is used as the container CIDR block. Constraints: Once you have created a cluster that uses a container tunnel network, you cannot modify the CIDR blocks. Once you have created a cluster that uses a VPC network, you can add new CIDR blocks, but you are unable to modify the existing ones. If you need to adjust the CIDR blocks, you will have to create a cluster. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
cidr |
Yes |
String |
Details: Container CIDR block. 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19 is recommended. Constraints: If a CIDR block conflict occurs, an error will be reported. Options: N/A Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
eniSubnetId |
Yes |
String |
Details: IPv4 subnet ID of the subnet where an elastic network interface resides Constraints: IPv6 is not supported. This field will be deprecated. Use subnets instead. Options: N/A Default value: N/A To obtain the value: |
eniSubnetCIDR |
No |
String |
Details: ENI subnet CIDR block Constraints: This parameter is being deprecated. The new field subnets is recommended. Options: N/A Default value: N/A |
subnets |
Yes |
Array of NetworkSubnet objects |
Details: List of IPv4 subnet IDs Constraints: None |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
subnetID |
Yes |
String |
Details: ID of the IPv4 subnet where the container network interfaces are in Constraints: IPv6 is not supported. Options: N/A Default value: N/A To obtain the value: |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
IPv4CIDR |
No |
String |
Details: Value range of the Kubernetes clusterIP IPv4 CIDR block Constraints: None Options: N/A Default value: 10.247.0.0/16 |
IPv6CIDR |
No |
String |
Details: Value range of the Kubernetes clusterIP IPv6 CIDR block Constraints: IPv6 Service CIDR blocks can be configured only for CCE Turbo clusters with IPv6 dual stack enabled. Options: N/A Default value: Default value for a CCE Turbo cluster: fc00::/112 Default value for a CCE standard cluster: fd00:1234::/120 |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
cidrs |
No |
Array of strings |
Details: Trustlist of network CIDRs that are allowed to access cluster APIs. You are advised to allow the traffic from VPC and container network CIDRs. Constraints: This parameter is valid only when a cluster is created. Options: N/A Default value: By default, no trustlist is configured, and the value is 0.0.0.0/0. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
mode |
No |
String |
Details: Cluster authentication mode Constraints: None Options:
Default value: |
authenticatingProxy |
No |
AuthenticatingProxy object |
Details: Configuration related to the authenticating_proxy mode Constraints: This field is mandatory when the authentication mode is authenticating_proxy. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
ca |
No |
String |
Details: X509 CA certificate (Base64-encoded) configured in authenticating_proxy mode Constraints: This field is mandatory when the cluster authentication mode is authenticating_proxy. Options: Maximum size: 1 MB Default value: N/A |
cert |
No |
String |
Details: 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.) Constraints: This field is mandatory when the cluster authentication mode is authenticating_proxy. Options: Maximum size: 1 MB Default value: N/A |
privateKey |
No |
String |
Details: 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.) Constraints: This field is mandatory when the cluster authentication mode is authenticating_proxy. Options: Maximum size: 1 MB Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
availabilityZone |
No |
String |
Details: AZ where a control plane node is located. The AZ name must be specified. Constraints: None Options: N/A Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
clusterAZ |
No |
String |
Details: AZs of master nodes in a cluster Constraints: None Options:
Default value: If no AZ is specified, an AZ is randomly allocated by default. |
dssMasterVolumes |
No |
String |
Details: Whether the system and data disks of a master node use DSS storage pools. If this parameter is unspecified or left blank, EVS disks are used by default. Constraints: This parameter is mandatory for dedicated CCE clusters. It is in the following format: <rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType> Specifically:
Options: N/A Default value: N/A 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 |
Details: ID of the enterprise project that a cluster belongs to Constraints: An enterprise project can be configured only after the enterprise project function is enabled. Options: N/A Default value: N/A |
kubeProxyMode |
No |
String |
Details: Service forwarding mode Constraints: This parameter has been deprecated. If both this parameter and kubeProxyMode in ClusterSpec are specified, the latter is used. Options:
Default value: iptables |
clusterExternalIP |
No |
String |
Details: EIP of a cluster control plane node. After an EIP is bound to the control plane node, you can access the cluster management plane APIs through the EIP. Constraints: None Options: N/A Default value: N/A |
alpha.cce/fixPoolMask |
No |
String |
Details: Number of mask bits of the fixed IP address pool of the container networks. This parameter determines the maximum number of IP addresses that can be assigned to containers on a node. This, along with the maxPods setting during node creation, determines the maximum number of pods that can be created on a node. For details, see Maximum Number of Pods That Can Be Created on a Node. Constraints: Only the vpc-router networks support this function. Options: Integers from 24 to 28 Default value: 24 |
decMasterFlavor |
No |
String |
Details: Master node flavor in a dedicated CCE cluster Constraints: None Options: N/A Default value: N/A |
dockerUmaskMode |
No |
String |
Details: Default UmaskMode configuration of Docker in a cluster Constraints: None Options: Default value: normal |
kubernetes.io/cpuManagerPolicy |
No |
String |
Details: Cluster CPU management policy Constraints: None Options:
Default value: none |
upgradefrom |
No |
String |
Details: Records of how a cluster is upgraded to its current version Constraints: This field is only returned by a query API. Options: N/A Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
name |
No |
String |
Details: Component name Constraints: None Options: N/A Default value: N/A |
configurations |
No |
Array of ConfigurationItem objects |
Details: Component configuration items Constraints: None |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
name |
No |
String |
Details: Configuration overrides of the default components in a cluster. Constraints: If you specify a component or parameter that is not supported, this configuration item will be ignored. Options: N/A Default value: N/A |
value |
No |
AnyType |
Details: Configuration overrides of the default components in a cluster. Constraints: If you specify a component or parameter that is not supported, this configuration item will be ignored. Options: N/A Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
alarm |
Yes |
AlarmInfo object |
Details: Alarm assistant settings. CCE is integrated with AOM, which enables alarm functionality, allowing for easy search and configuration of alarms. The Cloud Native Cluster Monitoring add-on sends metric rule data in CCE alarm center to AOM instances. Constraints: None |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
topics |
Yes |
Array of strings |
Details: Contact group list. You can enter SMN topic names and configure contact groups to manage endpoints that have subscribed to alarm messages. Constraints: None |
alarmRuleTemplateId |
No |
String |
Details: Alarm rule template ID transferred when the alarm assistant is enabled. By default, the alarm rule template in the container scenario is used. Constraints: None Options: N/A Default value: N/A |
promInstanceID |
No |
String |
Details: ID of the AOM Prometheus instance transferred when the alarm assistant is enabled. If the Prometheus add-on is not installed or the AOM instance is not connected, there is no need to specify this parameter. In this case, the alarm center will not generate metric alarm rules. Constraints: None Options: N/A Default value: N/A |
promEnterpriseProjectID |
No |
String |
Details: Enterprise project ID of the AOM Prometheus instance transferred when the alarm assistant is enabled. If the Prometheus add-on is not installed or the AOM instance is not connected, there is no need to specify this parameter. In this case, the alarm center will not generate metric alarm rules. Constraints: None Options: N/A Default value: N/A |
Response Parameters
Status code: 201
Parameter |
Type |
Description |
---|---|---|
kind |
String |
Details: API type Constraints: The value cannot be changed. Options: Default value: N/A |
apiVersion |
String |
Details: API version Constraints: The value cannot be changed. Options: Default value: N/A |
metadata |
ClusterMetadata object |
Details: Basic information about a cluster. Metadata is a collection of attributes. Constraints: None |
spec |
ClusterSpec object |
Details: Detailed description about a cluster. CCE creates or updates objects by defining or updating spec. Constraints: None |
status |
ClusterStatus object |
Details: Cluster status and ID of a cluster creation job Constraints: None |
Parameter |
Type |
Description |
---|---|---|
name |
String |
Details: Cluster name Constraints: None Options: Enter 4 to 128 characters starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed. Default value: N/A |
uid |
String |
Details: Cluster ID, which identifies a cluster Constraints: The value is automatically generated after the object is created. A user-defined value will not take effect. Options: N/A Default value: N/A |
alias |
String |
Details: Alias of a cluster name displayed on the CCE console. The name can be changed. A cluster alias must be unique. Constraints: 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 creating a cluster or other response bodies, if the cluster alias is not configured, no value will be returned. Options: Enter 4 to 128 characters starting with a letter and not starting or ending with a hyphen (-). Only digits, letters, and hyphens (-) are allowed. Default value: N/A |
annotations |
Map<String,String> |
Details: Cluster annotations in the format of key-value pairs "annotations": { "key1" : "value1", "key2" : "value2" } Constraints: This field is not stored in the database and is only used to specify the add-ons to be installed in the cluster. Options: N/A Default value: N/A
NOTE:
|
labels |
Map<String,String> |
Details: Cluster labels, in the format of key-value pairs Constraints: 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. Custom values are invalid. Options: N/A Default value: N/A |
creationTimestamp |
String |
Details: Time when a cluster was created Constraints: The value is automatically recorded during cluster creation and cannot be specified. Options: N/A Default value: N/A |
updateTimestamp |
String |
Details: Time when a cluster was updated Constraints: The value is automatically recorded during cluster updates and cannot be specified. Options: N/A Default value: N/A |
timezone |
String |
Details: Time zone of a cluster. The time zone must be included in IANA Time Zone Database. Constraints: None Options: N/A Default value: N/A |
Parameter |
Type |
Description |
---|---|---|
category |
String |
Details: Cluster type Constraints: None Options: CCE clusters support hybrid deployment of VMs and BMSs, and heterogeneous nodes such as GPU and NPU nodes, allowing you to run your containers in a secure, stable container runtime environment based on a high-performance network model. Default value: CCE when the container network is not set to eni |
type |
String |
Details: Master node architecture Constraints: None Options: Default value: VirtualMachine |
flavor |
String |
Details: Cluster specifications. Specifications of clusters of v1.15 or later can be changed after they are created. For details, see Modifying Cluster Specifications. Configure this parameter based on actual service requirements. Constraints: None Options:
Default value: N/A
NOTE:
The fields in the parameters are described as follows:
|
version |
String |
Details: Cluster version, which mirrors the baseline version of the Kubernetes community. The latest commercial version is recommended. You can create clusters of the latest three versions on the CCE console. To learn which cluster versions are available, log in to the CCE console, create a cluster, and check the supported cluster versions. 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. Constraints: The value must be in the format of vX.Y[.Z[-rN]], for example, v1.30, v1.30.0, or v1.30.0-r0. Specifying either of these values will create a cluster of version 1.30. Options: N/A Default value: |
platformVersion |
String |
Details: CCE cluster platform version, which is an 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. Constraints: This parameter cannot be customized, and when you create a cluster, the latest corresponding platform version is selected automatically. Options: The format of platformVersion is cce.X.Y.
Default value: N/A |
legacyVersion |
String |
Details: (Deprecated) Outdated version of CCE clusters, which serves no practical purpose and is only used to showcase the cluster version and platform version combination. The version number is globally unique. For example, if the cluster version is va.b and the platformVersion is cce.X.Y, the value of legacyVersion is va.b.X-rY. Constraints: None Options: N/A Default value: N/A |
description |
String |
Details: Cluster description, for example, which purpose the cluster is intended to serve. By default, this parameter is left unspecified. To modify cluster description after a cluster is created, call the API for updating a specified cluster or go to the cluster details page on the CCE console. Constraints: Only UTF-8 encoding is supported. The length must be less than or equal to 200 bytes. Options: N/A Default value: N/A |
customSan |
Array of strings |
Details: Custom Subject Alternative Name (SAN) in the server certificate of a cluster API server, which must comply with the SSL and X509 standard formats Constraints: Duplicate names are not allowed. Options: Values in the IP address or domain name format Default value: N/A 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 |
Details: Whether a cluster supports IPv6 addresses. It is supported by clusters v1.15 and later. Constraints: After IPv6 is enabled, iptables is not supported. The VPC network model does not support IPv4/IPv6 dual-stack. Options: Default value: false |
hostNetwork |
HostNetwork object |
Details: Node network parameters, including VPC and subnet ID. This field is mandatory because nodes in a cluster communicate with each other using a VPC. Constraints: None |
containerNetwork |
ContainerNetwork object |
Details: Container network parameters, including the container network model and container CIDR block Constraints: None |
serviceNetwork |
ServiceNetwork object |
Details: Service CIDR block, including IPv4 CIDR block Constraints: None |
publicAccess |
PublicAccess object |
Details: Cluster API access control Constraints: None |
authentication |
Authentication object |
Details: Configurations of the cluster authentication mode Constraints: None |
billingMode |
Integer |
Details: Cluster billing mode Constraints: None Options: Default value: 0 |
masters |
Array of MasterSpec objects |
Details: Advanced settings of the control plane nodes in a cluster. You can specify AZs for them. Constraints: If this parameter is not specified, no value is returned. |
kubernetesSvcIpRange |
String |
Details: Service CIDR blocks which kubernetes clusterIP must fall within. This parameter is available only for clusters v1.11.7 and later. If this parameter is not specified during cluster creation, the default value 10.247.0.0/16 is used. This parameter is being deprecated, so you can use serviceNetwork instead. The new field contains the IPv4 CIDR blocks. Constraints: None Options: N/A Default value: N/A |
clusterTags |
Array of ResourceTag objects |
Details: Cluster resource tags Constraints: None |
kubeProxyMode |
String |
Details: Service forwarding mode Constraints: None Options:
Default value: iptables is used by default. |
az |
String |
Details: AZ (being deprecated). Constraints: This field is only returned by a query API. |
extendParam |
ClusterExtendParam object |
Details: Extended field to decide whether a cluster will span across AZs or belong to a specified enterprise project, or whether a dedicated CCE cluster is to be created Constraints: None |
supportIstio |
Boolean |
Details: Whether Istio is supported Constraints: None Options: Default value: true |
deletionProtection |
Boolean |
Details: Cluster deletion protection, which prevents the deletion of a cluster when this function is enabled Constraints: None Options: Default value: false |
configurationsOverride |
Array of PackageConfiguration objects |
Details: Overrides the default component configurations in a cluster. Constraints: If you specify a component or parameter that is not supported, the configuration item will be ignored. |
clusterOps |
ClusterOps object |
Details: Cluster O&M settings Constraints: None |
encryptionConfig |
EncryptionConfig object |
Details: Configuration of secret encryption. Only one encryption mode can be configured. By default, the CCE-managed key is used for encryption. (Users are not aware of the key being used.) Constraints: None Options: N/A Default value: N/A |
Parameter |
Type |
Description |
---|---|---|
mode |
String |
Details: Container network type Constraints: Only one container network type can be selected. Options:
Default value: N/A |
cidr |
String |
Details: Container CIDR block. 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19 is recommended. If the selected CIDR block conflicts with existing ones, an error will be reported. Constraints: This parameter cannot be modified after the cluster is created. (It has been deprecated. If cidrs has been configured, the specified CIDR blocks will be ignored.) Once you have created a cluster that uses a VPC network, you can add new CIDR blocks, but you are unable to modify the existing ones. If you need to adjust the CIDR blocks, you will have to create a cluster. Options: Values in IPv4 CIDR format Default value: If this parameter is left blank, a unique CIDR block is randomly allocated from 172.(16–31).0.0/16 and 10.(0 | 16 | 32 | 48 | 64 | 80 | 96 | 112).0.0/12. |
cidrs |
Array of ContainerCIDR objects |
Details: List of container CIDR blocks. In clusters 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 clusters earlier than v1.21, if the cidrs field is used, the first CIDR element in the array is used as the container CIDR block. Constraints: Once you have created a cluster that uses a container tunnel network, you cannot modify the CIDR blocks. Once you have created a cluster that uses a VPC network, you can add new CIDR blocks, but you are unable to modify the existing ones. If you need to adjust the CIDR blocks, you will have to create a cluster. |
Parameter |
Type |
Description |
---|---|---|
cidr |
String |
Details: Container CIDR block. 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19 is recommended. Constraints: If a CIDR block conflict occurs, an error will be reported. Options: N/A Default value: N/A |
Parameter |
Type |
Description |
---|---|---|
eniSubnetId |
String |
Details: IPv4 subnet ID of the subnet where an elastic network interface resides Constraints: IPv6 is not supported. This field will be deprecated. Use subnets instead. Options: N/A Default value: N/A To obtain the value: |
eniSubnetCIDR |
String |
Details: ENI subnet CIDR block Constraints: This parameter is being deprecated. The new field subnets is recommended. Options: N/A Default value: N/A |
subnets |
Array of NetworkSubnet objects |
Details: List of IPv4 subnet IDs Constraints: None |
Parameter |
Type |
Description |
---|---|---|
subnetID |
String |
Details: ID of the IPv4 subnet where the container network interfaces are in Constraints: IPv6 is not supported. Options: N/A Default value: N/A To obtain the value: |
Parameter |
Type |
Description |
---|---|---|
IPv4CIDR |
String |
Details: Value range of the Kubernetes clusterIP IPv4 CIDR block Constraints: None Options: N/A Default value: 10.247.0.0/16 |
IPv6CIDR |
String |
Details: Value range of the Kubernetes clusterIP IPv6 CIDR block Constraints: IPv6 Service CIDR blocks can be configured only for CCE Turbo clusters with IPv6 dual stack enabled. Options: N/A Default value: Default value for a CCE Turbo cluster: fc00::/112 Default value for a CCE standard cluster: fd00:1234::/120 |
Parameter |
Type |
Description |
---|---|---|
cidrs |
Array of strings |
Details: Trustlist of network CIDRs that are allowed to access cluster APIs. You are advised to allow the traffic from VPC and container network CIDRs. Constraints: This parameter is valid only when a cluster is created. Options: N/A Default value: By default, no trustlist is configured, and the value is 0.0.0.0/0. |
Parameter |
Type |
Description |
---|---|---|
mode |
String |
Details: Cluster authentication mode Constraints: None Options:
Default value: |
authenticatingProxy |
AuthenticatingProxy object |
Details: Configuration related to the authenticating_proxy mode Constraints: This field is mandatory when the authentication mode is authenticating_proxy. |
Parameter |
Type |
Description |
---|---|---|
ca |
String |
Details: X509 CA certificate (Base64-encoded) configured in authenticating_proxy mode Constraints: This field is mandatory when the cluster authentication mode is authenticating_proxy. Options: Maximum size: 1 MB Default value: N/A |
cert |
String |
Details: 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.) Constraints: This field is mandatory when the cluster authentication mode is authenticating_proxy. Options: Maximum size: 1 MB Default value: N/A |
privateKey |
String |
Details: 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.) Constraints: This field is mandatory when the cluster authentication mode is authenticating_proxy. Options: Maximum size: 1 MB Default value: N/A |
Parameter |
Type |
Description |
---|---|---|
availabilityZone |
String |
Details: AZ where a control plane node is located. The AZ name must be specified. Constraints: None Options: N/A Default value: N/A |
Parameter |
Type |
Description |
---|---|---|
clusterAZ |
String |
Details: AZs of master nodes in a cluster Constraints: None Options:
Default value: If no AZ is specified, an AZ is randomly allocated by default. |
dssMasterVolumes |
String |
Details: Whether the system and data disks of a master node use DSS storage pools. If this parameter is unspecified or left blank, EVS disks are used by default. Constraints: This parameter is mandatory for dedicated CCE clusters. It is in the following format: <rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType> Specifically:
Options: N/A Default value: N/A 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 |
Details: ID of the enterprise project that a cluster belongs to Constraints: An enterprise project can be configured only after the enterprise project function is enabled. Options: N/A Default value: N/A |
kubeProxyMode |
String |
Details: Service forwarding mode Constraints: This parameter has been deprecated. If both this parameter and kubeProxyMode in ClusterSpec are specified, the latter is used. Options:
Default value: iptables |
clusterExternalIP |
String |
Details: EIP of a cluster control plane node. After an EIP is bound to the control plane node, you can access the cluster management plane APIs through the EIP. Constraints: None Options: N/A Default value: N/A |
alpha.cce/fixPoolMask |
String |
Details: Number of mask bits of the fixed IP address pool of the container networks. This parameter determines the maximum number of IP addresses that can be assigned to containers on a node. This, along with the maxPods setting during node creation, determines the maximum number of pods that can be created on a node. For details, see Maximum Number of Pods That Can Be Created on a Node. Constraints: Only the vpc-router networks support this function. Options: Integers from 24 to 28 Default value: 24 |
decMasterFlavor |
String |
Details: Master node flavor in a dedicated CCE cluster Constraints: None Options: N/A Default value: N/A |
dockerUmaskMode |
String |
Details: Default UmaskMode configuration of Docker in a cluster Constraints: None Options: Default value: normal |
kubernetes.io/cpuManagerPolicy |
String |
Details: Cluster CPU management policy Constraints: None Options:
Default value: none |
upgradefrom |
String |
Details: Records of how a cluster is upgraded to its current version Constraints: This field is only returned by a query API. Options: N/A Default value: N/A |
Parameter |
Type |
Description |
---|---|---|
name |
String |
Details: Component name Constraints: None Options: N/A Default value: N/A |
configurations |
Array of ConfigurationItem objects |
Details: Component configuration items Constraints: None |
Parameter |
Type |
Description |
---|---|---|
name |
String |
Details: Configuration overrides of the default components in a cluster. Constraints: If you specify a component or parameter that is not supported, this configuration item will be ignored. Options: N/A Default value: N/A |
value |
AnyType |
Details: Configuration overrides of the default components in a cluster. Constraints: If you specify a component or parameter that is not supported, this configuration item will be ignored. Options: N/A Default value: N/A |
Parameter |
Type |
Description |
---|---|---|
alarm |
AlarmInfo object |
Details: Alarm assistant settings. CCE is integrated with AOM, which enables alarm functionality, allowing for easy search and configuration of alarms. The Cloud Native Cluster Monitoring add-on sends metric rule data in CCE alarm center to AOM instances. Constraints: None |
Parameter |
Type |
Description |
---|---|---|
topics |
Array of strings |
Details: Contact group list. You can enter SMN topic names and configure contact groups to manage endpoints that have subscribed to alarm messages. Constraints: None |
alarmRuleTemplateId |
String |
Details: Alarm rule template ID transferred when the alarm assistant is enabled. By default, the alarm rule template in the container scenario is used. Constraints: None Options: N/A Default value: N/A |
promInstanceID |
String |
Details: ID of the AOM Prometheus instance transferred when the alarm assistant is enabled. If the Prometheus add-on is not installed or the AOM instance is not connected, there is no need to specify this parameter. In this case, the alarm center will not generate metric alarm rules. Constraints: None Options: N/A Default value: N/A |
promEnterpriseProjectID |
String |
Details: Enterprise project ID of the AOM Prometheus instance transferred when the alarm assistant is enabled. If the Prometheus add-on is not installed or the AOM instance is not connected, there is no need to specify this parameter. In this case, the alarm center will not generate metric alarm rules. Constraints: None Options: N/A Default value: N/A |
Parameter |
Type |
Description |
---|---|---|
phase |
String |
Details: Cluster status Constraints: None Options: |
jobID |
String |
Details: ID of the job associated with the current cluster status. It supports:
Constraints: None Options: N/A
NOTE:
Job information is short-lived and is only used for tracking the progress of short-term jobs. Do not use it for cluster status query or other scenarios. |
reason |
String |
Details: Why a cluster changes to the current state. This parameter is returned if the cluster is not in the Available state. Constraints: None Options: N/A |
message |
String |
Details: Detailed information about why a cluster changes to the current state. This parameter is returned if the cluster is not in the Available state. Constraints: None Options: N/A |
endpoints |
Array of ClusterEndpoints objects |
Details: Access address of kube-apiserver in a cluster Constraints: None |
deleteOption |
Object |
Details: Status of the configuration to be deleted. This parameter is contained only in the response to the deletion request. Constraints: None Options: N/A |
deleteStatus |
Object |
Details: Information of the status to be deleted. This parameter is contained only in the response to the deletion request. Constraints: None Options: N/A |
Example Requests
-
Create an HA CCE cluster of v1.29 that has 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.29", "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.29 that has 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.29", "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.29 that has three master nodes and a maximum of 50 worker nodes and configure the custom default security group for 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.29", "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 } }
-
Configure the trustlist network CIDR for accessing the cluster API when creating a 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" }, "publicAccess" : { "cidrs" : [ "192.168.0.0/16" ] }, "containerNetwork" : { "mode" : "vpc-router", "cidr" : "10.0.0.0/16" }, "serviceNetwork" : { "IPv4CIDR" : "10.247.0.0/16", "IPv6CIDR" : "fc00::/112" }, "kubernetesSvcIpRange" : "10.247.0.0/16", "description" : "", "billingMode" : 0, "extendParam" : { "kubeProxyMode" : "iptables", "alpha.cce/fixPoolMask" : "25", "enterpriseProjectId" : "0" }, "authentication" : { "mode" : "rbac" }, "ipv6enable" : false } }
Example Responses
Status code: 201
The cluster creation job is successfully delivered.
{ "kind" : "Cluster", "apiVersion" : "v3", "metadata" : { "name" : "cluster", "uid" : "1df09f9a-5b9e-11ef-8f52-0255ac10003e", "creationTimestamp" : "2024-08-16 07:06:53.704389459 +0000 UTC", "updateTimestamp" : "2024-08-16 07:06:53.704389529 +0000 UTC", "annotations" : { "jobid" : "1e50bfbe-5b9e-11ef-8f52-0255ac10003e", "resourceJobId" : "1df0ec6b-5b9e-11ef-8f52-0255ac10003e" }, "timezone" : }, "spec" : { "publicAccess" : { }, "category" : "CCE", "type" : "VirtualMachine", "enableAutopilot" : false, "flavor" : "cce.s1.small", "version" : "v1.29", "platformVersion" : "cce.4.0", "configurationsOverride" : [ { "name" : "kube-apiserver", "configurations" : [ { "name" : "support-overload", "value" : true } ] } ], "hostNetwork" : { "vpc" : "0538a5d0-9a65-4c1d-a8bf-e9acee237980", "subnet" : "bc81be88-6e34-4b02-83bd-df0a1f7672c5" }, "containerNetwork" : { "mode" : "vpc-router", "cidr" : "172.17.0.0/16", "cidrs" : [ { "cidr" : "172.17.0.0/16" } ] }, "eniNetwork" : { }, "serviceNetwork" : { "IPv4CIDR" : "10.247.0.0/16" }, "authentication" : { "mode" : "rbac", "authenticatingProxy" : { } }, "billingMode" : 0, "kubernetesSvcIpRange" : "10.247.0.0/16", "kubeProxyMode" : "iptables", "extendParam" : { "alpha.cce/fixPoolMask" : "25", "enterpriseProjectId" : "0", "orderID" : "" } }, "status" : { "phase" : "Creating", "jobID" : "1e50bfbe-5b9e-11ef-8f52-0255ac10003e" } }
Status Codes
Status Code |
Description |
---|---|
201 |
The cluster creation job is successfully delivered. |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot