doc-exports/docs/opengauss/api-ref/opengauss_api_0015.html

Creating a DB Instance

Function

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

• Learn how to authenticate this API.
• Understand the API in Using APIs.
• Obtain the required region and endpoint.

URI

• URI format

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

• Example

  https://gaussdb.eu-de.otc.t-systems.com/v3/0483b6b16e954cb88930a360d2c4e663/instances

• Parameter description

  Table 1 Parameter description

  Name	Mandatory	Description
  project_id	Yes	Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID.

Request

Table 2 Parameter description

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 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.
disk_encryption_id	No	String	Key ID for disk encryption. The default value is empty.
flavor_ref	Yes	String	Specification code. The value cannot be empty. For details on how to obtain the GaussDB specification code, see DB 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 GaussDB in the same AZ or across three different AZs, and use commas (,) to separate AZs. For example: To deploy a DB instance in the same AZ, enter three same AZ IDs. To deploy a DB instance across three different AZs, enter three different AZ IDs. 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 VPC console and view the VPC ID in the VPC details. Method 2: See the section "Querying VPCs" in the Virtual Private Cloud API Reference.
subnet_id	Yes	String	Network ID. 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: See the section "Querying Subnets" in the Virtual Private Cloud API Reference. Method 2: See section "Querying Subnets" under "APIs" or "Querying Networks" under "OpenStack Neutron APIs" in 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: 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: See the section "Querying Security Groups" in the Virtual Private Cloud API Reference.
charge_info	No	Object	Billing type. For details, see Table 7.
time_zone	No	String	UTC time zone. If this parameter is not specified, GaussDB uses UTC 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.
coordinator_num	No	Integer	This parameter is available only for distributed instances. Number of CNs. The number of CNs cannot exceed twice the number of shards.
replica_num	No	Integer	Number of replicas. The value can be 2 or 3 (default).

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. Its value is enterprise for distributed instances and centralization_standard for primary/standby instances. It is case-insensitive.
consistency	Yes	String	Transaction consistency type. The value can be strong or eventual and is case-insensitive.
replication_mode	Yes	String	Replication mode for the standby node. Value: sync NOTE: sync indicates synchronous replication.

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 empty. 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: 0 to 732. If this parameter is not specified or is set to 0, the default value 7 is used.

Table 6 volume field data structure description

Name	Mandatory	Type	Description
type	Yes	String	Disk type. The value can only be ULTRAHIGH (case-sensitive), indicating SSD.
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 must be a multiple of (Number of shards x 40 GB), ranging from (Number of shards x 40 GB) to (Number of shards x 16 TB).

Table 7 chargeInfo field data structure description

Name	Mandatory	Type	Description
charge_mode	Yes	String	Billing mode. The value can only be postPaid.

• Example request

Creating an instance of the enterprise edition:
{
    "name": "user1-v3-independent", 
    "datastore": {
        "type": "GaussDB", 
        "version": "1.4"
    }, 
    "flavor_ref": "gaussdb.opengauss.ee.dn.m4.2xlarge.8.in", 
    "volume": {
        "type": "ULTRAHIGH", 
        "size": 120
    },
    "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab",
    "region": "eu-de",
     "availability_zone": "eu-de-01,eu-de-01,eu-de-01",
    "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": "b000d7c91f1749da87315700793a11d4pr14", 
    "time_zone": "UTC+08:00",
    "ha":{
        "mode":"enterprise",
        "consistency":"strong",
        "replication_mode":"sync",
        "consistency_protocol":"quorum"
    },
    "sharding_num": 1,
    "coordinator_num": 1,
    "replica_num": 3,
    "port":8000,
    "enable_force_switch":true
}

Response

• Normal response

  Table 8 Parameter description

  Name	Type	Description
  instance	Object	Instance information. For details, see Table 9.
  job_id	String	Instance creation task ID.

  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 starts 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.
  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.
  flavor_ref	String	Specification code. The value cannot be empty. For details on how to obtain the GaussDB specification code, see DB Instance Specifications.
  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	Distributed deployment. The value can be enterprise (Enterprise Edition). It is case-insensitive.
  replication_mode	String	Replication mode for the standby node. Value: sync. NOTE: sync indicates synchronous replication.
  consistency	String	(GaussDB reserved parameter) Transaction consistency type. The value can be strong or eventual.
  consistency_protocol	String	Replica consistency protocol. Value: quorum (default value) or paxos

  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 empty. 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 empty, 02:00-03:00 is returned for start_time by default.
  keep_days	Integer	Retention days for specific backup files. The value ranges from 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.
  size	Integer	Storage. When creating a distributed instance, you need to specify the storage to be a multiple of (Number of shards x 40 GB), ranging from (Number of shards x 40 GB) to (Number of shards x 16 TB).

  Table 14 charge_Info field data structure description

  Name	Type	Description
  charge_mode	String	Billing mode. The value can only be postPaid.

• Example normal response

  Creating a DB instance of the enterprise edition:
  {
      "instance": {
          "id": "ad8cd1440aa94a02ae4580fcbebb3143in14",
          "name": "user1-v3-independent",
          "status": "BUILD",
          "datastore": {
              "type": "GaussDB",
              "version": "1.4"
          },
          "ha": {
              "mode": "Enterprise",
              "replication_mode": "sync",
              "consistency": "strong",
              "consistency_protocol":"quorum"
          },
          "port": "8000",
          "volume": {
              "type": "ULTRAHIGH",
              "size": 120
          },
          "replica_num": 3,
  	"region": "eu-de",
          "backup_strategy": {
              "start_time": "17:00-18:00",
              "keep_days": 7
          },
          "flavor_ref":"gaussdb.opengauss.ee.dn.m4.2xlarge.8.in",
  	"availability_zone": "eu-de-01,eu-de-01,eu-de-01",
             "availability_zone": "bbb,ccc",
          "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"
  }
  

• Abnormal response

  For details, see Abnormal Request Results.

Status Code

• Normal

  202

• Abnormal

  For details, see Status Codes.

Error Code

For details, see Error Codes.

Parent topic: Instance Management