Updated on 2025-07-07 GMT+08:00

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

Table 1 Path Parameters

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

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

Content-Type

Yes

String

Details:

The request body type or format

Constraints:

The GET method is not verified.

Options:

  • application/json

  • application/json;charset=utf-8

  • application/x-pem-file

  • multipart/form-data (used when the FormData parameter is present)

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

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

kind

Yes

String

Details:

API type

Constraints:

The value cannot be changed.

Options:

  • Cluster

  • cluster

Default value:

N/A

apiVersion

Yes

String

Details:

API version

Constraints:

The value cannot be changed.

Options:

  • v3

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

Table 4 ClusterMetadata

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:
  • Annotations are not used to identify 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.

  • You can install ICAgent during cluster creation by adding the key-value pair "cluster.install.addons.external/install": "[{\"addonTemplateName\":\"icagent\"}]".

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

Table 5 CreateClusterRequestSpec

Parameter

Mandatory

Type

Description

category

No

String

Details:

Cluster type

Constraints:

None

Options:

  • CCE: CCE cluster.

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:

  • VirtualMachine: The master node is an x86 server.

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:

  • cce.s1.small: a small-scale CCE cluster with one control plane node and a maximum of 50 worker nodes

  • cce.s1.medium: a medium-scale CCE cluster with one control plane node and a maximum of 200 worker nodes

  • cce.s1.large: a large-scale CCE cluster with one control plane node and a maximum of 1,000 worker nodes

  • cce.s2.small: a small-scale CCE cluster with three control plane nodes and a maximum of 50 worker nodes

  • cce.s2.medium: a medium-scale CCE cluster with three control plane nodes and a maximum of 200 worker nodes

  • cce.s2.large: a large-scale CCE cluster with three control plane nodes and a maximum of 1,000 worker nodes

  • cce.s2.xlarge: an ultra-large-scale CCE cluster with three control plane nodes and a maximum of 2,000 worker nodes

Default value:

N/A

NOTE:

The fields in the parameters are described as follows:

  • s1: specifies a cluster with one control plane node. If the control plane node is faulty, the cluster will become unavailable, but running workloads in the cluster are not affected.

  • s2: specifies an HA cluster with three control plane nodes. If one of the control plane 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

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.

  • X: major version in the Kubernetes community

  • Y: minor version in the Kubernetes community

  • Z: patch version in the Kubernetes community

Options:

N/A

Default value:

  • If this parameter is left empty, a cluster of the latest version is created by default.

  • 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

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.

  • X: internal feature version, which indicates 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 released. No other modification is involved. The value starts from 0 and increases monotonically.

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:

  • true: IPv4/IPv6 dual-stack is enabled.

  • false: Only IPv4 is used.

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:

  • 0: pay-per-use

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:

  • iptables: traditional kube-proxy mode, which uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. Additionally, non-incremental updates will cause latency and obvious performance issues in the case of heavy service traffic.

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

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:

  • true: Cluster deletion protection is enabled.

  • false: Cluster deletion protection is disabled.

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

Table 6 HostNetwork

Parameter

Mandatory

Type

Description

vpc

Yes

String

Details:

ID of the VPC where nodes will be running

Constraints:

None

Options:

N/A

Default value:

N/A

To obtain the value:

  • Method 1: Log in to the VPC console and view the VPC ID in the VPC details page.

  • Method 2: Use the VPC APIs.

subnet

Yes

String

Details:

Network ID of the subnet where nodes will be running

Constraints:

None

Options:

N/A

Default value:

N/A

To obtain the value:

  • Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page.

  • Method 2: Use the VPC APIs.

SecurityGroup

No

String

Details:

ID of the default node security group in a cluster

Constraints:

None

Options:

N/A

Default value:

  • If this parameter is not specified, the system automatically creates a default node security group.

  • If this parameter is specified, the cluster will be bound to the specified security group.

NOTE:

To ensure proper communication, allow traffic from certain ports to the specified node security group.

controlPlaneSecurityGroup

No

String

Details:

ID of the master node security group in 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

Table 7 ContainerNetwork

Parameter

Mandatory

Type

Description

mode

Yes

String

Details:

Container network type

Constraints:

Only one container network type can be selected.

Options:

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

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.

Table 8 ContainerCIDR

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

Table 9 EniNetwork

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:

  • 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 APIs.

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

Table 10 NetworkSubnet

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:

  • 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 APIs.

Table 11 ServiceNetwork

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

Table 12 PublicAccess

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.

Table 13 Authentication

Parameter

Mandatory

Type

Description

mode

No

String

Details:

Cluster authentication mode

Constraints:

None

Options:

  • Clusters of Kubernetes 1.11 or earlier support x509, rbac, and authenticating_proxy. The parameter defaults to x509.

  • Clusters of Kubernetes 1.13 or later support rbac and authenticating_proxy. The parameter defaults to rbac.

  • Clusters of Kubernetes 1.11 or earlier support x509, rbac, and authenticating_proxy. The parameter defaults to rbac.

Default value:

  • Clusters of Kubernetes 1.11 or earlier: x509

  • Clusters of Kubernetes 1.13 or later: rbac

authenticatingProxy

No

AuthenticatingProxy object

Details:

Configuration related to the authenticating_proxy mode

Constraints:

This field is mandatory when the authentication mode is authenticating_proxy.

Table 14 AuthenticatingProxy

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

Table 15 MasterSpec

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

Table 16 ResourceTag

Parameter

Mandatory

Type

Description

key

No

String

Details:

Key

Constraints:

None

Options:

  • The value cannot be empty and cannot start or end with spaces. A maximum of 128 characters is supported.

  • The value can contain letters, digits, and spaces in UTF-8 format.

  • The value can contain the following special characters: _.:=+-@

  • The value cannot start with _sys_.

Default value:

N/A

value

No

String

Details:

Value

Constraints:

None

Options:

  • The value can be null but not the default. Max characters: 255

  • Letters, digits, and spaces in UTF-8 format are supported.

  • The value can contain the following special characters: _.:/=+-@

Default value:

N/A

Table 17 ClusterExtendParam

Parameter

Mandatory

Type

Description

clusterAZ

No

String

Details:

AZs of master nodes in a cluster

Constraints:

None

Options:

  • AZs supported by a specified region

  • multi_az: (Optional) multiple AZs, which can be configured only when a cluster with multiple master nodes is used

  • AZs of the dedicated cloud computing pool: Master nodes will be deployed in the DeC AZs. It is mandatory for dedicated CCE clusters.

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:

  • rootVol specifies the system disk. dataVol specifies a data disk.

  • dssPoolID specifies the ID of a DSS storage pool.

  • volType specifies the storage volume type of the DSS storage pool, such as SAS, SSD, SATA, ESSD, GPSSD, ESSD2, and GPSSD2.

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:

  • iptables: traditional kube-proxy mode, which uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. Additionally, non-incremental updates will cause latency and obvious performance issues in the case of heavy service traffic.

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

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:

  • secure

  • normal

Default value:

normal

kubernetes.io/cpuManagerPolicy

No

String

Details:

Cluster CPU management policy

Constraints:

None

Options:

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

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

Table 18 PackageConfiguration

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

Table 19 ConfigurationItem

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

Table 20 ClusterOps

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

Table 21 AlarmInfo

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

Table 22 EncryptionConfig

Parameter

Mandatory

Type

Description

mode

No

String

Details:

Encryption mode. Either encryption using the CCE-managed key or KMS key can be configured.

Constraints:

None

Options:

  • Default: Encryption is performed using the CCE-managed key.

  • KMS: KMS encryption is used.

Default value:

Default

kmsKeyID

No

String

Details:

KMS key ID

  • In the API for creating a cluster, if the mode field is set to Default, there is no need to specify this field. If the mode field is set to KMS, you can specify a value for this field. If this parameter is left blank, the default KMS key is used by default. If the default key does not exist, DEW will automatically create a default key (cce/default) for the user. To ensure proper cluster functionality, it is important to use a valid KMS key. Refrain from deleting or disabling the key before the cluster lifecycle is complete, as this may cause exceptions. Once a key has been configured for a cluster, it cannot be modified.

  • In the cluster query API, if the mode field is set to Default, the returned value of this field is empty. If the mode field is set to KMS, the specific key ID will be returned.

Constraints:

None

Options:

N/A

Default value:

N/A

Response Parameters

Status code: 201

Table 23 Response body parameters

Parameter

Type

Description

kind

String

Details:

API type

Constraints:

The value cannot be changed.

Options:

  • Cluster

  • cluster

Default value:

N/A

apiVersion

String

Details:

API version

Constraints:

The value cannot be changed.

Options:

  • v3

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

Table 24 ClusterMetadata

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:
  • Annotations are not used to identify 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.

  • You can install ICAgent during cluster creation by adding the key-value pair "cluster.install.addons.external/install": "[{\"addonTemplateName\":\"icagent\"}]".

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

Table 25 ClusterSpec

Parameter

Type

Description

category

String

Details:

Cluster type

Constraints:

None

Options:

  • CCE: CCE cluster.

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:

  • VirtualMachine: The master node is an x86 server.

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:

  • cce.s1.small: a small-scale CCE cluster with one control plane node and a maximum of 50 worker nodes

  • cce.s1.medium: a medium-scale CCE cluster with one control plane node and a maximum of 200 worker nodes

  • cce.s1.large: a large-scale CCE cluster with one control plane node and a maximum of 1,000 worker nodes

  • cce.s2.small: a small-scale CCE cluster with three control plane nodes and a maximum of 50 worker nodes

  • cce.s2.medium: a medium-scale CCE cluster with three control plane nodes and a maximum of 200 worker nodes

  • cce.s2.large: a large-scale CCE cluster with three control plane nodes and a maximum of 1,000 worker nodes

  • cce.s2.xlarge: an ultra-large-scale CCE cluster with three control plane nodes and a maximum of 2,000 worker nodes

Default value:

N/A

NOTE:

The fields in the parameters are described as follows:

  • s1: specifies a cluster with one control plane node. If the control plane node is faulty, the cluster will become unavailable, but running workloads in the cluster are not affected.

  • s2: specifies an HA cluster with three control plane nodes. If one of the control plane 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

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.

  • X: major version in the Kubernetes community

  • Y: minor version in the Kubernetes community

  • Z: patch version in the Kubernetes community

Options:

N/A

Default value:

  • If this parameter is left empty, a cluster of the latest version is created by default.

  • 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

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.

  • X: internal feature version, which indicates 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 released. No other modification is involved. The value starts from 0 and increases monotonically.

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:

  • true: IPv4/IPv6 dual-stack is enabled.

  • false: Only IPv4 is used.

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:

  • 0: pay-per-use

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:

  • iptables: traditional kube-proxy mode, which uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. Additionally, non-incremental updates will cause latency and obvious performance issues in the case of heavy service traffic.

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

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:

  • true: Istio is supported.

  • false: Istio is not supported.

Default value:

true

deletionProtection

Boolean

Details:

Cluster deletion protection, which prevents the deletion of a cluster when this function is enabled

Constraints:

None

Options:

  • true: Cluster deletion protection is enabled.

  • false: Cluster deletion protection is disabled.

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

Table 26 HostNetwork

Parameter

Type

Description

vpc

String

Details:

ID of the VPC where nodes will be running

Constraints:

None

Options:

N/A

Default value:

N/A

To obtain the value:

  • Method 1: Log in to the VPC console and view the VPC ID in the VPC details page.

  • Method 2: Use the VPC APIs.

subnet

String

Details:

Network ID of the subnet where nodes will be running

Constraints:

None

Options:

N/A

Default value:

N/A

To obtain the value:

  • Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page.

  • Method 2: Use the VPC APIs.

SecurityGroup

String

Details:

ID of the default node security group in a cluster

Constraints:

None

Options:

N/A

Default value:

  • If this parameter is not specified, the system automatically creates a default node security group.

  • If this parameter is specified, the cluster will be bound to the specified security group.

NOTE:

To ensure proper communication, allow traffic from certain ports to the specified node security group.

controlPlaneSecurityGroup

String

Details:

ID of the master node security group in 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

Table 27 ContainerNetwork

Parameter

Type

Description

mode

String

Details:

Container network type

Constraints:

Only one container network type can be selected.

Options:

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

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.

Table 28 ContainerCIDR

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

Table 29 EniNetwork

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:

  • 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 APIs.

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

Table 30 NetworkSubnet

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:

  • 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 APIs.

Table 31 ServiceNetwork

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

Table 32 PublicAccess

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.

Table 33 Authentication

Parameter

Type

Description

mode

String

Details:

Cluster authentication mode

Constraints:

None

Options:

  • Clusters of Kubernetes 1.11 or earlier support x509, rbac, and authenticating_proxy. The parameter defaults to x509.

  • Clusters of Kubernetes 1.13 or later support rbac and authenticating_proxy. The parameter defaults to rbac.

  • Clusters of Kubernetes 1.11 or earlier support x509, rbac, and authenticating_proxy. The parameter defaults to rbac.

Default value:

  • Clusters of Kubernetes 1.11 or earlier: x509

  • Clusters of Kubernetes 1.13 or later: rbac

authenticatingProxy

AuthenticatingProxy object

Details:

Configuration related to the authenticating_proxy mode

Constraints:

This field is mandatory when the authentication mode is authenticating_proxy.

Table 34 AuthenticatingProxy

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

Table 35 MasterSpec

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

Table 36 ResourceTag

Parameter

Type

Description

key

String

Details:

Key

Constraints:

None

Options:

  • The value cannot be empty and cannot start or end with spaces. A maximum of 128 characters is supported.

  • The value can contain letters, digits, and spaces in UTF-8 format.

  • The value can contain the following special characters: _.:=+-@

  • The value cannot start with _sys_.

Default value:

N/A

value

String

Details:

Value

Constraints:

None

Options:

  • The value can be null but not the default. Max characters: 255

  • Letters, digits, and spaces in UTF-8 format are supported.

  • The value can contain the following special characters: _.:/=+-@

Default value:

N/A

Table 37 ClusterExtendParam

Parameter

Type

Description

clusterAZ

String

Details:

AZs of master nodes in a cluster

Constraints:

None

Options:

  • AZs supported by a specified region

  • multi_az: (Optional) multiple AZs, which can be configured only when a cluster with multiple master nodes is used

  • AZs of the dedicated cloud computing pool: Master nodes will be deployed in the DeC AZs. It is mandatory for dedicated CCE clusters.

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:

  • rootVol specifies the system disk. dataVol specifies a data disk.

  • dssPoolID specifies the ID of a DSS storage pool.

  • volType specifies the storage volume type of the DSS storage pool, such as SAS, SSD, SATA, ESSD, GPSSD, ESSD2, and GPSSD2.

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:

  • iptables: traditional kube-proxy mode, which uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. Additionally, non-incremental updates will cause latency and obvious performance issues in the case of heavy service traffic.

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

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:

  • secure

  • normal

Default value:

normal

kubernetes.io/cpuManagerPolicy

String

Details:

Cluster CPU management policy

Constraints:

None

Options:

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

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

Table 38 PackageConfiguration

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

Table 39 ConfigurationItem

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

Table 40 ClusterOps

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

Table 41 AlarmInfo

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

Table 42 EncryptionConfig

Parameter

Type

Description

mode

String

Details:

Encryption mode. Either encryption using the CCE-managed key or KMS key can be configured.

Constraints:

None

Options:

  • Default: Encryption is performed using the CCE-managed key.

  • KMS: KMS encryption is used.

Default value:

Default

kmsKeyID

String

Details:

KMS key ID

  • In the API for creating a cluster, if the mode field is set to Default, there is no need to specify this field. If the mode field is set to KMS, you can specify a value for this field. If this parameter is left blank, the default KMS key is used by default. If the default key does not exist, DEW will automatically create a default key (cce/default) for the user. To ensure proper cluster functionality, it is important to use a valid KMS key. Refrain from deleting or disabling the key before the cluster lifecycle is complete, as this may cause exceptions. Once a key has been configured for a cluster, it cannot be modified.

  • In the cluster query API, if the mode field is set to Default, the returned value of this field is empty. If the mode field is set to KMS, the specific key ID will be returned.

Constraints:

None

Options:

N/A

Default value:

N/A

Table 43 ClusterStatus

Parameter

Type

Description

phase

String

Details:

Cluster status

Constraints:

None

Options:

  • Available: The cluster is running properly.

  • Unavailable: The cluster is exhibiting unexpected behavior and needs to be manually deleted.

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

  • ResizeFailed: Cluster specification changing is abnormal.

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

  • Freezing: The cluster is being frozen.

  • Frozen: The cluster has been frozen.

  • UnFreezing: The cluster is being unfrozen.

  • Awaking: The cluster is being woken up from hibernation.

  • Empty: The cluster does not have any resources. This field has been deprecated.

  • Error: Resources in the cluster are abnormal. You can manually delete the cluster.

jobID

String

Details:

ID of the job associated with the current cluster status. It supports:

  • ID of the associated job returned during cluster creation. You can use it to obtain the auxiliary job information for creating a cluster.

  • ID of the associated job returned when a cluster fails to be deleted or is being deleted. If this parameter is not empty, you can use the job ID to obtain the auxiliary job information for deleting a cluster.

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

Table 44 ClusterEndpoints

Parameter

Type

Description

url

String

Details:

Access address of kube-apiserver in a cluster

Constraints:

None

Options:

N/A

type

String

Details:

Type of the cluster access address

Constraints:

None

Options:

  • Internal: address for internal network access

  • External: address for external network access

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.