Creating a Cluster¶
Function¶
This API is used to create an empty cluster, which has only master nodes but do not have worker nodes. After creating a cluster by calling this API, you can add nodes to the cluster. For details, see Creating a Node.
Note
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.
Info collect agent (ICAgent) is an O&M data collection agent. It runs on each server to collect data from probes in real time. When this API is called to create a cluster, ICAgent is not installed by default. To automatically install ICAgent during cluster creation, add "cluster.install.addons.external/install": "[{\"addonTemplateName\":\"icagent\"}]" to the annotations field in the request body.
Before creating a cluster, Creating a VPC and Subnet. If a VPC and subnet already exists, you do not need to create them again.
By default, an account can create a maximum of five clusters in each region.
URI¶
POST /api/v3/projects/{project_id}/clusters
Table 1 describes the parameters of this API.
Parameter | Mandatory | Description |
---|---|---|
project_id | Yes | Project ID. For details about how to obtain the project ID, see How to Obtain Parameters in the API URI. |
Request¶
Request parameters:
Table 2 and Table 3 describe the request parameters.
Parameter | Mandatory | String | 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 parameter is mandatory and must be set to a user token. For details on how to obtain a user token, see API Usage Guidelines. |
Parameter | Mandatory | Type | Description |
---|---|---|---|
kind | Yes | String | API type. For a cluster management API, the parameter must be set to Cluster and cannot be changed. |
apiVersion | Yes | String | API version. The value is fixed at v3 and cannot be changed. |
metadata | Yes | metadata object | Basic information about a cluster. metadata is a collection of attributes. |
spec | Yes | spec object | Detailed description of the cluster to be created. CCE creates or updates objects by defining or updating its spec. |
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. |
uid | No | String | Unique resource ID, which is automatically generated after the resource is created. It cannot be specified. |
labels | No | Object | 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. |
annotations | No | Object | Cluster annotations in the format of key-value pairs. "annotations": {
"key1" : "value1",
"key2" : "value2"
}
Note
|
Parameter | Mandatory | Type | Description |
---|---|---|---|
category | No | String | Cluster category:
Note This parameter is valid in cluster of v1.17.17 or higher. |
type | Yes | String | Cluster type. VirtualMachine: The master node architecture is x86. |
flavor | Yes | String | Cluster flavor.
Note
|
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 > Create Cluster on the CCE console and check the Version parameter. You can call APIs to create clusters of other versions. However, these clusters will be gradually brought offline. For details about the offline policy, see the official CCE announcement. Note If this parameter is not set, the cluster of the latest version is created by default. |
platformVersion | No | String | Version of the CCE cluster platform, which is for viewing only and cannot be specified during cluster creation. The latest platform version corresponding to the cluster version is automatically selected during cluster creation. Value format: cce.X.Y
|
description | No | String | Cluster description, for example, which purpose the cluster is intended to serve. By default, this parameter is left unspecified. To modify cluster description after the cluster is created, call the API that is used to update information about a specified cluster or go to the cluster details page on the CCE console. |
customSan | No | Array of strings | Custom SAN field in the server certificate of the cluster API server, which must comply with the SSL and X509 format specifications.
example: SAN 1: DNS Name=example.com SAN 2: DNS Name=www.example.com SAN 3: DNS Name=example.net SAN 4: IP Address=93.184.216.34 |
ipv6enable | No | Boolean | Whether the cluster supports IPv6 addresses. This field is supported in clusters of v1.25 and later versions. |
hostNetwork | Yes | hostNetwork object | Node network parameters, including a VPC and subnet ID. hostNetwork is mandatory because nodes in a cluster communicate with each other by using a VPC. |
containerNetwork | Yes | containerNetwork object | Container network parameters, including a container network model and container CIDR block. |
publicAccess | No | PublicAccess object | Cluster API access control. |
authentication | No | authentication object | Configurations of the cluster authentication mode. |
masters | No | MasterSpec objects | Advanced configurations of the master node. |
kubernetesSvcIpRange | No | String | Service CIDR block or the IP address range which the kubernetes clusterIp must fall within. This parameter is available only for clusters of v1.11.7 and later. |
kubeProxyMode | No | String | Service forwarding mode. Two modes are available:
|
extendParam | No | extendParam object | Extended fields in the format of key-value pairs. If the cluster will span across AZs or belong to a specified enterprise project, set extended fields as described in Table 14. |
enableMasterVolumeEncryption | No | Boolean | The system disks and data disks of the master nodes in the cluster are encrypted. By default, the AES-256 encryption algorithm is used. This function is available in cluster of v1.25 and later versions. The configuration cannot be modified after the cluster is created. After this function is enabled, there is some disk I/O performance loss. |
Parameter | Mandatory | Type | Description |
---|---|---|---|
vpc | Yes | String | ID of the VPC used to create a master node. The VPC ID is obtained from Creating a VPC and Subnet. |
subnet | Yes | String | Network ID of the subnet. The value is obtained from Creating a VPC and Subnet. |
SecurityGroup | No | String | Default worker node security group ID of the cluster. If specified, the cluster will be bound to the target security group. Otherwise, the system will automatically create a default worker node security group for you. The default worker node security group needs to allow access from certain ports to ensure normal communications. |
Parameter | Mandatory | Type | Description |
---|---|---|---|
cidrs | No | Array of strings | Trustlist of network CIDRs that are allowed to access cluster APIs. You are advised to allow the traffic from VPC and container network CIDRs. By default, no trustlist is configured, and the value is ["0.0.0.0/0"]. Note This parameter is valid only when a cluster is created. |
Parameter | Mandatory | Type | Description |
---|---|---|---|
mode | No | String | Cluster authentication mode.
|
authenticatingProxy | No | authenticatingProxy object | Configurations of the authenticating_proxy mode. |
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. Note The uploaded CA certificate is used for both the authentication proxy and the kube-apiserver aggregation layer configuration. If the certificate is invalid, the cluster cannot be created. For details about the kube-apiserver aggregation layer, see Configure the Aggregation Layer. |
cert | No | String | Client certificate (Base64-encoded) issued by the X509 CA certificate configured in authenticating_proxy mode. This certificate is used for authentication from kube-apiserver to the extended API server. This field is mandatory when the cluster authentication mode is authenticating_proxy. For details about the kube-apiserver aggregation layer, see Configure the Aggregation Layer. |
privateKey | No | String | Private key (Base64-encoded) of the client certificate issued by the X509 CA certificate configured in authenticating_proxy mode. This key 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. This field is mandatory when the cluster authentication mode is authenticating_proxy. For details about the kube-apiserver aggregation layer, see Configure the Aggregation Layer. |
Parameter | Mandatory | Type | Description |
---|---|---|---|
mode | Yes | String | Container network model. Select one of the following possible values:
Note
|
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. This parameter cannot be modified after the cluster is created. Exercise caution when setting this parameter.(This parameter has been discarded. If cidrs has been configured, skip this parameter.) Minimum: 0 Maximum: 64 |
cidrs | No | Array of ContainerCIDR objects | List of container CIDR blocks. In clusters of v1.21 and later, the cidrs field is used. When the cluster network type is vpc-router, you can add multiple container CIDR blocks. In versions earlier than v1.21, if the cidrs field is used, the first CIDR element in the array is used as the container CIDR block. The configuration cannot be changed after the cluster is created. |
Parameter | Mandatory | Type | Description |
---|---|---|---|
cidr | Yes | String | Container CIDR block. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, and 192.168.0.0/16-19 |
Parameter | Mandatory | Type | Description |
---|---|---|---|
eniSubnetId | Yes | String | IPv4 Subnet ID of the ENI container subnet. Currently, IPv6 is not supported. |
eniSubnetCIDR | Yes | String | ENI subnet CIDR block. |
Parameter | Mandatory | Type | Description |
---|---|---|---|
availabilityZone | No | String | Availability Zone. For example: "masters": [
{
"availabilityZone": "eu-de-01"
},
{
"availabilityZone": "eu-de-01"
},
{
"availabilityZone": "eu-de-02"
}
],
|
Parameter | Mandatory | Type | Description |
---|---|---|---|
clusterAZ | No | String | If you want to enable multiple AZs for the cluster, enter {"clusterAZ": "multi_az"}. Note Only HA clusters support multiple AZs. To be specific, this field can be configured only when the flavor field in Table 5 is set to cce.s2.small, cce.s2.medium, cce.s2.large, cce.t2.small, cce.t2.medium, or cce.t2.large. After multi-AZ deployment is enabled, the three master nodes of the cluster are distributed in different AZs. The cluster remains available even when one of the AZs is down. |
dssMasterVolumes | No | String | Whether the system and data disks of a master node use dedicated distributed storage. If this parameter is omitted or left unspecified, EVS disks are used by default. |
kubeProxyMode | No | String | Service forwarding mode. Two modes are available:
Note This parameter has been deprecated. If both this parameter and kubeProxyMode under ClusterSpec are specified, the latter will be used. |
clusterExternalIP | No | String | EIP of the master node. |
alpha.cce/fixPoolMask | No | String | Number of mask bits of the fixed IP address pool of the container network model. This field is supported only for the VPC network model (vpc-router). This parameter determines the number of container IP addresses that can be allocated to a node. The maximum number of pods that can be created on a node is decided by this parameter and maxPods set during node creation. The value is an integer ranging from 24 to 28. |
kubernetes.io/cpuManagerPolicy | No | String | Cluster CPU management policy. The value can be none or static. The default value is none.
|
upgradefrom | No | String | Reserved. This field is returned only for a query. |
Example Request
CCE Cluster:
{
"kind": "Cluster",
"apiVersion": "v3",
"metadata": {
"name": "mycluster",
"labels": {
"foo": "bar"
},
"annotations": {
"foo2": "bar2"
}
},
"spec": {
"type": "VirtualMachine",
"flavor": "cce.s2.small",
"version": "v1.19.8-r0",
"description": "this is a demo cluster",
"hostNetwork": {
"vpc": "23d3725f-6ffe-400e-8fb6-b4f9a7b3e8c1",
"subnet": "c90b3ce5-e1f1-4c87-a006-644d78846438"
},
"containerNetwork": {
"mode": "overlay_l2",
"cidr": "172.16.0.0/16"
},
"authentication": {
"mode": "rbac",
},
"kubeProxyMode": "iptables",
"billingMode": 0,
"extendParam": {
"clusterAZ": "multi_az"
}
}
}
Response¶
Response parameters:
Table 15 describes the response parameters.
Parameter | Type | Description |
---|---|---|
kind | String | API type. The value is fixed at Cluster and cannot be changed. |
apiVersion | String | API version. The value is fixed at v3 and cannot be changed. |
metadata | metadata object | Cluster metadata, which is a collection of attributes. |
spec | spec object | Detailed description of the cluster to be created. CCE creates or updates objects by defining or updating its spec. |
status | status object | Cluster status and jobID of the cluster creation job. |
Parameter | Type | Description |
---|---|---|
name | String | Cluster name. |
uid | String | Cluster ID. |
creationTimestamp | String | Time when the cluster was created. |
updateTimestamp | String | Time when the cluster was updated. |
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. |
annotations | Map<String,String> | Cluster annotations in the format of key-value pairs. "annotations": { "key1" : "value1", "key2" : "value2" }
Note
|
Parameter | Type | Description |
---|---|---|
category | String | Cluster category:
Note This parameter is valid in cluster of v1.17.17 or higher. |
type | String | Cluster type. VirtualMachine: The master node architecture is x86. |
flavor | String | Cluster flavor, which cannot be changed after the cluster is created.
Note
|
version | String | Cluster's baseline Kubernetes version. The latest version is recommended. |
platformVersion | String | Version of the CCE cluster platform, which is for viewing only and cannot be specified during cluster creation. The latest platform version corresponding to the cluster version is automatically selected during cluster creation. Value format: cce.X.Y
|
description | String | Cluster description. |
customSan | Array of strings | Custom SAN field in the server certificate of the cluster API server, which must comply with the SSL and X509 format specifications.
example: SAN 1: DNS Name=example.com SAN 2: DNS Name=www.example.com SAN 3: DNS Name=example.net SAN 4: IP Address=93.184.216.34 |
ipv6enable | Boolean | Whether the cluster supports IPv6 addresses. This field is supported in clusters of v1.25 and later versions. |
hostNetwork | hostNetwork object | Node network parameters. |
containerNetwork | containerNetwork object | Container network parameters. |
publicAccess | PublicAccess object | Cluster API access control. |
authentication | authentication object | Configurations of the cluster authentication mode. |
billingMode | Integer | Billing mode of a node. Note This field is not supported for the current version. |
masters | Array of MasterSpec objects | Advanced configurations of the master node. |
kubernetesSvcIpRange | String | Service CIDR block or the IP address range which the kubernetes clusterIp must fall within. This parameter is available only for clusters of v1.11.7 and later. |
kubeProxyMode | String | Service forwarding mode. Two modes are available:
|
az | String | AZ. This field is returned only for a query. |
extendParam | extendParam object | Extended fields in the format of key-value pairs. |
supportIstio | Boolean | Whether Istio is supported. Note This field is not supported for the current version. |
Parameter | Type | Description |
---|---|---|
vpc | String | ID of the VPC used to create a master node. The VPC ID is obtained from Creating a VPC and Subnet. |
subnet | String | Network ID of the subnet. The value is obtained from Creating a VPC and Subnet. |
SecurityGroup | String | Default worker node security group ID of the cluster. If specified, the cluster will be bound to the target security group. Otherwise, the system will automatically create a default worker node security group for you. The default worker node security group needs to allow access from certain ports to ensure normal communications. |
Parameter | Mandatory | Type | Description |
---|---|---|---|
eniSubnetId | Yes | String | IPv4 Subnet ID of the ENI container subnet. Currently, IPv6 is not supported. |
eniSubnetCIDR | Yes | String | ENI subnet CIDR block. |
Parameter | Type | Description |
---|---|---|
cidrs | Array of strings | Trustlist of network CIDRs that are allowed to access cluster APIs. You are advised to allow the traffic from VPC and container network CIDRs. By default, no trustlist is configured, and the value is ["0.0.0.0/0"]. Note This parameter is valid only when a cluster is created. |
Parameter | Type | Description |
---|---|---|
mode | String | Cluster authentication mode.
|
Parameter | Type | Description |
---|---|---|
availabilityZone | String | Availability Zone. "masters": [
{
"availabilityZone": "eu-de-01"
},
{
"availabilityZone": "eu-de-01"
},
{
"availabilityZone": "eu-de-02"
}
],
|
Parameter | Type | Description |
---|---|---|
clusterAZ | String | If you want to enable multiple AZs for the cluster, enter {"clusterAZ": "multi_az"}. Note Only HA clusters support multiple AZs. To be specific, this field can be configured only when the flavor field in Table 5 is set to cce.s2.small, cce.s2.medium, cce.s2.large, cce.t2.small, cce.t2.medium, or cce.t2.large. After multi-AZ deployment is enabled, the three master nodes of the cluster are distributed in different AZs. The cluster remains available even when one of the AZs is down. |
dssMasterVolumes | String | Whether the system and data disks of a master node use dedicated distributed storage. If this parameter is omitted or left unspecified, EVS disks are used by default. |
kubeProxyMode | String | Service forwarding mode. Two modes are available:
|
clusterExternalIP | String | EIP used to access the cluster. |
alpha.cce/fixPoolMask | String | Number of mask bits of the fixed IP address pool of the container network model. This field is supported only for the VPC network model (vpc-router). This parameter determines the number of container IP addresses that can be allocated to a node. The maximum number of pods that can be created on a node is decided by this parameter and maxPods set during node creation. The value is an integer ranging from 24 to 28. |
kubernetes.io/cpuManagerPolicy | String | Cluster CPU management policy. The value can be none or static. The default value is none.
|
upgradefrom | String | Reserved. This field is returned only for a query. |
Parameter | Type | Description |
---|---|---|
phase | String | Cluster status. Possible values:
|
jobID | String | ID of the cluster creation job. You can query job progress by job ID to keep updated on cluster creation progress. |
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. |
Example response:
"kind": "Cluster",
"apiVersion": "v3",
"metadata": {
"name": "test-create-cluster",
"uid": "d6a883a1-8529-11ea-8e34-0255ac101108",
"creationTimestamp": "2020-04-23 06:15:32.974281119 +0000 UTC",
"updateTimestamp": "2020-04-23 06:15:32.974281688 +0000 UTC",
"labels": {
"foo": "bar"
},
"annotations": {
"foo2": "bar2"
}
},
"spec": {
"type": "VirtualMachine",
"flavor": "cce.s2.small",
"version": "v1.17.9-r0",
"description": "this is a demo cluster",
"ipv6enable": false,
"hostNetwork": {
"vpc": "23d3725f-6ffe-400e-8fb6-b4f9a7b3e8c1",
"subnet": "c90b3ce5-e1f1-4c87-a006-644d78846438"
},
"containerNetwork": {
"mode": "overlay_l2",
"cidr": "172.16.0.0/16"
},
"eniNetwork": {},
"authentication": {
"mode": "rbac",
"authenticatingProxy": {}
},
"billingMode": 0,
"extendParam": {
"clusterAZ": "multi_az"
},
"kubernetesSvcIpRange": "10.247.0.0/16",
"kubeProxyMode": "iptables"
},
"status": {
"phase": "Creating",
"jobID": "d6bcbb0b-8529-11ea-8e34-0255ac101108"
}
}
Status Code¶
Table 25 describes the status code of this API.
Status Code | Description |
---|---|
201 | The job for creating a cluster is successfully delivered. |
For the description about error status codes, see Status Code.