Creating a DB Instance (v5)_GaussDB

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

POST https://{Endpoint}/v5/{project_id}/instances

**Table 1** Parameter description
Name	Mandatory	Description
project_id	Yes	Explanation: Project ID of a tenant in a region. For details about how to obtain the value, see Obtaining a Project ID. Restrictions: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None

Request Parameters

**Table 2** Request parameters
Name	Mandatory	Type	Description
name	Yes	String	Instance name. Instances of the same type can have same names under the same tenant. The name must consist of 4 to 64 characters and start with a letter. It can contain only letters (case-sensitive), digits, hyphens (-), and underscores (_).
datastore	Yes	Object	Database information. For details, see Table 3.
ha	Yes	Object	Instance deployment model. For details, see Table 4.
configuration_id	No	String	Parameter template ID. 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	Port number used by the database to provide services for external systems, ranging from 1024 to 39998. It cannot be set to the default value 8000. 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.
password	Yes	String	Database password. The GaussDB database password must: Consist of 8 to 32 characters, including at least three of the following: uppercase letters, lowercase letters, digits, and special characters ~!@#$%^&*()-_=+\|[{}];:,<>/? Enter a strong password to improve security, preventing security risks such as brute force cracking.
backup_strategy	No	Object	Backup policy. For details, see Table 5.
enterprise_project_id	No	String	Enterprise project ID. This parameter is suitable only for enterprise tenants. For details, see id in the enterprise_project field data structure table in the section Querying Enterprise Projects of the Enterprise Management API Reference.
disk_encryption_id	No	String	Key ID for disk encryption. The default value is left blank. For details about key grant, see Creating a Grant in the Data Encryption Workshop User Guide.
flavor_ref	Yes	String	Specification code. The value cannot be left blank. To obtain its value, see the spec_code field in Querying Instance Specifications.
volume	Yes	Object	Volume information. For details, see Table 6.
region	Yes	String	Region ID. The value cannot be left blank. For details about how to obtain this parameter value, see Regions and Endpoints.
availability_zone	Yes	String	AZ ID. The value cannot be left blank. You can deploy a GaussDB instance in the same AZ or different AZs, and use commas (,) to separate AZs. The value cannot be left blank. For details about how to obtain this parameter value, see Regions and Endpoints.
vpc_id	Yes	String	VPC ID. To obtain this parameter value, use the following methods: Method 1: Log in to the VPC console and view the VPC ID in the VPC details page. Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs. Method 2: See the section "Querying VPCs" in the Virtual Private Cloud API Reference.
subnet_id	Yes	String	Network ID of the subnet. To obtain this parameter value, use either of the following methods: Method 1: Log in to VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page. Method 2: Query the subnet ID through the VPC API. For details, see Querying Subnets. Method 2: See the section "Querying Subnets" in the Virtual Private Cloud API Reference.
security_group_id	Yes	String	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. Method 1: Log in to VPC console. Choose Access Control > Security Groups in the navigation pane on the left. On the displayed page, click the target security group. You can view the security group ID on the displayed page. Method 2: Query the security group through the VPC API. For details, see Querying Security Groups. Method 2: See the section "Querying Security Groups" in the Virtual Private Cloud API Reference.
charge_info	No	Object	Billing type, which can be pay-per-use or yearly/monthly. For details, see Table 7.
time_zone	No	String	UTC time zone. If this parameter is not specified, GaussDB uses UTC in the International website by default. If this parameter is specified, the value ranges from UTC-12:00 to UTC+12:00 at the full hour. For example, the parameter can be UTC+08:00 rather than UTC+08:30.
sharding_num	No	Integer	This parameter is available only for distributed instances. Number of shards. The value ranges from 1 to 9.
coordinator_num	No	Integer	This parameter is available only for distributed instances. Number of CNs. The value ranges from 1 to 9. The number of CNs cannot exceed twice the number of shards.
replica_num	No	Integer	Number of replicas. The value can be 3. If this parameter is left blank, the default value is 3.
enable_force_switch	No	Boolean	Whether to forcibly promote a standby node to primary. The value can only be true or false. true indicates that the function is enabled, and false indicates that the function is disabled. The function is disabled by default. Only 1.2.2 and later versions are supported. NOTE: The function is suitable for the following scenario: When the primary node is faulty, a standby node is forcibly promoted to primary to provide services, ensuring the instance availability. When an instance is faulty, the forcible switchover enables the cluster to recover services as soon as possible at the cost of losing some data. This is an escape method used when the cluster is unavailable.
enable_single_float_ip	No	Boolean	Whether to enable single floating IP address policy, which is only suitable for primary/standby instances. Value range: true: This function is enabled. Only one floating IP address is bound to the primary node of a DB instance. If a primary/standby failover occurs, the floating IP address does not change. false (default value): The function is disabled. Each node is bound to a floating IP address. If a primary/standby failover occurs, the floating IP addresses change. NOTE: This parameter is only available for primary/standby instances that run 3.206 or later versions.

**Table 3** datastore field data structure description
Name	Mandatory	Type	Description
type	Yes	String	DB engine. Value: GaussDB. It is case-insensitive.
version	No	String	DB engine version. If this parameter is not specified, the latest version is used by default. For details, see Querying DB Engine Versions.

**Table 4** ha field data structure description
Name	Mandatory	Type	Description
mode	Yes	String	Deployment model. The value is case-insensitive and can be enterprise (enterprise edition) and combined (basic edition for combined deployment) for distributed instances and centralization_standard for primary/standby instances.
consistency	Yes	String	Transaction consistency type. The value is case-insensitive and can be: strong: strong consistency eventual: eventual consistency
replication_mode	Yes	String	Replication mode for the standby node. The value can only be set to sync, indicating that data is synchronized in synchronous mode.
instance_mode	No	String	Product type of the instance to be created. If this parameter is not specified, an instance of the enterprise edition will be created by default. To create an instance of the basic edition or ecosystem edition, you need to specify the parameter value. enterprise: The instance of the enterprise edition will be created. basic: The instance of the basic edition will be created. ecology: The instance of the ecosystem edition will be created.

**Table 5** backup_strategy field data structure description
Name	Mandatory	Type	Description
start_time	Yes	String	Backup time window. The creation of an automated backup will be triggered during the backup time window. 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 in the UTC format. The HH value must be 1 greater than the hh value. The values of mm and MM must be the same and must be set to 00. Example value: 08:00-09:00 23:00-00:00
keep_days	No	Integer	Retention days for specific backup files. Value: 1 to 36500. If this parameter is not specified, the default value 7 is used.

**Table 6** volume field data structure description
Name	Mandatory	Type	Description
type	Yes	String	Disk type. Value: ULTRAHIGH (SSD storage) or ESSD (extreme SSD storage). The value is case-sensitive.
size	Yes	Integer	Storage. For example, if this parameter is set to 40, 40 GB of storage is allocated to the created instance. ECS deployment: The value is 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).

**Table 7** chargeInfo field data structure description
Name	Mandatory	Type	Description
charge_mode	Yes	String	Billing mode. postPaid: pay-per-use billing. prePaid: yearly/monthly billing.
period_type	No	String	Subscription period. Value range: month: The service is subscribed by month. year: The service is subscribed by year. NOTE: This parameter is valid and mandatory only when charge_mode is set to prePaid.
period_num	No	Integer	This parameter is valid and mandatory only when charge_mode is set to prePaid. Value range: When period_type is set to month, the parameter value ranges from 1 to 9. When period_type is set to year, the parameter value ranges from 1 to 3. When a floating-point value is transferred, the value is automatically truncated to an integer.
is_auto_renew	No	Boolean	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. true: Automatic renewal is enabled. false: Automatic renewal is disabled. The default value is false.
is_auto_pay	No	Boolean	Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment mode of automatic renewal. true: The order will be automatically paid. false: The order will be manually paid. The default value is false.

Response Parameters

**Table 8** Response parameters
Name	Type	Description
instance	Object	Instance information. For details, see Table 9.
job_id	String	Instance creation task ID. This parameter is returned only when pay-per-use instances are created.
order_id	String	Order ID. This parameter is returned only for the creation of yearly/monthly instances.

**Table 9** instance description
Name	Type	Description
id	String	Instance ID.
name	String	Instance name. Instances of the same type can have same names under the same tenant. The value must consist of 4 to 64 characters and start with a letter. It is case-insensitive and contains only letters, digits, hyphens (-), and underscores (_).
status	String	Instance status. For example, BUILD indicates that the instance is being created. This parameter is returned only when pay-per-use instances are created.
datastore	Object	Database information. For details, see Table 10.
ha	Object	Database deployment model. For details, see Table 11.
replica_num	Integer	Number of replicas.
port	String	Database port, which is the same as the request parameter.
backup_strategy	Object	Automated backup policy. For details, see Table 12.
enterprise_project_id	String	Project ID.
flavor_ref	String	Specification code. The value cannot be left blank.
volume	Object	Volume information. For details, see Table 13.
region	String	Region ID.
availability_zone	String	AZ ID.
vpc_id	String	VPC ID.
subnet_id	String	Network ID of the subnet.
security_group_id	String	Security group to which the instance belongs.
charge_info	Object	Payment mode. For details, see Table 14.

**Table 10** datastore field data structure description
Name	Type	Description
type	String	DB engine. Value: GaussDB
version	String	DB engine version.

**Table 11** ha field data structure description
Name	Type	Description
mode	String	Deployment model. The value is case-insensitive and can be combined (basic edition for combined deployment) and enterprise (enterprise edition) for distributed instances and centralization_standard for primary/standby instances.
replication_mode	String	Replication mode for the standby node. The value can only be set to sync, indicating that data is synchronized in synchronous mode.
consistency	String	Transaction consistency type. This parameter is reserved for GaussDB. Value: strong: strong consistency eventual: eventual consistency
consistency_protocol	String	Replica consistency protocol. The value can be quorum (default value) or paxos. If it is not specified, the default value is used.

**Table 12** backup_strategy field data structure description
Name	Type	Description
start_time	String	Backup time window. The creation of an automated backup will be triggered during the backup time window. The value cannot be left blank. It must be a valid value in the "hh:mm-HH:MM" format. The current time is in the UTC format. The HH value must be 1 greater than the hh value. The values of mm and MM must be the same and must be set to 00. Example value: 08:00-09:00 23:00-00:00 If backup_strategy in the request body is left blank, 02:00-03:00 is returned for start_time by default.
keep_days	Integer	Retention days for specific backup files. Value range: 1 to 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.

**Table 13** volume field data structure description
Name	Type	Description
type	String	Disk type. Its value is case-sensitive and can be: ULTRAHIGH, indicating SSD. ESSD: indicates the extreme SSD.
size	Integer	Storage.

**Table 14** charge_Info field data structure description
Name	Type	Description
charge_mode	String	Billing mode. postPaid: pay-per-use billing. prePaid: yearly/monthly billing.
period_type	String	Subscription period. month: The service is subscribed by month. year: The service is subscribed by year. This parameter is valid and mandatory only when charge_mode is set to prePaid. Value: month year
period_num	Integer	This parameter is valid and mandatory only when charge_mode is set to prePaid. Value range: When period_type is set to month, the parameter value ranges from 1 to 9. When period_type is set to year, the parameter value ranges from 1 to 3.
is_auto_renew	Boolean	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. true: indicates that the subscription is automatically renewed. false: indicates that the subscription is not automatically renewed. The default value is false.
is_auto_pay	Boolean	Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment mode of automatic renewal. true: indicates that the order is automatically paid from the account. false: indicates that the order is manually paid from the account. The default value is false.

Example Request

Creating a distributed DB instance in the independent deployment (one-year yearly/monthly billing, DB engine 2.7, three AZs, three CNs, three shards, three replicas, and 8 vCPUs and 64 GB)

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-independent-02", 
    "datastore": {
        "type": "GaussDB", 
        "version": "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 primary/standby (1 primary + 2 standby) DB instance (pay-per-use billing, DB engine 2.7, single AZ, 8 vCPUs and 64 GB)

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-ha-01",
    "datastore": {
        "type": "GaussDB",
        "version": "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 primary/standby (1 primary + 2 standby) DB instance (one-year yearly/monthly billing, DB engine 2, three AZs, 8 vCPUs and 64 GB)

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-ha-02",
    "datastore": {
        "type": "GaussDB",
        "version": "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 DB instance in the independent deployment (pay-per-use billing, DB engine 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": "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 DB instance (one-year yearly/monthly billing, DB engine 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": "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"
}

Primary/Standby DB instance (1 primary + 2 standby, pay-per-use billing, DB engine 2.7, single AZ, 8 vCPUs and 64 GB) created.

{
    "instance": {
        "id": "ad8cd1440aa94a02ae4580fcbebb3143in14",
        "name": "user1-v3-ha-01",
        "status": "BUILD",
        "datastore": {
            "type": "GaussDB",
            "version": "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"
}

Primary/Standby DB instance (1 primary + 2 standby, one-year yearly/monthly billing, DB engine 2.7, three AZs, 8 vCPUs and 64 GB) created.

{
    "instance": {
        "id": "ad8cd1440aa94a02ae4580fcbebb3143in14",
        "name": "user1-v3-ha-02",
        "datastore": {
            "type": "GaussDB",
            "version": "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 Code

Normal
202
Abnormal
For details, see Status Codes.

Error Code

For details, see Error Codes.

Creating a DB Instance (v5)