Updated on 2025-10-21 GMT+08:00

Creating a StarRocks Instance

Function

This API is used to create a StarRocks instance. Before calling this API:

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependency

    gaussdbformysql:htapInstance:create

    Write

    instance *

    • g:EnterpriseProjectId

    • g:ResourceTag/<tag-key>

    gaussdb:htapInstance:create

    -

URI

POST /v3/{project_id}/instances/{instance_id}/starrocks

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID of a tenant in a region.

To obtain this value, see Obtaining a Project ID.

Constraints

N/A

Range

The value contains 32 characters. Only letters and digits are allowed.

Default Value

N/A

instance_id

Yes

String

Definition

TaurusDB instance ID, which is compliant with the UUID format.

Constraints

N/A

Range

The value contains 36 characters with a suffix of in07. Only letters and digits are allowed.

Default Value

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition

User token. To obtain this value, call the IAM API for obtaining a user token.

The value of X-Subject-Token in the response header is the token value.

Constraints

N/A

Range

N/A

Default Value

N/A

Content-Type

Yes

String

Definition

Content type.

Constraints

N/A

Range

application/json

Default Value

application/json

X-Language

No

String

Definition

Request language type.

Constraints

N/A

Range

  • en-us

  • zh-cn

Default Value

en-us

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Definition

Instance name. Instances of the same type can have the same name under the same tenant.

Constraints

N/A

Range

The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed. Chinese names are not supported.

Default Value

N/A

engine

Yes

engine object

Definition

Engine information.

Constraints

N/A

ha

Yes

ha object

Definition

Deployment information.

Constraints

N/A

fe_flavor_id

Yes

String

Definition

Specification ID of the frontend node. You can call the API Querying Specifications of an HTAP Instance to obtain the value. id in the response is the desired ID.

Constraints

N/A

Range

N/A

Default Value

N/A

be_flavor_id

Yes

String

Definition

Specification ID of the backend node. You can call the API Querying Specifications of an HTAP Instance to obtain the value. id in the response is the desired ID.

Constraints

N/A

Range

N/A

Default Value

N/A

db_root_pwd

Yes

String

Definition

Database password.

Constraints

N/A

Range

The password consists of 8 to 32 characters and contains at least three types of the following: uppercase letters, lowercase letters, digits, and special characters (~!@#$%^*-_=+?,()&|.). You are advised to enter a strong password to improve security and prevent security risks such as brute force cracking. If you enter a weak password, the system automatically determines that the password is invalid.

Default Value

N/A

fe_count

Yes

Integer

Definition

Number of frontend nodes.

Constraints

N/A

Range

  • The value is fixed to 1 for a single-node instance.

  • For a cluster instance, the value ranges from 3 to 10.

Default Value

N/A

be_count

Yes

Integer

Definition

Number of backend nodes.

Constraints

N/A

Range

  • The value is fixed to 1 for a single-node instance.

  • For a cluster instance, the value ranges from 3 to 10.

Default Value

N/A

az_mode

Yes

String

Definition

AZ mode.

Range

Currently, only single AZ is supported.

fe_volume

Yes

fe_volume object

Definition

Storage of the frontend node.

Constraints

N/A

be_volume

Yes

be_volume object

Definition

Storage of the backend node.

Constraints

N/A

az_code

Yes

String

Definition

AZ code.

Constraints

N/A

time_zone

No

String

Definition

Time zone.

Range

The default time zone is UTC+08:00.

tags_info

Yes

tags_info object

Definition

Tag information.

Constraints

N/A

security_group_id

No

String

Definition

Security group ID. By default, the value is the same as the ID of the security group associated with the TaurusDB instance.

Range

N/A

pay_info

No

pay_info object

Definition

Payment information.

Constraints

This parameter is mandatory for yearly/monthly billing.

region_code

No

String

Definition

AZ.

Constraints

This parameter is mandatory for yearly/monthly billing.

Range

N/A

Default Value

N/A

Table 4 engine

Parameter

Mandatory

Type

Description

type

Yes

String

Definition

Engine type.

Constraints

N/A

Range

Only StarRocks is supported.

Default Value

N/A

version

Yes

String

Definition

Major version number of the engine. To obtain this value, see Querying HTAP Engine Resources.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 5 ha

Parameter

Mandatory

Type

Description

mode

Yes

String

Definition

Deployment mode.

Constraints

N/A

Range

  • Single: single-node deployment

  • Cluster: cluster deployment

Default Value

N/A

Table 6 fe_volume

Parameter

Mandatory

Type

Description

io_type

Yes

String

Definition

Storage type. Obtain the value from the message returned by Querying HTAP Engine Resources.

Constraints

N/A

capacity_in_gb

Yes

Integer

Definition

Storage space, in GB.

Constraints

Increment: 10 GB

Range

50–1000

Default Value

N/A

Table 7 be_volume

Parameter

Mandatory

Type

Description

io_type

Yes

String

Definition

Storage type. Obtain the value from the message returned by Querying HTAP Engine Resources.

Constraints

N/A

capacity_in_gb

Yes

Integer

Definition

Storage space, in GB.

Constraints

Increment: 10 GB

Range

50–1000

Default Value

N/A

Table 8 tags_info

Parameter

Mandatory

Type

Description

sys_tags

Yes

Array of sys_tags objects

System tags.

Table 9 sys_tags

Parameter

Mandatory

Type

Description

key

Yes

String

Tag key.

value

Yes

String

Tag value.

Table 10 pay_info

Parameter

Mandatory

Type

Description

pay_model

No

String

Definition

Billing mode. The default value is 0. This parameter is mandatory for yearly/monthly billing.

Range

  • 0: pay-per-use

  • 1: yearly/monthly

period

No

String

Yearly/monthly subscription period. This parameter is mandatory for yearly/monthly billing.

period_type

No

String

Definition

Subscription period type. This parameter is mandatory for yearly/monthly billing.

Range

  • 2: monthly

  • 3: yearly

is_auto_renew

No

String

Definition

Whether to automatically renew the yearly/monthly subscription. This parameter is mandatory for yearly/monthly billing.

Range

  • 1: auto-renewal enabled

  • 0: auto-renewal disabled

Response Parameters

Status code: 201

Table 11 Response body parameters

Parameter

Type

Description

instance

instance object

Instance information.

job_id

String

Workflow ID.

Table 12 instance

Parameter

Type

Description

id

String

StarRocks instance ID, which is compliant with the UUID format.

az_code

String

AZ code.

az_mode

String

Definition

AZ mode.

Range

single: single AZ

multi: multiple AZs

name

String

Instance name.

engine

engine object

Engine information.

vpc_id

String

VPC ID.

security_group_id

String

Security group ID.

sub_net_id

String

Subnet ID.

db_user

String

Database user. The default value is root.

port

Integer

Database port number. The default value is 3306.

ha_mode

String

Deployment mode.

pay_info

pay_info object

Billing information.

enable_ssl

Boolean

Whether to enable SSL.

status

String

Instance status.

region

String

Region where the instance is deployed.

tags_info

tags_info object

Instance tags.

Table 13 engine

Parameter

Type

Description

type

String

Engine type.

version

String

Major version number of the engine.

Table 14 pay_info

Parameter

Type

Description

pay_model

String

Definition

Billing mode.

Range

  • 0: pay-per-use

  • 1: yearly/monthly

Default Value

StarRocks instances support only pay-per-use billing. The default value is 0.

order_id

String

Yearly/monthly order ID.

period

String

Yearly/monthly subscription period.

period_type

String

Subscription period type.

is_auto_renew

String

Whether to automatically renew the yearly/monthly subscription.

Table 15 tags_info

Parameter

Type

Description

tags

Array of tags objects

User tags. This parameter is left blank by default.

sys_tags

Array of sys_tags objects

System tags.

Table 16 tags

Parameter

Type

Description

key

String

Tag key.

value

String

Tag value.

Table 17 sys_tags

Parameter

Type

Description

key

String

Tag key.

value

String

Tag value.

Status code: 400

Table 18 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 19 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Request

Creating a DB instance

POST https://{endpoint}/v3/23a50154cf494ec9ad6883979a12db0a/instances/40dc4c5729f14aad893e2dcd5baf6a15in07/starrocks

{
  "name" : "htap-ff64",
  "engine" : {
    "type" : "star-rocks",
    "version" : "3.1"
  },
  "ha" : {
    "mode" : "Single"
  },
  "fe_flavor_id" : "afef3bfd-ac7c-32e1-ba44-c388acbb196a",
  "be_flavor_id" : "de565db8-0a96-37ea-9388-61167624712c",
  "db_root_pwd" : "Test@123!",
  "fe_count" : 1,
  "be_count" : 1,
  "az_mode" : "single",
  "fe_volume" : {
    "io_type" : "SSD",
    "capacity_in_gb" : 50
  },
  "be_volume" : {
    "io_type" : "SSD",
    "capacity_in_gb" : 50
  },
  "az_code" : "az",
  "time_zone" : "UTC+08:00",
  "tags_info" : {
    "sys_tags" : [ {
      "key" : "_sys_enterprise_project_id",
      "value" : "0"
    } ]
  }
}

Example Response

Status code: 201

Success.

{
  "instance" : {
    "id" : "590031445ef845bb912d7fc8243db80cin17",
    "az_code" : "az1",
    "az_mode" : "single",
    "name" : "htap-ff64",
    "engine" : {
      "type" : "star-rocks",
      "version" : "3.1"
    },
    "vpc_id" : "d5a1a29b-1476-490f-9682-c1a59593e7b0",
    "security_group_id" : "967a0ac2-3cae-4e57-a49a-d0f6ff07dcc1",
    "sub_net_id" : "2ce0bc80-bfc5-4d5e-9b78-a7f91572e03b",
    "db_user" : "root",
    "port" : 3306,
    "ha_mode" : "Single",
    "pay_info" : {
      "pay_model" : "0",
      "order_id" : null,
      "period" : null,
      "period_type" : null,
      "is_auto_renew" : null
    },
    "enable_ssl" : false,
    "status" : "creating",
    "region" : "az",
    "tags_info" : {
      "tags" : [ ],
      "sys_tags" : [ {
        "key" : "_sys_enterprise_project_id",
        "value" : "0"
      } ]
    }
  },
  "job_id" : "cf0b7506-1505-450f-9d95-ce9d93b6b5c3"
}

Status Code

For details, see Status Codes.

Error Code

For details, see Error Codes.