Configurar habilidades de DocumentDB en AWS Agent Toolkit para automatizar gestión de bases de datos

Introducción

Los equipos de DevOps y SRE suelen invertir horas manuales en operaciones repetitivas de bases de datos: aprovisionar clusters, migrar esquemas, ajustar parámetros de rendimiento o ejecutar revisiones de arquitectura. Amazon DocumentDB ahora ofrece una skill especializada dentro del AWS Agent Toolkit que encapsula estas operaciones en flujos de trabajo automatizados y auditados. Esto permite que agentes de IA (como los basados en modelos de lenguaje) ejecuten tareas complejas de DocumentDB usando workflows predefinidos, reduciendo errores y liberando tiempo para tareas de mayor valor.

En esta guía, configurarás el AWS Agent Toolkit para usar la skill de DocumentDB, integrarás permisos IAM, habilitarás logging con CloudTrail y ejecutarás los siete workflows disponibles (desde aprovisionamiento hasta upgrades de versión) usando tanto el servidor MCP como la CLI local.

Qué es y para qué sirve

La skill de Amazon DocumentDB en AWS Agent Toolkit es un plugin que expone funcionalidades clave de DocumentDB como APIs estandarizadas para agentes de IA. Estas APIs están diseñadas para ejecutar operaciones que, de otro modo, requerirían documentación detallada o scripts personalizados. Los siete workflows principales son:

• IAM guardrails: Los agentes solo pueden invocar roles con permisos mínimos (ej: documentdb:CreateDBCluster).
• CloudTrail logging: Todas las acciones quedan registradas en un log auditado.
• Ejecución local: Opcionalmente, podés ejecutar los workflows directamente desde la CLI de AWS sin usar agentes.

Prerequisitos

Antes de configurar la skill, asegurate de tener:

Creá un rol IAM llamado DocumentDBAgentRole con este policy JSON (guardalo en un archivo documentdb-agent-policy.json):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "documentdb:CreateDBCluster",
        "documentdb:DeleteDBCluster",
        "documentdb:DescribeDBClusters",
        "documentdb:ModifyDBCluster",
        "documentdb:CreateDBInstance",
        "documentdb:DeleteDBInstance",
        "documentdb:DescribeDBInstances",
        "documentdb:ModifyDBInstance",
        "dms:*",
        "rds:DescribeDBClusters",
        "rds:DescribeDBInstances",
        "iam:PassRole",
        "cloudtrail:StartLogging",
        "cloudtrail:DescribeTrails",
        "logs:CreateLogGroup",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

Aplicá el policy al rol usando:

aws iam create-role --role-name DocumentDBAgentRole --assume-role-policy-document file://trust-policy.json
aws iam put-role-policy --role-name DocumentDBAgentRole --policy-name DocumentDBAgentPolicy --policy-document file://documentdb-agent-policy.json

Guía paso a paso

Paso 1: Instalar el AWS Agent Toolkit y el AWS MCP Server

1. Cloná el repositorio del Agent Toolkit:

   git clone https://github.com/awslabs/aws-agent-toolkit.git
   cd aws-agent-toolkit
   

1. Instalá dependencias:

   python -m venv .venv
   source .venv/bin/activate  # Linux/macOS
   # O en Windows:
   # .venv\Scripts\activate
   pip install -r requirements.txt
   

1. Instalá el MCP Server:

   git clone https://github.com/awslabs/aws-mcp-server.git
   cd aws-mcp-server
   npm install
   npm run build
   

1. Configurá el MCP Server para usar el rol IAM creado:

   {
     "aws": {
       "region": "us-east-1",
       "roleArn": "arn:aws:iam::123456789012:role/DocumentDBAgentRole",
       "sessionName": "DocumentDBAgentSession"
     }
   }
   

Paso 2: Descargar y configurar la skill de Amazon DocumentDB

1. Descargá la skill desde GitHub:

   git clone https://github.com/awslabs/amazon-documentdb-skill.git
   cd amazon-documentdb-skill
   

1. Instalá la skill en el Agent Toolkit:

   cp -r amazon-documentdb-skill /ruta/a/aws-agent-toolkit/skills/
   

1. Verificá la instalación:

   python -m aws_agent_toolkit.cli list-skills
   

   Skills disponibles:
   - amazon_documentdb_skill
   - aws_mcp_server
   

Paso 3: Ejecutar workflows usando el MCP Server

Workflow 1: Provisionamiento de un cluster DocumentDB

1. Ejecutá el workflow:

   python -m aws_agent_toolkit.cli execute \
     --skill amazon_documentdb_skill \
     --workflow provision_cluster \
     --params '{
       "clusterIdentifier": "mi-cluster-demo",
       "instanceClass": "db.r6g.large",
       "shardCount": 3,
       "engineVersion": "5.0.0",
       "masterUsername": "admin",
       "masterUserPassword": "ClaveSegura123!",
       "vpcSecurityGroupIds": ["sg-1234567890abcdef0"],
       "subnetGroup": "default-vpc-12345678"
     }'
   

1. Verificá el resultado:

   aws documentdb describe-db-clusters --db-cluster-identifier mi-cluster-demo
   

   {
     "DBClusters": [
       {
         "DBClusterIdentifier": "mi-cluster-demo",
         "Engine": "docdb",
         "EngineVersion": "5.0.0",
         "Status": "available",
         "Endpoint": "mi-cluster-demo.cluster-1234567890abcdef0.us-east-1.docdb.amazonaws.com",
         "Port": 27017
       }
     ]
   }
   

Workflow 2: Migración con CDC usando AWS DMS

1. Ejecutá la migración:

   python -m aws_agent_toolkit.cli execute \
     --skill amazon_documentdb_skill \
     --workflow migrate_with_cdc \
     --params '{
       "sourceEndpoint": "mongodb://user:pass@mongo-source:27017",
       "targetEndpoint": "docdb://admin:ClaveSegura123!@mi-cluster-demo.cluster-1234567890abcdef0.us-east-1.docdb.amazonaws.com:27017",
       "replicationInstanceClass": "dms.t3.medium",
       "tableMappings": "{\"rules\": [{\"rule-type\": \"selection\", \"rule-id\": \"1\", \"rule-name\": \"AllTables\", \"object-locator\": {\"schema-name\": \"%\", \"table-name\": \"%\"}, \"rule-action\": \"include\"}]}"
     }'
   

1. Monitoreá el progreso:

   aws dms describe-replication-tasks --filters "Name=ReplicationTaskIdentifier,Values=Task-MongoToDocDB"
   

   "Status": "running"
   

Paso 4: Ejecutar workflows desde la CLI local (sin MCP Server)

Si preferís ejecutar los workflows directamente desde la CLI de AWS:

1. Usá el template de CDK (opcional):

   npx cdk init app --language typescript
   npm install @aws-cdk/aws-documentdb
   

1. Ejecutá un workflow de revisión Well-Architected:

   python -m amazon_documentdb_skill.execute \
     --workflow well_architected_review \
     --cluster-id mi-cluster-demo
   

   Check 1: [PASS] High Availability (3 shards)
   Check 2: [FAIL] Backup retention (7 days)
   Check 3: [PASS] Encryption at rest (enabled)
   

Paso 5: Habilitar logging con CloudTrail

1. Creá un trail para DocumentDB:

   aws cloudtrail create-trail --name DocumentDBLogs --s3-bucket-name mi-bucket-logs
   aws cloudtrail start-logging --name DocumentDBLogs --s3-bucket-name mi-bucket-logs
   

1. Verificá los logs:

   aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=CreateDBCluster
   

   "EventName": "CreateDBCluster",
   "ReadOnly": false,
   "Resources": [
     {"ResourceType": "AWS::DocumentDB::DBCluster", "ResourceName": "mi-cluster-demo"}
   ]
   

Consideraciones y buenas prácticas

Limitaciones conocidas

1. Aislamiento de entornos:

– Ejemplo de naming: mi-app-dev, mi-app-staging, mi-app-prod.

1. Seguridad:

– Ejemplo de rotación de credenciales:

     aws secretsmanager rotate-secret --secret-id DocumentDBMasterPassword
     

1. Monitoreo:

     aws cloudwatch put-metric-alarm --alarm-name DocumentDB-CPU-High \
       --metric-name CPUUtilization --namespace AWS/DocumentDB \
       --statistic Average --period 300 --threshold 80 \
       --comparison-operator GreaterThanThreshold \
       --evaluation-periods 2 --alarm-actions arn:aws:sns:us-east-1:123456789012:DocumentDBAlerts
     

1. Backup y recovery:

     aws documentdb modify-db-cluster \
       --db-cluster-identifier mi-cluster-demo \
       --backup-retention-period 35 \
       --apply-immediately
     

Conclusión

La skill de Amazon DocumentDB en AWS Agent Toolkit te permite automatizar operaciones críticas de bases de datos compatibles con MongoDB, reduciendo errores humanos y acelerando flujos de trabajo como migraciones, provisionamiento y optimización. Al integrar IAM guardrails, logging con CloudTrail y ejecución sandboxed, podés usar esta herramienta tanto con agentes de IA como en pipelines manuales sin comprometer seguridad.

Para empezar:

1. Configurá el rol IAM con permisos mínimos.
2. Instalá el Agent Toolkit y la skill.
3. Ejecutá workflows usando MCP Server o la CLI local.
4. Monitoreá todo con CloudTrail y CloudWatch.

Fuentes

• Amazon DocumentDB Skill en GitHub
• AWS MCP Server
• Documentación de AWS Agent Toolkit Quick Start
• Guía del desarrollador de Amazon DocumentDB