Uso de una canalización OpenSearch de ingestión con Amazon DocumentDB

Puede utilizar una canalización de OpenSearch ingestión con Amazon DocumentDB para transmitir los cambios en los documentos (como la creación, la actualización y la eliminación) a los dominios y colecciones de OpenSearch Amazon Service. La canalización de OpenSearch ingestión puede aprovechar los mecanismos de captura de datos de cambio (CDC), si están disponibles en su clúster de Amazon DocumentDB, API o las encuestas para proporcionar una forma de alta escala y baja latencia de transmitir datos de forma continua desde un clúster de Amazon DocumentDB.

Existen dos formas de utilizar Amazon DocumentDB como fuente para procesar los datos: con y sin una instantánea inicial completa.

Una instantánea inicial completa es una consulta masiva de toda una colección de Amazon DocumentDB. Amazon DocumentDB carga esta instantánea en Amazon S3. Desde allí, una canalización de OpenSearch ingestión la envía a un índice de un dominio o la divide en varios índices de un dominio. Para mantener la OpenSearch coherencia de los datos en Amazon DocumentDB, la canalización sincroniza todos los eventos de creación, actualización y eliminación de la colección de Amazon DocumentDB con los documentos guardados en el índice o los índices. OpenSearch

Cuando utiliza una instantánea inicial completa, la canalización de OpenSearch ingestión ingiere primero la instantánea y, a continuación, comienza a leer los datos de las secuencias de cambios de Amazon DocumentDB. Con el tiempo, recupera y mantiene la coherencia de los datos casi en tiempo real entre Amazon DocumentDB y. OpenSearch

También puede utilizar la integración de OpenSearch Ingestion con Amazon DocumentDB para transmitir eventos sin necesidad de una instantánea. Elija esta opción si ya dispone de una instantánea completa de algún otro mecanismo o si solo quiere transmitir los eventos actuales de una colección de Amazon DocumentDB con flujos de cambios.

Con estas dos opciones, debe habilitar una transmisión de cambios en su colección de Amazon DocumentDB si habilita una transmisión en su configuración en proceso. Si solo utiliza la carga completa o la exportación, no necesita habilitar una transmisión de cambios.

Requisitos previos

Antes de crear tu canalización OpenSearch de ingestión, lleva a cabo los siguientes pasos:

1. Cree un clúster de Amazon DocumentDB con permiso para leer datos siguiendo los pasos que se indican en Crear un clúster de Amazon DocumentDB de la Guía para desarrolladores de Amazon DocumentDB. Si utiliza CDC infraestructura, asegúrese de configurar el clúster de Amazon DocumentDB para publicar flujos de cambios.

2. TLSActívela en su clúster de Amazon DocumentDB.

3. Configure un espacio VPC CIDR de direcciones privado para usarlo con OpenSearch Ingestion.

4. Configure la autenticación en su clúster de Amazon DocumentDB con. AWS Secrets Manager Active la rotación de secretos siguiendo los pasos de Rotación automática de contraseñas para Amazon DocumentDB. Para obtener más información, consulte Acceso a bases de datos mediante seguridad y control de acceso basados en roles en Amazon DocumentDB.

5. Si utiliza un flujo de cambios para suscribirse a los cambios de datos de su colección de Amazon DocumentDB, evite la pérdida de datos ampliando el período de retención hasta 7 días con el change_stream_log_retention_duration parámetro. Los eventos de las transmisiones de cambios se almacenan durante 3 horas, de forma predeterminada, después de que se haya registrado el evento, lo que no es tiempo suficiente para recopilaciones grandes. Para modificar el período de retención del flujo de cambios, consulte Modificación de la duración de retención del registro de flujos de cambios.

6. Cree un dominio OpenSearch de servicio o una colección OpenSearch sin servidor. Para obtener más información, consulte Creación de dominios OpenSearch de servicio y Creación de colecciones.

7. Adjunta una política basada en recursos a tu dominio o una política de acceso a datos a tu colección. Estas políticas de acceso permiten a OpenSearch Ingestion escribir datos de su clúster de Amazon DocumentDB en su dominio o colección.

   El siguiente ejemplo de política de acceso a dominios permite que el rol de canalización, que se crea en el siguiente paso, escriba datos en un dominio. Asegúrate de actualizarlo resource con el tuyo propioARN.

   {
     "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 crear un IAM rol con los permisos correctos para acceder a los datos de escritura de la colección o el dominio, consulte Permisos necesarios para los dominios y Permisos obligatorios para las colecciones.

Paso 1: configurar el rol de canalización

Una vez establecidos los requisitos previos de la canalización de Amazon DocumentDB, configure la función de canalización que quiere usar en la configuración de la canalización y añada los siguientes permisos de Amazon DocumentDB a la función:

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

Debes proporcionar los EC2 permisos de Amazon anteriores en la IAM función que utilices para crear la canalización de OpenSearch ingestión, ya que la canalización utiliza estos permisos para crear y eliminar una interfaz de red en la tuyaVPC. La canalización solo puede acceder al clúster de Amazon DocumentDB a través de esta interfaz de red.

Paso 2: crear la canalización

A continuación, puede configurar una canalización de OpenSearch ingestión como la siguiente, que especifica Amazon DocumentDB como origen. Tenga en cuenta que para rellenar el nombre del índice, la getMetadata función documentdb_collection lo utiliza como clave de metadatos. Si desea usar un nombre de índice diferente sin el getMetadata método, puede usar la configuraciónindex: "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   

Puede utilizar un blueprint de Amazon DocumentDB preconfigurado para crear esta canalización. Para obtener más información, consulte Uso de esquemas para crear una canalización.

Si utiliza AWS Management Console para crear su canalización, también debe adjuntarla a la suya para poder utilizar Amazon DocumentDB como fuente. VPC Para ello, busque la sección de configuración de red, seleccione la VPC casilla Adjuntar a y elija una CIDR de las opciones predeterminadas proporcionadas o seleccione la suya propia. Puede utilizar cualquiera CIDR de ellos desde un espacio de direcciones privado, tal y como se define en las mejores prácticas actuales de RFC 1918.

Para crear un personalizadoCIDR, selecciona Otros en el menú desplegable. Para evitar una colisión de direcciones IP entre OpenSearch Ingestión y Amazon DocumentDB, asegúrese de que Amazon VPC CIDR DocumentDB sea diferente de la de Ingestión. CIDR OpenSearch

Para obtener más información, consulte Configurar el VPC acceso a una canalización.

Coherencia de datos

La canalización garantiza la coherencia de los datos mediante el sondeo continuo o la recepción de cambios del clúster de Amazon DocumentDB y la actualización de los documentos correspondientes del OpenSearch índice.

OpenSearch La ingestión apoya el end-to-end reconocimiento para garantizar la durabilidad de los datos. Cuando una canalización lee instantáneas o transmisiones, crea particiones de forma dinámica para el procesamiento paralelo. La canalización marca una partición como completa cuando recibe un acuse de recibo después de ingerir todos los registros del dominio o la OpenSearch colección.

Si quieres incorporarlos a una colección de búsquedas OpenSearch sin servidor, puedes generar un identificador de documento en la canalización. Si quieres incorporarlo a una colección de series temporales OpenSearch sin servidor, ten en cuenta que la canalización no genera un identificador de documento, por lo que debes omitirlo document_id: "${getMetadata(\"primary_key\")}" en la configuración del colector de canalizaciones.

Una canalización OpenSearch de ingestión también asigna las acciones de los eventos entrantes a las correspondientes acciones de indexación masiva para facilitar la ingesta de documentos. Esto mantiene la coherencia de los datos, de modo que cada cambio de datos en Amazon DocumentDB se concilia con los cambios en los documentos correspondientes. OpenSearch

Asignación de tipos de datos

OpenSearch El servicio asigna dinámicamente los tipos de datos de cada documento entrante al tipo de datos correspondiente en Amazon DocumentDB. La siguiente tabla muestra cómo OpenSearch Service mapea automáticamente varios tipos de datos.

Tipo de datos	OpenSearch	Amazon DocumentDB
Entero	OpenSearch asigna automáticamente valores enteros de Amazon DocumentDB a OpenSearch enteros. OpenSearch mapea dinámicamente el campo en función del primer documento enviado. Si tiene una combinación de tipos de datos para el mismo atributo en Amazon DocumentDB, es posible que se produzca un error en la asignación automática. Por ejemplo, si el primer documento tiene un atributo largo y un documento posterior tiene el mismo atributo que un entero, OpenSearch no podrá ingerir el segundo documento. En estos casos, debe proporcionar una plantilla de mapeo explícita que elija el tipo de número más flexible, como el siguiente: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	Amazon DocumentDB admite números enteros.
Largo	OpenSearch asigna automáticamente los valores largos de Amazon DocumentDB a OpenSearch largos. OpenSearch mapea dinámicamente el campo en función del primer documento enviado. Si tiene una combinación de tipos de datos para el mismo atributo en Amazon DocumentDB, es posible que se produzca un error en la asignación automática. Por ejemplo, si el primer documento tiene un atributo largo y un documento posterior tiene el mismo atributo que un entero, OpenSearch no podrá ingerir el segundo documento. En estos casos, debe proporcionar una plantilla de mapeo explícita que elija el tipo de número más flexible, como el siguiente: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	Amazon DocumentDB admite largos.
Cadena	OpenSearch mapea automáticamente los valores de cadena como texto. En algunas situaciones, como en el caso de los valores enumerados, puede asignarlos al tipo de palabra clave. El siguiente ejemplo muestra cómo asignar un atributo de Amazon DocumentDB denominado PartType a una OpenSearch palabra clave. { "template": { "mappings": { "properties": { "PartType": { "type": "keyword" } } } } }	Amazon DocumentDB admite cadenas.
Doble	OpenSearch asigna automáticamente los valores dobles de Amazon DocumentDB a OpenSearch dobles. OpenSearch mapea dinámicamente el campo en función del primer documento enviado. Si tiene una combinación de tipos de datos para el mismo atributo en Amazon DocumentDB, es posible que se produzca un error en la asignación automática. Por ejemplo, si el primer documento tiene un atributo largo y un documento posterior tiene el mismo atributo que un entero, OpenSearch no podrá ingerir el segundo documento. En estos casos, debe proporcionar una plantilla de mapeo explícita que elija el tipo de número más flexible, como el siguiente: { "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }	Amazon DocumentDB admite dobles.
Date	De forma predeterminada, la fecha se asigna a un número entero en OpenSearch. Puede definir una plantilla de mapeo personalizada para asignar una fecha a una OpenSearch fecha. { "template": { "mappings": { "properties": { "myDateField": { "type": "date", "format": "epoch_second" } } } } }	Amazon DocumentDB admite fechas.
Timestamp	De forma predeterminada, la marca de tiempo se asigna a un número entero en. OpenSearch Puede definir una plantilla de mapeo personalizada para asignar una fecha a una OpenSearch fecha. { "template": { "mappings": { "properties": { "myTimestampField": { "type": "date", "format": "epoch_second" } } } } }	Amazon DocumentDB admite marcas de tiempo.
Booleano	OpenSearch asigna un tipo booleano de Amazon DocumentDB a un tipo booleano. OpenSearch	Amazon DocumentDB admite atributos de tipo booleano.
Decimal	OpenSearch asigna los atributos del mapa de Amazon DocumentDB a campos anidados. Las mismas asignaciones se aplican dentro de un campo anidado. El siguiente ejemplo asigna una cadena de un campo anidado a un tipo de palabra clave en: OpenSearch { "template": { "mappings": { "properties": { "myDecimalField": { "type": "double" } } } } } Con esta asignación personalizada, puede consultar y agregar el campo con una precisión de doble nivel. El valor original conserva toda la precisión de la _source propiedad del OpenSearch documento. Sin este mapeo, OpenSearch usa texto por defecto.	Amazon DocumentDB admite decimales.
Expresión regular	El tipo de expresión regular crea campos anidados. Estos incluyen y. <myFieldName>.pattern <myFieldName>.options	Amazon DocumentDB admite expresiones regulares.
Datos Binary	OpenSearch asigna automáticamente los datos binarios de Amazon DocumentDB a OpenSearch texto. Puede proporcionar un mapeo para escribirlos como campos binarios. OpenSearch El siguiente ejemplo muestra cómo asignar un campo de Amazon DocumentDB denominado imageData a un campo OpenSearch binario. { "template": { "mappings": { "properties": { "imageData": { "type": "binary" } } } } }	Amazon DocumentDB admite campos de datos binarios.
ObjectId	Campos con un tipo de objectId mapa a campos de OpenSearch texto. El valor será la representación en cadena deobjectId.	Amazon DocumentDB admite. objectIds
Nulo	OpenSearch puede ingerir documentos con el tipo nulo de Amazon DocumentDB. Guarda el valor como un valor nulo en el documento. No hay ninguna asignación para este tipo y este campo no está indexado ni se puede buscar en él. Si se utiliza el mismo nombre de atributo para un tipo nulo y, posteriormente, se cambia a un tipo diferente, como una cadena, OpenSearch crea un mapeo dinámico para el primer valor no nulo. Los valores siguientes pueden seguir siendo valores nulos de Amazon DocumentDB.	Amazon DocumentDB admite campos de tipo nulo.
Sin definir	OpenSearch puede ingerir documentos con el tipo indefinido de Amazon DocumentDB. Guarda el valor como un valor nulo en el documento. No hay ninguna asignación para este tipo y este campo no está indexado ni se puede buscar en él. Si se utiliza el mismo nombre de campo para un tipo indefinido y, posteriormente, se cambia a un tipo diferente, como una cadena, OpenSearch crea un mapeo dinámico para el primer valor no indefinido. Los valores subsiguientes pueden seguir siendo valores indefinidos de Amazon DocumentDB.	Amazon DocumentDB admite campos de tipos indefinidos.
MinKey	OpenSearch puede ingerir documentos del tipo Amazon minKey DocumentDB. Guarda el valor como un valor nulo en el documento. No hay ninguna asignación para este tipo y este campo no está indexado ni se puede buscar en él. Si se utiliza el mismo nombre de campo para un minKey tipo y, posteriormente, se cambia a otro tipo, como una cadena, se OpenSearch crea un mapeo dinámico para el primer elemento que no sea un valor. minKey Los valores siguientes pueden seguir siendo valores de Amazon DocumentDB. minKey	Amazon DocumentDB admite campos de minKey tipos.
MaxKey	OpenSearch puede ingerir documentos del tipo Amazon maxKey DocumentDB. Guarda el valor como un valor nulo en el documento. No hay ninguna asignación para este tipo y este campo no está indexado ni se puede buscar en él. Si se utiliza el mismo nombre de campo para un maxKey tipo y, posteriormente, se cambia a otro tipo, como una cadena, se OpenSearch crea un mapeo dinámico para el primer elemento que no sea un valor. maxKey Los valores siguientes pueden seguir siendo valores de Amazon DocumentDB. maxKey	Amazon DocumentDB admite campos de maxKey tipos.

Le recomendamos que configure la cola de letras sin salida (DLQ) en su canal de ingestión. OpenSearch Si has configurado la cola, OpenSearch Service envía a la cola todos los documentos fallidos que no se puedan ingerir debido a errores de mapeo dinámico.

En caso de que las asignaciones automáticos fallen, puede usar template_type y template_content en su configuración de canalización para definir reglas de asignación explícitas. Como alternativa, puede crear plantillas de asignación directamente en su dominio o colección de búsqueda antes de iniciar la canalización.

Limitaciones

Tenga en cuenta las siguientes limitaciones al configurar una canalización de OpenSearch ingestión para Amazon DocumentDB:

• La integración OpenSearch de ingestión con Amazon DocumentDB actualmente no admite la ingesta entre regiones. El clúster de Amazon DocumentDB y la canalización OpenSearch de ingestión deben estar en el mismo lugar. Región de AWS

• La integración OpenSearch de ingestión con Amazon DocumentDB actualmente no admite la ingesta entre cuentas. El clúster de Amazon DocumentDB y la canalización OpenSearch de ingestión deben estar en el mismo lugar. Cuenta de AWS

• Una canalización OpenSearch de ingestión solo admite un clúster de Amazon DocumentDB como origen.

• La integración OpenSearch de Ingestión con Amazon DocumentDB admite específicamente los clústeres basados en instancias de Amazon DocumentDB. No es compatible con los clústeres elásticos de Amazon DocumentDB.

• La integración OpenSearch de ingestión solo es compatible AWS Secrets Manager como mecanismo de autenticación para su clúster de Amazon DocumentDB.

• No puede actualizar la configuración de canalización existente para ingerir datos de una base de datos o colección diferente. En su lugar, debes crear una nueva canalización.