Use CreateShardingDBInstance to create or clone a sharded cluster instance - ApsaraDB for MongoDB - Alibaba Cloud - ApsaraDB for MongoDB

Creates or clones an ApsaraDB for MongoDB sharded cluster instance.

Operation description

Before you call this operation, make sure that you fully understand the billing methods and pricing of ApsaraDB for MongoDB.
For more information about instance specifications of ApsaraDB for MongoDB, see Instance specifications.
To create a standalone or replica set instance, call the CreateDBInstance 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:CreateShardingDBInstance

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.	cn-hangzhou
ZoneId	string	No	The zone ID. You can call the DescribeRegions operation to query the zone ID.	cn-hangzhou-g
Engine	string	Yes	The database engine. Set the value to MongoDB. Valid values: MongoDB : MongoDB database engine.	MongoDB
EngineVersion	string	Yes	The database version number. Valid values: 8.0 7.0 6.0 5.0 4.4 4.2 4.0 Note For more information about the constraints on storage engines and versions, see Database engine versions and storage engines. When you call this operation to clone instance, set this parameter to the same value as the source instance.	4.4
DBInstanceDescription	string	No	The name of the instance. Valid values: The name must start with a letter. The name can contain digits, letters, underscores (_), periods (.), and hyphens (-). The name must be 2 to 256 characters in length.	test
SecurityIPList	string	No	The IP address whitelist of the instance. Separate multiple IP addresses with commas (,). IP addresses cannot be duplicated. The following three formats are supported: 0.0.0.0/0 IP address, such as 10.23.12.24. CIDR block, such as 10.23.12.0/24, where 24 indicates the length of the prefix in the IP address and the value ranges from 1 to 32. Note You can add up to 1,000 IP addresses or CIDR blocks to all IP address whitelist groups of an instance. If you set this parameter to 0.0.0.0/0, all IP addresses can access the instance. Exercise caution when you use this setting.	192.168.xx.xx,192.168.xx.xx
AccountPassword	string	No	The password of the root account. Valid values: The password must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. Special characters include !@#$%^&()_+-= The password must be 8 to 32 characters in length. Note* For more information about how to troubleshoot database connection failures caused by special characters in the connection string, see How do I troubleshoot connection failures caused by special characters in the account password of a connection string?.	123456Aa
ChargeType	string	No	The billing method of the instance. Valid values: PostPaid: pay-as-you-go. This is the default value. 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
Period	integer	No	The subscription period of the instance. Unit: months. Valid values: 1 to 9 (integer), 12, 24, 36, and 60. Note This parameter is available and required only when you set ChargeType to PrePaid.	1
NetworkType	string	No	The network type of the instance. Valid values: VPC: virtual private cloud (VPC).	VPC
VpcId	string	No	The VPC ID.	vpc-bp1n3i15v90el48nx****
VSwitchId	string	No	The vSwitch ID.	vsw-bp1vj604nj5a9zz74****
SrcDBInstanceId	string	No	The instance ID of the source instance. Note This parameter is required only when you call this operation to clone instance. You must also configure the RestoreTime parameter.	dds-bp11483712c1****
RestoreTime	string	No	The point in time to which you want to recover data. You can specify any point in time within the past seven days. Specify the time in the yyyy-MM-ddTHH:mm:ssZ format (UTC). Note This parameter is required only when you call this operation to clone instance. You must also configure the SrcDBInstanceId parameter.	2022-03-08T02:30:25Z
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 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****
StorageEngine	string	No	The storage engine of the instance. Set the value to WiredTiger. Note When you call this operation to clone instance, set this parameter to the same value as the source instance. For more information about the constraints on storage engines and versions, see Database engine versions and storage engines.	WiredTiger
AutoRenew	string	No	Specifies whether to enable auto-renewal for the instance. Valid values: true: enables auto-renewal. false: disables auto-renewal. You must manually renew the instance. This is the default value. Note This parameter is available and optional only when you set ChargeType to PrePaid.	true
ProtocolType	string	No	The type of the access protocol. Valid values: mongodb: MongoDB protocol. dynamodb: DynamoDB protocol. Valid values: mongodb : MongoDB protocol. dynamodb : DynamoDB protocol.	mongodb
Mongos	array<object>	Yes	The information about Mongos nodes.
	object	Yes	The information about Mongos nodes.
Class	string	Yes	The specification of the Mongos node. For more information, see Sharded cluster instance specifications. Note N in the parameter name specifies the sequence number of the Mongos node. For example, Mongos.2.Class specifies the specification of the second Mongos node. Valid values of N: 2 to 32.	mdb.shard.2x.xlarge.d
ReplicaSet	array<object>	Yes	The information about Shard nodes.
	object	No	The information about Shard nodes.
Class	string	Yes	The specification of the Shard node. For more information, see Sharded cluster instance specifications. Note N in the parameter name specifies the sequence number of the Shard node. For example, ReplicaSet.2.Class specifies the specification of the second Shard node. Valid values of N: 2 to 32.	dds.shard.standard
Storage	integer	Yes	The storage capacity of the Shard node. Unit: GB. Note The valid values are subject to the instance specifications. For more information, see Sharded cluster instance specifications. N in the parameter name specifies the sequence number of the Shard node. For example, ReplicaSet.2.Storage specifies the storage capacity of the second Shard node.	10
ReadonlyReplicas	integer	No	The number of read-only nodes for the Shard node. Valid values: 0 to 5 (integer). Default value: 0. Note N in the parameter name specifies the sequence number of the Shard node. For example, ReplicaSet.2.ReadonlyReplicas specifies the number of read-only nodes for the second Shard node.	0
ConfigServer	array<object>	Yes	The information about ConfigServer nodes.
	object	No	The information about ConfigServer nodes.
Class	string	Yes	The specification of the ConfigServer node. Valid values: mdb.shard.2x.xlarge.d: 4 vCPUs, 8 GB memory (dedicated). This value is supported only for instances that run version 4.4 or later. dds.cs.mid: 1 vCPU, 2 GB memory (general-purpose). This value is supported only for instances that run version 4.2 or earlier.	mdb.shard.2x.xlarge.d
Storage	integer	Yes	The storage capacity of the ConfigServer node. Unit: GB. Note The valid values are subject to the instance specifications. For more information, see Sharded cluster instance specifications.	20
SecondaryZoneId	string	No	The resource group ID. For more information, see View basic information of a resource group.	rg-acfmyiu4ekp****
HiddenZoneId	string	No	The secondary zone 1 for 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 only when the instance uses cloud disks. The value of this parameter cannot be the same as the values of ZoneId or HiddenZoneId. For more information about the multi-zone deployment strategy for sharded cluster instances, see Create a multi-zone sharded cluster instance.	cn-hangzhou-h
StorageType	string	No	The secondary zone 2 for 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 only when the instance uses cloud disks. The value of this parameter cannot be the same as the values of ZoneId or SecondaryZoneId. For more information about the multi-zone deployment strategy for sharded cluster instances, see Create a multi-zone sharded cluster instance.	cn-hangzhou-i
GlobalSecurityGroupIds	string	No	The storage type. Valid values: cloud_essd1: PL1 ESSD. cloud_essd2: PL2 ESSD. cloud_essd3: PL3 ESSD. local_ssd: local SSD. Note Instances that run version 4.4 or later support only cloud disks. If you do not specify this parameter, cloud_essd1 is used by default. Instances that run version 4.2 or earlier support only local disks. If you do not specify this parameter, local_ssd is used by default.	cloud_essd1
Tag	array<object>	No	The global IP address whitelist templates of the instance. Separate multiple templates with commas (,). Templates cannot be duplicated.	g-qxieqf40xjst1ngpr3jz
	object	No	The custom tags added to the instance.
Key	string	No	The key of the tag. Note N specifies the serial 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 serial 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
Encrypted	boolean	No	The custom tags.	true
EncryptionKey	string	No	Specifies whether to enable cloud disk encryption.	true
ProvisionedIops	integer	No	The custom encryption key ID.	2axxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SrcRegion	string	No	The provisioned IOPS.	1960
BackupId	string	No	The region where the source instance resides. Note This parameter is required when the backup recovery type is rebuilding a deleted instance. This parameter is required when the backup recovery type is cloning from a geo-redundancy backup.	cn-beijing
RestoreType	string	No	The cluster backup ID. Note This parameter is required only when RestoreType is set to 2 or 3.	cb-xxx
DestRegion	string	No	The backup recovery type. Valid values: 1: Recover the instance to a specified point in time. 2: Recover a released instance from a specified backup set. 3: Recover the instance from a specified geo-redundancy backup set.	1

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	D8F1D721-6439-4257-A89C-F1E8E9C9****
DBInstanceId	string	The instance ID.	dds-bp114f14849d****
OrderId	string	The order ID.	21010996721****

Examples

Success response

JSON format

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

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	InvaliadParameter.ShardsCount.LessThanSrc	The specified number of shards is less than that of source instance.
400	ORDER.ACCOUNT_INFORMATION_INCOMPLETE	Your information is incomplete. Complete your information before ordering.
400	InvalidRegion.Format	Specified Region is not valid.
400	Zone.Closed	The specified zone is closed.
400	TokenServiceError	The request token is duplicated.
400	InvalidParam	Param not valid.
400	InvalidEngineVersion.Malformed	Specified engine version is not valid.	The instance version information is empty or invalid.
400	InvalidParameters.Format	Specified parameters is not valid.	The parameter entered is invalid.
400	RestoreTypeNotSupported	The specified restoreType is not supported for the instance, check the input parameters 'RestoreType/BackupID/RestoreTime'.	The specified restoreType is not supported for the instance, check the input parameters 'RestoreType/BackupID/RestoreTime'.
500	VpcServiceError	Invoke vpc service error.	An error occurred when calling the VPC service.
403	InvalidBackupLogStatus	Current backup log enable status does not support this operation.
403	ReduceDiskNotSupport	Reduce disk size is not supported in clone/restore.	Reduce disk size is not supported in clone/restore.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.