Atualização da versão principal implementada do Amazon DocumentDB no local

O Amazon DocumentDB só disponibiliza novas versões do mecanismo de banco de dados após muitos testes. É possível escolher como e quando fazer a atualização dos clusters do Amazon DocumentDB para a nova versão.

Atualmente, o Amazon DocumentDB oferece suporte a três versões principais: Amazon DocumentDB 3.6, 4.0 e 5.0. Você pode realizar um upgrade de versão principal (MVU) no local do seu banco de dados, mantendo os mesmos endpoints, armazenamento e tags dos clusters e pode continuar usando seus aplicativos sem nenhuma modificação. Esse recurso está disponível gratuitamente em todas as regiões em que o Amazon DocumentDB 5.0 está disponível.

Importante

Seus clusters do Amazon DocumentDB ficarão indisponíveis durante a atualização da versão principal implementada e seus clusters passarão por várias reinicializações. O tempo de inatividade da atualização pode variar de cluster para cluster, dependendo do número de coleções, índices, bancos de dados e instâncias. Recomendamos realizar a atualização durante a janela de manutenção ou nas horas de baixa utilização. Depois que seu cluster for atualizado, você não poderá voltar às versões anteriores do cluster, mas poderá optar por restaurar seu snapshot de pré-atualização em um novo cluster.

MVUpré-requisitos e limitações

A seguir estão os pré-requisitos e limitações da atualização da versão principal implementada que talvez você precise entender e aplicar antes de realizar a atualização:

• Tipo de instância: o Amazon DocumentDB 4.0/5.0 não oferece suporte a instâncias r4.*. Para continuar com uma atualização da versão principal implementada, modifique as instâncias r4.* para instâncias r5.*. Consulte Modificar uma instância do Amazon DocumentDB para obter mais informações. Consulte Classes de instância compatíveis por região para obter as instâncias compatíveis com base na versão do mecanismo do Amazon DocumentDB.

• Patches de sistema operacional de instância: uma atualização da versão principal implementada precisa do patch mais recente do sistema operacional (SO) para continuar. Aplique todas as ações pendentes de manutenção do sistema operacional nas instâncias antes de prosseguir com a atualização implementada. Para obter mais informações, consulte Atualizações do sistema operacional Amazon DocumentDB.

  nota

  Em algumas situações, se você tiver patches pendentes do mecanismo em nível de cluster, os patches do sistema operacional da instância não estarão visíveis. Talvez seja necessário aplicar patches do mecanismo em nível de cluster antes de continuar com a aplicação dos patches do sistema operacional da instância e, posteriormente, com a atualização da versão principal implementada. Consulte Executar uma atualização de patch para a versão do mecanismo de um cluster.

• A atualização local da versão principal está disponível em todas as regiões em que o Amazon DocumentDB 5.0 está disponível.

• A atualização da versão principal implementada não é compatível com o Amazon DocumentDB 4.0 como versão de destino.

• A partir do Amazon DocumentDB 4.0, “.” em nomes de usuário não é suportado. Se você estiver atualizando do Amazon DocumentDB 3.6 para 5.0 e tiver um nome de usuário contendo” . “, recrie seu nome de usuário sem” . “, antes de prosseguir com o local. MVU

• Atualmente, a atualização da versão principal implementada não é compatível com os clusters globais e clusters elásticos do Amazon DocumentDB.

  nota

  Para atualizar seus clusters globais, exclua seus clusters secundários do cluster global, converta o cluster primário em um cluster regional, realize uma atualização da versão principal implementada no cluster regional (primário) e, em seguida, recrie o cluster global adicionando clusters secundários usando o mesmo nome para reter os mesmos endpoints anteriores. Observe que você incorrerá em cobranças de E/S enquanto o cluster primário atualizado replica os dados para os clusters secundários recém-adicionados. Para obter etapas detalhadas sobre como remover clusters secundários do cluster global antes de excluí-los, consulte Remover um cluster de um cluster global do Amazon DocumentDB.

• Se você tiver uma grande quantidade de índices (>3.000) operando em instâncias de desempenho com capacidade de intermitência (por exemplo, t3.medium ou t4g.medium), você deve escalar sua instância primária para uma instância maior (por exemplo, pelo menos r5.large) para realizar a atualização da versão principal no local. É possível optar por reduzir a escala do tamanho da instância quando a atualização da versão principal implementada for concluída. Consulte a tabela abaixo para ver o número máximo de índices compatíveis com os tipos de instância db.t3 e db.t4g para um upgrade local da versão principal:

  Instância	Índices máximos suportados para uso local MVU
  db.t4g.medium	3 mil
  db.t3.medium	10 mil

Práticas recomendadas para atualizações de versões principais implementadas

Realizar atualizações de versões principais implementadas usando clusters clonados

1. Para testar atualizações de versões principais implementadas, recomendamos usar o atributo de clonagem rápida para criar um clone do seu cluster de destino. Você não incorrerá em nenhum custo de armazenamento para testar a atualização da versão principal implementada em um volume clonado, a menos que modifique quaisquer dados no cluster. Para obter mais informações sobre o clone de volume, consulte Clonar um volume para um cluster Amazon DocumentDB.

2. Para obter uma estimativa mais realista do tempo necessário para concluir a atualização da versão principal implementada, combine a contagem de instâncias do cluster clonado com o cluster de destino.

3. Recomendamos que você teste totalmente o cluster do Amazon DocumentDB 5.0 recém-atualizado para verificar se há diferenças funcionais para garantir que tudo esteja funcionando conforme o esperado.

Antes de uma atualização da versão principal implementada

1. Tenha um grupo de parâmetros de cluster compatível com a versão pronto para uso.

   Use o grupo de parâmetros de cluster padrão do Amazon DocumentDB para a nova versão do mecanismo ou crie seu próprio grupo de parâmetros de cluster personalizado para a nova versão do mecanismo.

   Se você associar um grupo de parâmetros de cluster do Amazon DocumentDB como parte da solicitação da atualização, a atualização da versão principal implementada irá reiniciar automaticamente o cluster para aplicar o novo grupo de parâmetros.

2. Verifique se você atendeu aos pré-requisitos para uma atualização da versão principal implementada, conforme mencionado na seção Pré-requisitos e limitações.

3. Para criar um snapshot manual.

   O processo de atualização cria um snapshot do cluster de banco de dados durante a atualização. É altamente recomendável criar seu próprio snapshot manual antes do processo de atualização. Consulte Criação de um snapshot manual do cluster.

   nota

   O snapshot automático criado pelo processo de atualização não será excluído automaticamente após a conclusão da atualização da versão principal implementada. Esse snapshot não incorrerá em nenhuma cobrança, desde que esteja dentro do período de retenção. É possível optar por excluir esse snapshot depois de verificar uma atualização com êxito do seu cluster.

   O snapshot é chamado de preupgrade-<name>-<version>-<timestamp>.

   

4. Verifique se você já programou uma atualização da versão principal implementada do seu cluster.

   Se você modificou o cluster e optou por aplicá-lo na próxima janela de manutenção, o cronograma de atualização da versão principal no local não estará visível no console, mas você poderá visualizá-lo noCLI. É possível executar o comando a seguir para verificar se uma atualização da versão principal implementada já está agendada:

   aws docdb describe-db-cluster \
   --region $REGION \
   --db-cluster-identifier $CLUSTER_NAME
      
   "PendingModifiedValues": {
       "EngineVersion": "5.0.0"
   },

5. Faça várias simulações de execução usando clones de volume em ambientes inferiores para testar o cluster após a atualização da versão principal implementada em qualquer plano de execução e diferenças funcionais. Recomendamos a clonagem com o mesmo número e tamanho de instâncias para obter uma estimativa melhor do runtime da atualização da versão principal implementada. Para obter mais informações, consulte Clonar um volume para um cluster Amazon DocumentDB.

6. Se a etapa anterior tiver êxito, continue com a atualização da versão principal implementada no cluster de produção.

Durante uma atualização da versão principal implementada

É possível monitorar o progresso da atualização da versão principal implementada assinando os eventos de manutenção do cluster. Quando a atualização for concluída, você receberá o evento “A versão principal do cluster de banco de dados foi atualizada”. Esse e outros eventos que ocorrem durante a atualização aparecem na seção “Eventos e tags” da página de detalhes do cluster no console do Amazon DocumentDB. O status do cluster então muda de 'upgrading' (atualizando) para 'available' (disponível).

A partir deCLI, você pode correr aws docdb create-event-subscription para criar eventos e aws docdb describe-events monitorar o progresso. Você também pode configurar notificações de eventos para os eventos acima para a Amazon SNS como destino a ser notificado por e-mail, mensagens push e outros métodos. Para obter mais informações, consulte Inscrever-se em eventos do Amazon DocumentDB.

A atualização da versão principal implementada gera os seguintes eventos durante a atualização:

• Atualização em andamento: criando snapshot pré-atualização [preupgrade-<cluster-name>-<timestamp>]

• Atualização em andamento: volume de clonagem.

• Atualização em andamento: atualizando gravador.

• Atualização em andamento: atualizando leitores.

• A versão principal do cluster de banco de dados foi atualizada.

Os eventos também estão visíveis no console, na página Eventos:

No AWS CLI, você pode usar os seguintes comandos para monitorar o progresso:

aws docdb describe-events --source-identifier $CLUSTER_NAME --source-type db-cluster
{
    "Events": [
        {
            "SourceIdentifier": "mycluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster engine version upgrade started.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2023-07-11T23:20:32.444000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:xxxx:cluster:mycluster"
        }
    ]
}

Após uma atualização da versão principal implementada

Para o Amazon DocumentDB 3.6, adicione uma tag ao cluster para diferenciar que o cluster foi atualizado para o Amazon DocumentDB 5.0 a partir do Amazon DocumentDB 3.6, e que ele não é um cluster do Amazon DocumentDB 5.0 recém-criado. Consulte a seção sobre diferenças entre um cluster do Amazon DocumentDB 5.0 atualizado e um cluster novo do Amazon DocumentDB 5.0.

Faça um snapshot manual após a conclusão da atualização da versão principal implementada, caso você precise fazer uma restauração para o estado pós-atualização. O processo automático do snapshot será retomado assim que a atualização da versão principal implementada for concluída. O snapshot manual não incorrerá em nenhuma cobrança, desde que esteja dentro do período de retenção.

Para usar os novos recursos associados ao Amazon DocumentDB 5.0, por exemplo, criptografia em nível de campo do lado do cliente, recomendamos atualizar a versão do driver para a versão MongoDB 5.0. API Para obter mais informações, consulte Novidades do Amazon DocumentDB 5.0 para obter uma lista dos recursos do Amazon DocumentDB 5.0.

Importante

Imediatamente após realizar a atualização local da versão principal (MVU), seu cluster Amazon DocumentDB 5.0 preencherá novamente os metadados do índice, com base nos quais o mecanismo de banco de dados otimiza os planos de execução de consultas. O desempenho esperado da consulta em seu cluster Amazon DocumentDB será retomado após a conclusão do processo de recálculo dos metadados do índice. Normalmente, esse processo é concluído em alguns minutos, mas pode durar até duas horas, dependendo do número de índices em seu cluster.

Além disso, uma reinicialização imediata, um failover ou uma ampliação/redução de escala de sua instância de gravador após a instalação podem interromper o processo de MVU cálculo dos metadados do índice em seu cluster. Após a MVU conclusão da instalação, recomendamos fazer essas alterações depois de observar o desempenho esperado da consulta em seu cluster Amazon DocumentDB 5.0.

Entre em contato com o AWS suporte se você perceber que essa queda temporária de desempenho persiste por mais de duas horas após a instalação. MVU

Teste totalmente o cluster do Amazon DocumentDB 5.0 atualizado para garantir que tudo esteja funcionando conforme o esperado.

nota

Depois de realizar uma operação local MVU em um cluster do Amazon DocumentDB com fluxos de alterações habilitados, os eventos anteriores do fluxo de alterações são preservados e podem ser retomados usando ou. resumeToken startAtOperationTime Como é o caso de qualquer cluster Amazon DocumentDB recém-criado, os registros de eventos de stream de alterações mais antigos serão change_stream_log_retention_duration excluídos se o tamanho do log for maior que 51.200 MB.

Executar uma atualização de versão principal no local

Using the AWS Management Console

Para realizar uma atualização de versão principal no local usando AWS Management Console:

1. Faça login no AWS Management Console e abra o console do Amazon DocumentDB.

2. Na tabela Clusters, selecione o cluster de origem, clique em Ações e, em seguida, em Modificar.

   

3. Na caixa de diálogo Modificar cluster na seção Especificações do cluster, escolha a versão do banco de dados de destino (5.0) no menu suspenso Versão do mecanismo.

   

4. Na seção Opções do cluster, escolha o grupo de parâmetros de cluster apropriado (default.docdb5.0) ou um grupo de parâmetros criado de forma personalizada.

   

5. Depois de concluído, role para baixo e escolha Continuar.

6. Na seção Programação de modificações, escolha seu plano de programação preferido: aplicar imediatamente ou aplicar na próxima janela de manutenção.

   Depois, selecione Modify Cluster (Modificar cluster).

   

7. Na tabela de clusters, observe o status do seu cluster à medida que ele está sendo atualizado:

   

Using the AWS CLI

Use a modify-db-cluster API versão do motor e o conjunto de allow-major-version-upgrade sinalizadores desejados:

aws docdb modify-db-cluster \
 ‐‐db-cluster-identifier $CLUSTER_NAME \
 ‐‐allow-major-version-upgrade \
 ‐‐engine-version 5.0 \
 ‐‐apply-immediately \
 ‐‐cluster-parameter-group $PARAMETER_GROUP \
 ‐‐region $REGION

Diferenças entre os clusters atualizados do Amazon DocumentDB 3.6/4.0 a 5.0 e os novos clusters do Amazon DocumentDB 5.0

• Comparações de subdocumentos para vários tipos de dados numéricos:

  • Se o cluster for migrado do Amazon DocumentDB 3.6, ele herdará o comportamento de comparação de subdocumentos do Amazon DocumentDB 3.6. A diferença funcional é limitada aos tipos numéricos (como Long, Double, Decimal128) em um subdocumento. Por exemplo, {a: {b: {NumberLong(1)}} não é igual a {a: {b: 1}} no Amazon DocumentDB 3.6, embora sejam comparados como iguais nas versões 4.0 e posteriores do Amazon DocumentDB.

  • Esse comportamento de comparação de subdocumentos só existe no Amazon DocumentDB 3.6 e nos clusters do Amazon DocumentDB 5.0 que foram atualizados da versão 3.6 usando uma atualização da versão principal implementada. Isso não se aplica aos clusters recém-criados do Amazon DocumentDB 5.0.

• Uma atualização da versão principal implementada retém os índices originais do cluster atualizado. Como prática recomendada geral, recomendamos eliminar e recriar seus índices após a conclusão bem-sucedida do MVU in-loco. Com o Amazon DocumentDB 5.0, aprimoramos a eficiência geral do processo de coleta de lixo, especialmente para baixos índices de cardinalidade. Se você já teve problemas históricos com a coleta de lixo em seus clusters do Amazon DocumentDB 3.6 ou 4.0, esses clusters se beneficiarão da eliminação e recriação de índices após o término. MVU A recriação de índices não é um requisito. No entanto, a recriação de um índice pode envolver E/S e tempo adicionais. Para obter mais informações, consulte Gerenciando Índices do Amazon DocumentDB.

nota

Para obter uma lista das diferenças funcionais entre o Amazon DocumentDB 3.6/4.0 e o Amazon DocumentDB 5.0, consulte Compatibilidade do Amazon DocumentDB com o MongoDB.

Solução de problemas de atualização da versão principal implementada

• Em caso de falha, a atualização da versão principal implementada tentará reverter a atualização para assumir o último estado operacional do cluster antes do início da atualização. Uma reversão realizada com êxito gerará um evento: "Database cluster is in a state that cannot be upgraded: DocumentDB cluster is in a state where major version upgrade cannot be completed successfully" (o cluster de banco de dados está em um estado que não pode ser atualizado: o cluster DocumentDB está em um estado em que a atualização da versão principal não pode ser concluída com êxito). Nesse momento, você deve entrar em contato com a equipe de AWS suporte para solucionar o problema e tentar novamente a atualização da versão. É possível continuar usando sua workload como antes. Em qualquer outro cenário raro em que a atualização esteja demorando mais do que o esperado, entre em contato com a equipe de AWS suporte para obter ajuda.

• Depois que seu in-loco MVU for concluído com êxito, seu cluster atualizado poderá sofrer uma degradação temporária do desempenho e alta CPU utilização por um pequeno período de tempo, enquanto o processo de atualização dos metadados do índice estiver em execução. Se você continuar enfrentando uma degradação do desempenho por mais de 2 horas, entre em contato com o AWS suporte.