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

Você pode usar um pipeline de OpenSearch ingestão com o Amazon DocumentDB para transmitir alterações de documentos (como criar, atualizar e excluir) para domínios e coleções do OpenSearch Amazon Service. O pipeline de OpenSearch ingestão pode aproveitar os mecanismos de captura de dados de alteração (CDC), se disponíveis em seu cluster Amazon DocumentDB, ou a pesquisa de API para fornecer uma forma de alta escala e baixa latência de transmitir dados continuamente de um cluster do Amazon DocumentDB.

Há duas maneiras de usar o Amazon DocumentDB como fonte para processar dados — com e sem um snapshot inicial completo.

Um snapshot inicial completo é uma consulta em massa de uma coleção inteira do Amazon DocumentDB. O Amazon DocumentDB carrega esse snapshot no Amazon S3. A partir daí, um pipeline de OpenSearch ingestão o envia para um índice em um domínio ou o particiona em vários índices em um domínio. Para manter os dados no Amazon DocumentDB e OpenSearch consistentes, o pipeline sincroniza todos os eventos de criação, atualização e exclusão na coleção do Amazon DocumentDB com os documentos salvos no índice ou índices. OpenSearch

Quando você usa um snapshot inicial completo, seu pipeline de OpenSearch ingestão primeiro ingere o snapshot e depois começa a ler os dados dos fluxos de alterações do Amazon DocumentDB. Eventualmente, ele recupera e mantém a consistência de dados quase em tempo real entre o Amazon DocumentDB e. OpenSearch

Você também pode usar a integração do OpenSearch Ingestion com o Amazon DocumentDB para transmitir eventos sem um snapshot. Escolha essa opção se você já tiver um snapshot completo de algum outro mecanismo ou se quiser apenas transmitir eventos atuais de uma coleção do Amazon DocumentDB com fluxos de alterações.

Com essas duas opções, você deve habilitar um stream de alterações em sua coleção do Amazon DocumentDB se você habilitar um stream em sua configuração em pipeline. Se você usa apenas carga total ou exportação, não precisa ativar um fluxo de alterações.

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, certifique-se de configurar seu cluster Amazon DocumentDB para publicar fluxos de alterações.

2. Configure a autenticação em seu cluster Amazon DocumentDB com. AWS Secrets Manager Ative a rotação de segredos seguindo as etapas em Rotação automática de senhas para o Amazon DocumentDB. Para obter mais informações, consulte Acesso ao banco de dados usando controle de acesso e segurança baseados em funções no Amazon DocumentDB.

3. Se você usar um stream 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 do Change Streams 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.

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

5. 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, consulte Permissões obrigatórias para domínios e Permissões obrigatórias para coleções.

Etapa 1: configurar a função do pipeline

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

{
    "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 permissões do Amazon EC2 acima sobre a função do IAM que você usa para criar o pipeline de OpenSearch ingestão, pois o pipeline usa essas permissões para criar e excluir uma interface de rede em sua VPC. O pipeline só pode acessar o cluster Amazon DocumentDB 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 getMetadata função usa documentdb_collection como chave de metadados. Se quiser usar um nome de índice diferente sem o getMetadata método, você pode usar a configuraçãoindex: "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 blueprint pré-configurado do Amazon DocumentDB para criar esse pipeline. Para ter 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 sua própria.

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

Mapeaar 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 você tiver uma combinação de tipos de dados para o mesmo atributo no Amazon DocumentDB, o mapeamento automático poderá falhar. Por exemplo, se o 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, você deve fornecer um modelo de mapeamento explícito que escolha 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 você tiver uma combinação de tipos de dados para o mesmo atributo no Amazon DocumentDB, o mapeamento automático poderá falhar. Por exemplo, se o 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, você deve fornecer um modelo de mapeamento explícito que escolha o tipo de número mais flexível, como o seguinte: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	O Amazon DocumentDB oferece suporte a 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 cadeias de caracteres.
Double	OpenSearch mapeia automaticamente os valores duplos do Amazon DocumentDB para OpenSearch duplos. OpenSearch mapeia dinamicamente o campo com base no primeiro documento enviado. Se você tiver uma combinação de tipos de dados para o mesmo atributo no Amazon DocumentDB, o mapeamento automático poderá falhar. Por exemplo, se o 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, você deve fornecer um modelo de mapeamento explícito que escolha o tipo de número mais flexível, como o seguinte: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	O Amazon DocumentDB oferece suporte a duplas.
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 timestamps.
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 decimais.
Expressão Regular	O tipo regex cria campos aninhados. Isso inclui <myFieldName>.pattern <myFieldName>.options e.	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 cadeia de caracteres 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 de tipos indefinidos.
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.