Updated on 2023-04-03 GMT+08:00

Creating a cluster

Function

This API is used to create a cluster.

URI

POST /v1.0/{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 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 object.

Table 3 CreateClusterBody

Parameter

Mandatory

Type

Description

instance

Yes

CreateClusterInstanceBody object

Instance.

datastore

Yes

CreateClusterDatastoreBody object

Search engine.

name

Yes

String

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

instanceNum

Yes

Integer

Number of clusters. The value range is 1 to 32.

backupStrategy

No

CreateClusterBackupStrategyBody object

Automatic snapshot creation policy, which is disabled by default.

The automatic snapshot creation policy is enabled only if backupStrategy is not left blank.

httpsEnable

No

Boolean

Whether communication is encrypted on the cluster. The value can be true or false. By default, communication encryption is disabled. If httpsEnable is set to true, authorityEnable must be set to true.

  • true: Communication is encrypted on the cluster.
  • false: Communication is not encrypted on the cluster.

This parameter is supported in clusters 6.5.4 or later.

authorityEnable

No

Boolean

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

  • true indicates that authentication is enabled for the cluster.
  • true indicates that authentication is enabled 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 mandatory only if authorityEnable is set to true.

  • The administrator password must meet the following requirements:
    • The password can contain 8 to 32 characters.
    • Passwords must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters (~!@#$%^&*()-_=+\|[{}];:,<.>/?).
  • Weak password verification is required for a security cluster. You are advised to set a strong password.

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

Table 4 CreateClusterInstanceBody

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. If flavorRef is set to a local disk flavor, leave this parameter blank. Currently, the following local disk flavors are supported:

  • ess.spec-i3small
  • ess.spec-i3medium
  • ess.spec-i3.8xlarge.8
  • ess.spec-ds.xlarge.8
  • ess.spec-ds.2xlarge.8
  • ess.spec-ds.4xlarge.8

nics

Yes

CreateClusterInstanceNicsBody object

Subnet ID.

availability_zone

No

String

AZ. A single AZ is created when this parameter is not specified.

Separate multiple AZs with commas (,), for example, az1,az2. AZs must be unique. 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.

Table 5 CreateClusterInstanceVolumeBody

Parameter

Mandatory

Type

Description

volume_type

Yes

String

Volume type.

  • COMMON: common I/O
  • HIGH: high I/O
  • ULTRAHIGH: Ultra-high I/O

size

Yes

Integer

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

Table 6 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 7 CreateClusterDatastoreBody

Parameter

Mandatory

Type

Description

version

Yes

String

Esasticsearch engine version. For details, see CSS Supported Cluster Versions.

type

Yes

String

Engine type. Currently, only Elasticsearch is supported.

Table 8 CreateClusterBackupStrategyBody

Parameter

Mandatory

Type

Description

period

Yes

String

Time when a snapshot is automatically created every day. Snapshots can only be created on the hour. The time format is the time followed by the time zone, specifically, HH:mm z. In the format, 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.

prefix

Yes

String

Prefix of a snapshot that is automatically created, which is manually entered. Enter up to 32 characters and start with a lowercase letter. Lowercase letters, digits, hyphens (-), and underscores (_) are allowed.

keepday

Yes

Integer

Number of days for which automatically created snapshots are retained. Value range: 1 to 90

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

IAM agency used to access OBS.

If none of the bucket, basePath, and agency parameters are specified, the system automatically creates an OBS bucket and an IAM agency. Otherwise, the configured parameters will take effect.

Table 9 CreateClusterTagsBody

Parameter

Mandatory

Type

Description

key

Yes

String

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

value

Yes

String

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

Response Parameters

Status code: 200

Table 10 Response body parameters

Parameter

Type

Description

cluster

CreateClusterClusterResponse object

Cluster object. [For a pay-per-use cluster, only the cluster parameter is returned.] (tag:hc,hws)

Table 11 CreateClusterClusterResponse

Parameter

Type

Description

id

String

Cluster ID.

name

String

Cluster name

Example Requests

Example request for creating a pay-per-use cluster.

POST /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters

{
  "cluster" : {
    "name" : "ES-Test",
    "datastore" : {
      "version" : "x.x.x",
      "type" : "elasticsearch"
    },
    "backupStrategy" : {
      "period" : "16:00 GMT+08:00",
      "prefix" : "snapshot",
      "keepday" : 7
    },
    "instanceNum" : 4,
    "instance" : {
      "flavorRef" : "ess.spec-XuXg",
      "volume" : {
        "volume_type" : "COMMON",
        "size" : 100
      },
      "nics" : {
        "vpcId" : "fccd753c-xxx-xxx-xxx-5ddf78d1a1b2",
        "netId" : "af1c65ae-xxx-xxx-xxx-81d6b365c9f1",
        "securityGroupId" : "7e3fed21-xxx-xxx-xxx-34e51124f614"
      },
      "availability_zone" : "xx-xxx-xx"
    },
    "httpsEnable" : true,
    "authorityEnable" : true,
    "adminPwd" : "xxxxxx",
    "enterprise_project_id" : "3e1c74a0-xxx-xxx-xxxx-c6b9e46cf81b",
    "tags" : [ {
      "key" : "k1",
      "value" : "v1"
    }, {
      "key" : "k2",
      "value" : "v2"
    } ]
  }
}

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 did not meet one of the preconditions contained in the request.

Error Codes

See Error Codes.