alibabacloud-mongodb-instances-manage

What this skill does

# 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](references/cli-installation-guide.md) for installation instructions.
>
> [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation.
> [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date.

```bash
aliyun version
aliyun plugin install --names dds kms resourcemanager bssopenapi
```

**[MUST] CLI User-Agent** — Every `aliyun` CLI command invocation must include:
`--user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage`

> **[MUST] Enable AI-Mode** — AI-mode is required for Agent Skill execution.
> Run the following commands before any CLI invocation:
> ```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](https://ram.console.aliyun.com/manage/ak) and configure outside this session.

## RAM Permissions

This skill requires the following RAM permissions. See [references/ram-policies.md § Full Permission Quick Reference](references/ram-policies.md) 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

```bash
# Query instance list
# If user specifies instance type, query that type only; if not specified, must query both types separately:
aliyun dds describe-db-instances --biz-region-id <region> --db-instance-type replicate --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
aliyun dds describe-db-instances --biz-region-id <region> --db-instance-type sharding --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
# ⚠️ Without --db-instance-type, only replicate is returned by default; sharded clusters will be missed

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

# Query all supported regions
aliyun dds describe-regions --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mongodb-instances-manage
```

> Cross-region lookup scripts and full-region scan scripts: see [references/operations.md § Query Regions and Instances](references/operations.md)

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