Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Manuel de migration vers Amazon DocumentDB

Ce runbook fournit un guide complet pour la migration d'une base de données MongoDB vers Amazon DocumentDB à l'aide AWS Database Migration Service de (DMS). Il est conçu pour aider les administrateurs de bases de données, les ingénieurs cloud et les développeurs tout au long du processus de migration de bout en bout, de la découverte initiale à la validation après la migration.

Compte tenu des différences d'implémentation et de fonctionnalités prises en charge entre MongoDB et Amazon DocumentDB, ce runbook met l'accent sur une approche structurée et systématique. Il présente les principales évaluations préalables à la migration, met en lumière les considérations de compatibilité et détaille les tâches clés requises pour garantir une migration réussie avec un minimum de perturbations.

Le runbook est organisé selon les rubriques suivantes :

En suivant les instructions de ce manuel, les équipes peuvent garantir une transition fluide, sécurisée et efficace vers Amazon DocumentDB, tout en préservant les fonctionnalités de l'application et en minimisant les risques.

Compatibilité

Lors de la migration de MongoDB vers Amazon DocumentDB, une évaluation initiale approfondie et un contrôle de compatibilité des fonctionnalités sont essentiels pour une migration réussie. Ce processus commence par un inventaire complet de vos fonctionnalités MongoDB, y compris les opérateurs de pipeline d'agrégation, les modèles de requêtes, les index et les modèles de données.

Amazon DocumentDB étant compatible avec les API MongoDB 3.6, 4.0, 5.0 et 8.0, les applications utilisant de nouvelles MongoDB-specific fonctionnalités peuvent nécessiter une refactorisation. Les domaines critiques à évaluer incluent les mécanismes de partitionnement (Amazon DocumentDB utilise une approche différente), les implémentations de transactions, la fonctionnalité des flux de modifications et les types d'index (en particulier les index fragmentés et partiels).

Les caractéristiques de performances diffèrent également, Amazon DocumentDB étant optimisé pour les charges de travail d'entreprise avec des performances prévisibles. Les tests doivent impliquer l'exécution de charges de travail représentatives sur les deux systèmes afin d'identifier les modèles de requêtes susceptibles de nécessiter une optimisation.

Le suivi des plans d'exécution afin de détecter d'éventuels écarts de performance est important pendant la phase d'évaluation. Cela permet de créer une feuille de route de migration claire, d'identifier les modifications nécessaires aux applications et d'établir des délais réalistes pour une transition en douceur.

Compatibilité des fonctionnalités de base

Support complet des fonctionnalités

Amélioré AWS-fonctionnalités intégrées

Avantages de l'architecture moderne

Pour une présentation complète des fonctionnalités d'Amazon DocumentDB, reportez-vous au API, opérations et types de données MongoDB pris en charge dans Amazon DocumentDB et Différences fonctionnelles : Amazon DocumentDB et MongoDB pour optimiser le potentiel de votre base de données.

Amazon DocumentDB ne prend pas en charge tous les index proposés par MongoDB. Nous fournissons un outil d'indexation gratuit pour vérifier la compatibilité. Exécutez l'outil d'indexation pour évaluer l'incompatibilité et planifier des solutions de contournement en conséquence.

Outil d'évaluation de la compatibilité Amazon DocumentDB

L'outil de compatibilité entre MongoDB et Amazon DocumentDB est un utilitaire open source disponible sur GitHub qui permet d'évaluer la compatibilité de la charge de travail de MongoDB avec Amazon DocumentDB en analysant les journaux MongoDB ou le code source de l'application.

Fonctions principales

Méthodes d'évaluation

Log-based évaluation

Analyse du code source

Pour de meilleurs résultats, utilisez les deux méthodes d'évaluation dans la mesure du possible afin d'obtenir une image complète des problèmes de compatibilité avant la migration.

Découverte des charges de travail

La migration de MongoDB vers Amazon DocumentDB nécessite une compréhension approfondie de la charge de travail de base de données existante. La découverte de la charge de travail consiste à analyser les modèles d'utilisation de votre base de données, les structures de données, les performances des requêtes et les dépendances opérationnelles afin de garantir une transition fluide avec un minimum de perturbations. Cette section décrit les principales étapes de la découverte de la charge de travail afin de faciliter une migration efficace de MongoDB vers Amazon DocumentDB.

Évaluation du déploiement actuel de MongoDB

Avant la migration, il est essentiel d'évaluer l'environnement MongoDB actuel, notamment :

Identifier les différences entre les modèles de données

Bien qu'Amazon DocumentDB le soit MongoDB-compatible, il existe des différences dans les fonctionnalités prises en charge, telles que :

Analyse des requêtes et des performances

Comprendre le comportement des requêtes permet d'optimiser les performances de migration et de post-migration. Les principaux domaines à analyser sont les suivants :

Révision de la sécurité et du contrôle d'accès

Authentification et autorisation

Chiffrement

Assurez-vous que le chiffrement au repos et en transit est conforme aux exigences de conformité.

Configuration réseau

Planifiez la configuration du Virtual Private Cloud (VPC) et les règles des groupes de sécurité.

Considérations relatives au fonctionnement et à la surveillance

Pour maintenir la fiabilité du système, la découverte de la charge de travail doit également inclure :

Migration des index

La migration de MongoDB vers Amazon DocumentDB implique de transférer non seulement des données, mais également des index afin de maintenir les performances des requêtes et d'optimiser les opérations de base de données. Cette section décrit le processus détaillé étape par étape pour migrer les index de MongoDB vers Amazon DocumentDB tout en garantissant la compatibilité et l'efficacité.

Utilisation de l'outil d'indexation Amazon DocumentDB

Cloner l'outil d'index

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

pip install -r requirements.txt

Exporter des index depuis MongoDB (en cas de migration depuis MongoDB)

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

Exporter des index depuis Amazon DocumentDB (en cas de migration depuis 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'

Importer des index

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'

Vérifier les index

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

Migration d'utilisateur

La migration des utilisateurs de MongoDB vers Amazon DocumentDB est essentielle pour maintenir le contrôle d'accès, l'authentification et la sécurité des bases de données. Cette section décrit les étapes détaillées à suivre pour réussir la migration des utilisateurs de MongoDB tout en préservant leurs rôles et leurs autorisations à l'aide de l'outil d'exportation utilisateur Amazon DocumentDB.

Utilisation de l'outil d'exportation des utilisateurs d'Amazon DocumentDB

Les utilisateurs et les rôles sont Export Users tool exportés depuis MongoDB ou Amazon DocumentDB vers JavaScript des fichiers, qui peuvent ensuite être utilisés pour les recréer dans un autre cluster.

Conditions préalables

# 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

Étape 1 : Exporter les utilisateurs et les rôles

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

Étape 2 : Modifier le fichier des utilisateurs

// 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" }
]
})

Étape 3 : Restaurer les rôles personnalisés dans Amazon DocumentDB

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

Étape 4 : Restaurer les utilisateurs dans 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

Remarques importantes

Cette méthode fournit une approche sécurisée et flexible pour la migration des utilisateurs et des rôles de MongoDB vers Amazon DocumentDB tout en permettant de réinitialiser les mots de passe pendant le processus de migration.

Migrations des données

Migration en ligne

Cette section décrit les étapes détaillées à suivre pour effectuer une migration en ligne de MongoDB vers Amazon DocumentDB afin de minimiser les temps d'arrêt et de garantir une réplication continue. AWS DMS Pour commencer, vous devez configurer un cluster Amazon DocumentDB comme cible et vous assurer que votre instance MongoDB est correctement configurée en tant que source, ce qui nécessite généralement le mode jeu de répliques pour la capture des données de modification. Ensuite, vous créez une instance de réplication DMS et définissez les points de terminaison source et cible avec les informations de connexion nécessaires. Après avoir validé les points de terminaison, vous configurez et lancez une tâche de migration qui peut inclure le chargement complet des données, la réplication continue, ou les deux.

Configurer la cible (Amazon DocumentDB)

Création d'un groupe de paramètres personnalisé

Consultez nos Console de gestion AWS AWS CLI procédures dansCréation de groupes de paramètres de cluster Amazon DocumentDB.

Création d'un cluster Amazon DocumentDB

Configuration de la source

MongoDB et Amazon DocumentDB peuvent tous deux servir de sources de migration, selon votre scénario :

Avant de commencer la migration, configurez votre source pour autoriser AWS DMS l'accès.

Créez un utilisateur MongoDB avec les autorisations appropriées :

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

Configurez le réseau et l'authentification.

Lors de la configuration de la connectivité réseau pour la migration de MongoDB vers DMS :

EC2-hosted Source de MongoDB

On-premises Source de MongoDB

Source de l'Atlas MongoDB

Source d'Amazon DocumentDB

Configurez votre groupe de sécurité Amazon DocumentDB source pour autoriser le trafic entrant en provenance du groupe de sécurité de l'instance de réplication DMS.

Création d'une instance de réplication DMS

Utilisez DMS Buddy pour provisionner votre infrastructure DMS. Il crée une infrastructure de migration optimale avec des paramètres DMS et des tailles d'instance optimaux.

Si vous préférez configurer manuellement, procédez comme suit :

Création de points de terminaison DMS

Création d'un point de terminaison source

Pour une source MongoDB

Pour une source Amazon DocumentDB

Création d'un point de terminaison cible (Amazon DocumentDB)

Créer une tâche de réplication

Migration hors ligne

Cette section décrit la procédure à suivre pour effectuer une migration hors ligne depuis une instance MongoDB autogérée vers Amazon DocumentDB à l'aide des outils natifs de MongoDB : et. mongodump mongorestore

Conditions préalables

Exigences relatives à Source MongoDB

Configuration requise pour Target Amazon DocumentDB

Exigences générales

Préparer un cluster Amazon DocumentDB

Créez un cluster Amazon DocumentDB dans AWS :

Effectuez le vidage des données (mongodump)

Choisissez l'une des options suivantes pour créer un fichier de vidage :

Transférer les fichiers de vidage vers l'environnement de restauration

Choisissez une méthode appropriée en fonction de la taille de votre décharge :

Restaurer les données sur Amazon DocumentDB (mongorestore)

Avant de démarrer le processus de restauration, créez les index dans Amazon DocumentDB. Vous pouvez utiliser l'outil Amazon DocumentDB Index pour exporter et importer des index.

Choisissez l'une des options suivantes pour restaurer les données :

Contrôle

Cette section fournit un processus de surveillance détaillé permettant de suivre la progression, les performances et l'état d'une migration en cours depuis :

MongoDB vers Amazon DocumentDB

or

Amazon DocumentDB vers Amazon DocumentDB

Les étapes de surveillance s'appliquent quelle que soit la méthode de migration (AWS DMS mongodump/mongorestore, ou autres outils).

AWS DMS Surveillance de la migration (le cas échéant)

Surveillez les CloudWatch indicateurs clés suivants :

Métriques de la phase de pleine charge

Métriques de phase du CDC

Indicateurs relatifs aux ressources

Métriques d'erreur

Créez des CloudWatch alarmes pour des indicateurs critiques tels que CDCLatencyTarget et CPUUtilization pour recevoir des notifications en cas de dégradation des performances de migration.

Journaux DMS (CloudWatch journaux)

État de la tâche DMS (à l'aide de AWS CLI)

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

Flux d'état attendu :

création → prêt → en cours d'exécution → arrêt → arrêté (ou échec)

Surveiller à l'aide de docdb-dashboarder

L'docdb-dashboarderoutil fournit une surveillance complète des clusters Amazon DocumentDB en générant automatiquement des CloudWatch tableaux de bord contenant des indicateurs de performance essentiels. Ces tableaux de bord affichent des mesures critiques au niveau du cluster (retard de réplication, compteurs d'opérations), des mesures au niveau de l'instance (processeur, mémoire, connexions) et des mesures de stockage (utilisation du volume, stockage de sauvegarde). Pour les scénarios de migration, l'outil propose des tableaux de bord spécialisés qui suivent la progression de la migration à l'aide de mesures telles que le décalage de réplication CDC et les taux de fonctionnement. Les tableaux de bord peuvent surveiller plusieurs clusters simultanément et incluent la prise en charge des NVMe-backed instances. En visualisant ces indicateurs, les équipes peuvent identifier de manière proactive les goulots d'étranglement en matière de performances, optimiser l'allocation des ressources et garantir le bon fonctionnement de leurs déploiements Amazon DocumentDB. L'outil élimine le besoin de créer manuellement des tableaux de bord tout en fournissant une surveillance cohérente dans tous les environnements. Pour obtenir des instructions de configuration et des options de configuration avancées, consultez le référentiel Amazon DocumentDB Dashboarder Tool. GitHub

Validation

Cette section décrit un processus de validation détaillé pour garantir la cohérence, l'intégrité et la compatibilité des applications des données après la migration depuis :

MongoDB vers Amazon DocumentDB

or

Amazon DocumentDB vers Amazon DocumentDB

Les étapes de validation s'appliquent quelle que soit la méthode de migration (AWS DMS mongodump/mongorestore, ou autres outils).

Liste de contrôle de validation

Vérifiez que le nombre de documents de chaque collection correspond à celui de la source à celui de la cible :

Source de MongoDB

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

Cible Amazon DocumentDB

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

Validation du schéma et de l'index

Assurez-vous que :

Vérifiez les collections (source ou cible)

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

vérifier les index (source ou cible)

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

Comparez la liste des collections pour vous assurer qu'il n'y a aucune collection manquante ou supplémentaire.

Vérifiez les index en vérifiant les noms des index, les définitions de clés, les contraintes uniques et les index TTL (le cas échéant).

Vérifiez les règles de validation des schémas (si vous utilisez la validation des schémas dans 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"

Échantillonnage des données et validation sur le terrain

Vous pouvez échantillonner des documents de manière aléatoire et comparer les champs entre la source et la cible.

Échantillonnage manuel

Récupérez cinq documents au hasard (source) :

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

Récupérez les mêmes identifiants de document (cible) :

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

Échantillonnage automatique

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']}")

Validation via DataDiffer un outil

L'DataDiffer outil fournit un moyen fiable de comparer les données entre les bases de données source et cible.

Conditions préalables

Les conditions préalables suivantes doivent être remplies avant d'installer l' DataDiffer outil :

Configuration et installation

Clonez le référentiel et accédez au DataDiffer répertoire

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

Installation des dépendances requises

pip install -r requirements.txt

Validation des données en cours

Créez un fichier de configuration (par exemple, config.json) avec les détails de connexion

{
"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
}
}

Exécutez l' DataDiffer outil

python differ.py --config config.json

Pour les grandes collections, utilisez l'échantillonnage pour valider un sous-ensemble de données

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

Pour valider plusieurs collections, créez des fichiers de configuration distincts ou utilisez le mode batch

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

Interprétation des résultats

L'outil produira :

Bonnes pratiques

Voici les meilleures pratiques à adopter lors de l'utilisation de DataDiffer cet outil :