# Alicloud Mongodb Ops

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-buhaiqing-aliyun-skills-alicloud-mongodb-ops`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [buhaiqing](https://agentstack.voostack.com/s/buhaiqing)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** https://github.com/buhaiqing/aliyun-skills/tree/main/alicloud-mongodb-ops

## Install

```sh
agentstack add skill-buhaiqing-aliyun-skills-alicloud-mongodb-ops
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> This skill follows the [Agent Skill OpenSpec](https://agentskills.io/specification).

# Alibaba Cloud MongoDB / ApsaraDB for MongoDB Operations Skill

## Overview

Alibaba Cloud MongoDB (ApsaraDB for MongoDB / DDS) provides managed MongoDB-compatible
document database services supporting standalone, replica set, and sharded cluster
architectures. This skill is an **operational runbook** for agents: explicit scope,
credential rules, pre-flight checks, **dual-path execution** (official **SDK/API**
and **CLI** flows), response validation, and failure recovery.

### CLI applicability (repository policy)

- **`cli_applicability: dual-path`:** Official `aliyun` fully supports `dds` (MongoDB).
  Each execution flow documents **both** the SDK step and the `aliyun` step for
  every operation.

### Five Core Standards (Quality Gates)

| # | Standard | How This Skill Fulfills It |
|---|----------|---------------------------|
| 1 | **Clear Boundaries** | SHOULD/SHOULD NOT Use conditions with precise triggers and delegation rules |
| 2 | **Structured I/O** | Placeholder conventions (`{{env.*}}`, `{{user.*}}`, `{{output.*}}`) with type and source documented |
| 3 | **Explicit Actionable Steps** | Every operation: Pre-flight → Execute → Validate → Recover, with numbered imperative steps |
| 4 | **Complete Failure Strategies** | Error taxonomy table with ≥ 10 product-specific codes; HALT vs retry per error type |
| 5 | **Absolute Single Responsibility** | One product, one primary resource model; cross-product delegation to other skills |

### Well-Architected Framework Integration (卓越架构)

Operations map to Alibaba Cloud's [Well-Architected Framework](https://help.aliyun.com/zh/product/2362200.html):
- **安全 (Security)**: IAM permissions, credential masking, network isolation
- **稳定 (Stability)**: Backup/restore, multi-AZ, DR runbook, failure-oriented design
- **成本 (Cost)**: Billing model comparison, waste detection, right-sizing
- **效率 (Efficiency)**: Batch operations, CI/CD integration, automation patterns
- **性能 (Performance)**: Metrics, auto-scaling, performance baselines

## Runtime Rules

| Area | Rule | Reference |
| --- | --- | --- |
| CLI path | **MANDATORY**: Always prefer the harness wrapper `./scripts/mongodb-harness-wrapper.sh` for all MongoDB CLI operations to enable automated self-repair and dynamic optimization; fallback to native `aliyun dds` only when the wrapper is unavailable or `harness-lib.sh` is missing. | [CLI](references/cli-usage.md), [SkillOpt](references/skillopt-integration.md) |
| Credentials | Read {{env.*}} from environment; never ask user to paste secrets | Integration |
| GCL | All write operations MUST pass GCL review before execution | GCL Rubric |

> **EXECUTION MANDATORY RULE**: 所有 control-plane CLI 执行步骤 **必须** 通过 Harness wrapper `./scripts/mongodb-harness-wrapper.sh` 运行。
> 以下所有代码块中的 `aliyun dds ...` 命令在执行时应替换为 `./scripts/mongodb-harness-wrapper.sh  ...`。
> 仅在 wrapper 脚本不可用或 `harness-lib.sh` 缺失时，才退回到原生 `aliyun dds` CLI 调用。
> 参考 `## Runtime Rules` 中的 CLI path 规则。
## Trigger & Scope (Agent-Readable)

### SHOULD Use This Skill When

- User mentions "Alibaba Cloud MongoDB" OR "ApsaraDB for MongoDB" OR "DDS" OR "云数据库MongoDB" OR "文档数据库"
- Task involves CRUD or lifecycle operations on **MongoDB instances** (create, describe, modify, delete, list, restart, upgrade)
- Task involves **instance accounts** (create, describe, delete, reset password)
- Task involves **databases** (create, describe, delete)
- Task involves **backups** (create, describe, restore, delete)
- Task involves **whitelists / security groups** (describe, modify)
- Task involves **parameters** (describe, modify)
- Task involves **performance monitoring** (CPU, memory, connections, IOPS, operation counts)
- Task involves **slow query logs** (describe, analyze)
- Task involves **instance migration, scaling, or architecture changes**

### SHOULD NOT Use This Skill When

- Task is purely billing / account management → delegate to: `alicloud-billing-ops`
- Task is RAM / permission model only → delegate to: `alicloud-ram-ops`
- Task is about **RDS (relational database)** → delegate to: `alicloud-rds-ops`
- Task is about **PolarDB MySQL** → delegate to: `alicloud-polar-mysql-ops`
- Task is about **PolarDB PostgreSQL** → delegate to: `alicloud-polar-postgresql-ops`
- Task is about **Redis / Tair** → delegate to: `alicloud-redis-ops`
- User insists on **console-only** flows with no API → state limitation; do not invent undocumented HTTP steps

## Delegation Rules

| 能力 | 委托目标 | 说明 |
|------|----------|------|
| GCL 质量门禁 | `alicloud-gcl-runner-ops` | 对写操作执行前，委托 GCL 循环进行对抗性评审 |

## Key Concepts

### Instance Types

| Type | Architecture | Use Case | HA Support |
|------|--------------|----------|------------|
| **standalone** | Single node | Dev/test, low-criticality | No HA |
| **replicaset** | 3/5/7 nodes | Production workloads | Multi-AZ HA, automatic failover |
| **sharding** | Mongos + Shard + Config | Large-scale, high-throughput | Horizontal scaling |

**Details:** See `references/sharding-ops.md` for sharding architecture and `references/replicaset-ops.md` for replica set operations.

### Engine Versions

| Version | Status | Notes |
|---------|--------|-------|
| 4.0 | Legacy | Extended support |
| 4.2 | Stable | Recommended for compatibility |
| 4.4 | Stable | Most common production version |
| 5.0 | Active | New features, improved performance |
| 6.0 | Active | Latest LTS, enhanced sharding |
| 7.0 | Active | Newest, advanced features |

### Storage Types

| Type | Performance | Use Case |
|------|-------------|----------|
| **cloud_ssd** | Standard SSD | General workloads |
| **cloud_essd** | Enhanced SSD | High IOPS, latency-sensitive |

## Core Actions

### Instance Lifecycle

| Operation | API | CLI | Complexity | Risk |
|-----------|-----|-----|------------|------|
| Create | `CreateDBInstance` | `aliyun dds CreateDBInstance` | High | Low |
| Describe | `DescribeDBInstances` | `aliyun dds DescribeDBInstances` | Low | None |
| Describe Attribute | `DescribeDBInstanceAttribute` | `aliyun dds DescribeDBInstanceAttribute` | Low | None |
| Modify Spec | `ModifyDBInstanceSpec` | `aliyun dds ModifyDBInstanceSpec` | Medium | Medium |
| Restart | `RestartDBInstance` | `aliyun dds RestartDBInstance` | Low | Medium |
| Delete | `DeleteDBInstance` | `aliyun dds DeleteDBInstance` | Low | **High** — irreversible |

**Pre-flight pattern (all operations):**
1. Verify SDK/CLI availability: `aliyun version`
2. Verify credentials exist (non-empty check only, never expose values)
3. Verify region: `aliyun dds DescribeRegions`
4. Verify instance exists (for modify/restart/delete): `DescribeDBInstances`

**State Transitions:**

| Operation | Initial → Target | Poll Interval | Max Wait |
|-----------|------------------|---------------|----------|
| CreateDBInstance | — → `Running` | 10s | 600s |
| RestartDBInstance | `Running` → `Running` | 10s | 300s |
| DeleteDBInstance | any → absent | 10s | 300s |
| ModifyDBInstanceSpec | `Running` → `Running` | 10s | 600s |

### Polling Strategy

MongoDB 实例创建/变配/删除等为异步操作；shell 轮询模板与 Go SDK 备选见
[references/polling-patterns.md](references/polling-patterns.md)。分片集群 AddShard 后验证见
[references/sharding-ops.md](references/sharding-ops.md)。

### Account Management

| Operation | API | CLI |
|-----------|-----|-----|
| Describe Accounts | `DescribeAccounts` | `aliyun dds DescribeAccounts` |
| Create Account | `CreateAccount` | `aliyun dds CreateAccount` |
| Delete Account | `DeleteAccount` | `aliyun dds DeleteAccount` |
| Reset Password | `ResetAccountPassword` | `aliyun dds ResetAccountPassword` |

**Account Types:** `root` (system admin) / `normal` (application accounts)

**Password Policy:**
- Minimum 8 characters; recommend 16+ for production
- Must contain uppercase, lowercase, digit, and special character
- Avoid common passwords and dictionary words
- Rotate passwords every 90 days for production accounts

**Least Privilege Best Practices:**

| Practice | Recommendation | Risk if Ignored |
|----------|----------------|-----------------|
| **Application accounts** | Create dedicated `normal` accounts per application | Root compromise = full database access |
| **Database scope** | Grant account access to only required databases | Over-permissioned accounts increase blast radius |
| **Role assignment** | Use built-in roles: `read`, `readWrite`, `dbAdmin` | Custom roles may have excessive permissions |
| **Root usage** | Reserve `root` for DBA operations only | Application bugs can destroy all data |

**Example: Create Least-Privilege Application Account**
```bash
# Create a normal account with readWrite on a single database
aliyun dds CreateAccount \
  --DBInstanceId "{{user.db_instance_id}}" \
  --AccountName "app_user" \
  --AccountPassword "{{user.app_password}}" \
  --AccountType "Normal"

# After creation, grant specific database permissions via MongoDB shell
# (Alibaba Cloud MongoDB may require console or additional API for role assignment)
```

### Database Operations

| Operation | API | CLI |
|-----------|-----|-----|
| Describe Databases | `DescribeDatabases` | `aliyun dds DescribeDatabases` |
| Create Database | `CreateDatabase` | `aliyun dds CreateDatabase` |
| Delete Database | `DeleteDatabase` | `aliyun dds DeleteDatabase` |

### Backup Operations

| Operation | API | CLI |
|-----------|-----|-----|
| Describe Backups | `DescribeBackups` | `aliyun dds DescribeBackups` |
| Create Backup | `CreateBackup` | `aliyun dds CreateBackup` |
| Restore Instance | `RestoreDBInstance` | `aliyun dds RestoreDBInstance` |

**Backup Types:** `Automated` (scheduled) / `Manual` (user-initiated)
**Backup Modes:** `Physical` / `Logical`

**Backup Cost Considerations:**
- Backup storage is billed separately from instance storage
- Physical backups are typically larger than logical backups
- Automated backups follow the instance retention policy (default 7 days)
- Long-term retention increases storage costs; evaluate necessity

**Cost-Efficient Backup Strategy:**
```bash
# Review backup sizes and retention
aliyun dds DescribeBackups \
  --DBInstanceId "{{user.db_instance_id}}" \
  --output cols=BackupId,BackupSize,BackupType,BackupMode,BackupStartTime \
  rows=Backups.Backup[]

# Estimate: total backup storage cost ≈ Σ(BackupSize) × backup_storage_unit_price
# Delegate to alicloud-billing-ops for precise cost breakdown
```

### Monitoring & Diagnostics

| Operation | API | CLI | Purpose |
|-----------|-----|-----|---------|
| Performance Metrics | `DescribeDBInstancePerformance` | `aliyun dds DescribeDBInstancePerformance` | CPU/Memory/Connections/IOPS |
| Slow Logs | `DescribeSlowLogRecords` | `aliyun dds DescribeSlowLogRecords` | Query analysis |
| Parameters | `DescribeParameters` | `aliyun dds DescribeParameters` | Config inspection |

**Key Metrics:** `CPUUsage`, `MemoryUsage`, `ConnectionUsage`, `IOPSUsage` (CMS namespace: `acs_mongodb_dashboard`)

### DAS Integration (Database Autonomy Service)

For advanced performance analysis, connect to DAS console or use DAS APIs:

```bash
# Query DAS for performance insights
# Note: DAS provides additional AI-powered diagnostics beyond basic metrics
```

**Supported Anomaly Patterns:**

| # | Pattern | Detection Criteria | Action |
|---|---------|-------------------|--------|
| 1 | **Memory-Connection双高** | MemoryUsage > 85% AND ConnectionUsage高 | Check connection leaks, query optimization |
| 2 | **查询延迟异常** | QueryLatency突增 (>3x baseline) | Analyze slow queries, check indexes |
| 3 | **索引缺失预警** | 慢查询 + 无索引覆盖 | Create covering indexes |
| 4 | **存储空间预警** | StorageUsage > 85% | Archive/cleanup or scale storage |

**DAS Diagnostic Commands:**
```bash
# For detailed slow query analysis, delegate to alicloud-das-ops
# aliyun das DescribeSlowLogRecords
```

### Operation: Intelligent Inspection（MongoDB 智能巡检）

**Purpose**: 主动发现 MongoDB 实例性能瓶颈、安全风险和容量问题

**Five-Step Workflow**:
1. **Discovery**: `aliyun dds DescribeDBInstances` 列出所有实例
2. **Collection**: 批量采集 CPU/Memory/IOPS/Connections/Storage 指标
3. **Detection**: 应用异常模式检测 (4种已定义模式)
4. **Diagnosis**: 深度分析慢查询、索引缺失、连接池状态
5. **Report**: 生成巡检报告 (Markdown格式)

**CLI Script Template**:
```bash
#!/bin/bash
# mongodb-intelligent-inspection.sh
# Usage: ./mongodb-intelligent-inspection.sh  

InstanceId=${1}
RegionId=${2:-cn-hangzhou}

# 采集指标
aliyun dds DescribeDBInstancePerformance \
  --DBInstanceId $InstanceId \
  --RegionId $RegionId \
  --Key "CPUUsage_MemoryUsage_IOPS_Connections"

# 检查索引缺失
aliyun dds DescribeIndexRecommendation \
  --DBInstanceId $InstanceId

# 生成报告
echo "## MongoDB 巡检报告 - ${InstanceId}"
echo "| 指标 | 当前值 | 状态 |"
echo "|------|--------|------|"
```

**Inspection Scoring**:
- CPU使用率  90%: 10分
- 总分  **凭据安全（强制）：** 参考 [Credential Masking 规则](../alicloud-skill-generator/references/credential-masking.md)

## Critical Rules

### Pre-flight Checks

| Check | Method | On Failure |
|-------|--------|------------|
| Credentials | Env vars non-empty | HALT; user configures |
| Region | `DescribeRegions` | Suggest valid region |
| VPC/VSwitch | `alicloud-vpc-ops` | Delegate to VPC skill |
| Quota | `DescribeAvailableResource` | HALT; user raises quota |

### Safety Gates (Require User Confirmation)

- **DeleteDBInstance** — irreversible deletion
- **DeleteDatabase** — data loss
- **DeleteAccount** — access removal
- **RestoreDBInstance** — data overwrite
- **RestartDBInstance** — brief downtime
- **ModifyDBInstanceSpec** — potential interruption

### Cost Awareness (FinOps)

> For comprehensive cost analysis and optimization, delegate to `alicloud-billing-ops` or `finops-analysis-aliyun`.

**Billing Model Quick Reference:**

| Model | Best For | Cost Characteristic |
|-------|----------|---------------------|
| **Subscription** (包年包月) | Long-running production | Lower unit cost; upfront commitment |
| **Pay-As-You-Go** (按量付费) | Dev/test, short-term | Higher unit cost; no commitment |

**Cost-Impacting Parameters on Create/Modify:**

| Parameter | Cost Impact | Recommendation |
|-----------|-------------|----------------|
| `DBInstanceClass` | Primary driver | Start small, scale based on metrics |
| `DBInstanceStorage` | Linear with size | Use ESSD PL1 for most workloads |
| `ReplicationFactor` | Multiplies node cost | 3 for production, 1 for dev/test |
| `NetworkType` | Cross-region traffic billed | Keep app and DB in same region/VPC |

**Pre-creation Cost Check:**
```bash
# Query price before creating (reference only — actual billing varies)
aliyun dds DescribePrice \
  --RegionId "{{user.region}}" \
  --DBInstanceClass "{{user.db_instance_class}}" \
  --DBInstanceStorage "{{user.db_instance_storage}}" \
  --PayType "{{user.pay_type|PrePaid}}"
```

**Resource Efficiency Check:**
```bash
# Identify underutilized instances for potential downsizing
aliyun dds DescribeDBInstances \
  --RegionId "{{user.region}}" \
  --output cols=DBInstanceId,DBInstanceClass,DBInstanceStatus,CreationTime \
  rows=DBInstances.DBInstance[]

# For detailed utilization analysis (CPU < 5% for 7 days), delegate to:
# - `finops-analysis-aliyun` for cross-resource cost optimization
# - `alicloud-billing-ops` for billing and usage breakdown
```

## Escalation Rules

### HALT Conditions (No Retry)

| Error Code | Action |
|------------|--------|
| `InvalidParameter` / 400 | Fix args from OpenAPI spec |
| `QuotaExceeded` | HALT; user raises quota |
| `InsufficientBalance` | HALT; user resolves billing |
| `DBInstanceAlreadyExists` | Ask reuse vs new name |
| `DBInstanceNotFound` | HALT; verify instance ID |

### Retry Conditions

| Error Pattern | Max Retries | Backoff | Action |
|---------------|-------------|---------|--------|
| Throttling / 429 | 3 | exponential | Respect `Retry-After` |
| `InternalError` / 5xx | 3 | 2s, 4s, 8s | Retry; then HALT with RequestId |
| Network timeout | 3 | exponential | Retry with backoff |

### Ask User Before Proceeding

- Multiple instances match query — ask which to target
- Operation affects production insta

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** [buhaiqing/aliyun-skills](https://github.com/buhaiqing/aliyun-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-buhaiqing-aliyun-skills-alicloud-mongodb-ops
- Seller: https://agentstack.voostack.com/s/buhaiqing
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.