Utilizzo di una pipeline OpenSearch di importazione con Amazon DocumentDB

Puoi utilizzare una pipeline OpenSearch di importazione con Amazon DocumentDB per trasmettere le modifiche ai documenti (ad esempio creazione, aggiornamento ed eliminazione) a domini e raccolte di Amazon OpenSearch Service. La pipeline OpenSearch Ingestion può sfruttare i meccanismi di change data capture (CDC), se disponibili sul tuo cluster Amazon DocumentDB, o il API polling per fornire un modo su larga scala e a bassa latenza per lo streaming continuo di dati da un cluster Amazon DocumentDB.

Esistono due modi per utilizzare Amazon DocumentDB come origine per elaborare i dati: con e senza uno snapshot iniziale completo.

Uno snapshot iniziale completo è una query collettiva di un'intera raccolta Amazon DocumentDB. Amazon DocumentDB carica questa istantanea su Amazon S3. Da lì, una pipeline di OpenSearch Ingestion lo invia a un indice in un dominio o lo partiziona in più indici in un dominio. Per mantenere OpenSearch coerenti i dati in Amazon DocumentDB, la pipeline sincronizza tutti gli eventi di creazione, aggiornamento ed eliminazione nella raccolta Amazon DocumentDB con i documenti salvati nell'indice o negli indici. OpenSearch

Quando si utilizza uno snapshot iniziale completo, la pipeline di OpenSearch Ingestion prima lo inserisce e poi inizia a leggere i dati dai flussi di modifiche di Amazon DocumentDB. Alla fine recupera e mantiene la coerenza dei dati quasi in tempo reale tra Amazon OpenSearch DocumentDB e.

Puoi anche utilizzare l'integrazione di OpenSearch Ingestion con Amazon DocumentDB per lo streaming di eventi senza uno snapshot. Scegli questa opzione se disponi già di uno snapshot completo di un altro meccanismo o se desideri semplicemente trasmettere in streaming gli eventi correnti da una raccolta Amazon DocumentDB con flussi di modifiche.

Con entrambe queste opzioni, devi abilitare un flusso di modifiche sulla tua raccolta Amazon DocumentDB se abiliti uno stream nella configurazione in pipeline. Se utilizzi solo il caricamento completo o l'esportazione, non è necessario abilitare un flusso di modifiche.

Prerequisiti

Prima di creare la pipeline OpenSearch di Ingestion, effettuate le seguenti operazioni:

1. Crea un cluster Amazon DocumentDB con l'autorizzazione a leggere i dati seguendo i passaggi descritti in Creare un cluster Amazon DocumentDB nella Amazon DocumentDB Developer Guide. Se utilizzi l'CDCinfrastruttura, assicurati di configurare il cluster Amazon DocumentDB per pubblicare flussi di modifiche.

2. Abilita TLS sul tuo cluster Amazon DocumentDB.

3. Configura uno spazio VPC CIDR di indirizzi privato da utilizzare con OpenSearch Ingestion.

4. Configura l'autenticazione sul tuo cluster Amazon DocumentDB con. AWS Secrets Manager Abilita la rotazione dei segreti seguendo i passaggi descritti in Rotazione automatica delle password per Amazon DocumentDB. Per ulteriori informazioni, consulta Accesso al database con controllo e sicurezza degli accessi basati sui ruoli in Amazon DocumentDB.

5. Se utilizzi un flusso di modifiche per sottoscrivere le modifiche ai dati sulla tua raccolta Amazon DocumentDB, evita la perdita di dati estendendo il periodo di conservazione fino a 7 giorni utilizzando il parametro. change_stream_log_retention_duration Gli eventi Change Streams vengono archiviati per impostazione predefinita per 3 ore dopo la registrazione dell'evento, tempo non sufficiente per raccolte di grandi dimensioni. Per modificare il periodo di conservazione del Change Stream Log, consulta Modifica della durata di conservazione del log di Change Stream.

