Creating an Instance

Updated on 2024-09-11 GMT+08:00

Online Debugging

CLI Examples

View PDF

Function

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

Learn how to authorize and authenticate it.
Obtain the required region and endpoint.

URI

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

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID.
instance_id	Yes	String	GaussDB(for MySQL) instance ID, which is compliant with the UUID format.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	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.
X-Language	No	String	Request language type. The default value is en-us. Values: en-us zh-cn

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
name	Yes	String	ClickHouse instance name. The value: Consists of 4 to 64 characters. Must start with a letter and can contain letters, digits, hyphens (-), and underscores (_). Cannot contain other special characters.
engine	Yes	ClickHouseEngineInfo object	Engine information.
ha	Yes	ha object	Deployment information.
flavor_id	Yes	String	Node specification ID. To obtain this value, see Querying Specifications of an HTAP Instance.
db_root_pwd	Yes	String	Password of user root. The value: Consists of 8 to 32 characters. Must contain at least three types of the following characters: uppercase letters, lowercase letters, digits, and special characters (~!@#/%^*-_=+?,)
az_mode	Yes	String	AZ type. Values: single: single AZ double: multiple AZs
volume	Yes	volume object	Storage specifications.
az_code	Yes	String	AZ code. If mode in ha is set to Ha, enter multiple AZs and separate them with commas (,), for example, cn-southwest-244b,cn-southwest-244a.
time_zone	No	String	Time zone. The default value is the time zone of the GaussDB(for MySQL) instance.
tags_info	Yes	tags_info object	Tag value.
pay_info	No	pay_info object	Payment information.

**Table 4** ClickHouseEngineInfo
Parameter	Mandatory	Type	Description
type	Yes	String	DB engine type. Only click-house is supported.
version	Yes	String	Database version with only one digit. To obtain this value, see Querying HTAP Engine Resources.

**Table 5** ha
Parameter	Mandatory	Type	Description
mode	Yes	String	Deployment mode. Values: Single: single-node Ha: primary/standby

**Table 6** volume
Parameter	Mandatory	Type	Description
io_type	Yes	String	Disk I/O type. Values: SSD: ultra-high I/O ESSD: extreme SSD
capacity_in_gb	Yes	Integer	Disk capacity. Value range: 50 GB to 32,000 GB.

**Table 7** tags_info
Parameter	Mandatory	Type	Description
sys_tags	Yes	Array of sys_tags objects	System tags.

**Table 8** sys_tags
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key.
value	Yes	String	Tag value.

**Table 9** pay_info
Parameter	Mandatory	Type	Description
pay_model	No	String	Billing mode. The default value is 0. Values: Values: 0: pay-per-use billing 1: yearly/monthly billing
order_id	No	String	Yearly/monthly order ID.
period	No	Integer	Yearly/monthly subscription period.
period_type	No	Integer	Subscription period type. Values: 2: monthly 3: yearly
is_auto_renew	No	Integer	Whether to automatically renew the yearly/monthly subscription. Values: 1: auto-renewal enabled 0: auto-renewal disabled

Response Parameters

Status code: 202

**Table 10** Response body parameters
Parameter	Type	Description
instance	CreateChInstanceInfo object	DB instance information.
job_id	String	Job ID.

**Table 11** CreateChInstanceInfo
Parameter	Type	Description
id	String	Instance ID.
az_code	String	AZ.
az_mode	String	AZ type. Values: single: single AZ double: multiple AZs
name	String	Instance name.
engine	ClickHouseEngineInfo object	Engine information.
vpc_id	String	VPC ID.
security_group_id	String	Security group ID.
subnet_id	String	Subnet ID.
db_user	String	Database user.
port	Integer	Database port. Value range: 0–65535.
ha_mode	String	Deployment mode. Values: Single: single-node Ha: primary/standby
pay_info	pay_info object	Billing information.
ssl_option	Boolean	Whether to enable SSL.
status	String	Instance status. Values: creating normal abnormal createfailed deleted
region	String	Region where the instance is deployed.
tags_info	tags_info object	Instance tags.

**Table 12** ClickHouseEngineInfo
Parameter	Type	Description
type	String	DB engine type. Only click-house is supported.
version	String	Database version with only one digit. To obtain this value, see Querying HTAP Engine Resources.

**Table 13** pay_info
Parameter	Type	Description
pay_model	String	Billing mode. The default value is 0. Values: Values: 0: pay-per-use billing 1: yearly/monthly billing
order_id	String	Yearly/monthly order ID.
period	String	Yearly/monthly subscription period.
period_type	String	Subscription period type. Values: 2: monthly 3: yearly
is_auto_renew	String	Whether to automatically renew the yearly/monthly subscription. Values: 1: auto-renewal enabled 0: auto-renewal disabled

**Table 14** tags_info
Parameter	Type	Description
tags	Array of tags objects	User tags.
sys_tags	Array of sys_tags objects	System tags.

**Table 15** tags
Parameter	Type	Description
key	String	Tag key.
value	String	Tag value.

**Table 16** sys_tags
Parameter	Type	Description
key	String	Tag key.
value	String	Tag value.

Status code: 400

**Table 17** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 500

**Table 18** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Request

Creating a ClickHouse instance

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

{
  "name" : "htap-cfd5",
  "engine" : {
    "type" : "click-house",
    "version" : "1"
  },
  "ha" : {
    "mode" : "Single"
  },
  "flavor_id" : "b44cfde6-d250-313c-8d7a-cd216f071658",
  "db_root_pwd" : "Rds_1234",
  "az_mode" : "single",
  "volume" : {
    "io_type" : "ESSD",
    "capacity_in_gb" : 40
  },
  "az_code" : "cn-southwest-244a",
  "time_zone" : "UTC+08:00",
  "tags_info" : {
    "sys_tags" : [ {
      "key" : "_sys_enterprise_project_id",
      "value" : "0"
    } ]
  }
}

Example Response

Status code: 202

Success.

{
    "instance": {
        "id": "2cdec02d8c4a4c88aecae08684dd8076in16",
        "az_code": "cn-southwest-244a",
        "az_mode": "double",
        "name": "htap-cfd5",
        "engine": {
            "type": "click-house",
            "version": "1"
        },
        "vpc_id": "467f1291-994f-4d3a-9db6-d4c563218df5",
        "security_group_id": "3dc780b1-9d92-4850-9b98-be248e1b5962",
        "subnet_id": "d99cd68c-0067-436d-869e-d32e902d0074",
        "db_user": "root",
        "port": null,
        "ha_mode": "Single"
        "pay_info": {
            "pay_model": "0",
            "order_id": null,
            "period": null,
            "period_type": null,
            "is_auto_renew": null,
        },
        "ssl_option": false,      
        "status": "creating",
        "region": "cn-southwest-244",
        "tags_info": {
            "tags": [],
            "sys_tags": [
                {
                    "key": "_sys_enterprise_project_id",
                    "value": "0"
                }
            ]
        }
    },
    "job_id": "76078f0b-5162-45c8-b95f-4c1afd37536c",
}