Creating a DB Instance (v5)
Function
This API is derived from the API for creating a DB instance (v3.1). The Subscription-Agency field is added to the request header of the API. This field is only available when a shared key is used to create a yearly/monthly GaussDB instance. Before calling this API:
- Learn how to authenticate this API.
- Obtain the required region and endpoint.
Constraints
- The current API supports only the new IAM plane authentication.
- When using a shared KMS key to create a yearly/monthly instance, you need to create an agency for the Billing service and authorize the system policy ServicePolicyForGaussDBFulfillment to the agency. You can obtain the agency URN in the format of "iam::{account_id}:agency:{agency_name}". When calling this API, you add the Subscription-Agency header to the request and set its value to the agency URN.
URI
Name |
Mandatory |
Description |
---|---|---|
project_id |
Yes |
Definition Project ID of a tenant in a region. To obtain the value, see Obtaining a Project ID. Constraints N/A Range The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A |
Request Parameters
Name |
Mandatory |
Type |
Description |
---|---|---|---|
name |
Yes |
String |
Definition Instance name. Instances of the same type can have same names under the same tenant. Constraints N/A Range The name can contain 4 to 64 characters and must start with a letter. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed. Default Value N/A |
datastore |
Yes |
Object |
Definition Database information. For details, see Table 3. Constraints N/A |
ha |
Yes |
Object |
Definition Instance deployment model. For details, see Table 4. Constraints N/A |
configuration_id |
No |
String |
Definition Parameter template ID. Constraints N/A Range N/A Default Value If this parameter is not specified, the default parameter template is used and this parameter is not returned in the response body. |
port |
No |
String |
Definition Port for applications to access the database. Constraints The following ports are not allowed: 2378, 2379, 2380, 4999, 5000, 5999, 6000, 6001, 8097, 8098, 12016, 12017, 20049, 20050, 21731, 21732, 32122, 32123, and 32124. Range 1024–39998 Default Value 8000 |
password |
Yes |
String |
Definition Database password. Constraints N/A Range Contain 8 to 32 characters, including at least three of the following: uppercase letters, lowercase letters, digits, and special characters. Supported special characters: ~!@#%^*-_=+?, A strong password helps improve security and mitigate potential threats like brute force attacks. Default Value N/A |
backup_strategy |
No |
Object |
Definition Backup policy. For details, see Table 5. Constraints N/A |
enterprise_project_id |
No |
String |
Definition Enterprise project ID. For details, see id in the enterprise_project field data structure table in Querying Enterprise Projects of Enterprise Management API Reference. Constraints This parameter is suitable only for enterprise tenants. Range N/A Default Value N/A |
disk_encryption_id |
No |
String |
Definition ID of the key used for disk encryption. For details about key grant, see Creating a Grant in the Data Encryption Workshop User Guide. Constraints N/A Range N/A Default Value It is left blank by default. |
flavor_ref |
Yes |
String |
Definition Specification code. To obtain its value, see the spec_code field in Querying Instance Specifications. Constraints The value cannot be left blank. Range N/A Default Value N/A |
volume |
Yes |
Object |
Definition Volume information. For details, see Table 6. Constraints N/A |
region |
Yes |
String |
Definition Region ID. For details, see Regions and Endpoints. Constraints The value cannot be left blank. Range N/A Default Value N/A |
availability_zone |
Yes |
String |
Definition AZ ID. Constraints The value cannot be left blank. Range You can specify one or multiple AZs to deploy a GaussDB instance. Use commas (,) to separate AZs. The AZ ID can be obtained from the response returned after the API Querying Instance Specifications is called. Default Value N/A |
vpc_id |
Yes |
String |
Definition VPC ID. To obtain this parameter value, use either of the following methods:
Constraints N/A Range N/A Default Value N/A |
subnet_id |
Yes |
String |
Definition Network ID of the subnet. To obtain this parameter value, use either of the following methods:
Constraints N/A Range N/A Default Value N/A |
security_group_id |
Yes |
String |
Definition Security group which the instance is associated with. To obtain this parameter value, use either of the following methods: If you do not need to specify a security group, contact customer service.
Constraints N/A Range N/A Default Value N/A |
charge_info |
No |
Object |
Definition Billing mode, which can be pay-per-use or yearly/monthly. For details, see Table 7. Constraints N/A |
time_zone |
No |
String |
Definition UTC time zone. Constraints N/A Range
Default Value UTC time for GaussDB in the international website |
sharding_num |
No |
Integer |
Definition Number of shards. Constraints This parameter is available only for distributed instances. Range 1–256 Default Value N/A |
coordinator_num |
No |
Integer |
Definition Number of CNs. Constraints This parameter is available only for distributed instances. The number of CNs cannot exceed twice the number of shards. Range 1~256 Default Value N/A |
replica_num |
No |
Integer |
Definition Number of replicas. Constraints N/A Range The value can be 3. Default Value 3 |
enable_force_switch |
No |
Boolean |
Definition Whether to enable the function of forcibly promoting a standby node to primary.
NOTE:
If the primary node fails, this function enables a standby node to be forcibly promoted to primary to provide services, ensuring the instance availability. When an instance is faulty, a forcible switchover enables the instance to run normally as soon as possible at the cost of losing some data. This is an escape method used when the instance is unavailable. Constraints This function is available only for instances of version 1.2.2 or later. Range
Default Value false |
enable_single_float_ip |
No |
Boolean |
Definition Single private IP address policy. Constraints This parameter is only available for centralized instances of V2.0-3.207 or later. Range
Default Value false |
Name |
Mandatory |
Type |
Description |
---|---|---|---|
type |
Yes |
String |
Definition Database engine. Constraints N/A Range GaussDB (case-insensitive): indicates the GaussDB engine. Default Value GaussDB |
version |
No |
String |
Definition DB engine version. For details about the versions supported by GaussDB, see Querying DB Engine Versions. Constraints N/A Range N/A Default Value The latest version. |
Name |
Mandatory |
Type |
Description |
---|---|---|---|
mode |
Yes |
String |
Definition Instance type. Constraints N/A Range Deployment model. The value is case-insensitive and can be enterprise (enterprise edition) for distributed instances and centralization_standard for centralized instances. Default Value N/A |
consistency |
Yes |
String |
Definition Transaction consistency type. Constraints N/A Range The value is case-insensitive.
Default Value N/A |
replication_mode |
Yes |
String |
Definition Replication mode for the standby instance. Constraints N/A Range sync: indicates synchronous replication. Default Value sync |
instance_mode |
No |
String |
Definition Edition type of the instance to be created. Constraints N/A Range
Default Value enterprise |
Name |
Mandatory |
Type |
Description |
---|---|---|---|
start_time |
Yes |
String |
Definition Backup time window. Automated backups will be created during the backup time window. Constraints N/A Range The value cannot be left blank or negative. It must be a valid value in the hh:mm-HH:MM format. The current time is the UTC time.
Example value:
Default Value N/A |
keep_days |
No |
Integer |
Definition Retention days for specific backup files. Constraints N/A Range 1–36500. Default Value The default value is 7. |
Name |
Mandatory |
Type |
Description |
---|---|---|---|
type |
Yes |
String |
Definition Disk type. Constraints N/A Range
Default Value N/A |
size |
Yes |
Integer |
Definition Storage. For example, if this parameter is set to 40, 40 GB of storage is allocated to the created instance. Constraints N/A Range ECS-based deployment: The value ranges from (number_of_shards x 40 GB) to (number_of_shards x 24 TB) and must be a multiple of (number_of_shards x 4 GB). |
Name |
Mandatory |
Type |
Description |
---|---|---|---|
charge_mode |
Yes |
String |
Definition Billing mode. Constraints N/A Range
Default Value N/A |
period_type |
No |
String |
Definition Subscription type. Constraints This parameter is valid and mandatory only when charge_mode is set to prePaid. Range
Default Value N/A |
period_num |
No |
Integer |
Definition Subscription time. Constraints This parameter is valid and mandatory only when charge_mode is set to prePaid. Range
When a floating-point value is used, the value is automatically truncated to an integer. Default Value N/A |
is_auto_renew |
No |
Boolean |
Definition Whether automatic renewal is enabled for yearly/monthly instances. If you enable this function, the order will be automatically paid during the subscription renewal. The default renewal period is one month for monthly subscription and one year for yearly subscription. The renewal period can be configured as needed. Constraints N/A Range
Default Value false |
is_auto_pay |
No |
Boolean |
Definition Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment mode of automatic renewal. Constraints N/A Range
Default Value false |
Response Parameters
Name |
Type |
Description |
---|---|---|
instance |
Object |
Definition Instance information. For details, see Table 9. |
job_id |
String |
Definition ID of the job for creating an instance. This parameter is returned only when pay-per-use instances are created. Range N/A |
order_id |
String |
Definition Order ID. This parameter is returned only for the creation of yearly/monthly instances. Range N/A |
Name |
Type |
Description |
---|---|---|
id |
String |
Definition Instance ID. Range N/A |
name |
String |
Definition Instance name. Instances of the same type can have same names under the same tenant. Range The value must start with a letter and contain 4 to 64 characters. Only letters (case-insensitive), digits, hyphens (-), and underscores (_) are allowed. |
status |
String |
Definition Instance status. For example, BUILD indicates that the instance is being created. This parameter is returned only when pay-per-use instances are created. Range N/A |
datastore |
Object |
Definition Database information. For details, see Table 10. |
ha |
Object |
Definition Database deployment model. For details, see Table 11. |
replica_num |
Integer |
Definition Number of replicas. Range N/A |
port |
String |
Definition Database port, which is the same as the request parameter. Range N/A |
backup_strategy |
Object |
Definition Automated backup policy. For details, see Table 12. |
enterprise_project_id |
String |
Definition Project ID. Range N/A |
flavor_ref |
String |
Definition Specification code. Range N/A |
volume |
Object |
Definition Volume information. For details, see Table 13. |
region |
String |
Definition Region ID. Range N/A |
availability_zone |
String |
Definition AZ ID. Range N/A |
vpc_id |
String |
Definition VPC ID. Range N/A |
subnet_id |
String |
Definition Network ID of the subnet. Range N/A |
security_group_id |
String |
Definition Security group to which the instance belongs. Range N/A |
charge_info |
Object |
Definition Payment mode. For details, see Table 14. |
Name |
Type |
Description |
---|---|---|
type |
String |
Definition Database engine. Range GaussDB |
version |
String |
Definition DB engine version. Range N/A |
Name |
Type |
Description |
---|---|---|
mode |
String |
Definition Deployment model. The value is case-insensitive and can be and enterprise (enterprise edition) for distributed instances and centralization_standard for centralized instances. Range N/A |
replication_mode |
String |
Definition Replication mode for the standby instance. Range sync: The data is synchronized in synchronous mode. |
consistency |
String |
Definition (GaussDB reserved parameter) Instance consistency type. Range
|
consistency_protocol |
String |
Definition Replica consistency protocol. If it is not specified, the default value quorum is used. Range
|
Name |
Type |
Description |
---|---|---|
start_time |
String |
Definition Backup time window. Automated backups will be created during the backup time window. Range The value cannot be left blank. It must be a valid value in the hh:mm-HH:MM format. The current time is the UTC time.
Example value:
If backup_strategy in the request body is left blank, 02:00-03:00 is returned for start_time by default. |
keep_days |
Integer |
Definition Retention days for specific backup files. Range 1–732. If the backup_strategy field is not specified in the request body, keep_days in the response body is set to 7 days by default. |
Name |
Type |
Description |
---|---|---|
type |
String |
Definition Disk type. Range The value is case-sensitive.
|
size |
Integer |
Definition Storage. Range N/A |
Name |
Type |
Description |
---|---|---|
charge_mode |
String |
Definition Billing mode. Range postPaid: pay-per-use billing. prePaid: yearly/monthly billing. |
period_type |
String |
Definition Subscription type. This parameter is valid and mandatory only when charge_mode is set to prePaid. Range
|
period_num |
Integer |
Definition Subscription period. This parameter is valid and mandatory only when charge_mode is set to prePaid. Range If period_type is set to month, the value ranges from 1 to 9. If period_type is set to year, the value ranges from 1 to 3. |
is_auto_renew |
Boolean |
Definition Whether automatic renewal is enabled for yearly/monthly instances. If you enable this function, the order will be automatically paid during the subscription renewal. The default renewal period is one month for monthly subscription and one year for yearly subscription. The renewal period can be configured as needed. Range
|
is_auto_pay |
Boolean |
Definition Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment mode of automatic renewal. Range
|
Example Request
- Creating a distributed instance with the following configurations: independent deployment, yearly/monthly billing (1 year), DB engine V2.0-2.7, three AZs, three CNs, three shards, three replicas, and 8 vCPUs | 64 GB
POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.2/0483b6b16e954cb88930a360d2c4e663/instances { "name": "user1-v3-independent-02", "datastore": { "type": "GaussDB", "version": "V2.0-2.7" }, "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", "volume": { "type": "ULTRAHIGH", "size": 120 }, "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab", "region": "aaa", "availability_zone": "bbb,ccc,ddd", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", "backup_strategy": { "start_time": "17:00-18:00", "keep_days": 7 }, "charge_info": { "charge_mode": "prePaid", "period_type": "year", "period_num": 1 }, "password": "xxxxxx", "configuration_id": "", "enterprise_project_id": "", "time_zone": "UTC+08:00", "ha":{ "mode":"enterprise", "consistency":"strong", "replication_mode":"sync" }, "sharding_num": 3, "coordinator_num": 3, "replica_num": 3, "port":8000, "enable_force_switch":true }
- Creating a centralized instance with the following configurations: 1 primary + 2 standby deployment, pay-per-use billing, DB engine V2.0-2.7, single AZ, and 8 vCPUs | 64 GB
POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.2/0483b6b16e954cb88930a360d2c4e663/instances { "name": "user1-v3-ha-01", "datastore": { "type": "GaussDB", "version": "V2.0-2.7" }, "flavor_ref": "gaussdb.opengauss.ee.km1.2xlarge.arm8.ha", "volume": { "type": "ULTRAHIGH", "size": 120 }, "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab", "region": "aaa", "availability_zone": "bbb,bbb,bbb", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", "backup_strategy": { "start_time": "17:00-18:00", "keep_days": 7 }, "charge_info": { "charge_mode": "postPaid" }, "password": "xxxxxx", "configuration_id": "", "enterprise_project_id": "", "time_zone": "UTC+08:00", "ha": { "mode": "centralization_standard", "consistency": "strong", "replication_mode": "sync" }, "replica_num": 3, "port": 8000, "enable_force_switch": true }
- Creating a centralized instance with the following configurations: 1 primary + 2 standby deployment, yearly/monthly billing (1 year), DB engine V2.0-2.7, three AZs, and 8 vCPUs | 64 GB
POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.2/0483b6b16e954cb88930a360d2c4e663/instances { "name": "user1-v3-ha-02", "datastore": { "type": "GaussDB", "version": "V2.0-2.7" }, "flavor_ref": "gaussdb.opengauss.ee.km1.2xlarge.arm8.ha", "volume": { "type": "ULTRAHIGH", "size": 120 }, "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab", "region": "aaa", "availability_zone": "bbb,ccc,ddd", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", "backup_strategy": { "start_time": "17:00-18:00", "keep_days": 7 }, "charge_info": { "charge_mode": "prePaid", "period_type": "year", "period_num": 1 }, "password": "xxxxxx", "configuration_id": "", "enterprise_project_id": "", "time_zone": "UTC+08:00", "ha": { "mode": "centralization_standard", "consistency": "strong", "replication_mode": "sync" }, "replica_num": 3, "port": 8000, "enable_force_switch": true }
Example Response
- Distributed instance in the independent deployment (pay-per-use billing, DB engine V2.0-2.7, single AZ, 3 CNs, 3 shards, 3 replicas, 8 vCPUs and 64 GB) created.
{ "instance": { "id": "ad8cd1440aa94a02ae4580fcbebb3143in14", "name": "user1-v3-independent-01", "status": "BUILD", "datastore": { "type": "GaussDB", "version": "V2.0-2.7" }, "ha": { "mode": "Enterprise", "replication_mode": "sync", "consistency": "strong" }, "port": "8000", "volume": { "type": "ULTRAHIGH", "size": 120 }, "replica_num": 3, "region": "aaa", "backup_strategy": { "start_time": "17:00-18:00", "keep_days": 7 }, "enterprise_project_id": "0", "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", "availability_zone": "bbb,bbb,bbb", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", "charge_info": { "charge_mode": "postPaid" } }, "job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af" }
- Distributed instance (one-year yearly/monthly billing, DB engine V2.0-2.7, three AZs, three CNs, three shards, three replicas, 8 vCPUs and 64 GB) created.
{ "instance": { "id": "ad8cd1440aa94a02ae4580fcbebb3143in14", "name": "user1-v3-independent-02", "datastore": { "type": "GaussDB", "version": "V2.0-2.7" }, "ha": { "mode": "Enterprise", "replication_mode": "sync", "consistency": "strong" }, "port": "8000", "volume": { "type": "ULTRAHIGH", "size": 120 }, "replica_num": 3, "region": "aaa", "backup_strategy": { "start_time": "17:00-18:00", "keep_days": 7 }, "enterprise_project_id": "0", "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", "availability_zone": "bbb,bbb,bbb", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", "charge_info": { "charge_mode": "prePaid", "period_type": "year", "period_num": 1, "is_auto_renew": false, "is_auto_pay": false } }, "job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af" }
- Centralized instance with the following configurations created: HA (1 primary + 2 standby) deployment, pay-per-use billing, DB engine V2.0-2.7, single AZ, and 8 vCPUs | 64 GB
{ "instance": { "id": "ad8cd1440aa94a02ae4580fcbebb3143in14", "name": "user1-v3-ha-01", "status": "BUILD", "datastore": { "type": "GaussDB", "version": "V2.0-2.7" }, "ha": { "mode": "Enterprise", "replication_mode": "sync", "consistency": "strong" }, "port": "8000", "volume": { "type": "ULTRAHIGH", "size": 120 }, "region": "aaa", "replica_num": 3, "backup_strategy": { "start_time": "17:00-18:00", "keep_days": 7 }, "enterprise_project_id": "0", "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", "availability_zone": "bbb,bbb,bbb", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "charge_info": { "charge_mode": "postPaid" }, "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f" }, "job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af" }
- Centralized instance with the following configurations created: HA (1 primary + 2 standby) deployment, yearly/monthly billing (1 year), DB engine V2.0-2.7, three AZs, and 8 vCPUs | 64 GB
{ "instance": { "id": "ad8cd1440aa94a02ae4580fcbebb3143in14", "name": "user1-v3-ha-02", "datastore": { "type": "GaussDB", "version": "V2.0-2.7" }, "ha": { "mode": "Enterprise", "replication_mode": "sync", "consistency": "strong" }, "port": "8000", "volume": { "type": "ULTRAHIGH", "size": 120 }, "replica_num": 3, "region": "aaa", "backup_strategy": { "start_time": "17:00-18:00", "keep_days": 7 }, "enterprise_project_id": "0", "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", "availability_zone": "bbb,bbb,bbb", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", "charge_info": { "charge_mode": "prePaid", "period_type": "year", "period_num": 1, "is_auto_renew": false, "is_auto_pay": false } }, "job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af" }
Status Codes
- Normal
- Abnormal
For details, see Status Codes.
Error Codes
For details, see Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot