Usando um pipeline OpenSearch de ingestão com o Amazon DocumentDB

Você pode usar o plug-in DocumentDB para transmitir alterações de documentos, como criações, atualizações e exclusões, para o Amazon Service. OpenSearch O pipeline suporta captura de dados de alteração (CDC), se disponível, ou pesquisa de API para streaming de alta escala e baixa latência.

Você pode processar dados com ou sem um instantâneo inicial completo. Um snapshot completo captura uma coleção inteira do Amazon DocumentDB e a carrega no Amazon S3. Em seguida, o pipeline envia os dados para um ou mais OpenSearch índices. Depois de ingerir o snapshot, o pipeline sincroniza as mudanças em andamento para manter a consistência e, eventualmente, recebe atualizações quase em tempo real.

Se você já tem um instantâneo completo de outra fonte ou só precisa processar novos eventos, você pode transmitir sem um instantâneo. Nesse caso, o pipeline lê diretamente dos fluxos de alteração do Amazon DocumentDB sem uma carga inicial em massa.

Se você habilitar o streaming, deverá habilitar um stream de alterações na sua coleção do Amazon DocumentDB. No entanto, se você realizar apenas uma carga ou exportação completa, não precisará de um fluxo de alteração.

Pré-requisitos

Antes de criar seu pipeline OpenSearch de ingestão, execute as seguintes etapas:

1. Crie um cluster Amazon DocumentDB com permissão para ler dados seguindo as etapas em Criar um cluster Amazon DocumentDB no Guia do desenvolvedor do Amazon DocumentDB. Se você usa a infraestrutura CDC, configure seu cluster Amazon DocumentDB para publicar fluxos de alterações.

2. Habilitar o TLS no cluster do Amazon DocumentDB.

3. Configure um CIDR VPC de um espaço de endereço privado para uso com o Ingestion. OpenSearch

4. Configure a autenticação em seu cluster Amazon DocumentDB com. AWS Secrets Manager Habilite a alternância de segredos seguindo as etapas em Alternância automática de senhas para o Amazon DocumentDB. Para obter mais informações, consulte Acesso ao banco de dados usando controle de acesso baseado em funções e Segurança no Amazon DocumentDB.

5. Se você usar um fluxo de alterações para assinar as alterações de dados em sua coleção do Amazon DocumentDB, evite a perda de dados estendendo o período de retenção para até 7 dias usando o parâmetro change_stream_log_retention_duration. Os eventos de fluxos de alterações são armazenados por 3 horas, por padrão, após a gravação do evento, o que não é tempo suficiente para grandes coleções. Para modificar o período de retenção do fluxo de alterações, consulte Modificação da duração da retenção do log do fluxo de alterações.

6. Crie um domínio OpenSearch de serviço ou uma coleção OpenSearch sem servidor. Para obter mais informações, consulte Criação OpenSearch de domínios de serviço e Criação de coleções.

7. Anexe uma política baseada em recursos ao seu domínio ou uma política de acesso a dados à sua coleção. Essas políticas de acesso permitem que o OpenSearch Inestion grave dados do seu cluster Amazon DocumentDB em seu domínio ou coleção.

   O exemplo de política de acesso ao domínio a seguir permite que a função de pipeline, que você cria na próxima etapa, grave dados em um domínio. Lembre-se de atualizar o resource com seu próprio ARN.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::pipeline-account-id:role/pipeline-role"
         },
         "Action": [
           "es:DescribeDomain",
           "es:ESHttp*"
         ],
         "Resource": [
           "arn:aws:es:region:account-id:domain/domain-name"
         ]
       }
     ]
   }

   Para criar uma função do IAM com as permissões corretas para acessar dados de gravação na coleção ou no domínio, consulteConfigurando funções e usuários na Amazon OpenSearch Ingestion.

Etapa 1: configurar a função do pipeline

Depois de configurar os pré-requisitos do pipeline do Amazon DocumentDB, defina o perfil de pipeline que você deseja usar na configuração do pipeline e adicione as seguintes permissões do pipeline do Amazon DocumentDB nesse perfil:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "allowS3ListObjectAccess",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::s3-bucket"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": "s3-prefix/*"
                }
            }
        },
        {
            "Sid": "allowReadAndWriteToS3ForExportStream",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::s3-bucket/s3-prefix/*"
            ]
        },
        {
            "Sid": "SecretsManagerReadAccess",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": ["arn:aws:secretsmanager:region:account-id:secret:secret-name"]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:AttachNetworkInterface",
                "ec2:CreateNetworkInterface",
                "ec2:CreateNetworkInterfacePermission",
                "ec2:DeleteNetworkInterface",
                "ec2:DeleteNetworkInterfacePermission",
                "ec2:DetachNetworkInterface",
                "ec2:DescribeNetworkInterfaces"
            ],
            "Resource": [
                "arn:aws:ec2:*:account-id:network-interface/*",
                "arn:aws:ec2:*:account-id:subnet/*",
                "arn:aws:ec2:*:account-id:security-group/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeDhcpOptions",
                "ec2:DescribeRouteTables",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSubnets",
                "ec2:DescribeVpcs",
                "ec2:Describe*"
            ],
            "Resource": "*"
        },
        { 
            "Effect": "Allow",
            "Action": [ 
                "ec2:CreateTags"
            ],
            "Resource": "arn:aws:ec2:*:*:network-interface/*",
            "Condition": { 
               "StringEquals": 
                    {
                        "aws:RequestTag/OSISManaged": "true"
                    } 
            } 
        }
    ]
}

Você deve fornecer as EC2 permissões da Amazon acima sobre a função do IAM que você usa para criar o pipeline de OpenSearch ingestão porque o pipeline usa essas permissões para criar e excluir uma interface de rede em sua VPC. O pipeline pode acessar o cluster do Amazon DocumentDB somente por meio dessa interface de rede.

Etapa 2: Criar o pipeline

Em seguida, você pode configurar um pipeline de OpenSearch ingestão como o seguinte, que especifica o Amazon DocumentDB como origem. Observe que, para preencher o nome do índice, a função getMetadata usa documentdb_collection como chave de metadados. Se quiser usar um nome de índice diferente sem o método getMetadata, você pode usar a configuração index: "my_index_name".

version: "2"
documentdb-pipeline:
  source:
    documentdb:
      acknowledgments: true
      host: "https://docdb-cluster-id.us-east-1.docdb.amazonaws.com"
      port: 27017
      authentication:
        username: ${aws_secrets:secret:username}
        password: ${aws_secrets:secret:password}
      aws:
        sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
      s3_bucket: "bucket-name"
      s3_region: "bucket-region" 
      s3_prefix: "path" #optional path for storing the temporary data
      collections:
        - collection: "dbname.collection"
          export: true
          stream: true
  sink:
  - opensearch:
      hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
      index: "${getMetadata(\"documentdb_collection\")}"
      index_type: custom
      document_id: "${getMetadata(\"primary_key\")}"
      action: "${getMetadata(\"opensearch_action\")}"
      document_version: "${getMetadata(\"document_version\")}"
      document_version_type: "external"
extension:
  aws:
    secrets:
      secret:
        secret_id: "my-docdb-secret"
        region: "us-east-1"
        sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
        refresh_interval: PT1H   

Você pode usar um esquema pré-configurado do Amazon DocumentDB para criar esse pipeline. Para obter mais informações, consulte Usar esquemas para criar um pipeline.

Se você estiver usando o AWS Management Console para criar seu pipeline, você também deve anexar seu pipeline à sua VPC para usar o Amazon DocumentDB como fonte. Para fazer isso, encontre a seção Configuração de rede, marque a caixa de seleção Anexar à VPC e escolha seu CIDR em uma das opções padrão fornecidas ou selecione a sua própria. Você pode usar qualquer CIDR de um espaço de endereço privado, conforme definido em Melhor prática atual RFC 1918.

Para fornecer um CIDR personalizado, selecione Outro no menu suspenso. Para evitar uma colisão de endereços IP entre OpenSearch ingestão e Amazon DocumentDB, certifique-se de que o CIDR de VPC do Amazon DocumentDB seja diferente do CIDR para ingestão. OpenSearch

Para obter mais informações, consulte Configurar o acesso à VPC para um pipeline.

Consistência de dados

O pipeline garante a consistência dos dados pesquisando continuamente ou recebendo alterações do cluster Amazon DocumentDB e atualizando os documentos correspondentes no OpenSearch índice.

OpenSearch A ingestão suporta o end-to-end reconhecimento para garantir a durabilidade dos dados. Quando um pipeline lê snapshots ou fluxos, ele cria partições dinamicamente para processamento paralelo. O pipeline marca uma partição como concluída quando ela recebe uma confirmação após a ingestão de todos os registros no OpenSearch domínio ou na coleção.

Se quiser fazer a ingestão em uma coleção de pesquisa OpenSearch sem servidor, você pode gerar uma ID de documento no pipeline. Se você quiser fazer a ingestão em uma coleção de séries temporais OpenSearch sem servidor, observe que o pipeline não gera uma ID de documento, portanto, você deve omiti-lo document_id: "${getMetadata(\"primary_key\")}" na configuração do coletor do pipeline.

Um pipeline OpenSearch de ingestão também mapeia as ações de eventos recebidos em ações de indexação em massa correspondentes para ajudar a ingerir documentos. Isso mantém os dados consistentes, de modo que cada alteração de dados no Amazon DocumentDB seja reconciliada com as alterações correspondentes no documento. OpenSearch

Mapear tipo de dados

OpenSearch O serviço mapeia dinamicamente os tipos de dados em cada documento recebido para o tipo de dados correspondente no Amazon DocumentDB. A tabela a seguir mostra como o OpenSearch Service mapeia automaticamente vários tipos de dados.

Tipo de dados	OpenSearch	Amazon DocumentDB
Inteiro	OpenSearch mapeia automaticamente os valores inteiros do Amazon DocumentDB para números inteiros. OpenSearch OpenSearch mapeia dinamicamente o campo com base no primeiro documento enviado. Se houver uma combinação de tipos de dados para o mesmo atributo no Amazon DocumentDB, o mapeamento automático poderá falhar. Por exemplo, se seu primeiro documento tiver um atributo longo e um documento posterior tiver esse mesmo atributo como número inteiro, OpenSearch não conseguirá ingerir o segundo documento. Nesses casos, é necessário fornecer um modelo de mapeamento explícito que escolhe o tipo de número mais flexível, como o seguinte: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	O Amazon DocumentDB oferece suporte a números inteiros.
Longo	OpenSearch mapeia automaticamente valores longos do Amazon DocumentDB para OpenSearch longos. OpenSearch mapeia dinamicamente o campo com base no primeiro documento enviado. Se houver uma combinação de tipos de dados para o mesmo atributo no Amazon DocumentDB, o mapeamento automático poderá falhar. Por exemplo, se seu primeiro documento tiver um atributo longo e um documento posterior tiver esse mesmo atributo como número inteiro, OpenSearch não conseguirá ingerir o segundo documento. Nesses casos, é necessário fornecer um modelo de mapeamento explícito que escolhe o tipo de número mais flexível, como o seguinte: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	O Amazon DocumentDB oferece suporte a valores longos.
String	OpenSearch mapeia automaticamente valores de string como texto. Em algumas situações, como valores enumerados, é possível mapear para o tipo de palavra-chave. O exemplo a seguir mostra como mapear um atributo do Amazon DocumentDB nomeado PartType para uma OpenSearch palavra-chave. { "template": { "mappings": { "properties": { "PartType": { "type": "keyword" } } } } }	O Amazon DocumentDB oferece suporte a strings.
Duplo	OpenSearch mapeia automaticamente os valores duplos do Amazon DocumentDB para OpenSearch duplos. OpenSearch mapeia dinamicamente o campo com base no primeiro documento enviado. Se houver uma combinação de tipos de dados para o mesmo atributo no Amazon DocumentDB, o mapeamento automático poderá falhar. Por exemplo, se seu primeiro documento tiver um atributo longo e um documento posterior tiver esse mesmo atributo como número inteiro, OpenSearch não conseguirá ingerir o segundo documento. Nesses casos, é necessário fornecer um modelo de mapeamento explícito que escolhe o tipo de número mais flexível, como o seguinte: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	O Amazon DocumentDB oferece suporte a valores duplos.
Data	Por padrão, a data é mapeada para um número inteiro em OpenSearch. Você pode definir um modelo de mapeamento personalizado para mapear uma data até uma OpenSearch data. { "template": { "mappings": { "properties": { "myDateField": { "type": "date", "format": "epoch_second" } } } } }	O Amazon DocumentDB oferece suporte a datas.
Timestamp	Por padrão, o timestamp é mapeado para um número inteiro em. OpenSearch Você pode definir um modelo de mapeamento personalizado para mapear uma data até uma OpenSearch data. { "template": { "mappings": { "properties": { "myTimestampField": { "type": "date", "format": "epoch_second" } } } } }	O Amazon DocumentDB oferece suporte a carimbos de data/hora.
Booleano	OpenSearch mapeia um tipo booleano do Amazon DocumentDB em um OpenSearch tipo booleano.	O Amazon DocumentDB oferece suporte a atributos do tipo booleano.
Decimal	OpenSearch mapeia os atributos de mapas do Amazon DocumentDB para campos aninhados. Os mesmos mapeamentos são aplicáveis a um campo aninhado. O exemplo a seguir mapeia uma string em um campo aninhado para um tipo de palavra-chave em OpenSearch: { "template": { "mappings": { "properties": { "myDecimalField": { "type": "double" } } } } } Com esse mapeamento personalizado, você pode consultar e agregar o campo com precisão de dois níveis. O valor original mantém a precisão total na _source propriedade do OpenSearch documento. Sem esse mapeamento, OpenSearch usa texto por padrão.	O Amazon DocumentDB oferece suporte a números decimais.
Expressão Regular	O tipo regex cria campos aninhados. Entre eles estão <myFieldName>.pattern e <myFieldName>.options.	O Amazon DocumentDB oferece suporte a expressões regulares.
Dados binários	OpenSearch mapeia automaticamente os dados binários do Amazon DocumentDB para OpenSearch texto. Você pode fornecer um mapeamento para escrevê-los como campos binários OpenSearch. O exemplo a seguir mostra como mapear um campo Amazon DocumentDB nomeado imageData para um campo OpenSearch binário. { "template": { "mappings": { "properties": { "imageData": { "type": "binary" } } } } }	O Amazon DocumentDB oferece suporte a campos de dados binários.
ObjectId	Campos com um tipo de ID de objeto são mapeados para campos de OpenSearch texto. O valor será a representação em string do objectId.	O Amazon DocumentDB oferece suporte a objectIds.
Null	OpenSearch pode ingerir documentos com o tipo nulo Amazon DocumentDB. Ele salva o valor como um valor nulo no documento. Não há mapeamento para esse tipo, e esse campo não é indexado nem pesquisável. Se o mesmo nome de atributo for usado para um tipo nulo e depois for alterado para um tipo diferente, como string, OpenSearch criará um mapeamento dinâmico para o primeiro valor não nulo. Os valores subsequentes ainda podem ser valores nulos do Amazon DocumentDB.	O Amazon DocumentDB oferece suporte a campos do tipo nulo.
Não definido	OpenSearch pode ingerir documentos com o tipo indefinido do Amazon DocumentDB. Ele salva o valor como um valor nulo no documento. Não há mapeamento para esse tipo, e esse campo não é indexado nem pesquisável. Se o mesmo nome de campo for usado para um tipo indefinido e depois mudar para um tipo diferente, como string, OpenSearch cria um mapeamento dinâmico para o primeiro valor não indefinido. Os valores subsequentes ainda podem ser valores indefinidos do Amazon DocumentDB.	O Amazon DocumentDB oferece suporte a campos do tipo indefinido.
MinKey	OpenSearch pode ingerir documentos com o tipo MinKey do Amazon DocumentDB. Ele salva o valor como um valor nulo no documento. Não há mapeamento para esse tipo, e esse campo não é indexado nem pesquisável. Se o mesmo nome de campo for usado para um tipo MinKey e depois for alterado para um tipo diferente, como string, OpenSearch criará um mapeamento dinâmico para o primeiro valor que não seja MinKey. Os valores subsequentes ainda podem ser valores minKey do Amazon DocumentDB.	O Amazon DocumentDB oferece suporte a campos do tipo minKey.
MaxKey	OpenSearch pode ingerir documentos com o tipo Amazon DocumentDB MaxKey. Ele salva o valor como um valor nulo no documento. Não há mapeamento para esse tipo, e esse campo não é indexado nem pesquisável. Se o mesmo nome de campo for usado para um tipo MaxKey e depois for alterado para um tipo diferente, como string, OpenSearch criará um mapeamento dinâmico para o primeiro valor que não seja MaxKey. Os valores subsequentes ainda podem ser valores maxKey do Amazon DocumentDB.	O Amazon DocumentDB oferece suporte a campos do tipo maxKey.

Recomendamos que você configure a fila de mensagens mortas (DLQ) em seu pipeline de ingestão. OpenSearch Se você configurou a fila, o OpenSearch Service envia todos os documentos com falha que não podem ser ingeridos devido a falhas de mapeamento dinâmico para a fila.

Se os mapeamentos automáticos falharem, será possível usar template_type e template_content na configuração do pipeline para definir regras de mapeamento explícitas. Como alternativa, é possível criar modelos de mapeamento diretamente no seu domínio de pesquisa ou na sua coleção antes de iniciar o pipeline.

Limitações

Considere as seguintes limitações ao configurar um pipeline de OpenSearch ingestão para o Amazon DocumentDB:

• Atualmente, a integração de OpenSearch ingestão com o Amazon DocumentDB não oferece suporte à ingestão entre regiões. Seu cluster do Amazon DocumentDB e seu pipeline OpenSearch de ingestão devem estar no mesmo. Região da AWS

• Atualmente, a integração de OpenSearch ingestão com o Amazon DocumentDB não oferece suporte à ingestão entre contas. Seu cluster do Amazon DocumentDB e seu pipeline OpenSearch de ingestão devem estar no mesmo. Conta da AWS

• Um pipeline OpenSearch de ingestão suporta somente um cluster Amazon DocumentDB como origem.

• A integração do OpenSearch Inestion com o Amazon DocumentDB oferece suporte específico a clusters baseados em instâncias do Amazon DocumentDB. Ele não é compatível com clusters elásticos do Amazon DocumentDB.

• A integração do OpenSearch Inestion só é compatível com AWS Secrets Manager um mecanismo de autenticação para seu cluster Amazon DocumentDB.

• Você não pode atualizar a configuração existente do pipeline para ingerir dados de um banco de dados ou coleção diferente. Em vez disso, você deve criar um novo pipeline.

CloudWatch Alarmes recomendados

Para obter o melhor desempenho, recomendamos que você use os seguintes CloudWatch alarmes ao criar um pipeline de OpenSearch ingestão para acessar um cluster do Amazon DocumentDB como fonte.

CloudWatch Alarme	Descrição
<pipeline-name>.documentdb.Credenciais alteradas	Essa métrica indica com que frequência AWS os segredos são alternados.
<pipeline-name>.banco de dados de documentos. executorRefreshErrors	Essa métrica indica falhas na atualização de segredos da AWS .
<pipeline-name>.banco de dados de documentos. exportRecordsTotal	Essa métrica indica o número de registros exportados do Amazon DocumentDB.
<pipeline-name>.banco de dados de documentos. exportRecordsProcessed	Essa métrica indica o número de registros processados pelo pipeline OpenSearch de ingestão.
<pipeline-name>.banco de dados de documentos. exportRecordProcessingErros	Essa métrica indica o número de erros de processamento em um pipeline OpenSearch de ingestão durante a leitura dos dados de um cluster do Amazon DocumentDB.
<pipeline-name>.banco de dados de documentos. exportRecordsSuccessTotal	Essa métrica indica o número total de registros de exportação processados com êxito.
<pipeline-name>.banco de dados de documentos. exportRecordsFailedTotal	Essa métrica indica o número total de registros de exportação com falha no processamento.
<pipeline-name>.documentdb.bytes recebidos	Essa métrica indica o número total de bytes recebidos por um pipeline OpenSearch de ingestão.
<pipeline-name>.documentdb.bytes processados	Essa métrica indica o número total de bytes processados por um pipeline OpenSearch de ingestão.
<pipeline-name>.banco de dados de documentos. exportPartitionQueryTotal	Essa métrica indica o total da partição de exportação.
<pipeline-name>.banco de dados de documentos. streamRecordsSuccessTotal	Essa métrica indica o número de registros processados com êxito a partir do fluxo.
<pipeline-name>.banco de dados de documentos. streamRecordsFailedTotal	Essa métrica indica o número total de registros com falha no processamento do fluxo.