Elaborare gli eventi Amazon DocumentDB con Lambda

Per elaborare gli eventi in un flusso di modifica di Amazon DocumentDB (compatibile con MongoDB), puoi utilizzare una funzione Lambda configurando un cluster Amazon DocumentDB come origine degli eventi. Successivamente puoi automatizzare i carichi di lavoro basati sugli eventi invocando la funzione Lambda con il cluster Amazon DocumentDB ogni volta che i dati cambiano.

Lambda elabora gli eventi di Amazon DocumentDB nei flussi di modifica in sequenza secondo l'ordine in cui arrivano. Per questo motivo, la tua funzione può gestire solo una invocazione simultanea da Amazon DocumentDB alla volta. Per monitorare la tua funzione, puoi tenere traccia dei relativi parametri di simultaneità.

Esempio di evento Amazon DocumentDB

{
    "eventSourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:canaryclusterb2a659a2-qo5tcmqkcl03",
    "events": [
        {
            "event": {
                "_id": {
                    "_data": "0163eeb6e7000000090100000009000041e1"
                },
                "clusterTime": {
                    "$timestamp": {
                        "t": 1676588775,
                        "i": 9
                    }
                },
                "documentKey": {
                    "_id": {
                        "$oid": "63eeb6e7d418cd98afb1c1d7"
                    }
                },
                "fullDocument": {
                    "_id": {
                        "$oid": "63eeb6e7d418cd98afb1c1d7"
                    },
                    "anyField": "sampleValue"
                },
                "ns": {
                    "db": "test_database",
                    "coll": "test_collection"
                },
                "operationType": "insert"
            }
        }
    ],
    "eventSource": "aws:docdb"
}

Per ulteriori informazioni sugli eventi in questo esempio e sulle loro forme, consulta la sezione Eventi di modifica sul sito Web della documentazione di MongoDB.

Prerequisiti e autorizzazioni

Prima di utilizzare Amazon DocumentDB come origine degli eventi della funzione Lambda, è necessario tenere a mente i seguenti prerequisiti. Devi:

Configurare la sicurezza della rete

Per concedere a Lambda l'accesso completo ad Amazon DocumentDB tramite lo strumento di mappatura dell'origine degli eventi, il cluster deve utilizzare un endpoint pubblico (indirizzo IP pubblico) oppure devi fornire l'accesso all'Amazon VPC in cui hai creato il cluster.

Quando usi Amazon DocumentDB con Lambda, crea endpoint VPC AWS PrivateLink che forniscono alla funzione l'accesso alle risorse del tuo Amazon VPC.

Crea un endpoint per fornire l'accesso alle seguenti risorse:

In alternativa, configura un gateway NAT su ogni sottorete pubblica in Amazon VPC. Per ulteriori informazioni, consulta Abilitare l'accesso a Internet per funzioni Lambda connesse a un VPC.

Quando crei uno strumento di mappatura dell'origine degli eventi per Amazon DocumentDB, Lambda verifica se le interfacce di rete elastiche (ENI) sono già presenti per le sottoreti e i gruppi di sicurezza configurati per il tuo Amazon VPC. Se Lambda trova ENI esistenti, prova a riutilizzarle. Altrimenti, Lambda crea nuove ENI per connettersi all'origine dell'evento e richiamare la tua funzione.

Configura i gruppi di sicurezza per l'Amazon VPC contenente il tuo cluster. Per impostazione predefinita, Amazon DocumentDB utilizza le seguenti porte: 27017.

Se il cluster utilizza l'autenticazione, puoi anche limitare la policy degli endpoint per l'endpoint Secrets Manager. Per chiamare l'API Secrets Manager, Lambda utilizza il ruolo della funzione, non il principale del servizio Lambda.

{
      "Statement": [
          {
              "Action": "secretsmanager:GetSecretValue",
              "Effect": "Allow",
              "Principal": {
                  "AWS": [
                      "arn:aws::iam::123456789012:role/my-role"
                  ]
              },
              "Resource": "arn:aws::secretsmanager:us-west-2:123456789012:secret:my-secret"
          }
      ]
  }

Quando utilizzi gli endpoint Amazon VPC, AWS indirizza le chiamate API per richiamare la funzione utilizzando l'interfaccia di rete elastica (ENI) dell'endpoint. Il principale del servizio Lambda deve richiamare lambda:InvokeFunction tutti i ruoli e le funzioni che utilizzano tali ENI.

Per impostazione predefinita, gli endpoint Amazon VPC dispongono di policy IAM aperte che consentono un ampio accesso alle risorse. La best practice consiste nel limitare queste policy per eseguire le azioni necessarie utilizzando quell'endpoint. Per garantire che lo strumento di mappatura dell'origine degli eventi sia in grado di richiamare la funzione Lambda, la policy degli endpoint VPC deve consentire al principale del servizio Lambda di chiamare sts:AssumeRole e lambda:InvokeFunction. Limitare le policy degli endpoint VPC per consentire solo le chiamate API provenienti dall'organizzazione impedisce il corretto funzionamento dello strumento di mappatura dell'origine degli eventi, pertanto "Resource": "*" è richiesto in queste policy.

Il seguente esempio di policy degli endpoint VPC mostra come concedere l'accesso richiesto al principale del servizio Lambda per gli endpoint AWS STS e Lambda.

{
      "Statement": [
          {
              "Action": "sts:AssumeRole",
              "Effect": "Allow",
              "Principal": {
                  "Service": [
                      "lambda.amazonaws.com"
                  ]
              },
              "Resource": "*"
          }
      ]
    }

{
      "Statement": [
          {
              "Action": "lambda:InvokeFunction",
              "Effect": "Allow",
              "Principal": {
                  "Service": [
                      "lambda.amazonaws.com"
                  ]
              },
              "Resource": "*"
          }
      ]
  }

Creazione di una mappatura dell'origine degli eventi Amazon DocumentDB (console)

Per configurare una funzione Lambda per la lettura dal flusso di modifica di un cluster Amazon DocumentDB, crea una mappatura dell'origine degli eventi. In questa sezione viene descritto come eseguire questa operazione dalla console Lambda. Per le istruzioni relative all'SDK AWS e alla AWS CLI, consulta la sezione Creazione di una mappatura dell'origine degli eventi Amazon DocumentDB (SDK o CLI).

Lambda supporta le seguenti opzioni per le origini degli eventi Amazon DocumentDB:

Creazione di una mappatura dell'origine degli eventi Amazon DocumentDB (SDK o CLI)

Per creare o gestire una mappatura dell'origine degli eventi Amazon DocumentDB tramite un SDK AWS, puoi utilizzare le seguenti operazioni dell'API:

Per creare la mappatura dell'origine eventi con l'AWS CLI, utilizzare il comando create-event-source-mapping. L'esempio seguente utilizza questo comando per mappare una funzione denominata my-function a un flusso di modifica Amazon DocumentDB. L'origine degli eventi è indicata da un nome della risorsa Amazon (ARN), con una dimensione batch di 500, a partire dal timestamp in formato Unix. Il comando specifica anche la chiave Secrets Manager che Lambda utilizza per connettersi ad Amazon DocumentDB. Inoltre, include document-db-event-source-config parametri che specificano il database e la raccolta da cui leggere.

aws lambda create-event-source-mapping --function-name my-function \
    --event-source-arn arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy
    --batch-size 500 \
    --starting-position AT_TIMESTAMP \
    --starting-position-timestamp 1541139109 \
    --source-access-configurations '[{"Type":"BASIC_AUTH","URI":"arn:aws:secretsmanager:us-east-1:123456789012:secret:DocDBSecret-BAtjxi"}]' \
    --document-db-event-source-config '{"DatabaseName":"test_database", "CollectionName": "test_collection"}' \

L'output visualizzato dovrebbe essere di questo tipo:

{
    "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284",
    "BatchSize": 500,
    "DocumentDBEventSourceConfig": {
        "CollectionName": "test_collection",
        "DatabaseName": "test_database",
        "FullDocument": "Default"
    },
    "MaximumBatchingWindowInSeconds": 0,
    "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy",
    "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
    "LastModified": 1541348195.412,
    "LastProcessingResult": "No records processed",
    "State": "Creating",
    "StateTransitionReason": "User action"
}

Dopo la creazione, puoi utilizzare il comando update-event-source-mapping per modificare le impostazioni di aggiornamento relative all'origine degli eventi di Amazon DocumentDB. Nell'esempio seguente, la dimensione del batch viene aggiornata a 1.000 e la finestra batch a 10 secondi. Per questo comando è necessario l'UUID della mappatura dell'origine degli eventi, recuperabile utilizzando il comando list-event-source-mapping o dalla console Lambda.

aws lambda update-event-source-mapping --function-name my-function \
    --uuid f89f8514-cdd9-4602-9e1f-01a5b77d449b \
    --batch-size 1000 \
    --batch-window 10

L'output visualizzato dovrebbe essere di questo tipo:

{
    "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284",
    "BatchSize": 500,
    "DocumentDBEventSourceConfig": {
        "CollectionName": "test_collection",
        "DatabaseName": "test_database",
        "FullDocument": "Default"
    },
    "MaximumBatchingWindowInSeconds": 0,
    "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy",
    "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
    "LastModified": 1541359182.919,
    "LastProcessingResult": "OK",
    "State": "Updating",
    "StateTransitionReason": "User action"
}

Lambda aggiorna le impostazioni in modo asincrono, pertanto potresti non essere in grado di visualizzare queste modifiche nell'output fino al completamento del processo. Per visualizzare le impostazioni correnti della mappatura dell'origine degli eventi, utilizza il comando get-event-source-mapping.

aws lambda get-event-source-mapping --uuid f89f8514-cdd9-4602-9e1f-01a5b77d449b

L'output visualizzato dovrebbe essere di questo tipo:

{
    "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284",
    "DocumentDBEventSourceConfig": {
        "CollectionName": "test_collection",
        "DatabaseName": "test_database",
        "FullDocument": "Default"
    },
    "BatchSize": 1000,
    "MaximumBatchingWindowInSeconds": 10,
    "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy",
    "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
    "LastModified": 1541359182.919,
    "LastProcessingResult": "OK",
    "State": "Enabled",
    "StateTransitionReason": "User action"
}

Per eliminare la mappatura dell'origine degli eventi di Amazon DocumentDB, utilizza il comando delete-event-source-mapping:

aws lambda delete-event-source-mapping \
    --uuid 2b733gdc-8ac3-cdf5-af3a-1827b3b11284

Posizioni di partenza di polling e flussi

Tieni presente che il polling dei flussi durante la creazione e gli aggiornamenti dello strumento di mappatura dell'origine degli eventi alla fine è coerente.

Questo comportamento implica che se specifichi LATEST come posizione iniziale del flusso, lo strumento di mappatura dell'origine degli eventi potrebbe perdere eventi durante la creazione o gli aggiornamenti. Per non perdere alcun evento, specifica la posizione iniziale del flusso come TRIM_HORIZON o AT_TIMESTAMP.

Monitoraggio dell'origine degli eventi di Amazon DocumentDB

Per aiutarti a monitorare l'origine degli eventi Amazon DocumentDB, Lambda emette il parametro IteratorAge quando la funzione termina l'elaborazione di un batch di record. L'età dell'iteratore è la differenza tra il timestamp dell'evento più recente e il timestamp corrente. Sostanzialmente, il parametro IteratorAge indica l'età dell'ultimo record elaborato nel batch. Se la funzione continua a elaborare nuovi eventi, puoi utilizzare la cronologia di iterazione per stimare la latenza tra il momento in cui un record viene aggiunto e il momento in cui viene elaborato dalla tua funzione. Una tendenza in aumento in IteratorAge può indicare problemi con la funzione. Per ulteriori informazioni, consulta Utilizzo dei parametri di CloudWatch Logs con Lambda.

I flussi di modifiche di Amazon DocumentDB non sono ottimizzati per gestire ampi intervalli di tempo tra gli eventi. Se l'origine eventi Amazon DocumentDB non riceve alcun evento per un periodo di tempo prolungato, Lambda può disabilitare lo strumento di mappatura dell'origine degli eventi. La durata di questo periodo di tempo può variare da alcune settimane a qualche mese a seconda delle dimensioni del cluster e di altri carichi di lavoro.

Lambda supporta payload di dimensioni massime di 6 MB. Tuttavia, gli eventi del flusso di modifica di Amazon DocumentDB possono avere dimensioni fino a 16 MB. Se il flusso di modifica tenta di inviare a Lambda un evento di flusso di modifica di dimensioni superiori a 6 MB, Lambda tralascia il messaggio ed emette il parametro OversizedRecordCount. Lambda emette tutte i parametri sulla base del miglior tentativo.