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: + **[Compatibilidade](#mig-runbook-compatibility)**: noções básicas dos recursos e tipos de dados do MongoDB com suporte no Amazon DocumentDB e identificação de possíveis incompatibilidades. + **[Descoberta de workload](#mig-runbook-workload)**— analise as cargas de trabalho existentes do MongoDB, incluindo read/write padrões, volumes de dados e linhas de base de desempenho. + **[Migração de índices](#mig-runbook-index)**: análise de estratégias para extrair e transformar índices do MongoDB para obter uma performance ideal no Amazon DocumentDB. + **[Migração do usuário](#mig-runbook-user)**: detalhamento da abordagem para a migração de usuários, perfis e controles de acesso do banco de dados para o Amazon DocumentDB. + **[Migrações de dados](#mig-runbook-data)**— Aborde vários métodos de uso da migração de dados AWS DMS, incluindo carregamento total e captura de dados de alteração (CDC). + **[Monitoramento](#mig-runbook-monitoring)**: detalhamento de várias abordagens de monitoramento na migração usando o DMS ou ferramentas nativas. + **[Validação](#mig-runbook-validation)**: fornecimento de procedimentos para verificações de integridade de dados, validação funcional e comparação de performance após a migração. 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 **Topics** + [compatibilidade de recursos principais](#w2aac15b9c13c13) + [Ferramenta de avaliação de compatibilidade do Amazon DocumentDB](#w2aac15b9c13c15) 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 + **Operações CRUD**: aproveite o suporte completo a todas as operações básicas de criação, leitura, atualização e exclusão, incluindo operadores em massa e de consulta, oferecendo compatibilidade perfeita com aplicações. + **Recursos avançados de indexação**: aproveite o suporte abrangente para índices de campo único, compostos, TTL, parciais, esparsos e 2dsphere, para otimizar a performance de suas consultas e índices de texto (versão 5) para pesquisas baseadas em texto. + **Enterprise-grade replicação ** — beneficie-se de um mecanismo robusto de failover automático com réplicas de leitura para uma alta disponibilidade superior sem sobrecarga operacional. + **Soluções avançadas de backup ** — Fique tranquilo com o sistema de backup automatizado com Point-in-Time recuperação (PITR) e instantâneos manuais sob demanda para proteção de dados. #### Avançado AWS-recursos integrados + **Agregação simplificada**: aproveite os estágios de agregação mais usados (`$match`, `$group`, `$sort`, `$project`, etc.) com performance otimizada para workloads corporativas. + **Suporte a transações**: implemente transações com vários documentos e várias coleções, perfeitas para a maioria das necessidades das aplicações de negócios. + **Real-time rastreamento de dados ** — habilite fluxos de alterações por meio de um comando simples e aumente o período de retenção do fluxo de alterações por meio de uma configuração simples de grupo de parâmetros para monitoramento de alterações de dados em tempo real. + **Location-based serviços ** — Implemente aplicações geoespaciais com suporte para índices de `$geoNear` operadores e 2dsphere. + **Recursos de pesquisa de texto**: utilize a funcionalidade de pesquisa de texto integrada para as necessidades de descoberta de conteúdo. #### Vantagens da arquitetura moderna + **Cloud-native design ** — desfrute AWS de uma arquitetura otimizada que substitui recursos legados, como operações MapReduce de pipeline de agregação mais eficientes. + **Segurança aprimorada ** — Beneficie-se da autenticação de X.509 certificados AWS Identity and Access Management (IAM) SCRAM-SHA-1 SCRAM-SHA-256,, e da autenticação baseada em senha. + **Performance previsível**: experimente uma performance consistente otimizada especificamente para workloads corporativas. 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](mongo-apis.md) e [Diferenças funcionais: Amazon DocumentDB e MongoDB](functional-differences.md) 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 ](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md) 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 ](https://github.com/awslabs/amazon-documentdb-tools/blob/master/compat-tool/README.md) 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** + **Log-based análise ** — Analisa os registros do MongoDB perfilador. Captura o comportamento real do tempo de execução, mas exige que a criação de perfil esteja habilitada e cobre apenas o período de registro. + **Análise do código-fonte ** — Escaneia o código-fonte do aplicativo para uso MongoDB da API. Fornece cobertura abrangente, mas pode sinalizar caminhos de código não utilizados e não pode detectar consultas construídas dinamicamente. **Pré-requisitos** + Python3,7\+ + Clone a ferramenta: `git clone https://github.com/awslabs/amazon-documentdb-tools.git` + Instalar dependências: `pip install -r compat-tool/requirements.txt` Para obter detalhes completos de uso e todas as opções disponíveis, consulte o [ README ](https://github.com/awslabs/amazon-documentdb-tools/blob/master/compat-tool/README.md) 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. **Topics** + [Avaliação da implantação existente do MongoDB](#w2aac15b9c15b7) + [Identificação de diferenças no modelo de dados](#w2aac15b9c15b9) + [Análise de consultas e de performance](#w2aac15b9c15c11) + [Verificação de segurança e controle de acesso](#w2aac15b9c15c13) + [Considerações operacionais e de monitoramento](#w2aac15b9c15c15) ### Avaliação da implantação existente do MongoDB Antes da migração, é fundamental avaliar o ambiente atual do MongoDB, incluindo: + **Arquitetura do cluster**: identifique o número de nós, conjuntos de réplicas e configurações de fragmentação. Ao migrar do MongoDB para o Amazon DocumentDB, entender sua configuração de fragmentação do MongoDB é importante porque o Amazon DocumentDB não oferece suporte à fragmentação controlada pelo usuário. As aplicações projetadas para um ambiente fragmentado do MongoDB precisarão de mudanças arquitetônicas, pois o Amazon DocumentDB usa uma abordagem de escalabilidade diferente com sua arquitetura baseada em armazenamento. Você precisará adaptar sua estratégia de distribuição de dados e possivelmente consolidar coleções fragmentadas ao migrar para o Amazon DocumentDB. + **Armazenamento e volume de dados**: meça o tamanho total dos dados e o tamanho do índice do seu cluster. Complemente isso com a [ferramenta de revisão Oplog](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/mongodb-oplog-review) para entender os padrões de gravação e a velocidade de crescimento dos dados. Para obter mais informações sobre como dimensionar seu cluster, consulte [Dimensionamento de instância](best_practices.md#best_practices-instance_sizing). + **Padrões de workload**: analise o throughput de leitura e gravação, a frequência de execução de consultas e a eficiência da indexação. + **Dependências operacionais**: documente todas as aplicações, serviços e integrações que dependam do MongoDB. ### Identificação de diferenças no modelo de dados Embora o Amazon DocumentDB seja MongoDB-compatible, existem diferenças nos recursos suportados, como: + **Transações**: o Amazon DocumentDB oferece suporte a transações ACID, mas com algumas [Limitações](transactions.md#transactions-limitations). + **Design do esquema**: garanta que as estruturas dos documentos, os documentos incorporados e as referências estejam alinhados às [práticas recomendadas do Amazon DocumentDB](https://d1.awsstatic.com/product-marketing/Data%20modeling%20with%20Amazon%20DocumentDB.pdf). ### 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: + **Consultas lentas**: identifique consultas com alto tempo de execução usando as ferramentas de criação de perfil do MongoDB. + **Padrões de consulta**: categorize os tipos de consulta comuns, incluindo operações e agregações CRUD. + **Uso de índices** avalie se os índices são utilizados de forma eficaz ou se precisam de otimização no Amazon DocumentDB. Para avaliar o uso de índices e otimizar a performance no Amazon DocumentDB, use o estágio do pipeline de agregação `$indexStats` combinado com o método `explain()` em suas consultas críticas. Comece executando `db.collection.aggregate([{$indexStats{}}])` para identificar quais índices estão sendo usados. É possível fazer uma análise mais detalhada executando suas consultas mais frequentes com `explainPlan`. + **Concorrência e distribuição de workloads**: avalie as taxas de leitura e gravação, o pool de conexões e os gargalos de performance. ### Verificação de segurança e controle de acesso **Autenticação e autorização ** + **MongoDB RBAC para Amazon DocumentDB IAM e RBAC ** — Mapeie os usuários e funções de controle de acesso baseados em funções do MongoDB às políticas (IAM) e aos AWS Identity and Access Management usuários de autenticação SCRAM do Amazon DocumentDB. + **Estratégia de migração de usuários**: planeje a migração de usuários do banco de dados, perfis personalizados e privilégios para os mecanismos de autenticação com suporte no Amazon DocumentDB. + **Diferenças de privilégios**: identifique os privilégios do MongoDB sem equivalentes diretos do Amazon DocumentDB (por exemplo, perfis de administração de cluster). + **Autenticação de aplicações**: atualize strings de conexão e gerenciamento de credenciais para as políticas de senha do Amazon DocumentDB. É possível usar o gerenciador de segredos para armazenar suas credenciais e alternar senhas. + **Gerenciamento da conta de serviço ** — Estabeleça processos para gerenciar as credenciais da conta de serviço no AWS Secrets Manager. + **Implementação de privilégios mínimos**: revise e refine os controles de acesso para implementar os princípios de privilégios mínimos no novo ambiente. **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)](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) 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: + **Estratégia de backup e restauração**: avalie os métodos de backup existentes e os recursos de backup do Amazon DocumentDB. + **AWS Backup integração ** — Aproveite o gerenciamento centralizado AWS Backup de backup em todos AWS os serviços, incluindo o Amazon DocumentDB. + **CloudWatch métricas ** — Mapeie as métricas de monitoramento do MongoDB com as CloudWatch métricas do Amazon DocumentDB para CPU, memória, conexões e armazenamento. + **Insights de performance**: implemente os Insights de performance do Amazon DocumentDB para visualizar a carga do banco de dados e analisar problemas de performance com análises detalhadas das consultas. + **Profiler ** — Configure o Amazon DocumentDB Profiler para capturar operações de execução lenta (semelhante ao profiler do MongoDB, mas com configurações da Amazon). DocumentDB-specific + Habilite por meio de grupos de parâmetros com limites apropriados. + Analise os dados do profiler para identificar oportunidades de otimização + **CloudWatch Eventos ** — Configure o monitoramento orientado por eventos para eventos de cluster do Amazon DocumentDB. + Configure notificações para eventos de backup, janelas de manutenção e failovers. + Integre-se ao Amazon SNS para alertas e respostas AWS Lambda automatizadas. + **Logs de auditoria**: planeje a configuração dos logs de auditoria para rastrear a atividade do usuário e eventos relevantes à segurança. + **Monitoramento aprimorado ** — habilite o monitoramento aprimorado para OS-level métricas granulares em intervalos de 1 segundo. ## Criar novo cluster de destino Crie um cluster Amazon DocumentDB seguindo as etapas em[Criar um cluster do Amazon DocumentDB](db-cluster-create.md). Ao configurar o cluster para migração, aplique estas recomendações: + **Classe de instância: ** escolha R8G para obter o melhor desempenho. Se o R8G não estiver disponível na sua região de destino, use o R6G. Escolha a instância mais grande possível para obter a melhor taxa de transferência de carga total. Diminua a escala após a conclusão da migração. + **Versão do motor: ** mais recente (8.0.1) + **Número de instâncias: ** escolha 1 instância para minimizar os custos durante a migração. Escale para 3 instâncias para obter alta disponibilidade após a conclusão da migração de carga total. + **Configurações de rede: ** certifique-se de que seu grupo de segurança do Amazon DocumentDB permita conexões de entrada do grupo de segurança da instância de replicação do DMS (para migrações on-line) ou do host de migração do EC2 (para migrações offline usando mongorestore). ## 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 ](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md) 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://:@: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://:@: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`](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/export-users) 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://:@: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 :27017 \ --tlsCAFile global-bundle.pem \ --username {{}} \ --password {{}} \ mongodb-roles.js ``` **Etapa 4: restauração de usuários no Amazon DocumentDB** ``` # Import users after roles are created mongosh \ --tls \ --host :27017 \ --tlsCAFile global-bundle.pem \ --username {{}} \ --password {{}} \ mongodb-users.js ``` **Observações importantes** + As senhas não são exportadas por motivos de segurança e deverão ser adicionadas manualmente ao arquivo users.js. + Os perfis devem ser importados antes dos usuários para garantir a atribuição adequada dos perfis. + A ferramenta gera JavaScript arquivos que podem ser executados diretamente com o shell mongosh. + Os perfis personalizados e seus privilégios são preservados durante a migração. + Essa abordagem permite revisar e modificar as permissões do usuário antes da importação. 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 **Topics** + [migração online](#w2aac15b9c23b5) + [Migração offline](#w2aac15b9c23b7) ### 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](#mig-runbook-configure-target). #### Configuração da fonte O MongoDB e o Amazon DocumentDB podem servir como origens de migração, dependendo do seu cenário: + **MongoDB como fonte ** — Comum ao migrar de um MongoDB local ou autogerenciado para um Amazon DocumentDB ou outros serviços de banco de dados. AWS Requer execução no modo de conjunto de réplicas com um oplog de tamanho adequado (certifique-se de que seja dimensionado para conter todas as operações durante a carga total) para oferecer suporte à captura de dados de alterações durante a migração. + **Amazon DocumentDB como origem ** — normalmente usado para replicação entre regiões, atualizações de versão ou migração para outros serviços de banco de dados, como o MongoDB Atlas. Requer [Ativar fluxos de alterações](change_streams.md#change_streams-enabling) a partir da configuração do parâmetro `change_stream_log_retention_duration` no grupo de parâmetros do cluster para capturar as alterações em andamento durante a migração. Certifique-se de que sua configuração `change_stream_log_retention_duration` seja grande o suficiente para cobrir o tempo necessário para concluir a carga completa. 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: "{{}}", 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** + Modifique o grupo de segurança do EC2 para permitir o tráfego de entrada do grupo de segurança da instância de replicação do DMS. + Adicione uma regra para a porta 27017 de TCP (ou sua porta personalizada do MongoDB). + Use o ID do grupo de segurança da instância de replicação do DMS como fonte para um controle de acesso preciso. + Certifique-se de que a sub-rede da instância do EC2 tenha uma rota para a sub-rede da instância de replicação do DMS. **On-premises Origem do MongoDB** + Configure seu firewall para permitir conexões de entrada dos endereços IP públicos da instância de replicação do DMS. + Se estiver usando Direct Connect uma VPN, garanta o roteamento adequado entre sua rede e a VPC que contém a instância DMS. + Teste a conectividade usando comandos telnet ou nc da sub-rede do DMS para seu servidor do MongoDB. **Origem no MongoDB Atlas** + Adicione os endereços IP de uma instância de replicação do DMS à lista de permissões de IP do MongoDB Atlas. + Configure o emparelhamento de VPC entre AWS VPC e MongoDB Atlas VPC se o Atlas estiver em execução. AWS + Configure AWS PrivateLink para conectividade privada (nível Enterprise), se estiver sendo executado em outro provedor de nuvem. + Crie um usuário dedicado com read/write as permissões apropriadas. + Use uma string de conexão do MongoDB Atlas com o modo de SSL definido como “verify-full”. + Garanta um tamanho de oplog suficiente para a duração da migração. **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 ](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/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: 1. No AWS DMS console, no painel de navegação, escolha ** Migrar ou replicar e, em seguida**, escolha Instâncias provisionadas. ** ** 1. Insira os detalhes da instância de replicação: + **Nome da instância**: escolha um nome exclusivo. + **Classe da instância**: selecione com base na workload. Exemplo: dms.r7i.large (cargas de trabalho pequenas), dms.r7i.4xlarge (cargas de trabalho grandes). + **Versão do motor**: 3.5.4 + **Armazenamento alocado**: o padrão é 50 GB (aumente se necessário). Isso é determinado pelo tamanho do documento updates/second e pela duração total do carregamento. + **Multi-AZ Implantação**: habilite a alta disponibilidade, se necessário. + Escolha a mesma VPC do Amazon DocumentDB. + Garanta que os **grupos de segurança** permitam tráfego de entrada da origem e do Amazon DocumentDB. 1. Escolha ** Criar instância de replicação ** e aguarde até que o status esteja disponível. #### Criação de endpoints da VPC ##### Criação de um endpoint de origem **Para uma origem do MongoDB** 1. No console do DMS, no painel de navegação, escolha **Migrar ou replicar** e, em seguida, escolha **Endpoints**. 1. Escolha **Criar endpoint**. 1. Na página **Criar endpoint**, escolha **Endpoint de origem**. 1. Na seção **Configuração do endpoint**: + Insira um **identificador de endpoint** exclusivo e significativo (por exemplo, “mongodb-source”). + Escolha o **MongoDB** como **Mecanismo de origem**. + Em **Acesso ao banco de dados de endpoint**, escolha **Fornecer informações de acesso manualmente**. + Em Nome ** do servidor**, insira seu{{MongoDB server DNS name/IP address}}. + Em **Porta**, insira **27017** (porta padrão do MongoDB). + Para o modo de ** autenticação**, escolha o modo apropriado para seu aplicativo (password/SSL) (o padrão é gerenciador de segredos). + Se o **Modo de autenticação** for **Senha**, forneça: + **Nome de usuário** e **Senha**: insira as credenciais do MongoDB. + **Nome do banco de dados**: o nome do seu banco de dados de origem. + **Mecanismo de autenticação**: SCRAM-SHA-1 (padrão) ou mecanismo apropriado 1. Em **Modo de metadados**, deixe a configuração padrão do **documento**. 1. Atributos adicionais de conexão: + authSource=admin (se o banco de dados de autenticação for diferente) + replicaSet= (necessário para o CDC) **Para uma origem do Amazon DocumentDB** 1. No console do DMS, no painel de navegação, escolha **Migrar ou replicar** e, em seguida, escolha **Endpoints**. 1. Escolha **Criar endpoint**. 1. Na página **Criar endpoint**, escolha **Endpoint de origem**. 1. Na seção **Configuração do endpoint**: + Insira um **identificador de endpoint** exclusivo e significativo (por exemplo, “docdb-source”). + Escolha **Amazon DocumentDB** como **Mecanismo de origem**. + Em **Acesso ao banco de dados de endpoint**, escolha **Fornecer informações de acesso manualmente**. + Em Nome ** do servidor**, insira seu{{source Amazon DocumentDB cluster endpoint}}. + Em **Porta**, insira **27017** (porta padrão para o Amazon DocumentDB). + Em **Modo de SSL**, escolha **verify-full** (recomendado para Amazon DocumentDB). + Em **Certificado CA**, escolha o certificado CA raiz do Amazon DocumentDB, + Para o modo de ** autenticação**, escolha o modo apropriado para seu aplicativo (password/SSL) (o padrão é gerenciador de segredos). + Se o **Modo de autenticação** for **Senha**, forneça: + **Nome de usuário** e **senha**: insira as credenciais do Amazon DocumentDB. + **Nome do banco de dados**: o nome do seu banco de dados de origem. + **Mecanismo de autenticação**: SCRAM-SHA-1 (padrão) ou mecanismo apropriado 1. Em **Modo de metadados**, deixe a configuração padrão do **documento**. ##### Criação de um endpoint de destino do Amazon DocumentDB. 1. No console do DMS, no painel de navegação, escolha **Migrar ou replicar** e, em seguida, escolha **Endpoints**. 1. Escolha **Criar endpoint**. 1. Na página **Criar endpoint**, escolha **Endpoint de destino**. 1. Na seção **Configuração do endpoint**: + Insira um **identificador de endpoint** exclusivo e significativo (por exemplo, “docdb-target”). + Escolha **Amazon DocumentDB** como **Mecanismo de destino**. + Para **Acesso ao banco de dados do endpoint**, escolha o método que você deseja usar para autenticar o acesso ao banco de dados: + Se você escolher **AWS Secrets Manager**, escolha o segredo em que você armazena suas credenciais do Amazon DocumentDB no campo **Segredo**. + Se você escolher **Fornecer informações de acesso manualmente**: + Em Nome ** do servidor**, insira seu{{target Amazon DocumentDB cluster endpoint}}. + Em **Porta**, insira **27017** (porta padrão para o Amazon DocumentDB). + Em **Modo de SSL**, escolha **verify-full** (recomendado para Amazon DocumentDB). + Em **Certificado CA**, baixe e especifique o pacote de certificados CA para verificação de SSL. + Para o modo de ** autenticação**, escolha o modo apropriado para seu aplicativo (password/SSL) (o padrão é gerenciador de segredos). + Se o **Modo de autenticação** for **Senha**, forneça: + **Nome de usuário** e **senha**: insira as credenciais do Amazon DocumentDB. + **Nome do banco de dados**: o nome do seu banco de dados de origem. + **Mecanismo de autenticação**: SCRAM-SHA-1 (padrão) ou mecanismo apropriado 1. Em **Modo de metadados**, deixe a configuração padrão do **documento**. #### Criação de tarefas de replicação 1. No console do DMS, no painel de navegação, escolha **Migrar ou replicar** e, em seguida, escolha **Tarefas**. 1. Escolha **Criar tarefa**. 1. Na página **Criar tarefa**, na seção **Configuração da tarefa**: + Insira um **Identificador de tarefa** exclusivo e significativo (por exemplo, “mongodb-docdb-replication”). + Escolha o endpoint de origem que você criou anteriormente no menu suspenso **Endpoint de banco de dados de origem**. + Escolha o endpoint de destino que você criou anteriormente no menu suspenso **Endpoint de banco de dados de destino**. + Escolha a instância de replicação que você criou anteriormente no menu ** suspenso Instância ** provisionada. + Em **Tipo de tarefa**, escolha **Migrar e replicar**. + Por ** quanto tempo você pretende continuar replicando da origem para o destino? **, escolha ** Por tempo limitado**. 1. Na seção **Configurações**: + No modo de preparação da tabela ** Target**, escolha ** Não fazer nada**. Caso contrário, as coleções e índices que já foram criados serão excluídos. + Para registros de ** tarefas**, marque a caixa ** Ativar CloudWatch ** registros. + Deixe os valores padrão para todas as outras configurações. 1. Na parte superior da ** seção ** Configurações, no modo de ** edição**, escolha o editor ** JSON ** e defina os seguintes atributos: ``` { "TargetMetadata": { "ParallelApplyThreads": 5 }, "FullLoadSettings": { "MaxFullLoadSubTasks": 16 } } ``` Defina `MaxFullLoadSubTasks` com base na contagem de coleções e na capacidade da instância. Use valores mais baixos (2—4) para coleções menores ou menores e valores mais altos (8—16) para muitas coleções grandes. Para dimensionamento automatizado, consulte [ DMS Buddy ](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/dms_buddy) on. GitHub 1. Na seção **Mapeamentos de tabela**, adicione uma nova regra de seleção: + Em **Nome do esquema**, adicione o banco de dados de origem a ser migrado. Use % para especificar vários bancos de dados. + No nome da **Tabela do esquema**, adicione o banco de dados de origem a ser migrado. Use % para especificar várias coleções. + Em **Ação**, deixe a configuração padrão de **Incluir** 1. Para coleções grandes (acima de 100 GB), adicione a **Regra de configurações de tabela**: + Em **Nome do esquema**, adicione o banco de dados de origem a ser migrado. Use % para especificar vários bancos de dados. + No nome da **Tabela do esquema**, adicione o banco de dados de origem a ser migrado. Use % para especificar várias coleções. + Para ** Número de partições**, defina com base na sua carga de trabalho. Para um pequeno número de coleções grandes, defina partições ≥ `MaxFullLoadSubTasks` para manter todos os trabalhadores ocupados. Para muitas coleções carregadas em paralelo, defina partições ≤, `MaxFullLoadSubTasks` pois a própria contagem de coleções fornece paralelismo suficiente. 1. Na seção **Avaliação de pré-migração**, certifique-se de que ela esteja desativada. A avaliação de pré-migração não é suportada pelo Amazon DocumentDB como destino e deve ser desativada. ### 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** + Acesso à instância de origem do MongoDB com as permissões apropriadas. + Instale o `mongodump`, se necessário (ele é instalado durante a instalação do MongoDB). + Verifique se há espaço em disco suficiente para os arquivos de despejo. **Requisitos do Amazon DocumentDB de destino** + Certifique-se de ter um cluster do Amazon DocumentDB provisionado. + Certifique-se de que haja uma instância do EC2 na mesma VPC do Amazon DocumentDB para facilitar a migração. + A conectividade de rede deve estar disponível entre seu ambiente de origem e o Amazon DocumentDB. + O **mongorestore** deve estar instalado na instância EC2 de migração. + As permissões apropriadas do IAM devem ser configuradas para acessar o Amazon DocumentDB, **Requisitos gerais ** + AWS CLI deve ser configurado (se estiver usando AWS serviços para armazenamento intermediário) + Uma largura de banda suficiente deve estar disponível para a transferência de dados. + A janela de tempo de inatividade deve ser aprovada (se estiver fazendo uma migração ao vivo, considere outras abordagens) #### Criação de um cluster do Amazon DocumentDB Consulte [Criar novo cluster de destino](#mig-runbook-configure-target). #### Execute o despejo de dados (mongodump) Escolha uma das opções a seguir para criar um arquivo de despejo: + **Opção 1: básica** ``` mongodump \ --uri="mongodb://{{}}:{{}}@{{}}:27017/{{}}" \ --out=/path/to/dump ``` + **Opção 2: melhor controle e performance** Comprime a saída com gzip, despeja as coleções em paralelo, ativa o TLS e lê a partir de uma réplica secundária, se disponível: ``` mongodump \ --uri="mongodb://{{}}:{{}}@{{}}:27017" \ --out=/path/to/dump \ --gzip \ --numParallelCollections=4 \ --tls \ --authenticationDatabase=admin \ --readPreference=secondaryPreferred ``` + **Opção 3: bancos de dados grandes** Despeja um banco de dados e uma coleção específicos, filtra documentos por consulta e envia para um único arquivo compactado: ``` mongodump \ --host={{}} \ --port=27017 \ --username={{}} \ --password={{}} \ --db={{}} \ --collection={{}} \ --query='{ "date": { "$gt": "2020-01-01" } }' \ --archive=/path/to/archive.gz \ --gzip \ --tls ``` #### Transferência dos arquivos de despejo para o ambiente de restauração Escolha um método apropriado com base no tamanho do seu despejo: + **Pequeno**: copie diretamente para sua máquina de migração (a instância EC2 que você criou anteriormente): ``` scp -r /path/to/dump user@migration-machine:/path/to/restore ``` + **Médio**: use o Amazon S3 como armazenamento intermediário: ``` aws s3 cp --recursive /path/to/dump s3://your-bucket/mongodb-dump/ ``` + **Grande ** — Para bancos de dados muito grandes, considere AWS DataSync uma transferência física. #### 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](https://github.com/awslabs/amazon-documentdb-tools/tree/master/index-tool) para exportar e importar índices. Escolha uma das opções a seguir para restaurar os dados: + **Opção 1: restauração básica** ``` mongorestore \ --uri="mongodb://{{}}:{{}}@{{}}:27017" \ --tls \ --tlsCAFile=global-bundle.pem \ /path/to/dump ``` + **Opção 2: melhor controle e performance** Restaura despejos compactados com gzip com coleta paralela e inserção de documentos. Ignora a restauração do índice, pois os índices são pré-criados: ``` mongorestore \ --uri="mongodb://{{}}:{{}}@{{}}:27017" \ --tls \ --tlsCAFile=global-bundle.pem \ --gzip \ --numParallelCollections=4 \ --numInsertionWorkersPerCollection=4 \ --noIndexRestore \ /path/to/dump ``` + **Opção 3: bancos de dados grandes ou controles específicos** Restaura a partir de um arquivo compactado com filtragem de namespace para incluir ou excluir bancos de dados e coleções específicos. Ignora a restauração do índice, pois os índices são pré-criados: ``` mongorestore \ --host={{}} \ --port=27017 \ --username={{}} \ --password={{}} \ --tls \ --tlsCAFile=global-bundle.pem \ --archive=/path/to/archive.gz \ --gzip \ --nsInclude="db1.*" \ --nsExclude="db1.sensitive_data" \ --noIndexRestore ``` ## 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** + **FullLoadThroughputBandwidthTarget**— Largura de banda de rede (KB/second) durante a carga total + **FullLoadThroughputRowsTarget**— Número de rows/documents carregamentos por segundo + **FullLoadThroughputTablesTarget**— Número de tables/collections concluídos por minuto + **FullLoadProgressPercent**— Porcentagem de carga completa concluída + **TablesLoaded**— Número de carregados tables/collections com sucesso + **TablesLoading**— Número de tables/collections carregamentos atuais + **TablesQueued**— Número de tables/collections espera para serem carregados + **TablesErrored**— Número do tables/collections que falhou ao carregar **Métricas da fase do CDC** + **CDCLatencyTarget**— Tempo de atraso (segundos) entre a alteração da fonte e o aplicativo de destino + **CDCLatencySource**— Tempo de atraso (segundos) entre a alteração na fonte e a leitura do DMS + **CDCThroughputRowsTarget**— Linhas por segundo aplicadas durante a replicação contínua + **CDCThroughputBandwidthTarget**— Largura de banda de rede (KB/second) durante o CDC + **CDCIncomingChanges**— Número de eventos de mudança recebidos da fonte + **CDCChangesMemoryTarget**— Memória usada (MB) para armazenar alterações no lado do alvo **Métricas de recursos ** + **CPUUtilization**: uso da CPU da instância de replicação + **FreeableMemory**— Memória disponível na instância de replicação + **FreeStorageSpace**— Armazenamento disponível na instância de replicação + **NetworkTransmitThroughput**— Taxa de transferência de rede para a instância de replicação + **NetworkReceiveThroughput**— Taxa de transferência de rede para a instância de replicação **Métricas de erros** + **ErrorsCount**— Número total de erros durante a migração + **TableErrorsCount**— Número de erros específicos da tabela + **RecordsErrorsCount**— Número de erros específicos do registro 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) 1. Acesse o console do Amazon CloudWatch Logs. 1. Encontre e escolha em seu grupo de logs. Ele se parece com “dms-tasks –”. 1. Procure por fluxos de log que possam conter informações de erro: + Fluxos com “error” no nome + Fluxos com IDs de tarefas ou nomes de endpoints + Os fluxos de log mais recentes durante o período de sua migração 1. Dentro desses fluxos, pesquise por palavras-chave como: + "error" + "exception" + "failed" + "warning" #### Status da tarefa do DMS (usando AWS CLI) ``` aws dms describe-replication-tasks \ --filters Name=replication-task-id,Values={{}} \ --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. ](https://github.com/awslabs/amazon-documentdb-tools/tree/master/monitoring/docdb-dashboarder) GitHub ## Validação **Topics** + [Lista de verificação de validação](#w2aac15b9c27b9) + [Validação de esquema e índices](#w2aac15b9c27c11) + [Amostragem de dados e validação em nível de campo](#w2aac15b9c27c13) + [Validação usando a DataDiffer ferramenta](#w2aac15b9c27c15) 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 {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db.{{}}.countDocuments()" ``` **Destino do Amazon DocumentDB** ``` mongosh \ --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls \ --tlsCAFile global-bundle.pem \ --eval "db.{{}}.countDocuments()" ``` ### Validação de esquema e índices Verifique se: + todas as coleções existem no destino. + os índices estão replicados corretamente. + as definições do esquema (se aplicadas) são idênticas. **Verifique as coleções (origem versus destino)** ``` mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db = db.getSiblingDB('{{}}'); db.getCollectionNames();" mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls --tlsCAFile global-bundle.pem \ --eval "db = db.getSiblingDB('{{}}'); db.getCollectionNames();" ``` **Verifique os índices (origem versus destino) ** ``` mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db.{{}}.getIndexes()" mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls --tlsCAFile global-bundle.pem \ --eval "db.{{}}.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 {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db.getCollectionInfos({name: '{{}}'})[0].options.validator" mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls --tlsCAFile global-bundle.pem \ --eval "db.getCollectionInfos({name: '{{}}'})[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 {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db.{{}}.aggregate([{ \$sample: { size: 5 } }])" ``` Obtenha os mesmos IDs de documentos (destino): ``` mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls --tlsCAFile global-bundle.pem \ --eval "db.{{}}.find({ _id: { \$in: [{{}}] } })" ``` **Amostragem automática** ``` import pymongo # Connect to source and target source_client = pymongo.MongoClient("{{}}") target_client = pymongo.MongoClient("{{}}", tls=True, tlsCAFile='global-bundle.pem') source_db = source_client["{{}}"] target_db = target_client["{{}}"] # Compare 100 random documents for doc in source_db["{{}}"].aggregate([{"$sample": {"size": 100}}]): target_doc = target_db["{{}}"].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 ](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/data-differ) 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: + Python3,7\+ + PyMongo biblioteca + Conectividade de rede com os clusters de origem do MongoDB e de destino do Amazon DocumentDB #### 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://:@:27017/?replicaSet=rs0", "db": "your_database", "collection": "your_collection" }, "target": { "uri": "mongodb://:@: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á: + Total de documentos na origem e no destino + Número de documentos correspondentes + Número de documentos ausentes + Número de documentos com diferenças + Relatório detalhado das diferenças (se houver) #### Práticas recomendadas A seguir estão as melhores práticas ao usar a DataDiffer ferramenta: + **Execute em fases**: primeiro valide a contagem de documentos, depois experimente os principais documentos e, por fim, faça uma comparação completa, se necessário. + **Verifique as diferenças de esquema**: o Amazon DocumentDB tem algumas limitações em comparação com o MongoDB. A ferramenta destacará tipos ou estruturas de dados incompatíveis. + **Valide durante períodos de silêncio**: execute a validação quando as operações de gravação forem mínimas para garantir a consistência. + **Monitore o uso de recursos**: o processo de comparação pode consumir muitos recursos. Ajuste o tamanho dos lotes e a contagem de linhas adequadamente. + **Valide os índices**: após a validação dos dados, certifique-se de que todos os índices necessários tenham sido criados no cluster de destino do Amazon DocumentDB. + **Resultados da validação de documentos**: mantenha um registro dos resultados da validação de cada coleção como parte da documentação de migração.