Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Runbook de migración de Amazon DocumentDB

Este manual proporciona una guía completa para migrar una base de datos de MongoDB a Amazon DocumentDB mediante (DMS). AWS Database Migration Service Está diseñado para ayudar a los administradores de bases de datos, ingenieros de nube y desarrolladores durante todo el proceso de migración, desde el descubrimiento inicial hasta la validación posterior a la end-to-end migración.

Dadas las diferencias en la implementación y las características compatibles entre MongoDB y Amazon DocumentDB, en este runbook se hace hincapié en un enfoque estructurado y sistemático. Se describen las evaluaciones esenciales previas a la migración, se destacan las consideraciones de compatibilidad y se detallan las tareas clave necesarias para garantizar una migración correcta con un mínimo de interrupciones.

El runbook se organiza en los siguientes temas:

Si se siguen las instrucciones de este runbook, los equipos pueden garantizar una transición fluida, segura y eficiente a Amazon DocumentDB, a la vez que conservan la funcionalidad de la aplicación y minimizan los riesgos.

Compatibilidad

Cuando se realiza una migración de MongoDB a Amazon DocumentDB, es esencial realizar una evaluación inicial exhaustiva y comprobar la compatibilidad de las características para que la migración se lleve a cabo correctamente. Este proceso comienza con un inventario completo de las características de MongoDB, incluidos los operadores de canalización de agregación, los patrones de consulta, los índices y los modelos de datos.

Dado que Amazon DocumentDB es compatible con las API de MongoDB 3.6, 4.0 y 5.0, es posible que sea necesario refactorizar las aplicaciones que utilizan características específicas de MongoDB más recientes. Las áreas críticas que se deben evaluar incluyen los mecanismos de partición (Amazon DocumentDB utiliza un enfoque diferente), las implementaciones de transacciones, la funcionalidad de los flujos de cambios y los tipos de índices (especialmente los índices dispersos y parciales).

Las características de rendimiento también difieren, ya que Amazon DocumentDB está optimizada para cargas de trabajo empresariales con un rendimiento predecible. Las pruebas deben incluir la ejecución de cargas de trabajo representativas en ambos sistemas para identificar los patrones de consulta que puedan requerir optimización.

Durante la fase de evaluación, es importante supervisar los planes de ejecución para detectar posibles brechas de rendimiento. Esto ayuda a crear una hoja de ruta de migración clara, ya que identifica los cambios necesarios en las aplicaciones y establece plazos realistas para una transición fluida.

Compatibilidad de características básicas

Soporte de características integral

Funciones integradas y mejoradas AWS

Ventajas de la arquitectura moderna

Para obtener una descripción general completa de las capacidades de Amazon DocumentDB, consulte APIsMongoDB, operaciones y tipos de datos compatibles en Amazon DocumentDB y Diferencias funcionales: Amazon DocumentDB y MongoDB para maximizar el potencial de su base de datos.

Amazon DocumentDB no es compatible con todos los índices que ofrece MongoDB. Proporcionamos una herramienta de indexación gratuita para comprobar la compatibilidad. Recomendamos utilizar la herramienta de indexación para evaluar la incompatibilidad y planificar las soluciones alternativas en consecuencia.

Herramienta de evaluación de compatibilidad de Amazon DocumentDB

La herramienta de compatibilidad de MongoDB a Amazon DocumentDB es una utilidad de código abierto GitHub que ayuda a evaluar la compatibilidad de las cargas de trabajo de MongoDB con Amazon DocumentDB mediante el análisis de los registros de MongoDB o del código fuente de la aplicación.

Características principales

Métodos de evaluación

Evaluación basada en registros

Análisis del código fuente

Para obtener los mejores resultados, recomendamos utilizar ambos métodos de evaluación siempre que sea posible para obtener una visión completa de los problemas de compatibilidad antes de la migración.

Detección de la carga de trabajo

La migración de MongoDB a Amazon DocumentDB requiere un conocimiento profundo de la carga de trabajo de la base de datos existente. La detección de la carga de trabajo es el proceso de analizar los patrones de uso de la base de datos, las estructuras de datos, el rendimiento de las consultas y las dependencias operativas para garantizar una transición fluida con una interrupción mínima. En esta sección se describen los pasos clave que implica la detección de cargas de trabajo para facilitar una migración eficaz de MongoDB a Amazon DocumentDB.

Evaluación de la implementación de MongoDB existente

Antes de la migración, es fundamental evaluar el entorno actual de MongoDB, que incluye:

Identificación de diferencias en los modelos de datos

Si bien Amazon DocumentDB es compatible con MongoDB, existen diferencias en las características compatibles, como:

Análisis de consultas y rendimiento

Comprender el comportamiento de las consultas ayuda a optimizar el rendimiento de la migración y después de la migración. Las siguientes son áreas clave que se deben analizar:

Revisión de seguridad y control de acceso

Autenticación y autorización

Cifrado

Asegúrese de que el cifrado en reposo y en tránsito se ajuste a los requisitos de conformidad.

Configuración de red

Planifique la configuración de la nube privada virtual (VPC) y las reglas de los grupos de seguridad.

Consideraciones operativas y de supervisión

Para mantener la fiabilidad del sistema, la detección de la carga de trabajo también debe incluir lo siguiente:

Migración de índices

La migración de MongoDB a Amazon DocumentDB implica transferir no solo datos, sino también índices para mantener el rendimiento de las consultas y optimizar las operaciones de la base de datos. En esta sección se describe el step-by-step proceso detallado para migrar índices de MongoDB a Amazon DocumentDB y, al mismo tiempo, garantizar la compatibilidad y la eficacia.

Uso de la herramienta de indexación de Amazon DocumentDB

Clonación de la herramienta de indexación

git clone https://github.com/aws-samples/amazon-documentdb-tools.git
cd amazon-documentdb-tools/index-tool

pip install -r requirements.txt

Exportación de índices desde MongoDB (si se migra desde MongoDB)

python3 migrationtools/documentdb_index_tool.py --dump-indexes --dir mongodb_index_export --uri
'mongodb://localhost:27017'

Exportación de índices desde Amazon DocumentDB (si se migra desde Amazon DocumentDB)

python3 migrationtools/documentdb_index_tool.py --dump-indexes --dir docdb_index_export --uri
'mongodb://user:password@mydocdb.cluster-cdtjj00yfi95.eu-west-
2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=rds-combined-ca-
bundle.pem&replicaSet=rs0&retryWrites=false'

Índices de importación

python3 migrationtools/documentdb_index_tool.py --restore-indexes --skip-incompatible --dir
mongodb_index_export --uri 'mongodb://user:password@mydocdb.cluster-cdtjj00yfi95.eu-west-
2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=rds-combined-ca-
bundle.pem&replicaSet=rs0&retryWrites=false'

Verificación de índices

python3 migrationtools/documentdb_index_tool.py --show-issues --dir mongodb_index_export

Migración de usuario

La migración de usuarios de MongoDB a Amazon DocumentDB es esencial para mantener el control de acceso, la autenticación y la seguridad de la base de datos. En esta sección se describen los pasos detallados para migrar correctamente los usuarios de MongoDB y, al mismo tiempo, conservar sus roles y permisos mediante la herramienta de exportación de usuarios de Amazon DocumentDB.

Uso de la herramienta de exportación de usuarios de Amazon DocumentDB

Export Users toolExporta los usuarios y las funciones de MongoDB o Amazon DocumentDB JavaScript a archivos, que luego se pueden usar para volver a crearlos en otro clúster.

Requisitos previos

# Clone the repository
git clone https://github.com/awslabs/amazon-documentdb-tools.git
cd amazon-documentdb-tools/migration/export-users

# Install required dependencies
pip install pymongo

Paso 1: exportar usuarios y roles

# Export users and roles to JavaScript files
python3 docdbExportUsers.py \
--users-file mongodb-users.js \
--roles-file mongodb-roles.js \
--uri "mongodb://admin:password@source-host:27017/"

Paso 2: editar el archivo de usuarios

// Example of how to update the users.js file
// Find each user creation statement and add the password
db.getSiblingDB("admin").createUser({
user: "appuser",
// Add password here
pwd: "newpassword",
roles: [
{ role: "readWrite", db: "mydb" }
]
})

Paso 3: restaurar roles personalizados en Amazon DocumentDB

# Import roles first
mongo --ssl \
--host target-host:27017 \
--sslCAFile rds-combined-ca-bundle.pem \
--username admin \
--password password \
mongodb-roles.js

Paso 4: restaurar usuarios en Amazon DocumentDB

# Import users after roles are created
mongo --ssl \
--host target-host:27017 \
--sslCAFile rds-combined-ca-bundle.pem \
--username admin \
--password password \
mongodb-users.js

Notas importantes

Este método proporciona un enfoque seguro y flexible para migrar usuarios y roles de MongoDB a Amazon DocumentDB y, al mismo tiempo, permite restablecer las contraseñas durante el proceso de migración.

Migración de datos

Migración en línea

En esta sección se proporcionan pasos detallados para realizar una migración en línea de MongoDB a Amazon DocumentDB para permitir un tiempo de inactividad mínimo y AWS DMS una replicación continua. Para empezar, debe configurar un clúster de Amazon DocumentDB como destino y asegurarse de que su instancia de MongoDB esté correctamente configurada como el origen, lo que normalmente requiere el modo de conjunto de réplicas para la captura de datos de cambios. A continuación, debe crear una instancia de replicación de DMS y definir los puntos de conexión de origen y destino con los detalles de conexión necesarios. Tras validar los puntos de conexión, debe configurar e iniciar una tarea de migración que puede incluir la carga completa de los datos, la replicación continua o ambas.

Configuración del destino (Amazon DocumentDB)

Cree un grupo de parámetros personalizado

Consulte los AWS CLI procedimientos Consola de administración de AWS o enCreación de grupos de parámetros de clúster de Amazon DocumentDB.

Create an Amazon DocumentDB cluster (Crear un clúster de Amazon DocumentDB)

Configurar el origen

Tanto MongoDB como Amazon DocumentDB pueden servir como orígenes de migración, según la situación:

Antes de iniciar la migración, configure la fuente para permitir el acceso. AWS DMS

Cree un usuario de MongoDB con los permisos adecuados:

db.createUser({
user: "dmsUser",
pwd: "yourSecurePassword",
roles: [{ role: "readAnyDatabase", db: "admin" }]
})

Configure la red y la autenticación.

Cuando configure la conectividad de red para la migración de MongoDB a DMS:

EC2-fuente MongoDB alojada

MongoDB en las instalaciones como origen

MongoDB Atlas como origen

Amazon DocumentDB como origen

Configure el grupo de seguridad de Amazon DocumentDB de origen para permitir el tráfico entrante desde el grupo de seguridad de la instancia de replicación de DMS.

Creación de una instancia de replicación de DMS

Recomendamos utilizar DMS Buddy para aprovisionar su infraestructura de DMS, ya que crea una infraestructura de migración óptima con una configuración de DMS y tamaños de instancia óptimos.

Si prefiere realizar la configuración manualmente, siga estos pasos:

Creación de puntos de conexión de DMS

Creación de un punto de conexión de origen

Si se toma MongoDB como origen

Si se toma Amazon DocumentDB como origen

Creación de un punto de conexión de destino (Amazon DocumentDB)

Creación de una tarea de replicación

Migración sin conexión

En esta sección se describe el proceso para realizar una migración sin conexión desde una instancia de MongoDB autogestionada a Amazon DocumentDB mediante herramientas nativas de MongoDB: mongodump y mongorestore.

Requisitos previos

Requisitos de MongoDB como origen

Requisitos de Amazon DocumentDB como destino

Requisitos generales

Preparación de un clúster de Amazon DocumentDB

Creación de un clúster de Amazon DocumentDB en AWS:

Realización de volcado de datos (mongodump)

Elija una de las siguientes opciones para crear un archivo de volcado:

Transferencia de archivos de volcado al entorno de restauración

Elija un método adecuado en función del tamaño del volcado:

Restauración de datos en Amazon DocumentDB (mongorestore)

Antes de iniciar el proceso de restauración, cree los índices en Amazon DocumentDB. Puede utilizar la herramienta de indexación de Amazon DocumentDB para exportar e importar índices.

Seleccione una de las siguientes opciones para restaurar los datos:

Supervisión

En esta sección se proporciona un proceso de supervisión detallado para hacer un seguimiento del progreso, el rendimiento y el estado de una migración en curso:

De MongoDB a Amazon DocumentDB

o

De Amazon DocumentDB a Amazon DocumentDB

Los pasos de supervisión se aplican independientemente del método de migración (AWS DMS, mongodump/mongorestore u otras herramientas).

AWS DMS Supervisión de la migración (si corresponde)

Supervise las siguientes CloudWatch métricas clave:

Métricas de la fase de carga completa

Métricas de la fase de CDC

Métricas de recursos

Métricas de errores

Cree CloudWatch alarmas para métricas críticas, como CDCLatencyTarget recibir notificaciones si CPUUtilization el rendimiento de la migración se deteriora.

Registros de DMS (registros) CloudWatch

Estado de la tarea de DMS (utilizando AWS CLI)

aws dms describe-replication-tasks --filters Name=replication-task id,Values=<task_id> --query
"ReplicationTasks[0].Status"

Flujo de estado previsto:

crear → listo → en ejecución → detener → detenido (o fallido)

Supervise usando docdb-dashboarder

La docdb-dashboarder herramienta proporciona una supervisión integral de los clústeres de Amazon DocumentDB mediante la generación automática de CloudWatch cuadros de mando con las métricas de rendimiento esenciales. Estos paneles muestran métricas críticas a nivel de clúster (retraso de réplica, contadores de operaciones), métricas a nivel de instancia (CPU, memoria, conexiones) y métricas de almacenamiento (uso del volumen, almacenamiento de copias de seguridad). Para las situaciones de migración, la herramienta ofrece paneles especializados que rastrean el progreso de la migración con métricas como el retraso en la replicación de la CDC y las tasas de operación. Los paneles pueden monitorear varios clústeres simultáneamente e incluyen soporte para NVMe instancias respaldadas. Si visualiza estas métricas, los equipos pueden identificar de forma proactiva los cuellos de botella en el rendimiento, optimizar la asignación de recursos y garantizar el buen funcionamiento de sus implementaciones de Amazon DocumentDB. La herramienta elimina la necesidad de crear un panel manual y, al mismo tiempo, proporciona una supervisión uniforme en todos los entornos. Para obtener instrucciones de configuración y opciones de configuración avanzadas, consulte el repositorio de herramientas Amazon DocumentDB Dashboarder. GitHub

Validación

En esta sección se proporciona un proceso de validación detallado para garantizar la coherencia de datos, la integridad y la compatibilidad de las aplicaciones tras la migración:

De MongoDB a Amazon DocumentDB

o

De Amazon DocumentDB a Amazon DocumentDB

Los pasos de validación se aplican independientemente del método de migración (AWS DMS, mongodump/mongorestore u otras herramientas).

Lista de comprobación de validación

Compruebe que el número de documentos de cada colección coincide con el de origen y el de destino:

MongoDB como origen

mongo --host <source_host> --port <port> --username <user> -- password <password> --eval
"db.<collection>.count()"

Amazon DocumentDB como destino

