CreateShardingDBInstance - ApsaraDB for MongoDB - Alibaba Cloud Documentation Center

Creates or clones a MongoDB sharded cluster instance.

Operation description

Before you call this operation, make sure that you understand the billing methods and pricing of ApsaraDB for MongoDB.
For more information about the instance types of ApsaraDB for MongoDB, see Instance types.
To create a standalone or replica set instance, you can 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.	MongoDB
EngineVersion	string	Yes	The database version. 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 database versions, see Versions and storage engines. When you clone an instance by calling this operation, the value of this parameter must be the same as that of the source instance.	4.4
DBInstanceDescription	string	No	The name of the instance. The name must meet the following requirements: It must start with a Chinese character or a letter. It can contain digits, Chinese characters, letters, underscores (_), periods (.), and hyphens (-). It 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 (,). Each IP address in the whitelist must be unique. The following formats are supported: 0.0.0.0/0 IP addresses, such as 10.23.12.24. CIDR blocks, such as 10.23.12.0/24. The /24 part indicates the prefix length of the CIDR block. The prefix length ranges from 1 to 32. Note You can add a maximum of 1,000 IP addresses or CIDR blocks to all IP address whitelists. The 0.0.0.0/0 entry allows access from all IP addresses. This is a high-risk setting. Configure it 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: It must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. Special characters include !@#$%^&()_+-= It must be 8 to 32 characters in length. Note* For information about how to resolve connection failures caused by special characters in passwords, see How do I fix connection failures caused by special characters in a password?.	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 specify the Period parameter.	PrePaid
Period	integer	No	The subscription duration of the instance. Unit: month. Valid values: 1 to 9 (integer), 12, 24, 36, and 60. Note This parameter is required and takes effect only when you set the ChargeType parameter to PrePaid.	1
NetworkType	string	No	The network type of the instance. Valid values: VPC: virtual private cloud.	VPC
VpcId	string	No	The virtual private cloud (VPC) ID.	vpc-bp1n3i15v90el48nx****
VSwitchId	string	No	The virtual switch ID.	vsw-bp1vj604nj5a9zz74****
SrcDBInstanceId	string	No	The source instance ID. Note This parameter is required only when you clone an instance by calling this operation. You must also specify the RestoreTime parameter.	dds-bp11483712c1****
RestoreTime	string	No	The point in time to which you want to restore data. You can specify any point in time within the last seven days. The time is in the yyyy-MM-ddTHH:mm:ssZ format. The time is in Coordinated Universal Time (UTC). Note This parameter is required only when you clone an instance by calling this operation. You must also specify the SrcDBInstanceId parameter.	2022-03-08T02:30:25Z
ClientToken	string	No	A 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****
StorageEngine	string	No	The storage engine of the instance. Set the value to WiredTiger. Note When you clone an instance by calling this operation, the value of this parameter must be the same as that of the source instance. For more information about the constraints on storage engines and database versions, see Versions and storage engines.	WiredTiger
AutoRenew	string	No	Specifies whether to enable auto-renewal for the instance. Valid values: true: Auto-renewal is enabled. false: Auto-renewal is disabled. You must manually renew the instance. This is the default value. Note This parameter is optional and takes effect only when you set the ChargeType parameter to PrePaid.	true
ProtocolType	string	No	The protocol type of the instance. Valid values: mongodb: MongoDB protocol. dynamodb: DynamoDB protocol.	mongodb
Mongos	array<object>	Yes	The information of Mongos nodes.
	object	Yes	The information of Mongos nodes.
Class	string	Yes	The instance type of the Mongos node. For more information, see Sharded cluster instance types. Note N in the parameter name specifies the serial number of the Mongos node. For example, Mongos.2.Class specifies the instance type of the second Mongos node. The value of N ranges from 2 to 32.	mdb.shard.2x.xlarge.d
ReplicaSet	array<object>	Yes	The information of shard nodes.
	object	No	The information of shard nodes.
Class	string	Yes	The instance type of the shard node. For more information, see Sharded cluster instance types. Note N in the parameter name specifies the serial number of the shard node. For example, ReplicaSet.2.Class specifies the instance type of the second shard node. The value of N ranges from 2 to 32.	dds.shard.standard
Storage	integer	Yes	The storage space of the shard node. Unit: GB. Note The value of this parameter is constrained by the instance type. For more information, see Sharded cluster instance types. N in the parameter name specifies the serial number of the shard node. For example, ReplicaSet.2.Storage specifies the storage space of the second shard node.	10
ReadonlyReplicas	integer	No	The number of read-only nodes in the shard node. Valid values: 0 to 5. The default value is 0. Note N in the parameter name specifies the serial number of the shard node. For example, ReplicaSet.2.ReadonlyReplicas specifies the number of read-only nodes in the second shard node.	0
ConfigServer	array<object>	Yes	The information of Configserver nodes.
	object	No	The information of Configserver nodes.
Class	string	Yes	The instance type of the Configserver node. Valid values: mdb.shard.2x.xlarge.d: 4-core 8 GB (dedicated). This instance type is available only for instances that run MongoDB 4.4 or later. dds.cs.mid: 1-core 2 GB (general-purpose). This instance type is available only for instances that run MongoDB 4.2 or earlier.	mdb.shard.2x.xlarge.d
Storage	integer	Yes	The storage space of the Configserver node. Unit: GB. Note The value of this parameter is constrained by the instance type. For more information, see Sharded cluster instance types.	20
ResourceGroupId	string	No	The resource group ID. For more information about resource groups, see View basic information of a resource group.	rg-acfmyiu4ekp****
SecondaryZoneId	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 for disk-based instances. The value of this parameter cannot be the same as the value of ZoneId or HiddenZoneId. For more information about the multi-zone deployment policy for sharded cluster instances, see Create a multi-zone sharded cluster instance.	cn-hangzhou-h
HiddenZoneId	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 for disk-based instances. The value of this parameter cannot be the same as the value of ZoneId or SecondaryZoneId. For more information about the multi-zone deployment policy for sharded cluster instances, see Create a multi-zone sharded cluster instance.	cn-hangzhou-i
StorageType	string	No	The storage type. Valid values: cloud_essd1: enhanced SSD (ESSD) PL1. cloud_essd2: ESSD PL2. cloud_essd3: ESSD PL3. local_ssd: local SSD. Note Instances that run MongoDB 4.4 or later support only disks. If you do not specify this parameter, cloud_essd1 is used. Instances that run MongoDB 4.2 or earlier support only local disks. If you do not specify this parameter, local_ssd is used.	cloud_essd1
GlobalSecurityGroupIds	string	No	The global IP address whitelist templates of the instance. Separate multiple templates with commas (,). Each template must be unique.	g-qxieqf40xjst1ngpr3jz
Tag	array<object>	No	The custom tags.
	object	No
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	Specifies whether to enable disk encryption.	true
EncryptionKey	string	No	The custom key ID.	2axxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ProvisionedIops	integer	No	The provisioned IOPS.	1960
SrcRegion	string	No	The region of the source instance. Note This parameter is required when you recreate a released instance from a backup. This parameter is required when you clone an instance from a geo-redundant backup.	cn-beijing
BackupId	string	No	The cluster backup ID. Note This parameter is required only when RestoreType is set to 2 or 3.	cb-xxx
RestoreType	string	No	The backup-based instance restoration method. 1: Restore the instance to a specific point in time. 2: Restore a released instance from a specific backup set. 3: Restore the instance from a specific geo-redundant backup set.	1
DestRegion	string	No	The region where the geo-redundant backup is stored.	cn-hangzhou

Response elements

Element	Type	Description	Example
	object	The returned information.
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.
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.
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.