Alibabacloud Mongodb Instances Manage

Alibaba Cloud MongoDB Instance Management

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.

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:

```bash

aliyun configure ai-mode enable

aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage"

```

[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:

>

1. No fabricated output: All displayed information must come from actual API query results. Speculation, fabrication, or splicing is strictly prohibited

2. Truncation handling: If API response is truncated (e.g., omitted), must re-query completely before displaying

3. Count validation: Displayed count must match TotalCount/actual count returned by API

4. No speculative time estimates: Do not provide time estimates without official documentation basis; only confirm status via API polling

5. Write operation response standard: After issuing any write operation (create, modify spec, cloud disk reconfiguration, add/delete node, etc.), only display RequestId (and DBInstanceId/OrderId if available), then ask the user whether to poll instance status. Do NOT start polling automatically before user confirmation.

6. 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

7. 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)

8. 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:

1. Call describe-db-instance-attribute to check DBInstanceStatus

2. 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

>

```bash

aliyun dds describe-db-instance-attribute --db-instance-id <id> --region <region> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage 2>&1 | grep '"DBInstanceStatus"'

```

Authentication

Pre-check: Alibaba Cloud Credentials Required

- NEVER read/echo/print AK/SK values (do NOT run echo $ALIBABA_CLOUD_ACCESS_KEY_ID)

- ONLY use aliyun configure list to check credential status

>

```bash

aliyun configure list

```

If no valid profile exists, obtain credentials from RAM Console and configure outside this session.

RAM Permissions

This skill requires the following RAM permissions. See references/ram-policies.md § Full Permission Quick Reference for the complete list.

[MUST] Permission error handling: When detecting Forbidden.RAM/NoPermission/Forbidden/SubAccountNoPermission:

1. Identify the missing permission (extract Action and Resource from the error message)

2. Guide the user to refer to references/ram-policies.md to request permissions

3. 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:

1. When the user has not specified a region, ask for the region first; do not iterate and search directly

2. 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

3. 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

4. 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

# 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

Cross-region lookup scripts and full-region scan scripts: see references/operations.md § Query Regions and Instances

Parameter Confirmation

[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:

[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

Full parameter confirmation format and required/optional parameter tables: see references/operations.md § Parameter Confirmation

Core Workflow

[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:

1. describe-rds-vpcs: Validate whether VPC ID exists and is available

2. describe-rds-vswitchs: Validate whether VSwitch ID exists in the specified VPC and matches the target zone

3. 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:

# 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

Detailed commands and parameters: see references/operations.md § Step 2: Query and Validate VPC and VSwitch

Create Replica Set Instance

- --db-instance-class must be queried via describe-available-resource (specs differ by region/zone/version/storage type)

- --zone-id must match the zone of --vswitch-id, otherwise InvalidVpcIdRegion.NotSupported error

- Multi-zone deployment requires --secondary-zone-id and --hidden-zone-id

aliyun dds create-db-instance \
  --biz-region-id <region> --zone-id <zone> --engine-version <ver> \
  --db-instance-class <class> --db-instance-storage <GB> \
  --vpc-id <vpc> --vswitch-id <vsw> --network-type VPC \
  --replication-factor 3 --storage-type cloud_essd1 --charge-type PostPaid \
  --db-instance-description <name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Optional: --secondary-zone-id --hidden-zone-id --readonly-replicas --encryption-key --resource-group-id
# Subscription: --charge-type PrePaid --period 1 --auto-renew true

Create Standalone Instance

- --replication-factor 1 --db-type replicate, storage type fixed to cloud_essd1

- Must use standalone-specific specs (ending with .1 like dds.sn2.large.1, or containing .single); cannot use replica set specs

- Not supported in some regions/zones; must query describe-available-resource --replication-factor 1 before creation

- When InvalidDBInstanceNodeCount error occurs, try other zones or suggest switching to replica set

aliyun dds create-db-instance ... --db-type replicate --replication-factor 1 \
  --db-instance-class <standalone-specific-spec> --storage-type cloud_essd1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Create Sharded Cluster Instance

- Minimum 2 Mongos and 2 Shards each (max 32); each Shard is a 3-node replica set by default

- --mongos / --replica-set parameters need to be repeated (specifying one node each time)

- Use --db-type sharding to query sharded cluster specs (--db-type normal is for replica sets only)

aliyun dds create-sharding-db-instance \
  --biz-region-id <region> --zone-id <zone> --engine MongoDB --engine-version <ver> \
  --vpc-id <vpc> --vswitch-id <vsw> --network-type VPC \
  --mongos Class=<class> --mongos Class=<class> \
  --replica-set Class=<class> ReadonlyReplicas=0 Storage=20 \
  --replica-set Class=<class> ReadonlyReplicas=0 Storage=20 \
  --config-server Class=<class> Storage=20 \
  --storage-type cloud_essd1 --charge-type PostPaid --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Instance Creation Error Diagnosis

Error diagnosis table: see references/operations.md § Instance Creation Error Diagnosis

Modify Replica Set Instance Configuration

[MUST] Before modification:

1. Query current configuration (describe-db-instance-attribute), extract DBInstanceStatus/DBInstanceClass/DBInstanceStorage/ReplicationFactor/ReadonlyReplicas/StorageType

2. Display "Current vs. New" comparison table and obtain user Y confirmation

3. 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

aliyun dds modify-db-instance-spec --db-instance-id <id> \
  [--db-instance-class <class>] [--db-instance-storage <GB>] \
  [--replication-factor 3/5/7] [--readonly-replicas 0-5] \
  [--order-type UPGRADE/DOWNGRADE] [--auto-pay true] \
  --effective-time Immediately/MaintainTime --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Full parameter description: see references/operations.md § Modify Replica Set Instance

Delete Instance

[MUST] Pre-deletion checklist:

1. Confirm ChargeType: PostPaid → can delete; PrePaid → cannot delete directly (wait expiry or console refund)

2. 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

3. [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

aliyun dds delete-db-instance --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Sharded Cluster Node Management

[MUST] Key limitations:

- Must retain at least 2 Mongos/Shards each, max 32

- New Shard configuration (spec + storage) must be ≥ the highest-configured existing Shard

- modify-node-spec strictly serial: must wait for previous modification to complete (Running) before issuing the next

- Batch modification modify-node-spec-batch does NOT support changing Shard readonly replica count; use individual modification instead

- When modifying multiple Shards, must confirm spec mapping and execution order with the user

- Storage in NodesInfo must be a numeric type (not string), otherwise InvalidParameter error

# Query sharded cluster node details (ShardList/MongosList contain NodeId)
aliyun dds describe-db-instance-attribute --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Add single node
aliyun dds create-node --db-instance-id <id> --node-type mongos/shard --node-class <class> [--node-storage <GB>] --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Batch add nodes (JSON format)
aliyun dds create-node-batch --db-instance-id <id> --nodes-info '{"Shards":[{"DBInstanceClass":"spec","Storage":40}],"Mongos":[{"DBInstanceClass":"spec"}]}' --auto-pay true --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Single node modification (strictly serial)
aliyun dds modify-node-spec --db-instance-id <id> --node-id <node-id> --node-class <class> [--node-storage <GB>] [--readonly-replicas 0-5] --effective-time Immediately/MaintainTime --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Batch modification (does not support readonly replica changes, requires DBInstanceName)
aliyun dds modify-node-spec-batch --db-instance-id <id> --nodes-info '{"Shards":[{"DBInstanceClass":"spec","DBInstanceName":"d-xxx","Storage":40}]}' --auto-pay true --effective-time Immediately --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Release node
aliyun dds delete-node --db-instance-id <id> --node-id <node-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Detailed command examples and NodesInfo format: see references/operations.md § Sharded Cluster Node Management

Cloud Disk Reconfiguration (Disk Type Upgrade)

[MUST] Independent from instance spec modification; used for disk type change or provisioned IOPS adjustment:

- Only supports ESSD PL1/PL2/PL3 → ESSD AutoPL (cloud_auto), one-way irreversible

- Prerequisite: Replica set storage > 40GB; Sharded cluster Shard storage > 40GB

- Provisioned IOPS range: 0~50000; interval between two modifications must be > 1 hour

- Before execution, must query and display MaxIOPS/MaxMBPS/StorageType, obtain user Y confirmation

- Do NOT execute before user confirmation

aliyun dds modify-db-instance-disk-type --db-instance-id <id> \
  --db-instance-storage-type cloud_auto [--provisioned-iops <0~50000>] \
  --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Full parameter description: see references/operations.md § Cloud Disk Reconfiguration

IOPS and Throughput Calculation Rules

[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

>

Full spec limit tables and calculation examples: see references/operations.md § IOPS and Throughput Calculation Rules

Reset root Password

[MUST] For sharded clusters, must ask the user before resetting password:

>

```

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 (!@#$%^&*()_+-=)

# Replica set / Standalone
aliyun dds reset-account-password --db-instance-id <id> --account-name root \
  --account-password <pwd> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Sharded cluster (--character-type db or cs, required)
aliyun dds reset-account-password --db-instance-id <id> --account-name root \
  --account-password <pwd> --character-type db --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

---

Instance Security Configuration

Manage IP Whitelist

[MUST] Before modifying whitelist:

1. First query current whitelist (describe-security-ips) and display to user

2. Ask for modification mode: Cover (overwrite, ⚠️ deletes existing IPs) / Append (add, errors on duplicate IPs) / Extend (extend, recommended)

3. Do NOT use Cover mode without asking the user

aliyun dds describe-security-ips --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds modify-security-ips --db-instance-id <id> --security-ips <IPs> --modify-mode Extend --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Specify group: add --security-ip-group-name <name>

Manage ECS Security Groups

Note: ECS security groups bound to sharded clusters only apply to Mongos nodes.

aliyun dds modify-security-group-configuration --db-instance-id <id> --security-group-id <sg-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds describe-security-group-configuration --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Manage Global Whitelist Templates

[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

# Create
aliyun dds create-global-security-ip-group --biz-region-id <region> --region <region> --global-ig-name <name> --gip-list <IPs> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Query
aliyun dds describe-global-security-ip-group --biz-region-id <region> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Associate with instance
aliyun dds modify-global-security-ip-group-relation --db-cluster-id <id> --global-security-group-id <gid> --biz-region-id <region> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

---

Manage Public Network Address

[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

# Allocate public address (add --node-id <s-xxx> for sharded clusters)
aliyun dds allocate-public-network-address --db-instance-id <id> [--node-id <s-xxx>] --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Release non-SRV public address
aliyun dds release-public-network-address --db-instance-id <id> [--node-id <s-xxx>] --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Release SRV public address (sharded cluster MUST use --node-id <mongos-id> + --connection-type SRV; omitting either causes InvalidParameters.Format)
aliyun dds release-public-network-address --db-instance-id <id> --node-id <s-xxx> --connection-type SRV --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Allocate SRV address (vpc=private, public=public; public SRV requires public network address first)
aliyun dds allocate-db-instance-srv-network-address --db-instance-id <id> --srv-connection-type vpc/public --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Query (replica set)
aliyun dds describe-replica-set-role --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Query (sharded cluster)
aliyun dds describe-sharding-network-address --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

---

Manage Instance Renewal

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.

# Manual renewal (--period: 1~9, 12, 24, 36 months)
aliyun dds renew-db-instance --db-instance-id <id> --period <months> --auto-pay true --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Enable auto-renewal (--duration required, in months)
aliyun dds modify-instance-auto-renewal-attribute --db-instance-id <id> --auto-renew true --duration 1 --biz-region-id <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Disable auto-renewal
aliyun dds modify-instance-auto-renewal-attribute --db-instance-id <id> --auto-renew false --biz-region-id <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Convert Instance Billing Type

Prerequisites: Instance status Running, not a legacy spec

[MUST] Use transform-instance-charge-type (NOT TransformToPrePaid — that API is forbidden)

# Pay-As-You-Go → Subscription
aliyun dds transform-instance-charge-type --instance-id <id> --charge-type PrePaid --period 1 --pricing-cycle Month --auto-pay true --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Subscription → Pay-As-You-Go (no period needed, may involve refund)
aliyun dds transform-instance-charge-type --instance-id <id> --charge-type PostPaid --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Manage Instance Maintenance Window

aliyun dds modify-db-instance-maintain-time --db-instance-id <id> --maintain-start-time "01:00Z" --maintain-end-time "02:00Z" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

---

Additional Operations

[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

Features Not Available via CLI

Verification Methods

See references/verification-method.md for details.

Best Practices

See references/operations.md § Best Practices for details.

References

Acceptance Criteria - MongoDB Instance Management

Scenario: MongoDB instance creation and management (Standalone/Replica Set/Sharded Cluster) Purpose: Skill test acceptance criteria

---

Correct CLI Command Patterns

1. Product — Verify product name exists

✅ CORRECT

aliyun dds create-db-instance ...

Product name dds is the correct identifier for ApsaraDB for MongoDB.

❌ INCORRECT

aliyun mongodb create-db-instance ...  # Wrong: product name should be dds
aliyun mongo create-db-instance ...    # Wrong: product name should be dds

2. Command — Verify command exists

✅ CORRECT (Plugin mode, using hyphens)

aliyun dds create-db-instance
aliyun dds describe-db-instances
aliyun dds describe-db-instance-attribute
aliyun dds delete-db-instance
aliyun dds describe-regions
aliyun dds describe-available-resource

❌ INCORRECT (Legacy API format)

aliyun dds CreateDBInstance            # Wrong: should use plugin mode
aliyun dds DescribeDBInstances         # Wrong: should use plugin mode

3. Parameters — Verify parameter names exist

✅ CORRECT (Using hyphen format)

--region-id cn-hangzhou
--zone-id cn-hangzhou-g
--engine-version "6.0"
--db-instance-class "dds.mongo.standard"
--db-instance-storage 20
--vpc-id "vpc-xxx"
--v-switch-id "vsw-xxx"
--replication-factor "3"
--storage-type cloud_essd1
--charge-type PostPaid
--user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT (CamelCase or wrong parameter names)

--RegionId cn-hangzhou                 # Wrong: should use --region-id
--ZoneId cn-hangzhou-g                 # Wrong: should use --zone-id
--EngineVersion "6.0"                  # Wrong: should use --engine-version
--DBInstanceClass "dds.mongo.standard" # Wrong: should use --db-instance-class
--VpcId "vpc-xxx"                      # Wrong: should use --vpc-id
--VSwitchId "vsw-xxx"                  # Wrong: should use --v-switch-id

4. User-Agent Flag — Verify inclusion is mandatory

✅ CORRECT

aliyun dds create-db-instance \
  --region-id cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT

aliyun dds create-db-instance \
  --region-id cn-hangzhou
# Missing --user-agent parameter

5. Parameter Values — Verify parameter value formats

EngineVersion (Database version)

✅ CORRECT: "8.0", "7.0", "6.0", "5.0", "4.4", "4.2", "4.0" ❌ INCORRECT: "3.4" (discontinued), "6" (missing minor version), 6.0 (should use quotes)

ReplicationFactor (Node count)

✅ CORRECT: "3", "5", "7" ❌ INCORRECT: "1", "2", "4", "6", 3 (should be wrapped in quotes as string)

ChargeType (Billing type)

✅ CORRECT: PostPaid, PrePaid ❌ INCORRECT: postpaid (wrong case), Postpaid (wrong case)

StorageType (Storage type)

✅ CORRECT: cloud_essd1, cloud_essd2, cloud_essd3, cloud_auto, local_ssd ❌ INCORRECT: essd, ssd, cloud_ssd

NetworkType (Network type)

✅ CORRECT: VPC ❌ INCORRECT: Classic (classic network no longer supports new instances), vpc (wrong case)

---

Command Validation Checklist

When validating CLI commands, check the following items:

---

API Response Validation

Successful instance creation response

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

Validation points:

• DBInstanceId is not empty
• RequestId exists

Query instance details response

{
  "DBInstances": {
    "DBInstance": [{
      "DBInstanceId": "dds-bp1234567890****",
      "DBInstanceStatus": "Running",
      "ReplicationFactor": "3",
      "EngineVersion": "6.0",
      "RegionId": "cn-hangzhou"
    }]
  }
}

Validation points:

• DBInstanceStatus is Running indicates instance is normal
• ReplicationFactor matches creation parameters
• EngineVersion matches creation parameters

---

Error Handling Patterns

Permission error

{
  "Code": "Forbidden.RAM",
  "Message": "User not authorized to operate on the specified resource."
}

Resolution: Check RAM permission policies and add required permissions

Parameter error

{
  "Code": "InvalidParameter",
  "Message": "The parameter xxx is invalid."
}

Resolution: Check if parameter names and values are correct

Insufficient resources

{
  "Code": "ResourceNotAvailable",
  "Message": "Resource you requested is not available in this region or zone."
}

Resolution: Switch availability zone or adjust instance specifications

---

Complete Command Example

The following is a complete, validated creation command example:

aliyun dds create-db-instance \
  --region-id cn-hangzhou \
  --zone-id cn-hangzhou-g \
  --engine-version "6.0" \
  --db-instance-class "dds.mongo.standard" \
  --db-instance-storage 20 \
  --vpc-id "vpc-bp175iuvg8nxqraf2****" \
  --v-switch-id "vsw-bp1gzt31twhlo0sa5****" \
  --network-type VPC \
  --replication-factor "3" \
  --storage-type cloud_essd1 \
  --charge-type PostPaid \
  --db-instance-description "my-mongodb-replica" \
  --user-agent AlibabaCloud-Agent-Skills

---

Pre-execution Validation

Before executing CLI commands, perform the following validation:

1. CLI version check

   aliyun version  # >= 3.3.1

2. Credential check

   aliyun configure list  # Confirm valid profile exists

3. Plugin check

   aliyun dds --help  # Confirm dds plugin is installed

4. Parameter confirmation

• All required parameters are provided
• Parameter values are within valid range
• Key parameters (RegionId, VpcId, etc.) confirmed with user

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Use directly for current session (no sudo or global install required)
./aliyun version

Linux

Note: Package manager installation (dpkg/rpm/yum) requires root privileges. Run as root or prepend your preferred privilege escalation method.

Debian/Ubuntu (dpkg)

# Download the latest Debian package
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.deb

# Install via dpkg (requires root)
dpkg -i aliyun-cli-linux-latest-amd64.deb

# Fix any dependency issues if needed
apt-get install -f

# Verify
aliyun version

CentOS/RHEL/Fedora (rpm/yum)

# Download the latest RPM package
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.rpm

# Install via rpm (requires root)
rpm -i aliyun-cli-linux-latest-amd64.rpm

# Or install via yum (handles dependencies, requires root)
yum localinstall aliyun-cli-linux-latest-amd64.rpm

# Verify
aliyun version

Without Root / Current Session Only

If you do not have root access, download and use the binary directly:

# Download binary tarball
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-linux-latest-amd64.tgz

# Use directly for current session (no installation required)
./aliyun version

ARM64 Architecture

# Debian/Ubuntu ARM64
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.deb
dpkg -i aliyun-cli-linux-latest-arm64.deb

# CentOS/RHEL ARM64
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.rpm
rpm -i aliyun-cli-linux-latest-arm64.rpm

# Or use binary tarball without root (ARM64)
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz
tar -xzf aliyun-cli-linux-latest-arm64.tgz
./aliyun version

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

MongoDB Instance Management - Detailed Operations Reference

This document contains detailed CLI command examples, parameter tables, and calculation spec tables extracted from SKILL.md.

---

Query Regions and Instances - Complete Scripts

Cross-region lookup for specific instance

INSTANCE_ID="dds-xxxxxxxxx"
REGIONS="cn-beijing cn-shanghai ap-southeast-1 us-west-1 us-east-1 cn-hangzhou cn-shenzhen cn-chengdu cn-hongkong cn-zhangjiakou"

for region in $REGIONS; do
  result=$(aliyun dds describe-db-instances \
    --db-instance-id $INSTANCE_ID \
    --biz-region-id $region \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage 2>&1 | grep '"DBInstanceId"')
  if [ ! -z "$result" ]; then
    instance_info=$(aliyun dds describe-db-instances \
      --db-instance-id $INSTANCE_ID \
      --biz-region-id $region \
      --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage)
    # Must use RegionId from the returned result as the actual region of the instance
    actual_region=$(echo "$instance_info" | jq -r '.DBInstances.DBInstance[0].RegionId')
    echo "Instance $INSTANCE_ID is located in region $actual_region"
    echo "$instance_info" | jq '.DBInstances.DBInstance[0]'
    break
  fi
done

Query instances across all regions

aliyun dds describe-regions --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage 2>&1 | \
  grep '"RegionId"' | sed 's/.*"RegionId": "\([^"]*\)".*/\1/' | \
  while read region; do
    echo "=== $region ==="
    aliyun dds describe-db-instances \
      --biz-region-id $region \
      --page-size 10 \
      --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage 2>&1 | \
      grep -E '"DBInstanceId"|"DBInstanceType"' | head -4
  done

---

Core Workflow - Detailed Steps

Step 0 (Optional): Create Resource Group

# Query existing resource groups
aliyun resourcemanager list-resource-groups --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Create new resource group
aliyun resourcemanager create-resource-group \
  --name "mongodb-project" \
  --display-name "MongoDB Project Resource Group" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Limit: A single Alibaba Cloud account can create up to 30 resource groups.

Step 0.5 (Optional): Create KMS Instance

KMS instances are created via Alibaba Cloud BSS OpenAPI, not directly through the KMS API.

# Subscription (China site)
aliyun bssopenapi create-instance \
  --product-code kms \
  --product-type kms_ddi_public_cn \
  --subscription-type Subscription \
  --period 12 \
  --renewal-status ManualRenewal \
  --parameter '[{"Code":"ProductVersion","Value":"3"},{"Code":"Region","Value":"cn-hangzhou"},{"Code":"Spec","Value":"1000"},{"Code":"KeyNum","Value":"1000"},{"Code":"SecretNum","Value":"0"},{"Code":"VpcNum","Value":"1"},{"Code":"log","Value":"0"}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

KMS ProductType Reference:

Important: After KMS instance creation, it must be activated in the KMS Console (configure VPC/VSwitch). This step only supports console operation.

Step 0.6 (Optional): Cloud Disk Encryption Configuration

KMS Key Region Constraint: Must be in the same region as the MongoDB instance.

Check Flow:

# Query KMS keys
aliyun kms list-keys --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Query KMS instances
aliyun kms list-kms-instances --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Create key (default key / software key)
aliyun kms create-key \
  --description "MongoDB cloud disk encryption key" \
  --key-spec Aliyun_AES_256 \
  --key-usage ENCRYPT/DECRYPT \
  --protection-level SOFTWARE \
  --region <region> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Step 1: Query Available Specifications

# Replica set specs (--db-type normal or omit)
aliyun dds describe-available-resource \
  --biz-region-id cn-hangzhou \
  --zone-id cn-hangzhou-g \
  --db-type normal \
  --engine-version 7.0 \
  --storage-type cloud_essd1 \
  --replication-factor 3 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Sharded cluster specs (--db-type sharding)
aliyun dds describe-available-resource \
  --biz-region-id cn-hangzhou \
  --zone-id cn-hangzhou-g \
  --db-type sharding \
  --engine-version 6.0 \
  --storage-type cloud_essd1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Standalone specs (--replication-factor 1)
aliyun dds describe-available-resource \
  --biz-region-id cn-hangzhou \
  --zone-id cn-hangzhou-g \
  --db-type normal \
  --replication-factor 1 \
  --engine-version 6.0 \
  --storage-type cloud_essd1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Note: --db-type only supports normal and sharding; mongos/shard will cause InvalidDbType error.

Step 2: Query and Validate VPC and VSwitch

# Query VPC list for specified zone (DDS-specific API, also returns VSwitches under VPC)
aliyun dds describe-rds-vpcs --zone-id cn-hangzhou-g --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query VSwitch list under specified VPC
aliyun dds describe-rds-vswitchs \
  --vpc-id vpc-bp191olzz22cgl073**** \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query VSwitches in specified zone
aliyun dds describe-rds-vswitchs \
  --vpc-id vpc-bp191olzz22cgl073**** \
  --zone-id cn-hangzhou-g \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Alternative: Generic VPC API query
aliyun vpc describe-vpcs --region-id cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun vpc describe-vswitches --region-id cn-hangzhou --vpc-id vpc-xxx --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

When VPC/VSwitch does not exist: 1. Notify user which ID does not exist, show query results as evidence 2. Query available resources in the target zone via describe-rds-vpcs / describe-rds-vswitchs 3. Present available VPC/VSwitch options to the user and ask them to select one 4. If no VPC/VSwitch is available in the target zone, inform the user that VPC/VSwitch creation is outside the scope of this skill and guide them to create VPC/VSwitch through the Alibaba Cloud console or administrator before retrying

Note: This skill manages MongoDB instances only. VPC and VSwitch creation require separate permissions and are not handled by this skill.

---

Parameter Confirmation - Complete Format

Pre-creation parameter confirmation format

═══════════════════════════════════════════════════════════════
          About to create MongoDB instance, please confirm parameters
═══════════════════════════════════════════════════════════════

[Basic Configuration]
  Region:                      cn-hangzhou
  Zone:                        cn-hangzhou-g
  Database Engine Version:     6.0
  Instance Type:               Replica Set

[Spec Configuration]
  Instance Class:              mdb.shard.4x.large.d
  Storage:                     40 GB
  Primary/Secondary Nodes:     3
  Readonly Nodes:              0

[Network Configuration]
  VPC ID:                      vpc-bp1xxxxxx
  VSwitch ID:                  vsw-bp1xxxxxx

[Other Configuration]
  Billing Type:                Pay-As-You-Go
  Instance Description:        test-mongodb
  Storage Type:                cloud_essd1

═══════════════════════════════════════════════════════════════
Please confirm the above parameters? (Enter Y to confirm, N to cancel and reconfigure):
═══════════════════════════════════════════════════════════════

Required Parameters

Optional Parameters

---

IOPS and Throughput Calculation Rules

Note: When displaying to users, baseline IOPS/throughput must use the MaxIOPS/MaxMBPS fields returned by the API, not formula-calculated values (actual values may include bonus storage, so actual ≥ calculated).

Formulas (reference):

• IOPS = min{ 1800 + 50×StorageGB, Spec IOPS Limit, Disk Type IOPS Limit }
• Throughput = min{ 120 + 0.5×StorageGB, Spec Throughput Limit, Disk Type Throughput Limit }

Cloud Disk Type Performance Limits

Dedicated Cloud Disk Spec IOPS/Throughput Limits

General-purpose Cloud Disk Spec IOPS/Throughput Limits

Calculation Examples

Example 1 (Storage-limited): Spec mdb.shard.2x.2xlarge.c (8C16GB general-purpose, 26250/256), Storage 20GB, cloud_essd1 (50000/350)

IOPS = min{1800+50×20, 26250, 50000} = min{2800, 26250, 50000} = 2800 (storage-limited)
Throughput = min{120+0.5×20, 256, 350} = 130 MB/s

Example 2 (Spec-limited): Spec mdb.shard.4x.large.d (2C8GB dedicated, 10000/128), Storage 500GB, cloud_essd1

IOPS = min{1800+50×500, 10000, 50000} = 10000 (spec-limited)
Throughput = min{120+0.5×500, 128, 350} = 128 MB/s (spec-limited)

---

Sharded Cluster Node Management - Detailed Commands

Query Node Information

# Query sharded cluster node details (ShardList/MongosList contain NodeId)
aliyun dds describe-db-instance-attribute \
  --db-instance-id dds-bp1sharding1234**** \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Batch Add Nodes - NodesInfo Format

# Batch add Shards
aliyun dds create-node-batch \
  --region ap-southeast-1 \
  --db-instance-id dds-t4nf2082c9293ba4 \
  --nodes-info '{"Shards":[{"DBInstanceClass":"mdb.shard.4x.xlarge.d","Storage":300},{"DBInstanceClass":"mdb.shard.4x.xlarge.d","Storage":300}]}' \
  --auto-pay true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Batch add Mongos
aliyun dds create-node-batch \
  --region ap-southeast-1 \
  --db-instance-id dds-t4n098c8f691fda4 \
  --nodes-info '{"Mongos":[{"DBInstanceClass":"mdb.shard.2x.xlarge.d"},{"DBInstanceClass":"mdb.shard.2x.xlarge.d"}]}' \
  --auto-pay true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Add Shards and Mongos simultaneously
aliyun dds create-node-batch \
  --region ap-southeast-1 \
  --db-instance-id dds-t4n098c8f691fda4 \
  --nodes-info '{"Shards":[{"DBInstanceClass":"mdb.shard.4x.xlarge.d","Storage":40,"ReadonlyReplicas":0}],"Mongos":[{"DBInstanceClass":"mdb.shard.2x.xlarge.d"}]}' \
  --auto-pay true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Batch Modify Node Specs - NodesInfo Format (requires DBInstanceName)

# Batch modify Shard specs (Storage must be numeric, not string)
aliyun dds modify-node-spec-batch \
  --region ap-southeast-1 \
  --db-instance-id dds-t4n098c8f691fda4 \
  --nodes-info '{"Shards":[{"DBInstanceClass":"mdb.shard.4x.xlarge.d","DBInstanceName":"d-t4n948d542391c84","Storage":40},{"DBInstanceClass":"mdb.shard.4x.xlarge.d","DBInstanceName":"d-t4n0c21a1daa00d4","Storage":40}]}' \
  --auto-pay true \
  --effective-time "Immediately" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Batch modify Mongos specs
aliyun dds modify-node-spec-batch \
  --region ap-southeast-1 \
  --db-instance-id dds-t4n098c8f691fda4 \
  --nodes-info '{"Mongos":[{"DBInstanceClass":"mdb.shard.4x.large.d","DBInstanceName":"s-t4n5062340aa8414"},{"DBInstanceClass":"mdb.shard.4x.large.d","DBInstanceName":"s-t4n37229302a2124"}]}' \
  --auto-pay true \
  --effective-time "Immediately" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Prerequisites for Releasing Nodes

Before releasing a Shard, confirm: 1. Remaining Shards ≥ 2 2. MongoDB Balancer is enabled 3. Remaining Shards have sufficient storage (data will be migrated when a Shard is released) 4. If duplicated key error occurs, clean orphaned documents first

---

Modify Replica Set Instance - Detailed Parameter Description

Modifiable Items

Complete Modification Commands

# Upgrade spec (Pay-As-You-Go, immediate effect)
aliyun dds modify-db-instance-spec \
  --db-instance-id dds-bp1ee12ad351**** \
  --db-instance-class "mdb.shard.4x.large.d" \
  --db-instance-storage 40 \
  --effective-time "Immediately" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Upgrade spec (Subscription)
aliyun dds modify-db-instance-spec \
  --db-instance-id dds-bp1ee12ad351**** \
  --db-instance-class "mdb.shard.4x.large.d" \
  --db-instance-storage 40 \
  --order-type "UPGRADE" \
  --auto-pay true \
  --effective-time "MaintainTime" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Change node count
aliyun dds modify-db-instance-spec \
  --db-instance-id dds-bp1ee12ad351**** \
  --replication-factor "5" \
  --effective-time "MaintainTime" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Change readonly node count
aliyun dds modify-db-instance-spec \
  --db-instance-id dds-bp1ee12ad351**** \
  --readonly-replicas "2" \
  --effective-time "Immediately" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Effective time: Immediately = immediate; MaintainTime = during maintenance window

Modification status: In progress = DBInstanceClassChanging; Complete = Running

Note: The OrderId returned from modification is for billing only. Do NOT use bssopenapi GetOrderDetail to query modification status.

---

Cloud Disk Reconfiguration - Complete Parameter Description

After reconfiguration: DBInstanceStatus=Running, StorageType=cloud_auto, ProvisionedIops set to configured value.

---

Security Configuration - Complete Command Examples

IP Whitelist Complete Examples

# Cover mode (high risk)
aliyun dds modify-security-ips --db-instance-id dds-xxx --security-ips "192.168.1.100,10.0.0.0/24" --modify-mode Cover --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Append mode (errors on duplicate IPs)
aliyun dds modify-security-ips --db-instance-id dds-xxx --security-ips "192.168.1.101" --modify-mode Append --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Extend mode (recommended, auto-merges duplicate IPs)
aliyun dds modify-security-ips --db-instance-id dds-xxx --security-ips "192.168.1.102" --modify-mode Extend --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Specify group
aliyun dds modify-security-ips --db-instance-id dds-xxx --security-ips "192.168.0.0/24" \
  --security-ip-group-name "app-servers" --security-ip-group-attribute "production" \
  --modify-mode Cover --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Global Whitelist Complete Examples

# Create
aliyun dds create-global-security-ip-group --biz-region-id cn-hangzhou --region cn-hangzhou \
  --global-ig-name "commonaccess" --gip-list "192.168.0.0/16,10.0.0.0/8" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Modify
aliyun dds modify-global-security-ip-group --biz-region-id cn-hangzhou --region cn-hangzhou \
  --global-security-group-id "g-sg-xxx" --global-ig-name "commonaccess" \
  --gip-list "192.168.0.0/16,10.0.0.0/8,172.16.0.0/12" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Delete
aliyun dds delete-global-security-ip-group --biz-region-id cn-hangzhou --region cn-hangzhou \
  --global-security-group-id "g-sg-xxx" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Naming convention: Template name must start and end with a letter, can only contain lowercase letters, digits, and underscores, length 2~120 characters.

---

Renewal - Complete Parameter Description

When --auto-pay false, payment must be completed in console: Billing > Billing & Cost Management > Orders > My Orders.

---

Billing Type Conversion - Complete Parameter Description

---

Instance Creation Error Diagnosis

Best Practices

1. Choose the same region as ECS, use VPC network to reduce network latency 2. Multi-zone deployment for production (--secondary-zone-id + --hidden-zone-id) 3. Storage type: ESSD PL2/PL3 for high performance, ESSD PL1/AutoPL for cost-sensitive scenarios 4. Password: At least three of uppercase/lowercase/digits/special characters, 8-32 characters; sharded clusters require separate password reset for db and cs nodes 5. Whitelist: 0.0.0.0/0 is prohibited in production; prefer Extend mode for whitelist modifications

---

Delete Instance - Pre-deletion Checklist

[MUST] Step 1: Confirm ChargeType

- PostPaid: can delete directly

- PrePaid: cannot delete — must wait for expiry or request refund via console

>

[MUST] Step 2 (Cloud disk instances only): Check BackupRetentionPolicyOnClusterDeletion

>

| Value | Meaning |

|-------|---------|

| 0 | Delete all backups immediately when instance is released |

| 1 | Auto-backup on release, keep last backup only (long-term retention) |

| 2 | Auto-backup on release, keep all backups (long-term retention) |

>

Query current policy, then ask the user if they want to change it before deleting:

- Only applies to cloud disk replica set / sharded cluster (StorageType=cloud_*)

- Local disk instances (local_ssd) do not support this field

- Retention cost: free for first 7 days after release; charged after 7 days (see pricing in help docs)

>

[MUST] Step 3: Final confirmation

Display instance ID, region, billing type, irreversible warning; require user to reply "confirm delete {instance ID}"

# Step 1: Check billing type
aliyun dds describe-db-instance-attribute --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage | jq '.DBInstances.DBInstance[0] | {DBInstanceId, ChargeType, StorageType}'

# Step 2 (cloud disk only): Check current backup retention policy on deletion
aliyun dds describe-backup-policy --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage | jq '{BackupRetentionPolicyOnClusterDeletion}'

# Step 2b (if user wants to change): Modify backup retention policy before deletion
# **[MUST]** modify-backup-policy requires --preferred-backup-time AND --preferred-backup-period even when only changing backup-retention-policy-on-cluster-deletion
# First query current values via describe-backup-policy, then pass them through unchanged
aliyun dds modify-backup-policy --db-instance-id <id> \
  --backup-retention-policy-on-cluster-deletion 2 \
  --preferred-backup-time "<current-value>" \
  --preferred-backup-period "<current-value>" \
  --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Step 3: Delete instance (PostPaid only)
aliyun dds delete-db-instance --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Additional Operations

Restart Instance / Node

Constraints:

- Instance must be in Running status

- Restart causes approximately 30 seconds of disconnection

- Recommended during off-peak hours or maintenance window

- restart-db-instance: Restarts the entire instance; supports optional --node-id for sharded cluster to restart a specific node (e.g., s-xxx, d-xxx)

- restart-node: Restarts an individual node, requires both --node-id and --role-id (both are required parameters); supports replica set and sharded cluster (not standalone)

- [MUST] restart-node only supports cloud disk instances (StorageType=cloud_*); local disk instances (local_ssd) return InsType.NotSupport — use restart-db-instance instead

- Sharded cluster: both --node-id (shard NodeId, e.g. d-xxx, from describe-db-instance-attribute) AND --role-id are required; omitting --node-id returns InvalidParameter: NodeId is not valid

- Query RoleId: [MUST] use describe-role-zone-info for all instance types — this returns ALL nodes including Hidden; describe-replica-set-role only returns Primary/Secondary and does NOT include Hidden node

# Restart entire instance
aliyun dds restart-db-instance --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Restart sharded cluster specific node via restart-db-instance (optional --node-id)
aliyun dds restart-db-instance --db-instance-id <id> --node-id <node-id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Restart specific node (replica set or sharded cluster, both --node-id and --role-id required)
# **[MUST]** Query RoleId via describe-role-zone-info (returns ALL nodes including Hidden)
# describe-replica-set-role does NOT return Hidden node
aliyun dds describe-role-zone-info --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds restart-node --db-instance-id <id> --node-id <node-id> --role-id <role-id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Backup Management

Backup method by instance type:

>

| Instance Type | Storage Type | Supported BackupMethod |

|--------------|-------------|----------------------|

| Replica Set / Sharded Cluster | Cloud disk (cloud_*) | Snapshot only |

| Replica Set / Sharded Cluster | Local disk (local_ssd) | Physical (default) / Logical |

| Standalone | Any | Snapshot (fixed, no parameter needed) |

>

[MUST] Cloud disk instances (StorageType starts with cloud_) must use --backup-method Snapshot. Using Physical/Logical will fail.

>

⚠️ WARNING: Cloud disk instances must explicitly pass --backup-method Snapshot. If omitted, the default is Physical, which causes IncorrectBackupSetMethod error on cloud disk instances.

>

Time format: yyyy-MM-ddTHH:mmZ (UTC time)

>

Backup retention: 7-730 days, or -1 for permanent retention

>

`--backup-retention-period` parameter:

- Applicable to cloud disk replica set and sharded cluster only (not standalone, not local disk)

- If omitted: follows the default retention policy configured in the backup policy

- Values: 7-730 (days) or -1 (permanent retention)

- Use when user specifies a custom retention period or requests permanent retention

>

create-backup response:

- Use BackupJobId field (NOT BackupId — that field is deprecated)

- BackupJobId is used to poll describe-backup-tasks and query describe-backups

>

Post-creation polling flow:

1. Call describe-backup-tasks → poll field BackupJobs[].BackupjobId (note: lowercase j) until job disappears from list (means completed)

- Response structure: BackupJobs[].BackupSetStatus / .Progress / .BackupjobId (int, not string)

2. Once completed, call describe-backups --backup-job-id <BackupJobId> to retrieve the final backup record

- Response structure: Backups.Backup[] (NOT Items.Backup)

- The BackupId in describe-backups is a different value from BackupJobId

# Create manual backup — cloud disk instance (Snapshot only, default retention)
aliyun dds create-backup --db-instance-id <id> --backup-method Snapshot --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Response: { "BackupJobId": "xxx", ... }  ← use BackupJobId (BackupId is deprecated)

# Create manual backup — cloud disk replica set/sharded cluster with custom retention (7-730 days or -1 for permanent)
aliyun dds create-backup --db-instance-id <id> --backup-method Snapshot --backup-retention-period 30 --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds create-backup --db-instance-id <id> --backup-method Snapshot --backup-retention-period -1 --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Create manual backup — local disk instance (Physical or Logical)
aliyun dds create-backup --db-instance-id <id> --backup-method Physical --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Poll backup task status (until job disappears from list = completed)
aliyun dds describe-backup-tasks --db-instance-id <id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Response: BackupJobs[].BackupjobId (int, lowercase j) / .BackupSetStatus / .Progress

# Query final backup record by BackupJobId
aliyun dds describe-backups --db-instance-id <id> --backup-job-id <BackupJobId> --start-time "<BackupStartTime - buffer>" --end-time "<BackupEndTime + buffer>" --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Response: Backups.Backup[] (NOT Items.Backup)

# Query backup list by time range
aliyun dds describe-backups --db-instance-id <id> --start-time "2025-01-01T00:00Z" --end-time "2025-12-31T23:59Z" --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query backup list — sharded cluster (must specify --node-id for the shard node)
aliyun dds describe-backups --db-instance-id <sharding-id> --node-id <shard-d-xxx> --start-time "2025-01-01T00:00Z" --end-time "2025-12-31T23:59Z" --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query backup policy
aliyun dds describe-backup-policy --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Modify backup policy — set retention days and preferred backup window
aliyun dds modify-backup-policy --db-instance-id <id> \
  --backup-retention-period 30 \
  --preferred-backup-time "03:00Z-04:00Z" \
  --preferred-backup-period "Monday,Wednesday,Friday" \
  --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Modify backup policy — enable log backup (sharded cluster cannot disable)
aliyun dds modify-backup-policy --db-instance-id <id> \
  --enable-backup-log 1 \
  --log-backup-retention-period 30 \
  --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Modify backup policy — enable high-frequency backup
aliyun dds modify-backup-policy --db-instance-id <id> \
  --backup-interval 30 \
  --snapshot-backup-type Flash \
  --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

ModifyBackupPolicy key parameters:

Parameter dependency: When modifying --preferred-backup-time, must also pass --preferred-backup-period in the same request. Otherwise the API returns InvalidParameter: PreferredBackupPeriod is not valid.

Flash high-frequency backup — cloud disk only: --snapshot-backup-type Flash is only effective on cloud disk instances (StorageType starts with cloud_). Local disk instances (local_ssd) calling with --snapshot-backup-type Flash will not return an error, but the setting is silently ignored and does not take effect.

Cross-region backup (only for cloud disk replica set / sharded cluster): Use --cross-backup-type, --src-region, --dest-region parameters. See official documentation for details.

>

Cross-region backup is asynchronous: Enabling or deleting cross-region backup is an async operation that requires backend processing time. When deleting cross-region backup, the request may return DBS.Cross.Backup.BuyInstance.Failed if backend route registration has not completed. In this case, wait and retry after a short interval.

DescribeBackupPolicy key return fields:

Local disk vs cloud disk return field differences: Local disk instances (local_ssd) do not return the following fields: BackupRetentionPolicyOnClusterDeletion, HighFrequencyBackupRetention, PreserveOneEachHour. These fields are only present in cloud disk instance responses.

Advanced backup mode (AdvancedBackup): Cloud disk sharded cluster instances support high-frequency backup (Flash snapshot). When enabled via --backup-interval and --snapshot-backup-type Flash, the backup policy returns additional fields such as HighFrequencyBackupRetention. Use describe-backup-policy to check the current advanced backup configuration.

Important: Once a cloud disk instance is upgraded to AdvancedBackup mode, the standard describe-backup-policy and modify-backup-policy commands become unavailable (returns BackupTypeAlreadyUpgrade error). Use DescribeAdvancedBackupPolicy / ModifyAdvancedBackupPolicy API instead. Note: these advanced backup commands are not yet available in the CLI.

Version Upgrade

UpgradeDBInstanceEngineVersion (major version upgrade):

- One-way irreversible (cannot downgrade)

- Instance will automatically restart 2-3 times during upgrade

- Applicable to all instance types (replica set, sharded cluster, standalone)

- [MUST] Query available versions via DescribeAvailableEngineVersion before upgrade

- Recommended to create a backup before upgrading

- Must execute during off-peak hours

>

UpgradeDBInstanceKernelVersion (kernel/minor version upgrade):

- Minor version patch with single restart

- Only supports replica set and sharded cluster (NOT standalone)

- No version number parameter needed — auto-selects latest available kernel version

- --switch-mode: 0 = immediate (default), 1 = during maintenance window

>

DescribeAvailableEngineVersion:

- Returns list of versions the instance can upgrade to

- Empty result means instance is already on the latest version

- Versions must be upgraded sequentially (e.g., 4.2→5.0→6.0, NOT 4.2→6.0 directly)

# Query available upgrade versions for an instance
aliyun dds describe-available-engine-version --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# Empty EngineVersions list = already on latest version

# Upgrade major engine version (e.g., 5.0 → 6.0) — will restart 2-3 times
aliyun dds upgrade-db-instance-engine-version --db-instance-id <id> --engine-version <target-version> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Upgrade kernel (minor) version — auto-selects latest, single restart
aliyun dds upgrade-db-instance-kernel-version --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Upgrade kernel version during maintenance window
aliyun dds upgrade-db-instance-kernel-version --db-instance-id <id> --switch-mode 1 --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

HA Switchover

Constraints:

- Triggers primary/secondary role switch with brief connectivity interruption

- [MUST] Must confirm with user before execution

- Only applicable to replica set and sharded cluster instances (NOT standalone)

- Replica set: --node-id is NOT required — switches primary/secondary at instance level

- Sharded cluster: --node-id is REQUIRED — specifies the shard ID (d-xxx) to perform switchover

- --role-ids (optional): comma-separated role IDs to switch; if omitted, all roles switched

- --switch-mode: 0 = immediate (default), 1 = during maintenance window

# HA switchover — replica set (no --node-id needed)
aliyun dds switch-db-instance-ha --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# HA switchover — sharded cluster (--node-id specifies shard ID d-xxx)
aliyun dds switch-db-instance-ha --db-instance-id <id> --node-id <shard-d-xxx> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# HA switchover during maintenance window
aliyun dds switch-db-instance-ha --db-instance-id <id> --switch-mode 1 --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Account Management

CreateAccount scope: Only for cloud disk sharded cluster instances (creates Shard accounts).

For replica set/standalone, use reset-account-password for root account (see SKILL.md § Reset root Password).

>

AccountName rules: 3-16 characters, lowercase letters + digits + underscores, must start with a lowercase letter. Created accounts have read-only permission.

>

⚠️ Reserved keywords: Some names (e.g., test, admin, root) are reserved and will return InvalidAccountName.Forbid error. Choose a different name if this occurs.

>

AccountPassword rules: 8-32 characters, must contain at least three of: uppercase/lowercase/digits/special characters (!@#$%^&*()_+-=)

>

ModifyAccountDescription: Does NOT support sharded cluster instances. Only for replica set/standalone root account.

# Create database account (cloud disk sharded cluster only)
aliyun dds create-account --db-instance-id <id> --account-name <name> --account-password <pwd> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Create database account with description (--account-description is optional)
aliyun dds create-account --db-instance-id <id> --account-name <name> --account-password <pwd> --account-description <desc> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query database accounts
aliyun dds describe-accounts --db-instance-id <id> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Modify account description (replica set/standalone only, NOT sharded cluster)
aliyun dds modify-account-description --db-instance-id <id> --account-name root --account-description <desc> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Tag Management

Constraints:

- Up to 20 tags per instance

- --resource-type must be INSTANCE

- Tag key and value: max 128 characters each

- Tags are auto-created if they don't exist; duplicate keys overwrite existing values

- When a tag is unbound from all instances, it is automatically deleted

# Bind tags to instance (--resource-id takes space-separated list; --tag takes Key=<k> Value=<v>, repeatable)
aliyun dds tag-resources --biz-region-id <region> --resource-type INSTANCE --resource-id <instance-id> --tag Key=<key> Value=<value> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Bind multiple tags to multiple instances
aliyun dds tag-resources --biz-region-id <region> --resource-type INSTANCE --resource-id <id1> <id2> --tag Key=<k1> Value=<v1> --tag Key=<k2> Value=<v2> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Unbind specific tags from instance (--tag-key takes space-separated list)
aliyun dds untag-resources --biz-region-id <region> --resource-type INSTANCE --resource-id <instance-id> --tag-key <key> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Unbind ALL tags from instance
aliyun dds untag-resources --biz-region-id <region> --resource-type INSTANCE --resource-id <instance-id> --all true --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query tags bound to specific instance
aliyun dds list-tag-resources --biz-region-id <region> --resource-type INSTANCE --resource-id <instance-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query instances by tag key/value
aliyun dds list-tag-resources --biz-region-id <region> --resource-type INSTANCE --tag Key=<key> Value=<value> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

# Query all existing tags
aliyun dds describe-tags --biz-region-id <region> --resource-type INSTANCE --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Note: For list-tag-resources, must provide at least one of --resource-id or --tag.

RAM Policies - MongoDB Instance Management

This document lists the RAM permission policies required for MongoDB instance management (Standalone/Replica Set/Sharded Cluster), covering all operations throughout the instance lifecycle.

Required Permissions

Core Permissions (Required for instance creation)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dds:CreateDBInstance",
        "dds:DescribeDBInstances",
        "dds:DescribeDBInstanceAttribute",
        "dds:DescribeRegions",
        "dds:DescribeAvailableResource"
      ],
      "Resource": "*"
    }
  ]
}

VPC Network Permissions (Query VPC and VSwitch)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcs",
        "vpc:DescribeVSwitches"
      ],
      "Resource": "*"
    }
  ]
}

KMS Key Management Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateKey",
        "kms:ListKeys",
        "kms:DescribeKey"
      ],
      "Resource": "*"
    }
  ]
}

Resource Group Management Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "rm:CreateResourceGroup",
        "rm:ListResourceGroups",
        "rm:GetResourceGroup"
      ],
      "Resource": "*"
    }
  ]
}

BssOpenApi Permissions (Create KMS instance)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bss:CreateInstance",
        "bss:QueryAvailableInstances",
        "bss:DescribePricingModule"
      ],
      "Resource": "*"
    }
  ]
}

Instance Management Permissions (Full management)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dds:CreateDBInstance",
        "dds:CreateShardingDBInstance",
        "dds:DeleteDBInstance",
        "dds:DescribeDBInstances",
        "dds:DescribeDBInstanceAttribute",
        "dds:DescribeRegions",
        "dds:DescribeAvailableResource",
        "dds:DescribeRdsVpcs",
        "dds:DescribeRdsVSwitchs",
        "dds:ModifyDBInstanceSpec",
        "dds:ModifyDBInstanceDiskType",
        "dds:ModifyDBInstanceDescription",
        "dds:ModifyDBInstanceMaintainTime",
        "dds:RestartDBInstance",
        "dds:ResetAccountPassword",
        "dds:ModifySecurityIps",
        "dds:DescribeSecurityIps",
        "dds:ModifySecurityGroupConfiguration",
        "dds:DescribeSecurityGroupConfiguration",
        "dds:CreateGlobalSecurityIPGroup",
        "dds:DescribeGlobalSecurityIPGroup",
        "dds:ModifyGlobalSecurityIPGroup",
        "dds:DeleteGlobalSecurityIPGroup",
        "dds:ModifyDBInstanceGlobalSecurityIPGroup",
        "dds:AllocatePublicNetworkAddress",
        "dds:ReleasePublicNetworkAddress",
        "dds:AllocateDBInstanceSrvNetworkAddress",
        "dds:DescribeReplicaSetRole",
        "dds:DescribeShardingNetworkAddress",
        "dds:RenewDBInstance",
        "dds:TransformInstanceChargeType",
        "dds:ModifyInstanceAutoRenewalAttribute",
        "dds:CreateNode",
        "dds:CreateNodeBatch",
        "dds:ModifyNodeSpec",
        "dds:ModifyNodeSpecBatch",
        "dds:DeleteNode"
      ],
      "Resource": "*"
    }
  ]
}

Network Security Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dds:ModifySecurityIps",
        "dds:DescribeSecurityIps"
      ],
      "Resource": "*"
    }
  ]
}

Backup and Restore Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dds:DescribeBackups",
        "dds:CreateBackup"
      ],
      "Resource": "*"
    }
  ]
}

Account Management Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dds:ResetAccountPassword"
      ],
      "Resource": "*"
    }
  ]
}

Tag Management Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dds:TagResources",
        "dds:UntagResources",
        "dds:ListTagResources"
      ],
      "Resource": "*"
    }
  ]
}

Complete Permission Policy

The following is the complete policy containing all permissions required for MongoDB instance management:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dds:CreateDBInstance",
        "dds:CreateShardingDBInstance",
        "dds:DeleteDBInstance",
        "dds:DescribeDBInstances",
        "dds:DescribeDBInstanceAttribute",
        "dds:DescribeRegions",
        "dds:DescribeAvailableResource",
        "dds:DescribeRdsVpcs",
        "dds:DescribeRdsVSwitchs",
        "dds:ModifyDBInstanceSpec",
        "dds:ModifyDBInstanceDiskType",
        "dds:ModifyDBInstanceDescription",
        "dds:ModifyDBInstanceMaintainTime",
        "dds:RestartDBInstance",
        "dds:ResetAccountPassword",
        "dds:ModifySecurityIps",
        "dds:DescribeSecurityIps",
        "dds:ModifySecurityGroupConfiguration",
        "dds:DescribeSecurityGroupConfiguration",
        "dds:CreateGlobalSecurityIPGroup",
        "dds:DescribeGlobalSecurityIPGroup",
        "dds:ModifyGlobalSecurityIPGroup",
        "dds:DeleteGlobalSecurityIPGroup",
        "dds:ModifyDBInstanceGlobalSecurityIPGroup",
        "dds:AllocatePublicNetworkAddress",
        "dds:ReleasePublicNetworkAddress",
        "dds:AllocateDBInstanceSrvNetworkAddress",
        "dds:DescribeReplicaSetRole",
        "dds:DescribeShardingNetworkAddress",
        "dds:RenewDBInstance",
        "dds:TransformInstanceChargeType",
        "dds:ModifyInstanceAutoRenewalAttribute",
        "dds:CreateNode",
        "dds:CreateNodeBatch",
        "dds:ModifyNodeSpec",
        "dds:ModifyNodeSpecBatch",
        "dds:DeleteNode",
        "dds:DescribeBackups",
        "dds:CreateBackup",
        "dds:ResetAccountPassword",
        "dds:TagResources",
        "dds:UntagResources",
        "dds:ListTagResources"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcs",
        "vpc:DescribeVSwitches"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateKey",
        "kms:ListKeys",
        "kms:ListKmsInstances",
        "kms:DescribeKey"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "rm:CreateResourceGroup",
        "rm:ListResourceGroups",
        "rm:GetResourceGroup"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "bss:CreateInstance",
        "bss:QueryAvailableInstances",
        "bss:DescribePricingModule"
      ],
      "Resource": "*"
    }
  ]
}

Permission Description

System Policies

Alibaba Cloud provides the following built-in system policies for direct use:

Full Permission Quick Reference

The following is the complete quick reference table for all permissions required by this skill (including Standalone/Replica Set/Sharded Cluster creation, spec modification, node management, renewal, security configuration, and all other operations):

Principle of Least Privilege

It is recommended to select permissions based on actual needs following the principle of least privilege:

1. Instance creation only: Use core permissions + VPC read permissions 2. Full management: Use instance management permissions + VPC permissions + network security permissions 3. Including backup/restore: Additionally add backup and restore permissions

Common Errors

Verification Method - MongoDB Instance Management Verification

This document provides verification methods after successful MongoDB instance creation and management operations.

Creation Success Verification

1. Query Instance Status

After instance creation, confirm success by querying instance attributes:

aliyun dds describe-db-instance-attribute \
  --db-instance-id <your-instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

2. Verify Instance Status is Running

After successful instance creation, DBInstanceStatus should be Running:

aliyun dds describe-db-instance-attribute \
  --db-instance-id <your-instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage \
  | grep -E '"DBInstanceStatus"'

Expected output:

"DBInstanceStatus": "Running",

3. Verify Replica Set Node Count

Confirm that the primary/secondary node count matches the configuration:

aliyun dds describe-db-instance-attribute \
  --db-instance-id <your-instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage \
  | grep -E '"ReplicationFactor"'

Expected output (3-node example):

"ReplicationFactor": "3",

Instance Status Reference

Complete Verification Script

#!/bin/bash
# MongoDB Replica Set Instance Creation Verification Script

INSTANCE_ID=$1

if [ -z "$INSTANCE_ID" ]; then
    echo "Usage: $0 <instance-id>"
    exit 1
fi

echo "=== Verifying MongoDB Instance: $INSTANCE_ID ==="

# Get instance attributes
RESULT=$(aliyun dds describe-db-instance-attribute \
  --db-instance-id "$INSTANCE_ID" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage 2>&1)

# Check if command succeeded
if [ $? -ne 0 ]; then
    echo "ERROR: Unable to retrieve instance information"
    echo "$RESULT"
    exit 1
fi

# Extract key information
STATUS=$(echo "$RESULT" | grep -o '"DBInstanceStatus": "[^"]*"' | cut -d'"' -f4)
REPLICATION=$(echo "$RESULT" | grep -o '"ReplicationFactor": "[^"]*"' | cut -d'"' -f4)
ENGINE_VERSION=$(echo "$RESULT" | grep -o '"EngineVersion": "[^"]*"' | cut -d'"' -f4)
REGION=$(echo "$RESULT" | grep -o '"RegionId": "[^"]*"' | cut -d'"' -f4)
STORAGE=$(echo "$RESULT" | grep -o '"DBInstanceStorage": [0-9]*' | cut -d':' -f2 | tr -d ' ')

echo "Instance Status: $STATUS"
echo "Node Count: $REPLICATION"
echo "Database Version: $ENGINE_VERSION"
echo "Region: $REGION"
echo "Storage: ${STORAGE}GB"

# Validate status
if [ "$STATUS" == "Running" ]; then
    echo ""
    echo "✅ Verification passed: Instance created successfully and running normally"
    exit 0
else
    echo ""
    echo "⚠️  Instance status is: $STATUS (waiting for Running)"
    exit 1
fi

Wait for Instance Ready

After instance creation, it may take several minutes to reach Running status. Use the following command to poll:

# Poll and wait for instance ready (max 10 minutes)
INSTANCE_ID="<your-instance-id>"
MAX_WAIT=600  # seconds
INTERVAL=30   # seconds
ELAPSED=0

while [ $ELAPSED -lt $MAX_WAIT ]; do
    STATUS=$(aliyun dds describe-db-instance-attribute \
      --db-instance-id "$INSTANCE_ID" \
      --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage \
      2>/dev/null | grep -o '"DBInstanceStatus": "[^"]*"' | cut -d'"' -f4)
    
    echo "Current status: $STATUS (elapsed: ${ELAPSED}s)"
    
    if [ "$STATUS" == "Running" ]; then
        echo "✅ Instance is ready"
        break
    fi
    
    sleep $INTERVAL
    ELAPSED=$((ELAPSED + INTERVAL))
done

if [ $ELAPSED -ge $MAX_WAIT ]; then
    echo "❌ Timeout: Instance did not become ready within ${MAX_WAIT} seconds"
    exit 1
fi

Network Connection Verification

After successful instance creation, verify network connectivity:

1. Get Connection Address

aliyun dds describe-db-instance-attribute \
  --db-instance-id <your-instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage \
  | grep -A5 '"ReplicaSetList"'

2. Test Connection Using mongosh (must be executed on an ECS in the same VPC)

# Connect using Primary node
mongosh "mongodb://root:<password>@<connection-string>:3717/admin?replicaSet=mgset-xxxxx"

Common Troubleshooting

Instance Stuck in Creating Status for a Long Time

Possible causes: 1. Insufficient resources in the region 2. Quota limitations

How to check:

# Check available resources
aliyun dds describe-available-resource \
  --region-id cn-hangzhou \
  --zone-id cn-hangzhou-g \
  --db-type replicate \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage

Unable to Connect to Instance

Checklist: 1. ✅ Is the instance status Running? 2. ✅ Does the IP whitelist include the client IP? 3. ✅ Are the ECS and MongoDB in the same VPC? 4. ✅ Do security group rules allow port 3717?

Check IP Whitelist

aliyun dds describe-security-ips \
  --db-instance-id <your-instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage