As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Runbook de migração do Amazon DocumentDB

Este runbook fornece um guia abrangente para migrar um banco de dados MongoDB para o Amazon DocumentDB usando (DMS). AWS Database Migration Service Ele foi projetado para oferecer suporte a administradores de banco de dados, engenheiros de nuvem e desenvolvedores em toda a jornada de end-to-end migração, desde a descoberta inicial até a validação pós-migração.

Dadas as diferenças na implementação e nos recursos com suporte entre o MongoDB e o Amazon DocumentDB, este runbook enfatiza uma abordagem estruturada e sistemática. Ele descreve as avaliações essenciais de pré-migração, destaca as considerações de compatibilidade e detalha as principais tarefas necessárias para garantir uma migração com êxito e com o mínimo de interrupções.

O runbook está organizado nos tópicos a seguir:

Seguindo as orientações deste runbook, as equipes podem garantir uma transição tranquila, segura e eficiente para o Amazon DocumentDB, preservando a funcionalidade da aplicação e minimizando os riscos.

Compatibilidade

Ao migrar do MongoDB para o Amazon DocumentDB, uma avaliação inicial completa e uma verificação de compatibilidade de recursos são essenciais para uma migração com êxito. Esse processo começa com um inventário abrangente dos recursos do MongoDB, incluindo operadores de pipeline de agregação, padrões de consulta, índices e modelos de dados.

Como o Amazon DocumentDB é compatível com as APIs do MongoDB 3.6, 4.0 e 5.0, as aplicações que usam recursos específicos do MongoDB podem exigir refatoração. As áreas críticas a serem avaliadas incluem mecanismos de fragmentação (o Amazon DocumentDB usa uma abordagem diferente), implementações de transações, funcionalidade de fluxos de mudança e tipos de índice (especialmente índices esparsos e parciais).

As características de performance também diferem, com o Amazon DocumentDB otimizado para workloads corporativas com performance previsível. Os testes devem envolver a execução de workloads representativas em ambos os sistemas para identificar padrões de consulta que possam precisar de otimização.

Monitorar os planos de execução para detectar possíveis lacunas de performance é importante durante a fase de avaliação. Isso ajuda a criar um roteiro de migração claro, identificando as mudanças necessárias nas aplicações e estabelecendo cronogramas realistas para uma transição suave.

compatibilidade de recursos principais

Suporte a recursos abrangentes

Recursos AWS integrados aprimorados

Vantagens da arquitetura moderna

Para obter uma visão geral abrangente dos recursos do Amazon DocumentDB, consulte APIsMongoDB, operações e tipos de dados compatíveis no Amazon DocumentDB e Diferenças funcionais: Amazon DocumentDB e MongoDB para maximizar o potencial do seu banco de dados.

O Amazon DocumentDB não oferece suporte a todos os índices oferecidos pelo MongoDB. Fornecemos uma ferramenta de índice gratuita para verificar a compatibilidade. Recomendamos executar a ferramenta de índice para avaliar a incompatibilidade e planejar soluções alternativas adequadamente.

Ferramenta de avaliação de compatibilidade do Amazon DocumentDB

A ferramenta de compatibilidade do MongoDB para o Amazon DocumentDB é um utilitário de código aberto disponível no GitHub que ajuda a avaliar a compatibilidade da carga de trabalho do MongoDB com o Amazon DocumentDB analisando os registros do MongoDB ou o código-fonte do aplicativo.

Recursos principais

Métodos de avaliação

Avaliação baseada em logs

Análise de código-fonte

Para obter melhores resultados, recomendamos usar os dois métodos de avaliação sempre que possível para obter uma visão completa dos desafios de compatibilidade antes da migração.

Descoberta de workload

A migração do MongoDB para o Amazon DocumentDB exige uma compreensão completa da workload do banco de dados existente. A descoberta da workload é o processo de analisar os padrões de uso do banco de dados, as estruturas de dados, a performance das consultas e as dependências operacionais para garantir uma transição perfeita com o mínimo de interrupção. Esta seção descreve as principais etapas envolvidas na descoberta da workload para facilitar uma migração efetiva do MongoDB para o Amazon DocumentDB.

Avaliação da implantação existente do MongoDB

Antes da migração, é fundamental avaliar o ambiente atual do MongoDB, incluindo:

Identificação de diferenças no modelo de dados

Embora o Amazon DocumentDB seja compatível com o MongoDB, há diferenças nos recursos com suporte, como:

Análise de consultas e de performance

Compreender o comportamento das consultas ajuda a otimizar a migração e a performance pós-migração. As principais áreas a serem analisadas incluem:

Verificação de segurança e controle de acesso

Autenticação e autorização

Criptografia

Garanta que a criptografia em repouso e em trânsito esteja alinhada aos requisitos de conformidade.

Configuração de rede

Planeje a configuração da nuvem privada virtual (VPC) e as regras do grupo de segurança.

Considerações operacionais e de monitoramento

Para manter a confiabilidade do sistema, a descoberta de workloads também deve incluir:

Migração de índices

A migração do MongoDB para o Amazon DocumentDB envolve a transferência não apenas de dados, mas também de índices para manter a performance das consultas e otimizar as operações do banco de dados. Esta seção descreve o step-by-step processo detalhado de migração de índices do MongoDB para o Amazon DocumentDB e, ao mesmo tempo, garante compatibilidade e eficiência.

Uso da ferramenta de índice do Amazon DocumentDB

Clonagem da ferramenta de índice

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

pip install -r requirements.txt

Exportação de índices do MongoDB (se estiver migrando a partir do MongoDB)

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

Exportação de índices do Amazon DocumentDB (se estiver migrando a partir do 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'

Importação de índices

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'

Verificação de índices

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

Migração do usuário

A migração de usuários do MongoDB para o Amazon DocumentDB é essencial para manter o controle de acesso, a autenticação e a segurança do banco de dados. Esta seção descreve as etapas detalhadas para uma migração com êxito dos usuários do MongoDB, preservando seus perfis e permissões, por meio da ferramenta de exportação de usuários do Amazon DocumentDB.

Uso da ferramenta de exportação de usuários do Amazon DocumentDB

Ele Export Users toolexporta usuários e funções do MongoDB ou do Amazon DocumentDB JavaScript para arquivos, que podem ser usados para recriá-los em outro cluster.

Pré-requisitos

# 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

Etapa 1: exportação de usuários e perfis

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

Etapa 2: edição do arquivo do usuário

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

Etapa 3: restauração de perfis personalizados no Amazon DocumentDB

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

Etapa 4: restauração de usuários no 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

Observações importantes

Esse método fornece uma abordagem segura e flexível para migrar usuários e perfis do MongoDB para o Amazon DocumentDB, permitindo redefinições de senha durante o processo de migração.

Migrações de dados

migração online

Esta seção fornece etapas detalhadas para realizar uma migração on-line do MongoDB para o Amazon DocumentDB AWS DMS usando para permitir o mínimo de tempo de inatividade e a replicação contínua. Para começar, você configura um cluster do Amazon DocumentDB como destino e garante que sua instância do MongoDB esteja configurada corretamente como origem, normalmente exigindo o modo de conjunto de réplicas para a captura de dados de alteração. Em seguida, você cria uma instância de replicação do DMS e define os endpoints de origem e de destino com os detalhes de conexão necessários. Depois de validar os endpoints, você configura e inicia uma tarefa de migração que pode incluir carga total de dados, replicação contínua ou ambas.

Configuração do destino (Amazon DocumentDB)

Crie um grupo de parâmetros personalizado

Veja os AWS CLI procedimentos Console de gerenciamento da AWS ou emCriando grupos de parâmetros de cluster do Amazon DocumentDB.

Criar um cluster do Amazon DocumentDB

Configuração da fonte

O MongoDB e o Amazon DocumentDB podem servir como origens de migração, dependendo do seu cenário:

Antes de iniciar a migração, configure sua fonte para permitir o AWS DMS acesso.

Crie um usuário do MongoDB com as permissões adequadas:

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

Configure a rede e a autenticação.

Ao configurar a conectividade de rede para a migração do MongoDB para o DMS:

EC2-fonte MongoDB hospedada

Origem do MongoDB on-premises

Origem no MongoDB Atlas

Origem no Amazon DocumentDB

Configure seu grupo de segurança do Amazon DocumentDB de origem para permitir o tráfego de entrada do grupo de segurança da instância de replicação do DMS.

Criação de uma instância de replicação do DMS.

Recomendamos o uso do DMS Buddy para provisionar sua infraestrutura do DMS, pois ela cria uma infraestrutura de migração ideal com configurações de DMS e tamanhos de instância ideais.

Se preferir configurar manualmente, siga estas etapas:

Criação de endpoints da VPC

Criação de um endpoint de origem

Para uma origem do MongoDB

Para uma origem do Amazon DocumentDB

Criação de um endpoint de destino do Amazon DocumentDB.

Criação de tarefas de replicação

Migração offline

Esta seção descreve o processo para realizar uma migração offline de uma instância autogerenciada do MongoDB para o Amazon DocumentDB usando ferramentas nativas do MongoDB: mongodump e mongorestore.

Pré-requisitos

Requisitos do MongoDB de origem

Requisitos do Amazon DocumentDB de destino

Requisitos gerais

Criação de um cluster do Amazon DocumentDB

Criação de um cluster do Amazon DocumentDB na AWS:

Execute o despejo de dados (mongodump)

Escolha uma das opções a seguir para criar um arquivo de despejo:

Transferência dos arquivos de despejo para o ambiente de restauração

Escolha um método apropriado com base no tamanho do seu despejo:

Restauração dos dados no Amazon DocumentDB (mongorestore)

Antes de iniciar o processo de restauração, crie os índices no Amazon DocumentDB. É possível utilizar a ferramenta de índice do Amazon DocumentDB para exportar e importar índices.

Escolha uma das opções a seguir para restaurar os dados:

Monitoramento

Esta seção fornece um processo de monitoramento detalhado para monitorar o andamento, a performance e a integridade de uma migração contínua de:

MongoDB para Amazon DocumentDB

or

Amazon DocumentDB para Amazon DocumentDB

As etapas de monitoramento se aplicam independentemente do método de migração (AWS DMS, mongodump/mongorestore ou outras ferramentas).

AWS DMS Monitoramento da migração (se aplicável)

Monitore as seguintes CloudWatch métricas principais:

Métricas da fase de carga total

Métricas da fase do CDC

Métricas de recursos

Métricas de erros

Crie CloudWatch alarmes para métricas críticas, como CDCLatencyTarget e CPUUtilization para receber notificações se o desempenho da migração diminuir.

Registros do DMS (CloudWatch registros)

Status da tarefa do DMS (usando AWS CLI)

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

Fluxo de status esperado:

em criação → pronto → em execução → parando → parado (ou com falha

Monitore usando docdb-dashboarder

A docdb-dashboarder ferramenta fornece monitoramento abrangente para clusters do Amazon DocumentDB por meio da geração automática de CloudWatch painéis com métricas essenciais de desempenho. Esses painéis exibem métricas críticas em nível de cluster (atraso de réplica, contadores de operação), métricas em nível de instância (CPU, memória, conexões) e métricas de armazenamento (uso de volume, armazenamento de backup). Para cenários de migração, a ferramenta oferece painéis especializados que monitoram o andamento da migração com métricas como atraso na replicação do CDC e taxas de operação. Os painéis podem monitorar vários clusters simultaneamente e incluir suporte para instâncias NVMe apoiadas. Ao visualizar essas métricas, as equipes podem identificar proativamente gargalos de performance, otimizar a alocação de recursos e garantir o bom funcionamento de suas implantações do Amazon DocumentDB. A ferramenta elimina a necessidade de criação manual de painéis e, ao mesmo tempo, fornece monitoramento consistente em todos os ambientes. Para obter instruções de configuração e opções avançadas de configuração, consulte o repositório Amazon DocumentDB Dashboarder Tool. GitHub

Validação

Esta seção fornece um processo de validação detalhado para garantir a consistência de dados, sua integridade e a compatibilidade das aplicações após a migração de:

MongoDB para Amazon DocumentDB

or

Amazon DocumentDB para Amazon DocumentDB

As etapas de validação se aplicam independentemente do método de migração (AWS DMS, mongodump/mongorestore ou outras ferramentas).

Lista de verificação de validação

Verifique se o número de documentos em cada coleção corresponde entre a origem e o destino:

Origem do MongoDB

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

Destino do Amazon DocumentDB

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

Validação de esquema e índices

Verifique se:

Verifique as coleções (origem versus destino)

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

verifique os índices (origem versus destino)

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

Compare a lista de coleções para garantir que não haja coleções ausentes ou extras.

Verifique os índices verificando os nomes dos índices, as definições de chave, as restrições exclusivas e os índices de TTL (se houver).

Verifique as regras de validação do esquema (se estiver usando a validação de esquema do 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"

Amostragem de dados e validação em nível de campo

É possível amostrar documentos aleatoriamente e comparar campos entre origem e destino.

Amostragem manual

Obtenha cinco documentos aleatórios (origem):

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

Busque o mesmo documento IDs (destino):

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

Amostragem automática

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

Validação usando a DataDiffer ferramenta

A DataDiffer ferramenta fornece uma maneira confiável de comparar dados entre bancos de dados de origem e de destino.

Pré-requisitos

Os seguintes pré-requisitos devem ser atendidos antes da instalação da ferramenta: DataDiffer

Configuração e instalação

Clone o repositório e navegue até o diretório DataDiffer

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

Instale as dependências necessárias

pip install -r requirements.txt

Execução da validação de dados

Crie um arquivo de configuração (por exemplo, config.json) com detalhes da conexão

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

Execute a DataDiffer ferramenta

python differ.py --config config.json

Para coleções grandes, use a amostragem para validar um subconjunto de dados

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

Para validar várias coleções, crie arquivos de configuração separados ou use o modo de lote

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

Como interpretar os resultados do

A saída da ferramenta será:

Práticas recomendadas

Veja a seguir as melhores práticas ao usar a DataDiffer ferramenta: