Updated on 2024-12-02 GMT+08:00

Creating a Cluster (V2)

Function

This API is used to create a cluster with multiple node types (for example, ess, ess-cold, ess-client, and ess-master).

Calling Method

For details, see Calling APIs.

URI

POST /v2.0/{project_id}/clusters

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain the project ID and name, see Obtaining a Project ID and Name.

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

cluster

Yes

CreateClusterBody object

Cluster.

Table 3 CreateClusterBody

Parameter

Mandatory

Type

Description

name

Yes

String

Cluster name. It contains 4 to 32 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed. The value must start with a letter.

backupStrategy

No

CreateClusterBackupStrategyBody object

Whether to enable automatic snapshot creation.

An automatic snapshot creation policy can be enabled only if backupStrategy is not left blank.

roles

Yes

Array of CreateClusterRolesBody objects

Cluster information.

nics

Yes

CreateClusterInstanceNicsBody object

Subnet ID.

enterprise_project_id

No

String

Enterprise project ID. When creating a cluster, associate the enterprise project ID with the cluster. The value can contain a maximum of 36 characters. It is string 0 or in UUID format with hyphens (-). Value 0 indicates the default enterprise project.

tags

No

Array of CreateClusterTagsBody objects

Cluster tags.

availability_zone

Yes

String

Availability zone (AZ). You need to specify the AZ name.

By default, a single AZ is specified. If multiple AZs are specified, use commas (,) to separate them. For example, if three AZs are selected in the CN North-Beijing4 region, the value of availability_zone is cn-north-4a,cn-north-4b,cn-north-4c. If a single AZ is used, the value of availability_zone is empty by default.

NOTE:

Note

- If multiple AZs are selected, the name of each AZ must be unique, and the number of nodes must be greater than or equal to the number of AZs.

- If the number of nodes is a multiple of the number of AZs, the nodes are evenly distributed to each AZ.

- If the number of nodes is not a multiple of the number of AZs, the absolute difference between node quantity in any two AZs is 1 at most.

datastore

Yes

CreateClusterDatastoreBody object

Engine type. The value can be **elasticsearch**.

authorityEnable

No

Boolean

Whether to enable authentication. The value can be true or false. Authentication is disabled by default.

  • true: Authentication is enabled for the cluster.
  • false: Authentication is disabled for the cluster.
NOTE:

This parameter is supported in clusters 6.5.4 or later.

httpsEnable

No

Boolean

Whether communication is encrypted on the cluster. The value can be true or false. By default, communication encryption is disabled. When httpsEnable is set to true, authorityEnable must be set to true. true: Communication is encrypted for the cluster. false: Communication is not encrypted for the cluster. This parameter is supported in clusters 6.5.4 or later.

adminPwd

No

String

Password of the cluster user admin in security mode. This parameter is available only when authorityEnable was set to true during cluster creation.

  • The value can contain 8 to 32 characters.
  • The value must contain at least 3 of the following character types: uppercase letters, lowercase letters, numbers, and special characters ~!@#$%&*()-_=|[{}];:,<.>/?

publicIPReq

No

CreateClusterPublicIpReq object

Public network access information. This parameter is valid only when **httpsEnable** is set to **true**.

publicKibanaReq

No

CreateClusterPublicKibanaReq object

Kibana public network access information. This parameter is valid only when **authorityEnable** is set to **true**.

Table 4 CreateClusterBackupStrategyBody

Parameter

Mandatory

Type

Description

period

Yes

String

Time when a snapshot is generated every day. Snapshots can only be generated on the hour. The format is HH:mm z: HH:mm refers to the hour time and z refers to the time zone. For example, 00:00 GMT+08:00 and 01:00 GMT+08:00.

NOTE:

The default value is 00:00 GMT+08:00. When frequency is set to HOUR, you do not need to specify period. By default, snapshot creation starts from the next hour after the settings are successful.

frequency

No

String

Frequency of automatically creating snapshots.

NOTE:

The default value is DAY. If this parameter is set to HOUR, the scheduled task is executed every hour. If this parameter is set to DAY, the scheduled task is executed every day. If this parameter is set to SUN, MON, TUE, WED, THU, FRI or SAT, the scheduled task is executed at the specified day of every week. For example, SUN indicates that the task is executed once every Sunday. The number of retained snapshots depends on the execution frequency and indexes set in the automatic snapshot creation policy. If the execution interval is short or the index data volume is large, the number of retained automatic snapshots may not reach the preset value. Set this value based on actual conditions.

prefix

Yes

String

Prefix of automatically generated snapshots. It is manually configured. Enter up to 32 characters and start with a lowercase letter. Lowercase letters, numbers, hyphens (-), and underscores (_) are allowed.

keepday

Yes

Integer

Number of snapshots that can be retained. The value ranges from 1 to 90. Expired snapshots will be automatically deleted on the half hour. The deletion policy applies only to automated snapshots that are executed at the same frequency as the current automatic snapshot creation policy.

bucket

No

String

Name of the OBS bucket used for backup.

basePath

No

String

Storage path of the snapshot in the OBS bucket.

agency

No

String

Agency name. You can create an agency to allow CSS to call other cloud services.

NOTE:

If none of the bucket, basePath, and agency parameters are specified, the system will automatically create an OBS bucket and an IAM agency. If the creation fails, you need to manually configure correct parameters.

Table 5 CreateClusterRolesBody

Parameter

Mandatory

Type

Description

flavorRef

Yes

String

Instance flavor. For details about the current instance flavor, see the name attribute in Obtaining the Instance Specifications List.

volume

Yes

CreateClusterInstanceVolumeBody object

Volume information.

type

Yes

String

  • **ess-master** indicates a master node.
  • **ess-client** indicates a client node.
  • **ess-cold** indicates a cold data node.
  • **ess** indicates a data node.

instanceNum

Yes

Integer

Number of instances.

  • If **ess** is selected, you can set the value to 1 to 32.
    • If both **ess** and **ess-master** are selected, you can set the value to 1 to 200.
    • If both **ess** and **ess-client** are selected, you can set the value to 1 to 32.
    • If both **ess** and **ess-cold** are selected, you can set the value to 1 to 32.
  • If **ess-master** is selected, you can set the value to an odd number within 3 and 10.
  • If **ess-client** is selected, you can set the value to 1 to 32.
  • If **ess-cold** is selected, you can set the value to 1 to 32.
Table 6 CreateClusterInstanceVolumeBody

Parameter

Mandatory

Type

Description

volume_type

Yes

String

Volume type.

  • **COMMON**: common I/O
  • **HIGH**: high I/O
  • **ULTRAHIGH**: ultra-high I/O
  • ESSD: ultra-fast SSD

size

Yes

Integer

Volume size. The value must be greater than 0 and must be a multiple of 4 and 10. For details about the disk size, see the diskrange attribute in Obtaining the Instance Specifications List. Unit: GB.

NOTE:

The default volume size of an ess-master and ess-client node is 40 GB and cannot be changed.

Table 7 CreateClusterInstanceNicsBody

Parameter

Mandatory

Type

Description

vpcId

Yes

String

VPC ID, which is used for configuring cluster network.

netId

Yes

String

Subnet ID (network ID).

securityGroupId

Yes

String

Security group ID.

Table 8 CreateClusterTagsBody

Parameter

Mandatory

Type

Description

key

Yes

String

Tag key. The value can contain 1 to 36 characters. Only digits, letters, hyphens (-), and underscores (_) are allowed.

value

Yes

String

Tag value. The value can contain 0 to 43 characters. Only digits, letters, hyphens (-), and underscores (_) are allowed.

Table 9 CreateClusterDatastoreBody

Parameter

Mandatory

Type

Description

version

Yes

String

Version of the CSS cluster engine. For details, see Supported Cluster Versions.

type

Yes

String

Engine type. The value can be **elasticsearch**.

Table 10 CreateClusterPublicIpReq

Parameter

Mandatory

Type

Description

eip

Yes

CreateClusterPublicEip object

EIP bandwidth information.

elbWhiteListReq

Yes

CreateClusterElbWhiteList object

EIP whitelist.

publicBindType

Yes

String

Whether to automatically bind an EIP. Currently, only auto_assign is supported.

eipId

No

String

EIP ID.

Table 11 CreateClusterPublicEip

Parameter

Mandatory

Type

Description

bandWidth

Yes

CreateClusterPublicEipSize object

Public network bandwidth.

Table 12 CreateClusterPublicEipSize

Parameter

Mandatory

Type

Description

size

Yes

Integer

Bandwidth size.

Table 13 CreateClusterElbWhiteList

Parameter

Mandatory

Type

Description

enableWhiteList

Yes

Boolean

Whether public network access control is enabled.

whiteList

No

String

Public network access control whitelist. Separate the whitelisted network segments or IP addresses with commas (,), and each of them must be unique.

Table 14 CreateClusterPublicKibanaReq

Parameter

Mandatory

Type

Description

eipSize

Yes

Integer

Bandwidth size.

elbWhiteList

Yes

CreateClusterPublicKibanaElbWhiteList object

Kibana whitelist information.

Table 15 CreateClusterPublicKibanaElbWhiteList

Parameter

Mandatory

Type

Description

whiteList

Yes

String

Whitelist. Separate the whitelisted network segments or IP addresses with commas (,), and each of them must be unique.

enableWhiteList

Yes

Boolean

Whether Kibana access control is enabled.

Response Parameters

Status code: 200

Table 16 Response body parameters

Parameter

Type

Description

cluster

CreateClusterResp object

Cluster. For a pay-per-use cluster, only the **cluster** parameter is returned.

Table 17 CreateClusterResp

Parameter

Type

Description

id

String

Cluster ID.

name

String

Cluster name.

Example Requests

  • Example request for creating a pay-per-use cluster.
    {
      "cluster" : {
        "name" : "css-cluster",
        "backupStrategy" : {
          "period" : "16:00 GMT+08:00",
          "prefix" : "snapshot",
          "keepday" : 7,
          "frequency" : "DAY",
          "bucket" : "OBS-obsName",
          "basePath" : "css_repository/obs-path",
          "agency" : "css_obs_agency"
        },
        "roles" : [ {
          "flavorRef" : "ess.spec-4u8g",
          "volume" : {
            "volume_type" : "COMMON",
            "size" : 100
          },
          "type" : "ess",
          "instanceNum" : 1
        } ],
        "nics" : {
          "vpcId" : "{VPC ID}",
          "netId" : "{NET ID}",
          "securityGroupId" : "{Security group ID}"
        },
        "enterprise_project_id" : 0,
        "tags" : [ {
          "key" : "k1",
          "value" : "v1"
        }, {
          "key" : "k2",
          "value" : "v2"
        } ],
        "availability_zone" : "{Az code}",
        "datastore" : {
          "version" : "{cluster-version}",
          "type" : "elasticsearch"
        },
        "authorityEnable" : true,
        "httpsEnable" : true,
        "adminPwd" : "{password}",
        "publicIPReq" : {
          "eip" : {
            "bandWidth" : {
              "size" : 5
            }
          },
          "elbWhiteListReq" : {
            "enableWhiteList" : true,
            "whiteList" : "127.0.0.1"
          },
          "publicBindType" : "auto_assign",
          "eipId" : null
        },
        "publicKibanaReq" : {
          "eipSize" : 5,
          "elbWhiteList" : {
            "whiteList" : "127.0.0.1",
            "enableWhiteList" : true
          }
        }
      }
    }

Example Responses

Status code: 200

Request succeeded.

  • Example response for creating a pay-per-use cluster.
    {
      "cluster" : {
        "id" : "ef683016-871e-48bc-bf93-74a29d60d214",
        "name" : "ES-Test"
      }
    }

Status Codes

Status Code

Description

200

Request succeeded.

400

Invalid request.

Modify the request before retry.

409

The request could not be completed due to a conflict with the current state of the resource.

The resource that the client attempts to create already exists, or the update request fails to be processed because of a conflict.

412

The server does not meet one of the preconditions that the requester puts on the request.

Error Codes

See Error Codes.