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 o (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 migração de ponta a ponta, 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 MongoDB 3.6, 4.0, 5.0 e 8.0, os aplicativos que usam recursos mais novos MongoDB-specific 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

Avançado AWS-recursos integrados

Vantagens da arquitetura moderna

Para obter uma visão geral abrangente dos recursos do Amazon DocumentDB, consulte APIs, operações e tipos de dados do MongoDB 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. Nós fornecemos uma ferramenta de indexação gratuita GitHub para verificar a compatibilidade. Execute a ferramenta de indexação para avaliar a incompatibilidade e planejar soluções alternativas adequadamente.

Ferramenta de avaliação de compatibilidade do Amazon DocumentDB

A ferramenta de compatibilidade do Amazon DocumentDB GitHub analisa sua MongoDB carga de trabalho e relata operadores, comandos e recursos que não são suportados ou exigem alterações no Amazon DocumentDB. Ele suporta versões de destino de 3.6 a 8.0.1 (padrão: 8.0.1).

Recomendado: modo URI (MongoDB5.0+)

O modo URI se conecta diretamente à sua instância do MongoDB, faz amostras de operações em tempo real e não requer criação de perfil ou acesso a registros.

Métodos alternativos

Pré-requisitos

Para obter detalhes completos de uso e todas as opções disponíveis, consulte o README em GitHub.

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 MongoDB-compatible, existem diferenças nos recursos suportados, 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:

Criar novo cluster de destino

Crie um cluster Amazon DocumentDB seguindo as etapas emCriar um cluster do Amazon DocumentDB. Ao configurar o cluster para migração, aplique estas recomendações:

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

Clone a ferramenta de indexação em GitHub

git clone https://github.com/awslabs/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 index_export \
  --uri 'mongodb://<username>:<password>@<source_endpoint>:27017'

Verificação de índices

python3 migrationtools/documentdb_index_tool.py \
  --show-issues \
  --dir index_export

Importação de índices

python3 migrationtools/documentdb_index_tool.py \
  --restore-indexes \
  --skip-incompatible \
  --dir index_export \
  --uri 'mongodb://<username>:<password>@<target_endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&retryWrites=false'

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 tool exporta usuários e funções do MongoDB ou do Amazon DocumentDB para JavaScript arquivos, que podem então 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://<username>:<password>@<source_endpoint>:27017"

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

As senhas não são exportadas por motivos de segurança. Abra o mongodb-users.js arquivo e adicione uma senha para cada usuário substituindo o pwd valor em cada createUser instrução:

db.getSiblingDB("admin").createUser({
  user: "appuser",
  pwd: "REPLACE_THIS_PASS",
  roles: [
    { role: "readWrite", db: "mydb" }
  ]
})

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

# Import roles first
mongosh \
  --tls \
  --host <target_endpoint>:27017 \
  --tlsCAFile global-bundle.pem \
  --username <username> \
  --password <password> \
  mongodb-roles.js

Etapa 4: restauração de usuários no Amazon DocumentDB

# Import users after roles are created
mongosh \
  --tls \
  --host <target_endpoint>:27017 \
  --tlsCAFile global-bundle.pem \
  --username <username> \
  --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 usando para permitir o mínimo de tempo de inatividade e AWS DMS 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.

Criar novo cluster de destino

Consulte Criar novo cluster de destino.

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: "<password>",
  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-hosted Origem do MongoDB

On-premises Origem do MongoDB

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.

Use o DMS Buddy on GitHub para criar uma infraestrutura de migração ideal com configurações e tamanhos de instância de DMS 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

Consulte Criar novo cluster de destino.

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 acompanhar o progresso, o desempenho e a integridade de uma migração contínua.

As etapas de monitoramento se aplicam independentemente do método de migração (AWS DMS mongodump/mongorestore, ou de 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 ao gerar automaticamente CloudWatch painéis com métricas de desempenho essenciais. 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 NVMe-backed instâncias. 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 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 dos dados, a integridade e a compatibilidade dos aplicativos após a migração.

As etapas de validação se aplicam independentemente do método de migração (AWS DMS mongodump/mongorestore, ou de 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

mongosh \
  --host <source_endpoint> \
  --port 27017 \
  --username <user> \
  --password <password> \
  --eval "db.<collection>.countDocuments()"

Destino do Amazon DocumentDB

mongosh \
  --host <target_endpoint> \
  --port 27017 \
  --username <user> \
  --password <password> \
  --tls \
  --tlsCAFile global-bundle.pem \
  --eval "db.<collection>.countDocuments()"

Validação de esquema e índices

Verifique se:

Verifique as coleções (origem versus destino)

mongosh --host <source_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --eval "db = db.getSiblingDB('<database>'); db.getCollectionNames();"

mongosh --host <target_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --tls --tlsCAFile global-bundle.pem \
  --eval "db = db.getSiblingDB('<database>'); db.getCollectionNames();"

Verifique os índices (origem versus destino)

mongosh --host <source_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --eval "db.<collection>.getIndexes()"

mongosh --host <target_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --tls --tlsCAFile global-bundle.pem \
  --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)

mongosh --host <source_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --eval "db.getCollectionInfos({name: '<collection>'})[0].options.validator"

mongosh --host <target_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --tls --tlsCAFile global-bundle.pem \
  --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):

mongosh --host <source_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --eval "db.<collection>.aggregate([{ \$sample: { size: 5 } }])"

Obtenha os mesmos IDs de documentos (destino):

mongosh --host <target_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --tls --tlsCAFile global-bundle.pem \
  --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>",
                                    tls=True,
                                    tlsCAFile='global-bundle.pem')
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 on GitHub 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 DataDiffer ferramenta:

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_endpoint>:27017/?replicaSet=rs0",
    "db": "your_database",
    "collection": "your_collection"
  },
  "target": {
    "uri": "mongodb://<username>:<password>@<target_endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&retryWrites=false",
    "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

A seguir estão as melhores práticas ao usar a DataDiffer ferramenta: