Help Center> Cloud Container Engine> API Reference> APIs> Cluster Management> Creating a Cluster
View PDF

Creating a Cluster

Function

This API is used to create an empty cluster, which has only master nodes but does not have worker nodes. After creating a cluster by calling this API, add a node.

  • The URL for cluster management is in the format of https://Endpoint/uri. In the URL, uri indicates the resource path, that is, the path for API access.
  • By default, ICAgent is not installed for the cluster created by calling this API. 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. For details about how to install ICAgent, see Installing the ICAgent.
  • By default, a maximum of five clusters can be created in a single region. If you need to create more clusters, submit a service ticket.

Constraints

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

A VPC is available. If you already have a VPC available, skip this step. A VPC provides an isolated, configurable, and manageable virtual network for CCE clusters. For details about how to create a VPC, see Creating a VPC.

Create a key pair for identity authentication upon remote node login. For details about how to create a key pair, see Creating a Key Pair. If you use a password to log in to a node, skip this step.

  • Plan the container CIDR block and Service CIDR block before creating a cluster. The CIDR block is a one-time configuration and cannot be changed after the cluster is created. If you want to use another CIDR block, you have to create a new cluster and assign the new CIDR block to the cluster.

Ensure that an agency has been correctly created and is not deleted. If the agency verification fails, the cluster fails to be created. For details about how to create an agency, see Cloud Service Delegation. To authorize ECS or BMS to call cloud services, select Cloud service as the agency type, click Select, and then select ECS BMS.

Ensure that you have sufficient cluster quota. If the cluster quota verification fails, the cluster will fail to be created. For details about quotas, see Quotas.

URI

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

Table 1 Path parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain the project ID, see How to Obtain Parameters in the API URI.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

Content-Type

Yes

String

Message body type (format).

Default: application/json

X-Auth-Token

Yes

String

Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this field is mandatory and must be set to a user token. For details about how to obtain a token, see Authentication.

Maximum: 16384
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

kind

Yes

String

API type. The value is fixed at Cluster or cluster and cannot be changed.

Default: Cluster

apiVersion

Yes

String

API version. The value is fixed at v3 and cannot be changed.

Default: v3

metadata

Yes

ClusterMetadata object

Basic information about a cluster. Metadata is a collection of attributes.

spec

Yes

V3ClusterSpec object

Detailed description of the cluster. CCE creates or updates objects by defining or updating spec.

status

No

ClusterStatus object

Cluster status and job ID of the cluster creation job.
Table 4 ClusterMetadata

Parameter

Mandatory

Type

Description

name

Yes

String

Cluster name.

Enter 4 to 128 characters starting with a letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed.

Minimum: 4

Maximum: 128

uid

No

String

Unique resource ID, which is automatically generated after the resource is created. It cannot be specified.

annotations

No

Map<String,String>

Cluster annotations in the format of key-value pairs.

"annotations": {
"key1" : "value1",
"key2" : "value2"
}
NOTE:

annotations is not used to identify or select objects. Metadata in annotations can be small or large, structured or unstructured, and can include characters that are not allowed in labels.

This field is not stored in the database and is used only to specify the add-ons to be installed in the cluster.

labels

No

Map<String,String>

Cluster labels in the format of key-value pairs.

NOTE:

The value of this field is automatically generated by the system and is used by the frontend to identify the features supported by the cluster during the upgrade. The value specified by the user is invalid.

creationTimestamp

No

String

Time when the cluster was created.

updateTimestamp

No

String

Time when the cluster was updated.
Table 5 V3ClusterSpec

Parameter

Mandatory

Type

Description

type

Yes

String

Cluster type. Options:

  • VirtualMachine: CCE cluster.

A CCE cluster manages a group of node resources based on Kubernetes. It can manage VMs, bare-metal machines, or a combination of both. Kubernetes automatically schedules containers onto available nodes. Before creating a containerized workload, you must have an available cluster.

  • ARM64: Kunpeng cluster.

Containers in a Kunpeng cluster can run on Kunpeng servers that use Arm architecture and Kunpeng processors. Kunpeng-accelerated cloud servers are easy to deploy and provide comparable scaling and scheduling performance as x86-based cloud servers.

Enumeration values:

  • VirtualMachine
  • ARM64

flavor

Yes

String

Default value: When you create a CCE cluster or Kunpeng cluster, the value is cce.s1.small for non-DeC scenarios and cce.dec.s1.small for DeC scenarios.

Cluster flavor, which cannot be changed after the cluster is created.

  • cce.s1.small: small-scale, single-master CCE cluster (≤ 50 nodes)
  • cce.s1.medium: medium-scale, single-master CCE cluster (≤ 200 nodes)
  • cce.s2.small: small-scale, multi-master CCE cluster (≤ 50 nodes)
  • cce.s2.medium: medium-scale, multi-master CCE cluster (≤ 200 nodes)
  • cce.s2.large: large-scale, multi-master CCE cluster (≤ 1,000 nodes)
  • cce.s2.xlarge: ultra-large-scale, multi-master CCE cluster (≤ 2,000 nodes)
NOTE:

s1: single-master CCE cluster

s2: multi-master CCE cluster

dec: dedicated CCE cluster. For example, cce.dec.s1.small is a small-scale, single-master, dedicated CCE cluster (≤ 50 nodes).

Values in the parentheses above indicate the maximum number of nodes that can be managed by the cluster. Select a management scale based on your service requirements.

A single-master cluster has only one master node. If the master node is down, the cluster will become unavailable and stop serving new workloads. However, existing workloads in the cluster are not affected.

A multi-master cluster is highly available. When a master node is faulty, the cluster is still available. For details about how to check the cluster mode, see How Do I Check Whether a Cluster Is in Multi-Master Mode.

version

No

String

Cluster version, which mirrors the baseline version of the Kubernetes community. The latest version is recommended.

You can create clusters of two latest versions on the CCE console. To learn which cluster versions are available, choose Dashboard > Buy Cluster on the CCE console and check the Version parameter. You can call APIs to create clusters of other versions. However, those cluster versions will be gradually brought offline. For details about the support policy, see CCE announcements.

NOTE:
  • If this field is not set, a cluster of the latest version is created by default.
  • If the baseline cluster version is specified but the R version is not specified, the system selects the latest R version of the cluster by default. You are advised not to specify the R version.

description

No

String

Cluster description, for example, which purpose the cluster is intended to serve. By default, this field is left unspecified. After a cluster is created, you can modify the cluster information by calling the API for updating a specified cluster. Alternatively, you can modify the cluster information in the Description column on the cluster details page. Only UTF-8 encoding is supported.

Minimum: 0

Maximum: 200

ipv6enable

No

Boolean

Whether the cluster supports IPv6 addresses. This field is supported in v1.15 and later versions.

hostNetwork

Yes

HostNetwork object

Node networking parameters, including VPC and subnet ID. This field is mandatory because nodes in a cluster communicate with each other by using a VPC.

containerNetwork

Yes

ContainerNetwork object

Container networking parameters, including the container network model and container CIDR block.

eniNetwork

No

EniNetwork object

Configuration of Cloud Native Network 2.0. Specify this field when creating a CCE Turbo cluster (in OBT).

authentication

No

Authentication object

Configurations of the cluster authentication mode.

billingMode

No

Integer

Billing mode of a cluster. Currently, only pay-per-use clusters can be created by calling this API. Value 0 indicates pay-per-use. If this field is left unspecified, the default value 0 is used.

Default: 0

masters

No

Array of MasterSpec objects

Advanced configuration of master nodes.

kubernetesSvcIpRange

No

String

Service CIDR block or the IP address range which kubernetes clusterIp must fall within. This field is available only for clusters of v1.11.7 and later.

clusterTags

No

Array of ResourceTag objects

Cluster resource tags.

kubeProxyMode

No

String

Service forwarding mode. Two modes are available:

iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes.

ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during Service updates. It is suitable for large-sized clusters.

NOTE:

This field is displayed only in the response. Set this field in extendParam when creating a cluster.

Enumeration values:

  • iptables
  • ipvs

az

No

String

AZ. This field is returned only for a query.

extendParam

No

Map<String,String>

Extended fields in the format of key-value pairs. If the cluster will span across AZs or belong to a specified enterprise project, or a dedicated CCE cluster is to be created, set extended fields as follows:

  • clusterAZ: AZ of master nodes in the cluster.
  • multi_az: (Optional) The cluster will span across AZs. This field is configurable only for high-availability clusters.
  • AZ of the dedicated cloud computing pool: The cluster will be deployed in the AZ of Dedicated Cloud (DeC). This field is mandatory for dedicated CCE clusters. For example, set this field to cn-north-4a for CN North-Beijing4, AZ 1.
  • dssMasterVolumes: Whether the system and data disks of a master node use dedicated distributed storage. If this field is omitted or left unspecified, EVS disks are used by default. This field is mandatory for dedicated CCE clusters. The value is in the following format:
<rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType>

Description: rootVol is the system disk. dataVol is the data disk. dssPoolID indicates the ID of the DSS storage pool. volType indicates the storage volume type of the DSS storage pool, such as SAS and SSD. Example: c950ee97-587c-4f24-8a74-3367e3da570f.sas;6edbc2f4-1507-44f8-ac0d-eed1d2608d38.ssd This field cannot be configured for non-dedicated CCE clusters.

  • enterpriseProjectId: If the cluster will belong to a specific enterprise project, set the key-value pair {"enterpriseProjectId":"xxx"}.
NOTE:
  • An enterprise project can be configured only after you have enabled the enterprise project service. For details, see Accessing the Enterprise Center.
  • The enterprise project to which the cluster belongs must be the same as the enterprise project to which other cloud service resources associated with the cluster belong.
  • kubeProxyMode: Service forwarding mode. Two modes are available:
  • iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes.
  • ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during Service updates. It is suitable for large-sized clusters.
  • clusterExternalIP: EIP of the master node.
  • alpha.cce/fixPoolMask: number of mask bits of the fixed IP address pool of the container network model. This field is supported only for the VPC network model. The value is an integer ranging from 24 to 28.
  • decMasterFlavor: flavor of the master nodes in the dedicated CCE cluster. Maximum length: 255 characters
  • dockerUmaskMode: default UmaskMode configuration of Docker in a cluster. The value can be secure or normal. If this parameter is not specified, normal is used by default.
  • kubernetes.io/cpuManagerPolicy: cluster CPU management policy. The value can be none or static. The default value is none.
  • none: CPU cores will not be exclusively allocated to workload pods. Select this value if you want a large pool of shareable CPU cores.
  • static: CPU cores can be exclusively allocated to workload pods. Select this value if your workload is sensitive to latency in CPU cache and scheduling.

supportIstio

No

Boolean

Whether Istio is supported.
Table 6 HostNetwork

Parameter

Mandatory

Type

Description

vpc

Yes

String

ID of the VPC used to create a master node. You can obtain the value of this parameter from Creating a VPC.

You can obtain the value in either of the following ways:

  • Method 1: Log in to the VPC console, and click the name of a VPC to view the VPC ID on the displayed details page.

Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs.

NOTE:

Currently, the VPC container network model does not support interconnection with VPCs that contain an extended CIDR block.

If you are an enterprise user, ensure that the enterprise project ID of the VPC is the same as that selected during cluster creation. The enterprise project ID of the cluster is specified by enterpriseProjectId in the extendParam field. The default value is 0, indicating the default enterprise project.

Minimum: 0

Maximum: 64

subnet

Yes

String

Network ID of the subnet used to create a master node. Perform the following step 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: Query the ID through the VPC API. For details, see Querying Subnets.

Minimum: 0

Maximum: 64

SecurityGroup

No

String

Security group ID of the node. The value is generated when you create a security group, and any user-defined value is invalid.
Table 7 ContainerNetwork

Parameter

Mandatory

Type

Description

mode

Yes

String

Container network model. Select one of the following possible values:

  • overlay_l2: an overlay_l2 network built for containers by using Open vSwitch (OVS).
  • vpc-router: an underlay_l2 network built for containers by using IPVlan and custom VPC routes.
  • eni*: cloud native 2.0 network model. This model deeply integrates the native ENI capability of VPC, uses the VPC CIDR block to allocate container addresses, and supports passthrough between load balancers and containers to provide high performance. You can use this network model when creating a CCE Turbo cluster (in OBT).

Tunnel network: In this model, the container network is an overlay network on top of a VPC network based on the VXLAN technology. VXLAN encapsulates Ethernet packets as UDP packets for tunnel transmission. Though at some cost of performance, the encapsulation in networking enables higher interoperability and compatibility with advanced features (such as network policy-based isolation), meeting the requirements of most applications.

VPC network: Routing is implemented within a VPC network according to custom VPC routes. Each node is assigned a CIDR block of a fixed size. vpc-router networks are free of tunnel encapsulation overheads and provide better container network performance than tunnel networks. In addition, as routes to node IP addresses and the containers have been configured on vpc-router, containers can be directly accessed from outside the cluster.

Minimum: 0

Maximum: 64

Enumeration values:

  • overlay_l2
  • vpc-router
  • eni

cidr

No

String

Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19. If the selected CIDR block conflicts with existing CIDR blocks, the system automatically selects another CIDR block.

If the maximum number of pods on a node is 110, each of the recommended container CIDR blocks supports at least 582 nodes. This field cannot be modified after the cluster is created. Exercise caution when setting this field.

Minimum: 0

Maximum: 64
Table 8 EniNetwork

Parameter

Mandatory

Type

Description

eniSubnetId

Yes

String

IPv4 network ID of the subnet for creating master nodes. Currently, IPv6 is not supported. To obtain the value, perform the following operations: - Method 1: Log in to the VPC console, click the subnet under the VPC to go to the subnet details page, and search for the IPv4 network ID. - Method 2: Query the ID through the VPC API. For details, see Querying Subnets.

Minimum: 0

Maximum: 64

eniSubnetCIDR

Yes

String

ENI subnet CIDR block.
Table 9 Authentication

Parameter

Mandatory

Type

Description

mode

No

String

Cluster authentication mode.

  • kubernetes Clusters of v1.11 or earlier support x509, rbac, and authenticating_proxy. The default value is x509.
  • Clusters of Kubernetes v1.13 or later support rbac and authenticating_proxy. The default value is rbac.

authenticatingProxy

No

AuthenticatingProxy object

Configuration related to the authenticating_proxy mode. This field is mandatory when the authentication mode is authenticating_proxy.
Table 10 AuthenticatingProxy

Parameter

Mandatory

Type

Description

ca

No

String

X509 CA certificate (Base64-encoded) configured in authenticating_proxy mode. This field is mandatory when the cluster authentication mode is authenticating_proxy. The maximum size of the certificate is 1 MB.
Table 11 MasterSpec

Parameter

Mandatory

Type

Description

availabilityZone

No

String

AZ.
Table 12 ResourceTag

Parameter

Mandatory

Type

Description

key

No

String

Key.

  • The value can contain a maximum of 36 UTF-8 characters.
  • The following special characters are not supported: [=*<>\,|/]+
  • ASCII control characters (0–31) are not supported.

Minimum: 1

Maximum: 36

value

No

String

Value.

  • The value can contain a maximum of 43 UTF-8 characters.
  • The following special characters are not supported: [=*<>\,|/]+
  • ASCII control characters (0–31) are not supported.

Maximum: 43
Table 13 ClusterStatus

Parameter

Mandatory

Type

Description

phase

No

String

Cluster status. Possible values:

  • Available: The cluster is running properly.
  • Unavailable: The cluster is exhibiting unexpected behavior. Manually delete the cluster or contact the administrator to delete the cluster.
  • 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.
  • Empty: The cluster has no resources.

jobID

No

String

Job ID.

reason

No

String

Reason of cluster state change. This parameter is returned if the cluster is not in the Available state.

message

No

String

Detailed information about why the cluster changes to the current state. This parameter is returned if the cluster is not in the Available state.

endpoints

No

Array of ClusterEndpoints objects

Access address of kube-apiserver in the cluster.

isLocked

No

Boolean

The CBC resource is locked.

lockScene

No

String

Scenario where the CBC resource is locked.

lockSource

No

String

Resource locking.

lockSourceId

No

String

ID of the locked resource.

deleteOption

No

Object

Whether to delete configurations. This parameter is contained only in the response to the deletion request.

deleteStatus

No

Object

Whether to delete the status information. This parameter is contained only in the response to the deletion request.
Table 14 ClusterEndpoints

Parameter

Mandatory

Type

Description

url

No

String

Access address of kube-apiserver in the cluster.

type

No

String

Type of the cluster access address.

  • Internal: address for internal network access
  • External: address for external network access

Response Parameters

Status code: 201

Table 15 Response body parameters

Parameter

Type

Description

kind

String

API type. The value is fixed at Cluster or cluster and cannot be changed.

Default: Cluster

apiVersion

String

API version. The value is fixed at v3 and cannot be changed.

Default: v3

metadata

ClusterMetadata object

Basic information about a cluster. Metadata is a collection of attributes.

spec

V3ClusterSpec object

Detailed description of the cluster. CCE creates or updates objects by defining or updating spec.

status

ClusterStatus object

Cluster status and job ID of the cluster creation job.
Table 16 ClusterMetadata

Parameter

Type

Description

name

String

Cluster name.

Enter 4 to 128 characters starting with a letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed.

Minimum: 4

Maximum: 128

uid

String

Unique resource ID, which is automatically generated after the resource is created. It cannot be specified.

annotations

Map<String,String>

Cluster annotations in the format of key-value pairs.

"annotations": {
"key1" : "value1",
"key2" : "value2"
}
NOTE:

annotations is not used to identify or select objects. Metadata in annotations can be small or large, structured or unstructured, and can include characters that are not allowed in labels.

This field is not stored in the database and is used only to specify the add-ons to be installed in the cluster.

labels

Map<String,String>

Cluster labels in the format of key-value pairs.

NOTE:

The value of this field is automatically generated by the system and is used by the frontend to identify the features supported by the cluster during the upgrade. The value specified by the user is invalid.

creationTimestamp

String

Time when the cluster was created.

updateTimestamp

String

Time when the cluster was updated.
Table 17 V3ClusterSpec

Parameter

Type

Description

type

String

Cluster type. Options:

  • VirtualMachine: CCE cluster.

A CCE cluster manages a group of node resources based on Kubernetes. It can manage VMs, bare-metal machines, or a combination of both. Kubernetes automatically schedules containers onto available nodes. Before creating a containerized workload, you must have an available cluster.

  • ARM64: Kunpeng cluster.

Containers in a Kunpeng cluster can run on Kunpeng servers that use Arm architecture and Kunpeng processors. Kunpeng-accelerated cloud servers are easy to deploy and provide comparable scaling and scheduling performance as x86-based cloud servers.

Enumeration values:

  • VirtualMachine
  • ARM64

flavor

String

Default value: When you create a CCE cluster or Kunpeng cluster, the value is cce.s1.small for non-DeC scenarios and cce.dec.s1.small for DeC scenarios.

Cluster flavor, which cannot be changed after the cluster is created.

  • cce.s1.small: small-scale, single-master CCE cluster (≤ 50 nodes)
  • cce.s1.medium: medium-scale, single-master CCE cluster (≤ 200 nodes)
  • cce.s2.small: small-scale, multi-master CCE cluster (≤ 50 nodes)
  • cce.s2.medium: medium-scale, multi-master CCE cluster (≤ 200 nodes)
  • cce.s2.large: large-scale, multi-master CCE cluster (≤ 1,000 nodes)
  • cce.s2.xlarge: ultra-large-scale, multi-master CCE cluster (≤ 2,000 nodes)
NOTE:

s1: single-master CCE cluster

s2: multi-master CCE cluster

dec: dedicated CCE cluster. For example, cce.dec.s1.small is a small-scale, single-master, dedicated CCE cluster (≤ 50 nodes).

Values in the parentheses above indicate the maximum number of nodes that can be managed by the cluster. Select a management scale based on your service requirements.

A single-master cluster has only one master node. If the master node is down, the cluster will become unavailable and stop serving new workloads. However, existing workloads in the cluster are not affected.

A multi-master cluster is highly available. When a master node is faulty, the cluster is still available. For details about how to check the cluster mode, see How Do I Check Whether a Cluster Is in Multi-Master Mode.

version

String

Cluster version, which mirrors the baseline version of the Kubernetes community. The latest version is recommended.

You can create clusters of two latest versions on the CCE console. To learn which cluster versions are available, choose Dashboard > Buy Cluster on the CCE console and check the Version parameter. You can call APIs to create clusters of other versions. However, those cluster versions will be gradually brought offline. For details about the support policy, see CCE announcements.

NOTE:
  • If this field is not set, a cluster of the latest version is created by default.
  • If the baseline cluster version is specified but the R version is not specified, the system selects the latest R version of the cluster by default. You are advised not to specify the R version.

description

String

Cluster description, for example, which purpose the cluster is intended to serve. By default, this field is left unspecified. After a cluster is created, you can modify the cluster information by calling the API for updating a specified cluster. Alternatively, you can modify the cluster information in the Description column on the cluster details page. Only UTF-8 encoding is supported.

Minimum: 0

Maximum: 200

ipv6enable

Boolean

Whether the cluster supports IPv6 addresses. This field is supported in v1.15 and later versions.

hostNetwork

HostNetwork object

Node networking parameters, including VPC and subnet ID. This field is mandatory because nodes in a cluster communicate with each other by using a VPC.

containerNetwork

ContainerNetwork object

Container networking parameters, including the container network model and container CIDR block.

eniNetwork

EniNetwork object

Configuration of Cloud Native Network 2.0. Specify this field when creating a CCE Turbo cluster (in OBT).

authentication

Authentication object

Configurations of the cluster authentication mode.

billingMode

Integer

Billing mode of a cluster. Currently, only pay-per-use clusters can be created by calling this API. Value 0 indicates pay-per-use. If this field is left unspecified, the default value 0 is used.

Default: 0

masters

Array of MasterSpec objects

Advanced configuration of master nodes.

kubernetesSvcIpRange

String

Service CIDR block or the IP address range which kubernetes clusterIp must fall within. This field is available only for clusters of v1.11.7 and later.

clusterTags

Array of ResourceTag objects

Cluster resource tags.

kubeProxyMode

String

Service forwarding mode. Two modes are available:

iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes.

ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during Service updates. It is suitable for large-sized clusters.

NOTE:

This field is displayed only in the response. Set this field in extendParam when creating a cluster.

Enumeration values:

  • iptables
  • ipvs

az

String

AZ. This field is returned only for a query.

extendParam

Map<String,String>

Extended fields in the format of key-value pairs. If the cluster will span across AZs or belong to a specified enterprise project, or a dedicated CCE cluster is to be created, set extended fields as follows:

  • clusterAZ: AZ of master nodes in the cluster.
  • multi_az: (Optional) The cluster will span across AZs. This field is configurable only for high-availability clusters.
  • AZ of the dedicated cloud computing pool: The cluster will be deployed in the AZ of Dedicated Cloud (DeC). This field is mandatory for dedicated CCE clusters. For example, set this field to cn-north-4a for CN North-Beijing4, AZ 1.
  • dssMasterVolumes: Whether the system and data disks of a master node use dedicated distributed storage. If this field is omitted or left unspecified, EVS disks are used by default. This field is mandatory for dedicated CCE clusters. The value is in the following format:
<rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType>

Description: rootVol is the system disk. dataVol is the data disk. dssPoolID indicates the ID of the DSS storage pool. volType indicates the storage volume type of the DSS storage pool, such as SAS and SSD. Example: c950ee97-587c-4f24-8a74-3367e3da570f.sas;6edbc2f4-1507-44f8-ac0d-eed1d2608d38.ssd This field cannot be configured for non-dedicated CCE clusters.

  • enterpriseProjectId: If the cluster will belong to a specific enterprise project, set the key-value pair {"enterpriseProjectId":"xxx"}.
NOTE:
  • An enterprise project can be configured only after you have enabled the enterprise project service. For details, see Accessing the Enterprise Center.
  • The enterprise project to which the cluster belongs must be the same as the enterprise project to which other cloud service resources associated with the cluster belong.
  • kubeProxyMode: Service forwarding mode. Two modes are available:
  • iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes.
  • ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode supports incremental updates and can keep connections uninterrupted during Service updates. It is suitable for large-sized clusters.
  • clusterExternalIP: EIP of the master node.
  • alpha.cce/fixPoolMask: number of mask bits of the fixed IP address pool of the container network model. This field is supported only for the VPC network model. The value is an integer ranging from 24 to 28.
  • decMasterFlavor: flavor of the master nodes in the dedicated CCE cluster. Maximum length: 255 characters
  • dockerUmaskMode: default UmaskMode configuration of Docker in a cluster. The value can be secure or normal. If this parameter is not specified, normal is used by default.
  • kubernetes.io/cpuManagerPolicy: cluster CPU management policy. The value can be none or static. The default value is none.
  • none: CPU cores will not be exclusively allocated to workload pods. Select this value if you want a large pool of shareable CPU cores.
  • static: CPU cores can be exclusively allocated to workload pods. Select this value if your workload is sensitive to latency in CPU cache and scheduling.

supportIstio

Boolean

Whether Istio is supported.
Table 18 HostNetwork

Parameter

Type

Description

vpc

String

ID of the VPC used to create a master node. You can obtain the value of this parameter from Creating a VPC.

You can obtain the value in either of the following ways:

  • Method 1: Log in to the VPC console, and click the name of a VPC to view the VPC ID on the displayed details page.

Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs.

NOTE:

Currently, the VPC container network model does not support interconnection with VPCs that contain an extended CIDR block.

If you are an enterprise user, ensure that the enterprise project ID of the VPC is the same as that selected during cluster creation. The enterprise project ID of the cluster is specified by enterpriseProjectId in the extendParam field. The default value is 0, indicating the default enterprise project.

Minimum: 0

Maximum: 64

subnet

String

Network ID of the subnet used to create a master node. Perform the following step 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: Query the ID through the VPC API. For details, see Querying Subnets.

Minimum: 0

Maximum: 64

SecurityGroup

String

Security group ID of the node. The value is generated when you create a security group, and any user-defined value is invalid.
Table 19 ContainerNetwork

Parameter

Type

Description

mode

String

Container network model. Select one of the following possible values:

  • overlay_l2: an overlay_l2 network built for containers by using Open vSwitch (OVS).
  • vpc-router: an underlay_l2 network built for containers by using IPVlan and custom VPC routes.
  • eni*: cloud native 2.0 network model. This model deeply integrates the native ENI capability of VPC, uses the VPC CIDR block to allocate container addresses, and supports passthrough between load balancers and containers to provide high performance. You can use this network model when creating a CCE Turbo cluster (in OBT).

Tunnel network: In this model, the container network is an overlay network on top of a VPC network based on the VXLAN technology. VXLAN encapsulates Ethernet packets as UDP packets for tunnel transmission. Though at some cost of performance, the encapsulation in networking enables higher interoperability and compatibility with advanced features (such as network policy-based isolation), meeting the requirements of most applications.

VPC network: Routing is implemented within a VPC network according to custom VPC routes. Each node is assigned a CIDR block of a fixed size. vpc-router networks are free of tunnel encapsulation overheads and provide better container network performance than tunnel networks. In addition, as routes to node IP addresses and the containers have been configured on vpc-router, containers can be directly accessed from outside the cluster.

Minimum: 0

Maximum: 64

Enumeration values:

  • overlay_l2
  • vpc-router
  • eni

cidr

String

Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19. If the selected CIDR block conflicts with existing CIDR blocks, the system automatically selects another CIDR block.

If the maximum number of pods on a node is 110, each of the recommended container CIDR blocks supports at least 582 nodes. This field cannot be modified after the cluster is created. Exercise caution when setting this field.

Minimum: 0

Maximum: 64
Table 20 EniNetwork

Parameter

Type

Description

eniSubnetId

String

IPv4 network ID of the subnet for creating master nodes. Currently, IPv6 is not supported. To obtain the value, perform the following operations: - Method 1: Log in to the VPC console, click the subnet under the VPC to go to the subnet details page, and search for the IPv4 network ID. - Method 2: Query the ID through the VPC API. For details, see Querying Subnets.

Minimum: 0

Maximum: 64

eniSubnetCIDR

String

ENI subnet CIDR block.
Table 21 Authentication

Parameter

Type

Description

mode

String

Cluster authentication mode.

  • kubernetes Clusters of v1.11 or earlier support x509, rbac, and authenticating_proxy. The default value is x509.
  • Clusters of Kubernetes v1.13 or later support rbac and authenticating_proxy. The default value is rbac.

authenticatingProxy

AuthenticatingProxy object

Configuration related to the authenticating_proxy mode. This field is mandatory when the authentication mode is authenticating_proxy.
Table 22 AuthenticatingProxy

Parameter

Type

Description

ca

String

X509 CA certificate (Base64-encoded) configured in authenticating_proxy mode. This field is mandatory when the cluster authentication mode is authenticating_proxy. The maximum size of the certificate is 1 MB.
Table 23 MasterSpec

Parameter

Type

Description

availabilityZone

String

AZ.
Table 24 ResourceTag

Parameter

Type

Description

key

String

Key.

  • The value can contain a maximum of 36 UTF-8 characters.
  • The following special characters are not supported: [=*<>\,|/]+
  • ASCII control characters (0–31) are not supported.

Minimum: 1

Maximum: 36

value

String

Value.

  • The value can contain a maximum of 43 UTF-8 characters.
  • The following special characters are not supported: [=*<>\,|/]+
  • ASCII control characters (0–31) are not supported.

Maximum: 43
Table 25 ClusterStatus

Parameter

Type

Description

phase

String

Cluster status. Possible values:

  • Available: The cluster is running properly.
  • Unavailable: The cluster is exhibiting unexpected behavior. Manually delete the cluster or contact the administrator to delete the cluster.
  • 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.
  • Empty: The cluster has no resources.

jobID

String

Job ID.

reason

String

Reason of cluster state change. This parameter is returned if the cluster is not in the Available state.

message

String

Detailed information about why the cluster changes to the current state. This parameter is returned if the cluster is not in the Available state.

endpoints

Array of ClusterEndpoints objects

Access address of kube-apiserver in the cluster.

isLocked

Boolean

The CBC resource is locked.

lockScene

String

Scenario where the CBC resource is locked.

lockSource

String

Resource locking.

lockSourceId

String

ID of the locked resource.

deleteOption

Object

Whether to delete configurations. This parameter is contained only in the response to the deletion request.

deleteStatus

Object

Whether to delete the status information. This parameter is contained only in the response to the deletion request.
Table 26 ClusterEndpoints

Parameter

Type

Description

url

String

Access address of kube-apiserver in the cluster.

type

String

Type of the cluster access address.

  • Internal: address for internal network access
  • External: address for external network access

Example Requests

Creating a CCE Cluster

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

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "mycluster",
    "labels" : {
      "foo" : "bar"
    },
    "annotations" : {
      "cluster.install.addons/install" : "[{\"addonTemplateName\":\"autoscaler\",\"version\":\"1.13.11\",\"values\":{\"flavor\":{\"description\":\"Has only one instance\",\"name\":\"Single\",\"replicas\":1,\"resources\":[{\"limitsCpu\":\"90m\",\"limitsMem\":\"200Mi\",\"name\":\"autoscaler\",\"requestsCpu\":\"50m\",\"requestsMem\":\"100Mi\"}]},\"custom\":{\"coresTotal\":32000,\"maxEmptyBulkDeleteFlag\":10,\"maxNodesTotal\":1000,\"memoryTotal\":128000,\"scaleDownDelayAfterAdd\":10,\"scaleDownDelayAfterDelete\":10,\"scaleDownDelayAfterFailure\":3,\"scaleDownEnabled\":false,\"scaleDownUnneededTime\":10,\"scaleDownUtilizationThreshold\":0.5,\"scaleUpCpuUtilizationThreshold\":1,\"scaleUpMemUtilizationThreshold\":1,\"scaleUpUnscheduledPodEnabled\":true,\"scaleUpUtilizationEnabled\":true,\"tenant_id\":\"22a8a02394794b908d256103a5b63c65\",\"unremovableNodeRecheckTimeout\":5}}},{\"addonTemplateName\":\"coredns\",\"version\":\"1.13.3\",\"values\":{\"flavor\":{\"description\":\"Has two instances\",\"name\":2500,\"replicas\":2,\"resources\":[{\"limitsCpu\":\"500m\",\"limitsMem\":\"512Mi\",\"name\":\"coredns\",\"requestsCpu\":\"500m\",\"requestsMem\":\"512Mi\"}]},\"custom\":{\"stub_domains\":{},\"upstream_nameservers\":[],\"tenant_id\":\"22a8a02394794b908d256103a5b63c65\"}}},{\"addonTemplateName\":\"gpu-beta\",\"version\":\"1.1.7\",\"values\":{\"custom\":{\"is_driver_from_nvidia\":true,\"nvidia_driver_download_url\":\"https://us.download.nvidia.com/tesla/396.37/NVIDIA-Linux-x86_64-396.37.run\"}}},{\"addonTemplateName\":\"storage-driver\",\"version\":\"\"}]"
    }
  },
  "spec" : {
    "type" : "VirtualMachine",
    "flavor" : "cce.s1.small",
    "version" : "v1.13.10-r1",
    "description" : "this is a demo cluster",
    "hostNetwork" : {
      "vpc" : "1cb74d47-8e09-4d14-a065-75f4fc03e5eb",
      "subnet" : "d44c089c-fbdc-49b3-ae8f-7b42c64219cf"
    },
    "containerNetwork" : {
      "mode" : "overlay_l2",
      "cidr" : "172.16.0.0/16"
    },
    "kubeProxyMode" : "iptables",
    "extendParam" : {
      "foo" : "bar"
    }
  }
}

Example Responses

Status code: 201

The cluster creation job is successfully delivered.

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "mycluster",
    "uid" : "128e36e5-ac4a-11ea-9846-0255ac101d1a",
    "creationTimestamp" : "2020-06-12 01:14:32.70889292 +0000 UTC",
    "updateTimestamp" : "2020-06-12 01:14:32.708893619 +0000 UTC"
  },
  "spec" : {
    "type" : "VirtualMachine",
    "flavor" : "cce.s2.small",
    "version" : "v1.15.6-r1",
    "ipv6enable" : false,
    "hostNetwork" : {
      "vpc" : "95e0ff1a-4c5f-478c-b6a7-f8ab09512d13",
      "subnet" : "a0bcff14-424d-450b-ad6a-fa89f839ef56"
    },
    "containerNetwork" : {
      "mode" : "overlay_l2",
      "cidr" : "172.16.0.0/16"
    },
    "eniNetwork" : { },
    "authentication" : {
      "mode" : "rbac",
      "authenticatingProxy" : { }
    },
    "billingMode" : 0,
    "kubernetesSvcIpRange" : "10.247.0.0/16"
  },
  "status" : {
    "phase" : "Creating",
    "jobID" : "1305e56c-ac4a-11ea-9846-0255ac101d1a"
  }
}

Status Codes

Status Code

Description

201

The cluster creation job is successfully delivered.

Error Codes

See Error Codes.

Parent topic: Cluster Management