Processar eventos do Amazon DocumentDB com o Lambda

Você pode usar uma função do Lambda para processar eventos em um fluxo de alterações do Amazon DocumentDB (compatível com MongoDB) ao configurar um cluster do Amazon DocumentDB como uma origem do evento. Em seguida, você pode automatizar workloads orientadas por eventos invocando a função do Lambda sempre que os dados são alterados com o cluster do Amazon DocumentDB.

O Lambda processa eventos dos fluxos de alterações do Amazon DocumentDB sequencialmente na ordem em que chegam. Consequentemente, a função só pode processar uma invocação simultânea do Amazon DocumentDB de cada vez. Para monitorar a função, você pode rastrear as métricas de simultaneidade dela.

Exemplo de evento do 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"
}

Para obter mais informações sobre os eventos neste exemplo e suas formas, consulte Alterar eventos no site de documentação do MongoDB.

Pré-requisitos e permissões

Antes que você possa usar o Amazon DocumentDB como origem do evento a sua função do Lambda, observe os pré-requisitos a seguir. Você deve:

Configuração de rede

Para que o Lambda use seu cluster do Amazon DocumentDB como uma origem de eventos, ele precisa de acesso à Amazon VPC na qual o cluster reside. Recomendamos implantar endpoints da VPC do AWS PrivateLink para o Lambda acessar sua VPC. Implante um endpoint da VPC para o Lambda e, se o cluster usar autenticação, implante também um endpoint da VPC para o Secrets Manager.

Como alternativa, verifique se a VPC associada ao cluster do  Amazon DocumentDB contém um gateway NAT por sub-rede pública. Para ter mais informações, consulte Habilitar o acesso à Internet para funções do Lambda conectadas à VPC.

Se você usa endpoints da VPC, também deve configurá-los para habilitar nomes DNS privados.

Quando você cria um mapeamento da origem do evento para um cluster do Amazon DocumentDB, o Lambda verifica se as interfaces de rede elástica (ENIs) já estão presentes nas sub-redes e nos grupos de segurança da VPC do seu cluster. Se o Lambda encontrar ENIs existentes, ele tentará reutilizá-las. Caso contrário, o Lambda criará novas ENIs para se conectar à origem do evento e invocar sua função.

Regras de grupos de segurança da VPC

Configure com as seguintes regras (no mínimo) os grupos de segurança da Amazon VPC que contêm seu cluster:

Trabalhar com endpoints da VPC

Quando você usa endpoints da VPC, as chamadas de API para invocar sua função são roteadas por esses endpoints usando as ENIs. A entidade principal do serviço Lambda precisa chamar lambda:InvokeFunction para quaisquer funções que usem essas ENIs.

Por padrão, os endpoints da VPC têm políticas do IAM que são abertas. A prática recomendada é restringir essas políticas a fim de permitir somente que entidades principais específicas executem as ações necessárias usando esse endpoint. Para garantir que seu mapeamento da origem do evento seja capaz de invocar sua função do Lambda, a política de endpoint da VPC deve permitir que a entidade principal do serviço Lambda chame lambda:InvokeFunction. A restrição de suas políticas de endpoint da VPC para apenas permitir chamadas de API originadas em sua organização impedirá o funcionamento adequado do mapeamento da origem do evento.

O seguinte exemplo de políticas de endpoint da VPC mostra como conceder o acesso necessário aos endpoints do Lambda.

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

Se o seu cluster do Amazon DocumentDB usar autenticação, você também poderá restringir a política de endpoint da VPC para o endpoint do Secrets Manager. Para chamar a API do Secrets Manager, o Lambda usa seu perfil de função, e não a entidade principal de serviço do Lambda. O exemplo a seguir mostra uma política de endpoint do Secrets Manager.

{
    "Statement": [
        {
            "Action": "secretsmanager:GetSecretValue",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "customer_function_execution_role_arn"
                ]
            },
            "Resource": "customer_secret_arn"
        }
    ]
}

Criar um mapeamento da origem do evento do Amazon DocumentDB (console)

Para que uma função do Lambda faça leituras de um fluxo de alterações de um cluster do Amazon DocumentDB, crie um mapeamento da origem do evento. Esta seção descreve como fazer isso pelo console do Lambda. Para obter o AWS SDK e instruções da AWS CLI, consulte Criar um mapeamento da origem do evento do Amazon DocumentDB (SDK ou CLI).

O Lambda oferece suporte às seguintes opções de origem do evento do Amazon DocumentDB:

Criar um mapeamento da origem do evento do Amazon DocumentDB (SDK ou CLI)

Para criar ou gerenciar um mapeamento da origem do evento do Amazon DocumentDB com um AWS SDK, você pode usar as seguintes operações de API:

Para criar o mapeamento de origem de eventos com a AWS CLI, use o comando create-event-source-mapping. O exemplo a seguir usa esse comando para mapear uma função denominada my-function para um fluxo de alterações do Amazon DocumentDB. A origem do evento é especificada por um nome do recurso da Amazon (ARN), com um tamanho de lote de 500, a partir do timestamp no horário do Unix. O comando também especifica a chave do Secrets Manager que o Lambda usa para se conectar ao Amazon DocumentDB. Além disso, ele inclui parâmetros document-db-event-source-config que especificam o banco de dados e a coleção de onde serão feitas as leituras.

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"}' \

Você deve ver uma saída semelhante a:

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

Após a criação, você pode usar o comando update-event-source-mapping para atualizar as configurações da origem do evento do Amazon DocumentDB. O exemplo a seguir atualiza o tamanho do lote para 1 mil e a janela do lote para dez segundos. Para esse comando, é necessário o UUID do mapeamento da origem do evento, que pode ser recuperado usando o comando list-event-source-mapping ou o console do Lambda.

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

Você deve ver uma saída semelhante a:

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

O Lambda atualiza as configurações de maneira assíncrona. Talvez você não veja essas alterações na saída até que o processo seja concluído. Para visualizar as configurações atuais do mapeamento da origem do evento, use o comando get-event-source-mapping.

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

Você deve ver uma saída semelhante a:

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

Para excluir o mapeamento da origem do evento do  Amazon DocumentDB, use o comando delete-event-source-mapping.

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

Posições iniciais de sondagem e fluxo

Esteja ciente de que a sondagem do fluxo durante a criação e as atualizações do mapeamento da origem do evento é, finalmente, consistente.

Esse comportamento significa que, se você especificar LATEST como posição inicial do fluxo, o mapeamento da origem do evento poderá perder eventos durante a criação ou as atualizações. Para garantir que nenhum evento seja perdido, especifique a posição inicial do fluxo como TRIM_HORIZON ou AT_TIMESTAMP.

Monitorar a origem do evento do Amazon DocumentDB

Para ajudar você a monitorar a origem do evento do Amazon DocumentDB, o Lambda gera a métrica IteratorAge quando a função termina de processar um lote de registros. Idade do iterador é a diferença entre o carimbo de data e hora do evento mais recente e o carimbo de data e hora atual. Essencialmente a métrica IteratorAge indica a idade do último registro processado no lote. Se a função atualmente estiver processando novos eventos, você poderá usar a idade do iterador para estimar a latência entre quando um registro é adicionado e quando a função o processa. Uma tendência crescente em IteratorAge pode indicar problemas com a função. Para ter mais informações, consulte Visualizar métricas das funções do Lambda.

Os fluxos de alterações do Amazon DocumentDB não são otimizados para processar grandes intervalos de tempo entre os eventos. Se sua origem de eventos do Amazon DocumentDB não receber nenhum evento por um longo período de tempo, o Lambda poderá desabilitar o mapeamento da origem do evento. A duração desse período pode variar de algumas semanas a alguns meses, dependendo do tamanho do cluster e de outras workloads.

O Lambda é compatível com cargas úteis de até 6 MB. Entretanto, os eventos de fluxo de alterações do Amazon DocumentDB podem ter até 16 MB. Se seu fluxo de alterações tentar enviar ao Lambda um evento de fluxo de alterações maior que 6 MB, o Lambda descartará a mensagem e emitirá a métrica OversizedRecordCount. O Lambda emite todas as métricas com base no melhor esforço.