Utilizzo di una pipeline OpenSearch di ingestione con Amazon DocumentDB

Puoi utilizzare il plug-in DocumentDB per trasmettere le modifiche ai documenti, come creazioni, aggiornamenti ed eliminazioni, ad Amazon Service. OpenSearch La pipeline supporta l'acquisizione dei dati di modifica (CDC), se disponibile, o il polling delle API per lo streaming su larga scala e a bassa latenza.

È possibile elaborare i dati con o senza un'istantanea iniziale completa. Uno snapshot completo acquisisce un'intera raccolta Amazon DocumentDB e la carica su Amazon S3. La pipeline invia quindi i dati a uno o più indici. OpenSearch Dopo aver acquisito l'istantanea, la pipeline sincronizza le modifiche in corso per mantenere la coerenza e alla fine recupera gli aggiornamenti quasi in tempo reale.

Se disponi già di un'istantanea completa da un'altra fonte o devi solo elaborare nuovi eventi, puoi eseguire lo streaming senza un'istantanea. In questo caso, la pipeline legge direttamente i flussi di modifiche di Amazon DocumentDB senza un carico iniziale di massa.

Se abiliti lo streaming, devi abilitare un flusso di modifiche sulla tua raccolta Amazon DocumentDB. Tuttavia, se esegui solo un caricamento o un'esportazione completi, non è necessario 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'infrastruttura CDC, configura il cluster Amazon DocumentDB per pubblicare flussi di modifiche.

2. Abilitare TLS sul cluster Amazon DocumentDB.

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

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, consulta Modifica della durata di conservazione del log del Change Stream.

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

7. Allega una policy basata sulle risorse al tuo dominio o una policy 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 aggiornarlo resource con il tuo 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 ruolo IAM con le autorizzazioni corrette per accedere ai dati di scrittura nella raccolta o nel dominio, consulta. Configurazione di ruoli e utenti in Amazon OpenSearch Ingestion

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 sul ruolo IAM 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 al tuo VPC per utilizzare Amazon DocumentDB come sorgente. Per farlo, trova la sezione Configurazione di rete, seleziona la casella di controllo Collega a VPC e scegli il tuo CIDR da una delle opzioni predefinite fornite oppure selezionane una personalizzata. È possibile utilizzare qualsiasi CIDR da uno spazio di indirizzi privato come definito nella RFC 1918 Best Current Practice.

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

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

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	I campi con un tipo di ObjectID vengono mappati ai campi di OpenSearch testo. Il valore sarà la rappresentazione in formato stringa di ObjectID.	Amazon DocumentDB supporta gli ObjectID.
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 DocumentDB MinKey. 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 MinKey e successivamente passa a un tipo diverso, ad esempio string, OpenSearch crea una mappatura dinamica per il primo valore non MinKey. I valori successivi possono ancora essere valori MinKey di Amazon DocumentDB.	Amazon DocumentDB supporta i campi di tipo MinKey.
MaxKey	OpenSearch può importare documenti con il tipo Amazon DocumentDB MaxKey. 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 di MaxKey e successivamente passa a un tipo diverso, ad esempio string, OpenSearch crea una mappatura dinamica per il primo valore non MaxKey. I valori successivi possono ancora essere valori MaxKey di Amazon DocumentDB.	Amazon DocumentDB supporta i campi di tipo MaxKey.

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 ingestion 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 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.Credenziali modificate	Questa metrica indica la frequenza con cui i segreti vengono ruotati. AWS
<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. Byte ricevuti	Questa metrica indica il numero totale di byte ricevuti da una pipeline di ingestione. OpenSearch
<pipeline-name>.DocumentDB. Byte elaborati	Questa metrica indica il numero totale di byte elaborati da una pipeline di ingestione. OpenSearch
<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.