• Cloud Container Engine

cce
  1. Help Center
  2. Cloud Container Engine
  3. API Reference 2.0
  4. API
  5. Cluster Management
  6. Creating a Container Cluster

Creating a Container Cluster

Function

This API is used to create a container cluster.

URI

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

Table 1 describes the parameters of the API.

Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Project ID.

Request

Request parameters:

Table 2 describes the request parameters.

Table 2 Parameter description

Parameter

Mandatory

Type

Description

kind

Yes

String

API type. The value is fixed to Cluster.

apiVersion

Yes

String

API version. The value is fixed to v3.

metadata

Yes

Table 3

-

spec

Yes

Table 4

-

Table 3 Data structure of the metadata field

Parameter

Mandatory

Type

Description

name

Yes

String

Cluster name.

NOTE:

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

labels

No

Map[string]string

Cluster label in the format of key/value.

annotations

No

Map[string]string

Cluster annotation in the format of key/value.

Table 4 Data structure of the spec field

Parameter

Mandatory

Type

Description

type

Yes

String

Cluster type.

  • VirtualMachine: a cluster of VM nodes.
  • BareMetal: a cluster of bare-metal nodes.

flavor

Yes

String

Cluster flavors. Currently supported flavors include:
  • cce.s1.small: small-scale single cluster (up to 50 nodes)
  • cce.s1.medium: medium-scale single cluster (up to 200 nodes)
  • cce.s1.large: large-scale single cluster (up to 1000 nodes)
  • cce.s2.small: small-scale HA cluster (up to 50 nodes)
  • cce.s2.medium: medium-scale HA cluster (up to 200 nodes)
  • cce.s2.large: large-scale HA cluster (up to 1000 nodes)
  • cce.t1.small: small-scale single physical machine cluster (up to 10 nodes)
  • cce.t1.medium: medium-scale single physical machine cluster (up to 100 nodes)
  • cce.t1.large: large-scale single physical machine cluster (up to 500 nodes)
  • cce.t2.small: small-scale HA physical machine cluster (up to 10 nodes)
  • cce.t2.medium: medium-scale HA physical machine cluster (up to 100 nodes)
  • cce.t2.large: large-scale HA physical machine cluster (up to 500 nodes)

version

No

String

Cluster version.

Value: v1.9.10-r2 or v1.11.7-r2.

NOTE:

If this parameter is not set, the latest version will be used.

description

No

String

Cluster description.

hostNetwork

Yes

Table 5

Node network parameters.

containerNetwork

Yes

Table 8

Container network parameters.

authentication

No

Table 6

Configurations of the cluster authentication mode.

billingMode

No

Integer

Billing mode of the cluster. Currently, only pay-per-use is supported.

NOTE:

To enable pay-per-use, set this parameter to 0. If this parameter is left unspecified, the value 0 will be used.

extendParam

No

String

Extended field. Format: Key-value pair.

NOTE:

In this field, you can configure multiple AZs and an EIP for the cluster. For details, see Table 7.

kubeProxMode

No

String

Service Forwarding Mode.

  • iptables: Traditional kube-proxy runs in iptables mode.
  • ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode is suitable for large-sized clusters.
Table 5 Data structure of the hostNetwork field

Parameter

Mandatory

Type

Description

vpc

Yes

String

ID of the VPC that is used to create a node.

subnet

Yes

String

ID of the subnet that is used to create a node.

highwaySubnet

No

NOTICE:

This parameter must be specified when you create a bare metal cluster.

String

ID of the high-speed network that is used to create a bare metal node. For details about how to obtain this value, see (Optional) Creating a High-Speed Network.

Table 6 Data structure of the authentication field

Parameter

Mandatory

Type

Description

mode

No

String

Cluster authentication.

Possible values: x509, rbac, and authenticating_proxy.

Default value: x509

Recommended value: rbac

Table 7 Data structure of the extendParam field

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

clusterExternalIP

No

String

EIP of a cluster.

Table 8 Data structure of the containerNetwork field

Parameter

Mandatory

Type

Description

mode

Yes

String

Network type.

Values:

  • overlay_l2

    An overlay_l2 network built for containers by using Open vSwitch (OVS).

  • underlay_ipvlan

    An underlay l2 network built for bare metal servers by using ipvlan.

  • vpc-router

    An underlay l2 network built for containers by using ipvlan and custom VPC routes.

cidr

No

String

Network segment of the container network.

Value range: 172.16.0.0/16 to 172.31.0.0/16

If a network segment conflict occurs, another network segment is automatically selected.

Example request:

  • Creating a VM cluster
    {
        "kind": "Cluster",
        "apiVersion": "v3",
        "metadata": {
            "name": "mycluster-demo",
            "labels": {
                "foo": "bar"
            },
            "annotations": {
                "foo2": "bar2"
            }
        },
        "spec": {
            "type": "VirtualMachine",
            "flavor": "cce.s1.small",
            "extendParam": {
                "clusterAZ": "multi_az",
                "clusterExternalIP": "10.185.72.122",
                "foo3": "bar3"
            },
            "version": "v1.11.7-r2",
            "description": "thisisademocluster",
            "hostNetwork": {
                "vpc": "a8cc62dc-acc2-47d0-9bfb-3b1d776c520b",
                "subnet": "6d9e5355-85af-4a89-af28-243edb700db6"
            },
            "containerNetwork": {
                "mode": "overlay_l2",
                "cidr": "172.16.0.0/16"
            },
            "authentication": {
                "mode": "x509"
            },
            "kubernetesSvcIpRange": "10.247.0.0/16",
            "kubeProxyMode": "iptables",
            "billingMode": 0
        }
    }
  • Creating a BMS cluster
    {
        "kind":"Cluster",
        "apiVersion":"v3",
        "metadata":{
            "name":"mycluster-baremetal",
            "labels":{
                "foo":"bar"
            },
            "annotations":{
                "foo2":"bar2"
            }
        },
        "spec":{
            "type":"BareMetal",
            "flavor":"cce.t1.small",
            "version":"v1.11.7-r2",
            "description":"this is a demo cluster",
            "hostNetwork":{
                "vpc":"09f9ee41-6a1e-475b-977b-a16adf0b14c5",
                "subnet":"2ca132cd-cddf-4c01-9abc-373610c8d5f6",
                "highwaySubnet":"a95d96e3-1f13-442a-8f06-f9cb4211eaa4"
            },
            "containerNetwork":{
                "mode":"underlay_ipvlan",
                "cidr":"10.1.0.0/16"
            },
            "billingMode":0,
            "extendParam":{
                "clusterExternalIP": "10.185.72.122",
                "foo": "bar"
            }
        }
    }

Response

Response parameters:

Table 9 describes the response parameters.

Table 9 Response parameters

Parameter

Type

Description

kind

String

API type. The value is fixed to Cluster.

apiVersion

String

API version. The value is fixed to v3.

metadata

Table 10

Metadata of a cluster.

spec

Table 11

Cluster parameters.

status

Table 13

Status of a cluster.

Table 10 Data structure of the metadata field

Parameter

Type

Description

name

String

Cluster name.

uid

String

Cluster ID.

creationTimestamp

String

Cluster creation timestamp.

updateTimestamp

String

Cluster update timestamp.

labels

String

Cluster label in the format of key/value.

annotations

String

Cluster annotation in the format of key/value.

Table 11 Data structure of the spec field

Parameter

Type

Description

type

String

Cluster type.

flavor

String

Cluster flavors. Currently supported flavors include:
  • cce.s1.small: small-scale single cluster (up to 50 nodes)
  • cce.s1.medium: medium-scale single cluster (up to 200 nodes)
  • cce.s1.large: large-scale single cluster (up to 1000 nodes)
  • cce.s2.small: small-scale HA cluster (up to 50 nodes)
  • cce.s2.medium: medium-scale HA cluster (up to 200 nodes)
  • cce.s2.large: large-scale HA cluster (up to 1000 nodes)
  • cce.t1.small: small-scale single physical machine cluster (up to 10 nodes)
  • cce.t1.medium: medium-scale single physical machine cluster (up to 100 nodes)
  • cce.t1.large: large-scale single physical machine cluster (up to 500 nodes)
  • cce.t2.small: small-scale HA physical machine cluster (up to 10 nodes)
  • cce.t2.medium: medium-scale HA physical machine cluster (up to 100 nodes)
  • cce.t2.large: large-scale HA physical machine cluster (up to 500 nodes)

version

String

Cluster version.

Value: v1.9.10-r2 or v1.11.7-r2.

NOTE:

If this parameter is not set, the latest version will be used.

description

String

Cluster description.

hostNetwork

Table 5

Node network parameters.

containerNetwork

Table 8

Container network parameters.

authentication

Table 12

Configurations of the cluster authentication mode.

billingMode

Integer

Billing mode of the cluster. Currently, only pay-per-use is supported.

extendParam

String

Extended field.

kubernetesSvcIpRange

String

Service CIDR block. Only clusters of Kubernetes v1.11.7 and later support this parameter.

kubeProxyMode

String

Service Forwarding Mode.

  • iptables: Traditional kube-proxy runs in iptables mode.
  • ipvs: Optimized kube-proxy mode with higher throughput and faster speed. This mode is suitable for large-sized clusters.
Table 12 Data structure of the authentication field

Parameter

Type

Description

mode

String

Cluster authentication.

Possible values: x509, rbac, and authenticating_proxy.

Default value: x509

Recommended value: rbac

Table 13 Data structure of the status field

Parameter

Type

Description

phase

String

Cluster status. The value can be Available, Unavailable, ScalingUp, ScalingDown, Creating, Deleting, Upgrading, Resizing, or Empty.

jobID

String

ID of the job for creating a cluster.

endpoint

Table 14

Access address of the kube-apiserver in the cluster.

Table 14 Data structure of the endpoint field

Parameter

Type

Description

internal

String

Internal network address.

external

String

External network address.

external_otc

String

Endpoint of the cluster to be accessed through API Gateway.

Example response:

{
    "kind": "Cluster",
    "apiVersion": "v3",
    "metadata": {
        "name": "mycluster-demo",
        "uid": "40c54866-38c5-11e9-b246-0255ac101413",
        "creationTimestamp": "2019-02-25 06:19:05.789461541 +0000 UTC",
        "updateTimestamp": "2019-02-25 06:19:05.789462592 +0000 UTC",
        "labels": {
            "foo": "bar"
        },
        "annotations": {
            "foo2": "bar2"
        }
    },
    "spec": {
        "type": "VirtualMachine",
        "flavor": "cce.s1.small",
        "version": "v1.11.7-r2",
        "description": "thisisademocluster",
        "hostNetwork": {
            "vpc": "a8cc62dc-acc2-47d0-9bfb-3b1d776c520b",
            "subnet": "6d9e5355-85af-4a89-af28-243edb700db6"
        },
        "containerNetwork": {
            "mode": "overlay_l2",
            "cidr": "172.16.0.0/16"
        },
        "authentication": {
            "mode": "x509"
        },
        "billingMode": 0,
        "extendParam": {
            "clusterAZ": "multi_az",
            "foo3": "bar3"
        },
        "kubernetesSvcIpRange": "10.247.0.0/16",
        "kubeProxyMode": "iptables"
    },
    "status": {
        "phase": "Creating",
        "jobID": "40e39973-38c5-11e9-b246-0255ac101413",
        "endpoints": {}
    }
}

Status Code

Table 15 describes the status code of the API.

Table 15 Status code

Status Code

Description

201

The job for creating a cluster is successfully delivered.

For details about error status codes, see Status Codes.