Updated on 2025-08-06 GMT+08:00

Creating a Cluster

Function

This API is used to create a cluster.

The cluster must run in a VPC. Before creating a cluster, you need to create a VPC and obtain the VPC and subnet IDs.

This API is an asynchronous API. It takes 10 to 15 minutes to create a cluster.

Calling Method

For details, see Calling APIs.

URI

POST /v1.0/{project_id}/clusters

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. To obtain the value, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

cluster

Yes

CreateClusterInfo object

Definition

Cluster object.

Range

Non-null object.

Table 3 CreateClusterInfo

Parameter

Mandatory

Type

Description

node_type

Yes

String

Definition

Node flavor ID. To obtain the value, call the API for querying flavors and view the id field in the API response.

Constraints

N/A

Range

The value must be the flavor ID returned by the API for querying flavors.

Default Value

N/A

number_of_node

Yes

Integer

Definition

Number of nodes.

Constraints

N/A

Range

For a cluster, the value is from 3 to 256. For a hybrid data warehouse (standalone), the value is 1.

Default Value

N/A

subnet_id

Yes

String

Definition

Subnet ID, which is used for configuring the cluster network.

Constraints

N/A

Range

The value must be a subnet in the VPC ID.

Default Value

N/A

security_group_id

Yes

String

Definition

Security group ID, which is used for configuring the cluster network.

Constraints

N/A

Range

If this parameter is not left blank, it must be a valid security group ID. If this parameter is left blank, the system automatically creates a security group.

Default Value

null

vpc_id

Yes

String

Definition

VPC ID, which is used for configuring cluster network.

Constraints

N/A

Range

The value must be a valid VPC ID.

Default Value

N/A

availability_zone

No

String

Definition

AZ of the cluster.

Constraints

N/A

Range

The AZ code must be valid at the current region and visible to the current user.

Default Value

AZ code of the first available AZ.

port

No

Integer

Definition

Cluster database port.

Constraints

N/A

Range

8000 to 30000

Default Value

8000

name

Yes

String

Definition

Cluster name.

Constraints

The value must be unique. It must contain 4 to 64 characters and start with a letter. Only letters, digits, hyphens (-), and underscores (_) are allowed.

Range

4 to 64 characters

Default Value

8000

user_name

Yes

String

Definition

Administrator username for logging in to a GaussDB(DWS) cluster.

Constraints

  • Only lowercase letters, digits, and underscores (_) are allowed.

  • The value must start with a lowercase letter or an underscore (_).

  • The value can contain 1 to 63 characters.

  • The value cannot be a keyword of the GaussDB(DWS) database.

Range

1 to 63 characters

Default Value

dbadmin

user_pwd

Yes

String

Definition

Administrator password for logging in to a GaussDB(DWS) cluster.

Constraints

N/A

Range

The value can contain 12 to 32 characters.

The value can contain at least three types of the following characters: uppercase letters, lowercase letters, numbers, and special characters (~!?,.:;_(){}[]/<>@#%^&*+|\=-).

The value must be different from the username or the username spelled backwards.

Default Value

N/A

public_ip

No

PublicIp object

Definition

Public IP address. If the parameter is not specified, public connection is not used by default.

Constraints

N/A

Range

N/A

Default Value

null

number_of_cn

No

Integer

Definition

Number of CNs deployed.

Constraints

N/A

Range

2 to Number of cluster nodes. The maximum value is 20.

Default Value

3

enterprise_project_id

No

String

Definition

Enterprise project ID for a cluster. If this parameter is not specified, the default value 0 (indicating that the ID of the default enterprise project) is used.

Constraints

N/A

Range

N/A

Default Value

0

tags

No

Tags object

Definition

Tag. By default, no tags are specified for the cluster.

Constraints

N/A

Range

N/A

Default Value

null

Table 4 PublicIp

Parameter

Mandatory

Type

Description

public_bind_type

No

String

Definition

EIP binding type.

Constraints

N/A

Range

auto_assign

not_use

bind_existing

Default Value

null

eip_id

No

String

Definition

EIP ID.

Constraints

N/A

Range

N/A

Default Value

null

Table 5 Tags

Parameter

Mandatory

Type

Description

key

Yes

String

Definition

Tag key.

Constraints

N/A

Range

  • It can contain a maximum of 128 Unicode characters. It cannot be an empty string, and cannot start or end with a space.

  • It cannot contain the following characters: =*<>\,|/

  • Only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-) are allowed.

Default Value

N/A

value

Yes

String

Definition

Tag value.

Constraints

N/A

Range

  • The value can contain a maximum of 256 characters and can be an empty string. It cannot start or end with a space.

  • It cannot contain the following characters: =*<>\,|/

  • Only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-) are allowed.

Default Value

N/A

Response Parameters

Status code: 200

Table 6 Response body parameters

Parameter

Type

Description

cluster

Cluster object

Definition

Cluster object.

Range

N/A

Table 7 Cluster

Parameter

Type

Description

id

String

Definition

Cluster ID.

Range

N/A

Example Requests

Create a data warehouse cluster (AZ: az1.dc1. Node flavor: dws.m1.xlarge.ultrahigh. Nodes: 3. Database port: 8000. The public IP address, the security group ID, subnet ID, and VPC ID are configured.)

POST https://{Endpoint}/v1.0/89cd04f168b84af6be287f71730fdb4b/clusters

{
  "cluster" : {
    "node_type" : "dws.m1.xlarge.ultrahigh",
    "number_of_node" : 3,
    "subnet_id" : "374eca02-cfc4-4de7-8ab5-dbebf7d9a720",
    "security_group_id" : "dc3ec145-9029-4b39-b5a3-ace5a01f772b",
    "vpc_id" : "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574",
    "availability_zone" : "az1.dc1",
    "port" : 8000,
    "name" : "dws-1",
    "user_name" : "dbadmin",
    "user_pwd" : "Passw0rd!",
    "public_ip" : {
      "public_bind_type" : "auto_assign",
      "eip_id" : ""
    },
    "enterprise_project_id" : "aca4e50a-266f-4786-827c-f8d6cc3fbada"
  }
}

Example Responses

Status code: 200

Request for creating a cluster submitted.

{
  "cluster" : {
    "id" : "7d85f602-a948-4a30-afd4-e84f47471c15"
  }
}

Status Codes

Status Code

Description

200

Request for creating a cluster submitted.

400

Request error.

401

Authentication failed.

403

You do not have required permissions.

500

Internal server error.

503

Service unavailable.