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

aliyun

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

[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

[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"'

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.

[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

[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

undefined

[MUST] Before executing any create/modify operation, must display a complete parameter list to the user and obtain Y/Yes confirmation

[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

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

undefined

• --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

• --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

• 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

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

[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

[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

[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

undefined

[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

[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

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

!@#$%^&*()_+-=

)

undefined

[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

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

[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

undefined

[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

undefined

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.

undefined

Prerequisites: Instance status

Running

, not a legacy spec [MUST] Use

transform-instance-charge-type

(NOT

TransformToPrePaid

— that API is forbidden)

undefined

[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

restart-db-instance

restart-node --node-id --role-id

StorageType=cloud_*

InsType.NotSupport

describe-role-zone-info

describe-replica-set-role

--node-id

d-xxx

--role-id

create-backup --backup-method

--backup-method Snapshot

--backup-retention-period

BackupJobId

BackupId

describe-backup-tasks

describe-backups --backup-job-id

describe-backups --start-time --end-time

yyyy-MM-ddTHH:mmZ

Backups.Backup[]

--backup-job-id

describe-backup-policy

modify-backup-policy

--preferred-backup-time

--preferred-backup-period

describe-backup-policy

upgrade-db-instance-engine-version

upgrade-db-instance-kernel-version

switch-db-instance-ha

describe-role-zone-info

--node-id

create-account

describe-accounts

tag-resources --resource-type INSTANCE

--resource-id

--tag Key=<k> Value=<v>

--biz-region-id

untag-resources --resource-type INSTANCE

list-tag-resources --resource-type INSTANCE

list-tag-resources

DescribeDBInstances

describe-tags

See references/verification-method.md for details.

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