6. Crea un dominio OpenSearch di servizio o una raccolta OpenSearch Serverless. Per ulteriori informazioni, consulta Creazione di domini OpenSearch di servizio e Creazione di raccolte.

7. Allega una politica basata sulle risorse al tuo dominio o una politica di accesso ai dati alla tua raccolta. Queste politiche di accesso consentono a OpenSearch Ingestion di scrivere dati dal tuo cluster Amazon DocumentDB al tuo dominio o alla tua raccolta.

   Il seguente esempio di policy di accesso al dominio consente al ruolo pipeline, creato nel passaggio successivo, di scrivere dati su un dominio. Assicurati di aggiornarli resource con i tuoi. 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"
         ]
       }
     ]
   }

   Per creare un IAM ruolo con le autorizzazioni corrette per accedere ai dati di scrittura nella raccolta o nel dominio, vedi Autorizzazioni richieste per i domini e Autorizzazioni richieste per le raccolte.

Fase 1: Configurare il ruolo della pipeline

Dopo aver impostato i prerequisiti della pipeline di Amazon DocumentDB, configura il ruolo pipeline che desideri utilizzare nella configurazione della pipeline e aggiungi le seguenti autorizzazioni Amazon DocumentDB nel ruolo:

{
    "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"
                    } 
            } 
        }
    ]
}

Devi fornire le EC2 autorizzazioni Amazon di cui sopra per il IAM ruolo che utilizzi per creare la pipeline OpenSearch Ingestion, poiché la pipeline utilizza queste autorizzazioni per creare ed eliminare un'interfaccia di rete nel tuo. VPC La pipeline può accedere al cluster Amazon DocumentDB solo tramite questa interfaccia di rete.

Fase 2: Creare la pipeline

È quindi possibile configurare una pipeline OpenSearch di ingestion come la seguente, che specifica Amazon DocumentDB come origine. Tieni presente che per compilare il nome dell'indice, la getMetadata funzione utilizza come chiave di metadati. documentdb_collection Se si desidera utilizzare un nome di indice diverso senza il getMetadata metodo, è possibile utilizzare la configurazione. 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   

Puoi utilizzare un blueprint Amazon DocumentDB preconfigurato per creare questa pipeline. Per ulteriori informazioni, consulta Utilizzo dei blueprint per creare una pipeline.

Se utilizzi il AWS Management Console per creare la tua pipeline, devi anche collegare la pipeline alla tua VPC per utilizzare Amazon DocumentDB come sorgente. Per farlo, trova la sezione Configurazione di rete, seleziona la VPC casella di controllo Allega a e scegli CIDR una delle opzioni predefinite fornite oppure selezionane una personalizzata. È possibile utilizzarne uno qualsiasi CIDR da uno spazio di indirizzi privato, come definito nella Best Current RFC Practice del 1918.

Per fornire una personalizzazioneCIDR, seleziona Altro dal menu a discesa. Per evitare una collisione negli indirizzi IP tra OpenSearch Ingestion e Amazon DocumentDB, assicurati che Amazon DocumentDB sia diverso da Amazon DocumentDB per Ingestion. VPC CIDR CIDR OpenSearch

Per ulteriori informazioni, consulta Configurazione dell'accesso per una pipeline. VPC

Coerenza dei dati

La pipeline garantisce la coerenza dei dati effettuando continuamente polling o ricevendo modifiche dal cluster Amazon DocumentDB e aggiornando i documenti corrispondenti nell'indice. OpenSearch

OpenSearch Ingestion supporta il end-to-end riconoscimento per garantire la durabilità dei dati. Quando una pipeline legge istantanee o flussi, crea dinamicamente partizioni per l'elaborazione parallela. La pipeline contrassegna una partizione come completa quando riceve un riconoscimento dopo aver acquisito tutti i record nel dominio o nella raccolta. OpenSearch

Se desideri importare in una raccolta di ricerca OpenSearch Serverless, puoi generare un ID di documento nella pipeline. Se desideri importare in una raccolta di serie temporali OpenSearch Serverless, tieni presente che la pipeline non genera un ID di documento, quindi devi document_id: "${getMetadata(\"primary_key\")}" ometterlo nella configurazione del pipeline sink.

Una pipeline OpenSearch di Ingestion mappa anche le azioni degli eventi in entrata nelle corrispondenti azioni di indicizzazione di massa per facilitare l'acquisizione dei documenti. Ciò mantiene i dati coerenti, in modo che ogni modifica dei dati in Amazon DocumentDB venga riconciliata con le corrispondenti modifiche al documento. OpenSearch

Mappatura dei tipi di dati

OpenSearch Il servizio mappa dinamicamente i tipi di dati in ogni documento in entrata al tipo di dati corrispondente in Amazon DocumentDB. La tabella seguente mostra come OpenSearch Service mappa automaticamente vari tipi di dati.

Tipo di dati	OpenSearch	Amazon DocumentDB
Numero intero	OpenSearch mappa automaticamente i valori interi di Amazon DocumentDB su numeri interi. OpenSearch OpenSearch mappa dinamicamente il campo in base al primo documento inviato. Se disponi di una combinazione di tipi di dati per lo stesso attributo in Amazon DocumentDB, la mappatura automatica potrebbe non riuscire. Ad esempio, se il primo documento ha un attributo lungo e un documento successivo ha lo stesso attributo come numero intero, OpenSearch non riesce a importare il secondo documento. In questi casi, è necessario fornire un modello di mappatura esplicito che scelga il tipo di numero più flessibile, come il seguente: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	Amazon DocumentDB supporta numeri interi.
Long	OpenSearch mappa automaticamente i valori long di Amazon DocumentDB su OpenSearch long. OpenSearch mappa dinamicamente il campo in base al primo documento inviato. Se disponi di una combinazione di tipi di dati per lo stesso attributo in Amazon DocumentDB, la mappatura automatica potrebbe non riuscire. Ad esempio, se il primo documento ha un attributo lungo e un documento successivo ha lo stesso attributo come numero intero, OpenSearch non riesce a importare il secondo documento. In questi casi, è necessario fornire un modello di mappatura esplicito che scelga il tipo di numero più flessibile, come il seguente: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	Amazon DocumentDB supporta i file long.
Stringa	OpenSearch mappa automaticamente i valori delle stringhe come testo. In alcune situazioni, come i valori enumerati, è possibile eseguire il mapping al tipo di parola chiave. L'esempio seguente mostra come mappare un attributo Amazon DocumentDB denominato PartType a una OpenSearch parola chiave. { "template": { "mappings": { "properties": { "PartType": { "type": "keyword" } } } } }	Amazon DocumentDB supporta le stringhe.
Doppio	OpenSearch mappa automaticamente i valori doppi di Amazon DocumentDB a OpenSearch valori doppi. OpenSearch mappa dinamicamente il campo in base al primo documento inviato. Se disponi di una combinazione di tipi di dati per lo stesso attributo in Amazon DocumentDB, la mappatura automatica potrebbe non riuscire. Ad esempio, se il primo documento ha un attributo lungo e un documento successivo ha lo stesso attributo come numero intero, OpenSearch non riesce a importare il secondo documento. In questi casi, è necessario fornire un modello di mappatura esplicito che scelga il tipo di numero più flessibile, come il seguente: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	Amazon DocumentDB supporta il doppio.
Data	Per impostazione predefinita, la data corrisponde a un numero intero in. OpenSearch È possibile definire un modello di mappatura personalizzato per associare una data a una OpenSearch data. { "template": { "mappings": { "properties": { "myDateField": { "type": "date", "format": "epoch_second" } } } } }	Amazon DocumentDB supporta le date.
Timestamp	Per impostazione predefinita, il timestamp corrisponde a un numero intero in. OpenSearch È possibile definire un modello di mappatura personalizzato per associare una data a una data. OpenSearch { "template": { "mappings": { "properties": { "myTimestampField": { "type": "date", "format": "epoch_second" } } } } }	Amazon DocumentDB supporta i timestamp.
Booleano	OpenSearch mappa un tipo booleano Amazon DocumentDB in un tipo booleano. OpenSearch	Amazon DocumentDB supporta gli attributi di tipo booleano.
Decimale	OpenSearch mappa gli attributi delle mappe di Amazon DocumentDB ai campi annidati. Le stesse mappature si applicano all'interno di un campo nidificato. L'esempio seguente mappa una stringa in un campo nidificato a un tipo di parola chiave in: OpenSearch { "template": { "mappings": { "properties": { "myDecimalField": { "type": "double" } } } } } Con questa mappatura personalizzata, puoi interrogare e aggregare il campo con una precisione a doppio livello. Il valore originale mantiene la massima precisione nella _source proprietà del documento. OpenSearch Senza questa mappatura, OpenSearch utilizza il testo per impostazione predefinita.	Amazon DocumentDB supporta i decimali.
Espressione regolare	Il tipo regex crea campi annidati. Questi includono <myFieldName>.pattern e. <myFieldName>.options	Amazon DocumentDB supporta le espressioni regolari.
Dati binari	OpenSearch mappa automaticamente i dati binari di Amazon DocumentDB su OpenSearch testo. Puoi fornire una mappatura in cui scriverli come campi binari. OpenSearch L'esempio seguente mostra come mappare un campo Amazon DocumentDB denominato imageData a un campo OpenSearch binario. { "template": { "mappings": { "properties": { "imageData": { "type": "binary" } } } } }	Amazon DocumentDB supporta campi di dati binari.
ObjectId	Campi con un tipo di objectId mappatura su campi di OpenSearch testo. Il valore sarà la rappresentazione in formato stringa diobjectId.	Amazon DocumentDB supporta. objectIds
Null	OpenSearch può importare documenti con il tipo null di Amazon DocumentDB. Salva il valore come valore nullo nel documento. Non esiste alcuna mappatura per questo tipo e questo campo non è indicizzato o ricercabile. Se lo stesso nome di attributo viene utilizzato per un tipo nullo e successivamente passa a un tipo diverso, ad esempio string, OpenSearch crea una mappatura dinamica per il primo valore non nullo. I valori successivi possono comunque essere valori null di Amazon DocumentDB.	Amazon DocumentDB supporta campi di tipo null.
Undefined	OpenSearch può importare documenti con il tipo non definito di Amazon DocumentDB. Salva il valore come valore nullo nel documento. Non esiste alcuna mappatura per questo tipo e questo campo non è indicizzato o ricercabile. Se lo stesso nome di campo viene utilizzato per un tipo non definito e successivamente passa a un tipo diverso, ad esempio string, OpenSearch crea una mappatura dinamica per il primo valore non definito. I valori successivi possono ancora essere valori non definiti di Amazon DocumentDB.	Amazon DocumentDB supporta campi di tipo non definito.
MinKey	OpenSearch può importare documenti con il tipo Amazon minKey DocumentDB. Salva il valore come valore nullo nel documento. Non esiste alcuna mappatura per questo tipo e questo campo non è indicizzato o ricercabile. Se lo stesso nome di campo viene utilizzato per un minKey tipo e successivamente viene modificato in un tipo diverso, ad esempio string, OpenSearch crea una mappatura dinamica per il primo non valore. minKey I valori successivi possono ancora essere valori di Amazon DocumentDB. minKey	Amazon DocumentDB supporta i campi minKey tipo.
MaxKey	OpenSearch può importare documenti con il tipo Amazon maxKey DocumentDB. Salva il valore come valore nullo nel documento. Non esiste alcuna mappatura per questo tipo e questo campo non è indicizzato o ricercabile. Se lo stesso nome di campo viene utilizzato per un maxKey tipo e successivamente viene modificato in un tipo diverso, ad esempio string, OpenSearch crea una mappatura dinamica per il primo non valore. maxKey I valori successivi possono ancora essere valori di Amazon DocumentDB. maxKey	Amazon DocumentDB supporta i campi maxKey tipo.

Ti consigliamo di configurare la dead-letter queue (DLQ) nella pipeline di Ingestion. OpenSearch Se hai configurato la coda, OpenSearch Service invia tutti i documenti non riusciti che non possono essere importati a causa di errori di mappatura dinamica sulla coda.

Nel caso in cui le mappature automatiche falliscano, puoi utilizzare template_type e template_content nella configurazione della pipeline per definire regole di mappatura esplicite. In alternativa, puoi creare modelli di mappatura direttamente nel tuo dominio di ricerca o nella tua raccolta prima di avviare la pipeline.

Limitazioni

Considera le seguenti limitazioni quando configuri una pipeline di OpenSearch ingestione per Amazon DocumentDB:

• L'integrazione OpenSearch di Ingestion con Amazon DocumentDB attualmente non supporta l'ingestione tra regioni. Il cluster Amazon DocumentDB e la pipeline OpenSearch di Ingestion devono trovarsi nello stesso ambiente. Regione AWS

• L'integrazione OpenSearch di Ingestion con Amazon DocumentDB attualmente non supporta l'ingestione tra account. Il cluster Amazon DocumentDB e la pipeline OpenSearch di Ingestion devono trovarsi nello stesso ambiente. Account AWS

• Una pipeline OpenSearch di importazione supporta solo un cluster Amazon DocumentDB come origine.

• L'integrazione OpenSearch di Ingestion con Amazon DocumentDB supporta specificamente i cluster basati su istanze di Amazon DocumentDB. Non supporta i cluster elastici di Amazon DocumentDB.

• L'integrazione OpenSearch di Ingestion supporta solo AWS Secrets Manager come meccanismo di autenticazione per il tuo cluster Amazon DocumentDB.

• Non puoi aggiornare la configurazione della pipeline esistente per importare dati da un database o una raccolta diversi. È invece necessario creare una nuova pipeline.

Allarmi consigliati CloudWatch

Per prestazioni ottimali, ti consigliamo di utilizzare i seguenti CloudWatch allarmi quando crei una pipeline di OpenSearch ingestion per accedere a un cluster Amazon DocumentDB come origine.

CloudWatch Allarme	Descrizione
<pipeline-name>.doucmentdb. credentialsChanged	Questa metrica indica la frequenza con cui AWS i segreti vengono ruotati.
<pipeline-name>.documentdb. executorRefreshErrors	Questa metrica indica gli errori nell'aggiornamento AWS dei segreti.
<pipeline-name>.documentdb. exportRecordsTotal	Questa metrica indica il numero di record esportati da Amazon DocumentDB.
<pipeline-name>.documentdb. exportRecordsProcessed	Questa metrica indica il numero di record elaborati dalla pipeline di OpenSearch ingestione.
<pipeline-name>.documentdb. exportRecordProcessingErrori	Questa metrica indica il numero di errori di elaborazione in una pipeline di OpenSearch ingestione durante la lettura dei dati da un cluster Amazon DocumentDB.
<pipeline-name>.documentdb. exportRecordsSuccessTotale	Questa metrica indica il numero totale di record di esportazione elaborati correttamente.
<pipeline-name>.documentdb. exportRecordsFailedTotale	Questa metrica indica il numero totale di record di esportazione che non sono stati elaborati.
<pipeline-name>.documentdb. bytesReceived	Questa metrica indica il numero totale di byte ricevuti da una pipeline di OpenSearch ingestione.
<pipeline-name>.documentdb. bytesProcessed	Questa metrica indica il numero totale di byte elaborati da una pipeline di OpenSearch ingestione.
<pipeline-name>.documentdb. exportPartitionQueryTotale	Questa metrica indica il totale della partizione di esportazione.
<pipeline-name>.documentdb. streamRecordsSuccessTotale	Questa metrica indica il numero di record elaborati con successo dallo stream.
<pipeline-name>.documentdb. streamRecordsFailedTotale	Questa metrica indica il numero totale di record non elaborati dallo stream.