mongo --host <target_host> --port <port> --username <user> -- password <password> --eval
"db.<collection>.count()"

Validación de esquemas e índices

Asegúrese de que:

Comprobación de colecciones (origen frente a destino)

mongo --host <source_host> --eval "show collections"
mongo --host <target_host> --ssl --eval "show collections"

Comprobación de índices (origen frente a destino)

mongo --host <source_host> --eval" db.<collection>.getIndexes()"
mongo --host <target_host> --ssl –eval" db.<collection>.getIndexes()"

Compare la lista de colecciones para asegurarse de que no haya colecciones faltantes ni adicionales.

Verifique los índices. Para ello, compruebe los nombres de los índices, las definiciones clave, las restricciones únicas y los índices TTL (si los hubiera).

Comprobación de reglas de validación de esquemas (si usa la validación de esquemas en MongoDB)

mongo --host <source_host> --eval" db.getCollectionInfos({name: '<collection>'})
[0].options.validator"
   mongo --host <target_host> --ssl –eval" db.getCollectionInfos({name: '<collection>'})[0].options.validator"

Muestreo de datos y validación a nivel de campo

Puede muestrear documentos de forma aleatoria y comparar campos entre el origen y el destino.

Muestreo manual

Obtenga cinco documentos aleatorios (origen):

mongo --host <source_host> --eval "db.<collection>.aggregate([{ \$sample: { size: 5 } }])"

Obtenga el mismo documento IDs (destino):

mongo --host <target_host> --ssl –eval "db.<collection>.find({ _id: { \$in: [<list_of_ids>] } })"

Muestreo automático

import pymongo
# Connect to source and target
source_client = pymongo.MongoClient("<source_uri>")
target_client = pymongo.MongoClient("<target_uri>", ssl=True)
source_db = source_client["<db_name>"]
target_db = target_client["<db_name>"]
# Compare 100 random documents
for doc in source_db.<collection>.aggregate([{ "$sample":
{ "size": 100 } }]):
target_doc = target_db.<collection>.find_one({ "_id":
doc["_id"] })
if target_doc != doc:
print(f"❌ Mismatch in _id: {doc['_id']}")
else:
print(f"✅ Match: {doc['_id']}")

Validación mediante herramienta DataDiffer

La DataDiffer herramienta proporciona una forma fiable de comparar los datos entre las bases de datos de origen y destino.

Requisitos previos

Se deben cumplir los siguientes requisitos previos antes de instalar la DataDiffer herramienta:

Instalación y configuración

Clona el repositorio y navega hasta el DataDiffer directorio

git clone https://github.com/awslabs/amazon-documentdb-tools.git
cd amazon-documentdb-tools/migration/data-differ

Instale las dependencias requeridas.

pip install -r requirements.txt

Ejecución de validación de datos

Cree un archivo de configuración (por ejemplo, config.json) con los detalles de la conexión.

{
"source": {
"uri": "mongodb://username:password@source-mongodb-
host:27017/?replicaSet=rs0",
"db": "your_database",
"collection": "your_collection"
},
"target": {
"uri": "mongodb://username:password@target-docdb-
cluster.region.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-
bundle.pem&replicaSet=rs0",
"db": "your_database",
"collection": "your_collection"
},
"options": {
"batch_size": 1000,
"threads": 4,
"sample_size": 0,
"verbose": true
}
}

Ejecute la DataDiffer herramienta

python differ.py --config config.json

En el caso de colecciones grandes, utilice el muestreo para validar un subconjunto de datos.

python differ.py --config config.json --sample-size 10000

Para validar varias colecciones, cree archivos de configuración independientes o utilice el modo por lotes

python differ.py --batch-config batch_config.json

Interpretación de los resultados

El resultado que mostrará la herramienta incluirá lo siguiente:

Prácticas recomendadas

Las siguientes son las prácticas recomendadas a la hora de utilizar la DataDiffer herramienta: