Alicloud Mongodb Ops

> This skill follows the Agent Skill OpenSpec.

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:

• 安全 (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 | |------|-------------|----------| | cloudssd | Standard SSD | General workloads | | cloudessd | 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

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

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

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

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

#!/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:

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

# 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
• Source: buhaiqing/aliyun-skills
• License: MIT

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