Create and manage Alibaba Cloud ApsaraDB for MongoDB instances: Standalone (dev/test), Replica Set (read-heavy), Sharded Cluster (high concurrency).
Installation Requirements
Pre-check: Aliyun CLI >= 3.3.3 required
Run aliyun version to verify >= 3.3.3. If not installed or version too low,
see references/cli-installation-guide.md for installation instructions.
[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
[MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.
bash
aliyun version
aliyun plugin install --names dds kms resourcemanager bssopenapi
[MUST] CLI User-Agent — Every aliyun CLI command invocation must include:
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
[MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution.
Run the following commands before any CLI invocation:
[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed.
bash
aliyun configure ai-mode disable
Information Display Standards
[MUST] All information displayed to the user must comply with:
No fabricated output: All displayed information must come from actual API query results. Speculation, fabrication, or splicing is strictly prohibited
Truncation handling: If API response is truncated (e.g., omitted), must re-query completely before displaying
Count validation: Displayed count must match TotalCount/actual count returned by API
No speculative time estimates: Do not provide time estimates without official documentation basis; only confirm status via API polling
Write operation response standard: After issuing any write operation (create, modify spec, cloud disk reconfiguration, add/delete node, etc.), only displayRequestId (and DBInstanceId/OrderId if available), then ask the user whether to poll instance status. Do NOT start polling automatically before user confirmation.
Auto-polling rules after instance creation:
It typically takes 10-25 minutes for a newly created instance to reach Running status
Scenario A: User only creates an instance with no follow-up operations → ask whether to poll
Scenario B: User has follow-up operations after creation (e.g., modify spec, configure whitelist, etc.) and has NOT explicitly stated they will check status manually → MUST auto-poll, querying describe-db-instance-attribute every 30 seconds until status is Running or timeout (30 minutes)
Scenario C: User explicitly states "I'll check myself", "handle it later", etc. → do not auto-poll, handle as Scenario A
Security configuration guidance after instance creation: After instance creation completes (status is Running), MUST proactively ask whether to perform security configuration (see security configuration menu in "Parameter Confirmation" section)
Subscription instance display: Must show remaining days; instances expiring within 10 days must display a warning below the list and guide toward renewal
Instance Status Pre-check Standard
[MUST] Must check instance status before executing non-query operations:
Call describe-db-instance-attribute to check DBInstanceStatus
Operations can only be issued when status is Running
Status
Description
Can Issue
Running
Running
✅
DBInstanceClassChanging
Changing spec
❌
NodeCreating / NodeDeleting
Creating/Deleting node
❌
Creating
Creating
❌
Locked
Locked
❌ Investigate cause first
Locked status diagnosis (check LockMode field):
LockByDiskQuota: Disk usage exceeded; auto-unlocks after expanding storage or cleaning data
Other values: Overdue or expired; renew or recharge
[MUST] Permission error handling: When detecting Forbidden.RAM/NoPermission/Forbidden/SubAccountNoPermission:
Identify the missing permission (extract Action and Resource from the error message)
Guide the user to refer to references/ram-policies.md to request permissions
Wait for user confirmation that permission has been granted before retrying; do NOT continue execution before the permission issue is resolved
Query Regions and Instances
[MUST] Region confirmation standard:
When the user has not specified a region, ask for the region first; do not iterate and search directly
Only iterate in the following order when the user explicitly states they are unsure: cn-beijing → cn-shanghai → ap-southeast-1 → us-west-1 → us-east-1 → cn-hangzhou → cn-shenzhen → cn-chengdu → cn-hongkong; if still not found, call DescribeRegions to get remaining regions
Query routing: Querying via cn-hangzhou may return instances from other regions; when displaying, RegionId must be based on the RegionId field returned by the API, not the query parameter
List display: Must be categorized by instance type; Subscription instances must show remaining days; instances expiring within 10 days must display a warning below the list and guide toward renewal
bash
# Query instance list
# If user specifies instance type, query that type only; if not specified, must query both types separately:
aliyun dds describe-db-instances --biz-region-id <region> --db-instance-type replicate --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds describe-db-instances --biz-region-id <region> --db-instance-type sharding --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# ⚠️ Without --db-instance-type, only replicate is returned by default; sharded clusters will be missed
# Query single instance details
aliyun dds describe-db-instance-attribute --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Query all supported regions
aliyun dds describe-regions --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
[MUST] Before executing any create/modify operation, must display a complete parameter list to the user and obtain Y/Yes confirmation
Workflow: Collect parameters → Display parameter list → Wait for Y confirmation → Execute → Only display RequestId/DBInstanceId → Ask whether to poll → Display security configuration guidance after completion
Security configuration guidance menu must be displayed after instance creation:
text
[0] Set root password - Cannot connect without password (priority)
[1] Set IP whitelist - Configure allowed access IPs
[2] Bind ECS security group - Control access via security group
[3] Associate global whitelist template - Use unified whitelist template
[4] Modify maintenance window - Set maintenance window
[5] Allocate public address - Enable public access (dev/test only)
[N] Skip
User already provided VPC/VSwitch ID (but validation is still required)
Validate zone
Creating replica set or sharded cluster instance
[MUST] Mandatory validation when user provides VPC/VSwitch:
Even if the user has provided VPC ID and VSwitch ID, must first call the following APIs to validate correctness and availability:
describe-rds-vpcs: Validate whether VPC ID exists and is available
describe-rds-vswitchs: Validate whether VSwitch ID exists in the specified VPC and matches the target zone
If any validation fails, must inform the user of the specific error and guide correction; do NOT directly use unvalidated VPC/VSwitch to create instances
[MUST] VPC/VSwitch validation must use DDS-specific APIs; generic VPC APIs (vpc DescribeVpcs/vpc DescribeVSwitches) are prohibited:
bash
# Step 1: Query available VPC list for specified zone (DDS-specific)
aliyun dds describe-rds-vpcs --zone-id <zone> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Step 2: Query available VSwitches under specified VPC (DDS-specific)
aliyun dds describe-rds-vswitchs --vpc-id <vpc-id> --zone-id <zone> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
Query current configuration (describe-db-instance-attribute), extract DBInstanceStatus/DBInstanceClass/DBInstanceStorage/ReplicationFactor/ReadonlyReplicas/StorageType
Display "Current vs. New" comparison table and obtain user Y confirmation
Do NOT execute modification command before user confirmation
Limitations: Storage downsizing, instance type change, and storage type change are not supported (for ESSD conversion, use the Cloud Disk Reconfiguration section)
Impact: Modification may cause 1-2 brief disconnections of ~30 seconds; recommended during off-peak hours
After successful modification command, only display RequestId/OrderId; do NOT auto-poll; must ask user for confirmation before starting
Confirm ChargeType: PostPaid → can delete; PrePaid → cannot delete directly (wait expiry or console refund)
Cloud disk instances only: query describe-backup-policy → check BackupRetentionPolicyOnClusterDeletion (0=delete all on release / 1=keep last backup / 2=keep all backups) → ask user if they want to change it via modify-backup-policy --backup-retention-policy-on-cluster-deletion before deleting; see operations.md
[MUST] Display confirmation to user: instance ID, region, billing type, irreversible data loss warning → requiring the user to reply "confirm delete {instance ID}" before executing
[MUST] Applicable only to cloud disk instances (not applicable to local disk):
When displaying baseline IOPS/throughput, must use MaxIOPS/MaxMBPS fields returned by API, NOT formula-calculated values (actual values ≥ formula values)
Formula (reference): IOPS = min{1800+50×StorageGB, spec limit, disk type limit}
IOPS improvement priority: Expand storage > Upgrade spec > Change disk type
[MUST] For sharded clusters, must ask the user before resetting password:
text
Which node type's password do you want to reset?
[1] db node (mongod, stores business data)
[2] cs node (configServer, stores cluster metadata)
[3] Reset both (execute twice separately)
Determine execution count based on user's answer; do NOT auto-execute twice without user confirmation
Password rules: 8-32 characters, must contain at least three of: uppercase letters/lowercase letters/digits/special characters (!@#$%^&*()_+-=)
[MUST] All global whitelist commands must specify both --region and --biz-region-id (same value)
Use --db-cluster-id (NOT--db-instance-id) when associating with instances
[MUST] Prerequisites for SRV address: (1) Cloud disk only; (2) Public SRV: allocate public address first; (3) Sharded cluster: allocate public on Mongos node (--node-id <s-xxx>) first; (4) Wait Running between each step
Check flow for sharded cluster public SRV:describe-sharding-network-address → if no public → allocate-public-network-address --node-id <mongos-s-xxx> → wait Running → allocate-db-instance-srv-network-address --srv-connection-type public → wait Running → confirm NodeType=logic with srv
[MUST] API Selection Rule for Network Address Query:
Replica Set: MUST use describe-replica-set-role
Sharded Cluster: MUST use describe-sharding-network-address
FORBIDDEN: DO NOT use describe-db-instance-attribute for network address queries — it does not return complete network info for sharded clusters. In results: NetworkType=Public=public; NodeType=logic+ConnectionType=SRV=SRV address
Renewal only applies to Subscription instances; auto-renewal takes effect the next day; no immediate charge on the day of activation. See references/operations.md for charge retry schedules.
[MUST] All operations below require instance status Running. Follow write operation response standard (§ Information Display Standards, item 5).
Detailed CLI commands and parameters: see references/operations.md § Additional Operations
Operation
CLI Command
Key Constraint
Restart instance
restart-db-instance
[MUST] confirm with user before executing: instance ID, expected ~30s disconnection; off-peak recommended
Restart node
restart-node --node-id --role-id
[MUST] confirm with user: instance ID + target node (RoleType/RoleId) before executing; Cloud disk only (StorageType=cloud_*), local disk → InsType.NotSupport; query RoleId via describe-role-zone-info (includes Hidden); describe-replica-set-role omits Hidden; sharded cluster requires both --node-id (e.g. d-xxx) AND --role-id
Manual backup
create-backup --backup-method
Cloud disk: must pass --backup-method Snapshot; local disk: Physical/Logical; cloud disk replica/sharded: --backup-retention-period (7-730 or -1 permanent); response use BackupJobId (NOT deprecated BackupId); poll via describe-backup-tasks then query describe-backups --backup-job-id; see operations.md
Query backups
describe-backups --start-time --end-time
Time: yyyy-MM-ddTHH:mmZ (UTC); response: Backups.Backup[]; filter by job: --backup-job-id
Query backup policy
describe-backup-policy
View retention days and window
Modify backup policy
modify-backup-policy
[MUST] always pass --preferred-backup-time AND --preferred-backup-period (required even when only changing other fields); query current values first via describe-backup-policy; sharded cluster cannot disable log backup
Upgrade major version
upgrade-db-instance-engine-version
One-way irreversible; query available versions first
Upgrade kernel version
upgrade-db-instance-kernel-version
Replica set & sharded cluster only (not standalone)
HA switchover
switch-db-instance-ha
[MUST] query nodes via describe-role-zone-info first; ask user which two nodes to swap roles (e.g. Primary↔Secondary, Secondary↔Hidden, etc.); sharded cluster: --node-id required
Create account
create-account
Cloud disk sharded cluster only; name: 3-16 chars lowercase
Query accounts
describe-accounts
List database accounts
Bind tags
tag-resources --resource-type INSTANCE
--resource-id space-separated list; --tag Key=<k> Value=<v> repeatable; up to 20 tags per instance; use --biz-region-id; see operations.md
Unbind tags
untag-resources --resource-type INSTANCE
Remove specific tag keys
Query tags
list-tag-resources --resource-type INSTANCE
[MUST] use list-tag-resources as the ONLY API for tag queries; FORBIDDEN: do NOT use DescribeDBInstances Tags field or describe-tags as substitute
Features Not Available via CLI
Feature
Description
KMS instance activation
After KMS instance creation, must be activated in KMS Console, configuring VPC/VSwitch
