Use CreateDBInstance to create or clone a replica set instance - ApsaraDB for MongoDB - Alibaba Cloud - ApsaraDB for MongoDB

Creates or clones an ApsaraDB for MongoDB replica set instance.

Operation description

Before using this operation, make sure you understand the billing methods and pricing of ApsaraDB for MongoDB.

For information about instance specifications, see Instance specifications.

To create a sharded cluster instance, call the CreateShardingDBInstance operation.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

dds:CreateDBInstance

create

*Instance

acs:dds:{#regionId}:{#accountId}:dbinstance/*

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. You can call the DescribeRegions operation to query the region ID. Note If you call this operation to clone clone instance or restore clone instance from the recycle bin, set this parameter to the same value as that of the source instance.	cn-hangzhou
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.	ETnLKlblzczshOTUbOCz****
ZoneId	string	No	The zone ID. You can call the DescribeRegions operation to query the zone ID.	cn-hangzhou-g
EngineVersion	string	Yes	The database engine version. Valid values: 8.0 7.0 6.0 5.0 4.4 4.2 4.0 Note If you call this operation to clone clone instance or restore clone instance from the recycle bin, set this parameter to the same value as that of the source instance. Warning Versions 3.4 and earlier are no longer available for purchase.	4.4
DBInstanceClass	string	Yes	The instance type. You can call the DescribeAvailableResource operation to query the available instance types.	dds.mongo.standard
DBInstanceStorage	integer	Yes	The instance storage capacity. Unit: GB. The valid values depend on the instance type. For details, see Replica set instance specifications.	10
DBInstanceDescription	string	No	The instance name. The name must meet the following requirements: Must start with a Chinese character or a letter. Can contain digits, Chinese characters, letters, underscores (_), periods (.), and hyphens (-). Must be 2 to 256 characters in length.	test
SecurityIPList	string	No	The IP whitelist of the instance. Separate multiple IP addresses with commas (,). Duplicate IP addresses are not allowed. The following formats are supported: 0.0.0.0/0 IP address format, such as 10.23.12.24. CIDR block format, such as 10.23.12.0/24. In this example, 24 indicates that the prefix of the CIDR block is 24 bits in length. The prefix length ranges from 1 to 32. Note Each instance supports a maximum of 1,000 IP addresses or CIDR blocks across all IP whitelist groups. 0.0.0.0/0 allows all IP addresses to access the instance database. This is a high-risk setting. Proceed with caution.	192.168.xx.xx,192.168.xx.xx
AccountPassword	string	No	The password of the root account. The password must meet the following requirements: Must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. Special characters include !@#$%^&()_+-=. Must be 8 to 32 characters in length. Note* For information about how to database connection failures caused by special characters in the password, see How do I database connection failures caused by special characters in the connection string?.	123456Aa
Period	integer	No	The subscription duration of the instance. Unit: months. Valid values: 1 to 9 (integers), 12, 24, 36, and 60. Note This parameter is available and required when ChargeType is set to PrePaid.	1
ChargeType	string	No	The billing method of the instance. Valid values: PostPaid: default value. Pay-as-you-go. PrePaid: Subscription. Note If you set this parameter to PrePaid, you must also configure the Period parameter. Valid values: PostPaid : pay-as-you-go. PrePaid : subscription.	PrePaid
NetworkType	string	No	The network type of the instance. Valid values: VPC: Virtual Private Cloud. Valid values: VPC : Virtual Private Cloud.	VPC
VpcId	string	No	The VPC ID.	vpc-bp175iuvg8nxqraf2****
VSwitchId	string	No	The vSwitch ID.	vsw-bp1gzt31twhlo0sa5****
SrcDBInstanceId	string	No	The source instance ID. Note If you call this operation to clone clone instance, you must configure this parameter along with the BackupId or RestoreTime parameter. If you call this operation to restore clone instance from the recycle bin, you only need to configure this parameter. The BackupId and RestoreTime parameters are not required.	dds-bp1ee12ad351****
BackupId	string	No	The backup ID. You can invoke the DescribeBackups operation to query the backup ID. Note This parameter is required only when you invoke this operation to clone a clone instance from a backup point. You must also configure the SrcDBInstanceId parameter.	32994****
RestoreTime	string	No	The point in time to recover the instance to. You can specify any point in time within the last 7 days. Specify the time in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC. Note This parameter is required only when you invoke this operation to clone a clone instance to a point in time. You must also configure the SrcDBInstanceId parameter.	2022-03-13T12:11:14Z
BusinessInfo	string	No	The additional information about the business.	{“ActivityId":"000000000"}
AutoRenew	string	No	Specifies whether to enable auto-renewal for the instance. Valid values: true: enables auto-renewal. false: default value. Disables auto-renewal. You must manually renew the instance. Note This parameter is available and optional when ChargeType is set to PrePaid.	true
DatabaseNames	string	No	The name of the database. Note When you invoke this operation to clone a clone instance, you can specify this parameter to clone specific databases. If you do not specify this parameter, all databases are cloned.	mongodbtest
CouponNo	string	No	Specifies whether to use a coupon. Valid values: default or null (default): uses a coupon. youhuiquan_promotion_option_id_for_blank: does not use a coupon.	default
StorageEngine	string	No	The storage engine of the instance. The value is fixed as WiredTiger. Note If you call this operation to clone clone instance or restore clone instance from the recycle bin, set this parameter to the same value as that of the source instance. For information about the constraints on storage engines and versions, see Versions and storage engines. Valid values: WiredTiger : WiredTiger storage engine.	WiredTiger
ReplicationFactor	string	No	The number of primary and secondary nodes in the replica set instance. Valid values: 3 (default) 5 7 Important This parameter is not required for single-node instances.	3
ReadonlyReplicas	string	No	The number of read-only nodes in the replica set instance. Valid values: 0 to 5 (integers). Default value: 0.	0
Engine	string	No	The resource group ID. Valid values: MongoDB : MongoDB database engine.	rg-acfmyiu4ekp****
StorageType	string	No	The dedicated cluster ID.	dhg-2x78****
SecondaryZoneId	string	No	The database engine. The value is fixed as MongoDB.	MongoDB
HiddenZoneId	string	No	The storage type. Valid values: cloud_essd1: PL1 ESSD. cloud_essd2: PL2 ESSD. cloud_essd3: PL3 ESSD. cloud_auto: ESSD AutoPL disk. local_ssd: local SSD. Note For single-node instances, if you specify cloud_essd1, the instance uses a cloud_essd disk. ESSD AutoPL disks are currently available only on the China site. For instances running version 4.4 or later, the default value is cloud_essd1. For instances running version 4.2 or earlier, the default value is local_ssd.	cloud_essd1
Tag	array<object>	No	The zone where the secondary node is deployed to implement multi-zone deployment. Valid values: cn-hangzhou-g: Hangzhou Zone G. cn-hangzhou-h: Hangzhou Zone H. cn-hangzhou-i: Hangzhou Zone I. cn-hongkong-b: Hong Kong (China) Zone B. cn-hongkong-c: Hong Kong (China) Zone C. cn-hongkong-d: Hong Kong (China) Zone D. cn-wulanchabu-a: Ulanqab Zone A. cn-wulanchabu-b: Ulanqab Zone B. cn-wulanchabu-c: Ulanqab Zone C. ap-southeast-1a: Singapore Zone A. ap-southeast-1b: Singapore Zone B. ap-southeast-1c: Singapore Zone C. ap-southeast-5a: Jakarta Zone A. ap-southeast-5b: Jakarta Zone B. ap-southeast-5c: Jakarta Zone C. eu-central-1a: Frankfurt Zone A. eu-central-1b: Frankfurt Zone B. eu-central-1c: Frankfurt Zone C. Note This parameter is available when the instance uses cloud disks. The value of this parameter cannot be the same as the values of ZoneId and HiddenZoneId.	cn-hangzhou-h
	object	No
Key	string	No	The key of the tag. Note N specifies the number of the tag. For example, Tag.1.Key specifies the key of the first tag, and Tag.2.Key specifies the key of the second tag.	testdatabase
Value	string	No	The value of the tag. Note N specifies the number of the tag. For example, Tag.1.Value specifies the value of the first tag, and Tag.2.Value specifies the value of the second tag.	apitest
GlobalSecurityGroupIds	string	No	The zone where the hidden node is deployed to implement multi-zone deployment. Valid values: cn-hangzhou-g: Hangzhou Zone G. cn-hangzhou-h: Hangzhou Zone H. cn-hangzhou-i: Hangzhou Zone I. cn-hongkong-b: Hong Kong (China) Zone B. cn-hongkong-c: Hong Kong (China) Zone C. cn-hongkong-d: Hong Kong (China) Zone D. cn-wulanchabu-a: Ulanqab Zone A. cn-wulanchabu-b: Ulanqab Zone B. cn-wulanchabu-c: Ulanqab Zone C. ap-southeast-1a: Singapore Zone A. ap-southeast-1b: Singapore Zone B. ap-southeast-1c: Singapore Zone C. ap-southeast-5a: Jakarta Zone A. ap-southeast-5b: Jakarta Zone B. ap-southeast-5c: Jakarta Zone C. eu-central-1a: Frankfurt Zone A. eu-central-1b: Frankfurt Zone B. eu-central-1c: Frankfurt Zone C. Note This parameter is available when the instance uses cloud disks. The value of this parameter cannot be the same as the values of ZoneId and SecondaryZoneId.	cn-hangzhou-i
Encrypted	boolean	No	The user-defined tags.	true
EncryptionKey	string	No	The global IP whitelist templates for the instance. Separate multiple templates with commas (,). Duplicate templates are not allowed. (This feature is in canary release.)	g-qxieqf40xjst1ngpr3jz
ProvisionedIops	integer	No	Specifies whether to enable cloud disk encryption.	true
RestoreType	string	No	The custom key ID.	2axxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SrcRegion	string	No	The provisioned performance (IOPS). Valid values: 0 to 50000.	1960

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	D8F1D721-6439-4257-A89C-F1E8E9C9****
DBInstanceId	string	The instance ID.	dds-bp144a7f2db8****
OrderId	string	The order ID.	21077576248****

Examples

Success response

JSON format

{
  "RequestId": "D8F1D721-6439-4257-A89C-F1E8E9C9****",
  "DBInstanceId": "dds-bp144a7f2db8****",
  "OrderId": "21077576248****"
}

Error codes

HTTP status code	Error code	Error message	Description
400	SecurityRisk.AuthVerification	we have detected a risk with your default payment method. An email and notification has been sent to you. Please re-submit your order before after verificaiton.
400	MissingParameter	Period is mandatory for this action.
400	ORDER.ACCOUNT_INFORMATION_INCOMPLETE	Your information is incomplete. Complete your information before ordering.
400	InvalidClientToken.Malformed	Specified parameter ClientToken is not valid.
400	InvalidDBInstanceDescription.Malformed	Specified parameter DBInstanceDescription is not valid.	Invalid node name.
400	InvalidSecurityIPListLength.Malformed	The quota of security ip exceeds.
400	InsufficientBalance	Your account does not have enough balance.	The payment failed. Please add another payment method. You can also top up or add funds to your account.
400	QuotaExceed.AfterpayInstance	Living afterpay instances quota exceeded.
400	InvalidCapacity.NotFound	The Capacity provided does not exist in our records.	The specified storage capacity is invalid. Specify a storage capacity within a valid range. Unit: MB.
400	ResourceNotAvailable	Resource you requested is not available for finance user.
400	IdempotentParameterMismatch	Request uses a client token in a previous request but is not identical to that request.	The specified ClientToken parameter is already in use. Specify a client token that has not been used. The ClientToken value is generated by the client and must be unique among different requests. The value can be up to 64 ASCII characters in length and cannot contain non-ASCII characters.
400	InvalidSecurityIPList.Malformed	The specified parameter "SecurityIPList" is not valid.
400	InvalidSecurityIPList.Duplicate	The Security IP address is not in the available range or occupied.
400	InvalidDBInstanceStorage.ValueNotSupported	The specified parameter DBInstanceStorage is not valid.
400	InvalidAccountPassword.Malformed	Specified parameter AccountPassword is not valid.
400	TokenServiceError	Duplicate ClientToken request.
400	Zone.Closed	The specified zone is closed.
400	PRICE.ORIGIN_PRICE_ERROR	The origin price error.
400	NO_AVAILABLE_PAYMENT_METHOD	No payment method is specified for your account. We recommend that you add a payment method.
400	InvalidEcsImage.NotFound	Specified ecs image does not exist.
400	SaleValidateNoSpecificCodeFailed	Specified Storage or Version or InstanceClass is invalid.	Storage or Version or InstanceClass is empty.
400	Trade_Not_Support_Async_Pay	Trade not support async pay.
400	InvalidZoneld	The specified primary zone, secondary zone and hidden zone cannot be the same.	The parameters of the primary zone, secondary zone and hidden zone cannot be the same.
400	SameZoneId	The specified primary zone, secondary zone require two different zones.	The specified primary zone, secondary zone require two different zones.
403	RealNameAuthenticationError	Your account has not passed the real-name authentication yet.	Real-name verification has not been completed for the Alibaba Cloud account. Complete real-name verification and try again.
403	RegionUnauthorized	There is no authority to create instance in the specified region.
403	OperationDenied	The resource is out of usage.	The resource is out of usage.
403	InvalidEngineVersionInRegion.NotAvailable	The EngineVersion in the Region is not available.
403	InvalidBackupLogStatus	Current backup log enable status does not support this operation.
403	IncorrectBackupSetState	Current backup set state does not support operations.
404	InvalidBackup.NotFound	The available backup does not exist in recovery time.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.