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 da segurança de rede

Para conceder ao Lambda acesso total ao Amazon DocumentDB por meio do mapeamento da origem do evento, seu cluster deve usar um endpoint público (endereço IP público) ou você deve fornecer acesso à Amazon VPC na qual o cluster foi criado.

Ao usar o Amazon DocumentDB com o Lambda, recomendamos a criação de endpoints de VPC do AWS PrivateLink para conceder acesso da sua função aos recursos na sua Amazon VPC.

Crie um endpoint para fornecer acesso aos seguintes recursos:

Como alternativa, configure um gateway NAT em cada sub-rede pública da Amazon VPC. Para ter mais informações, consulte Habilitar o acesso à Internet para funções do Lambda conectadas à VPC.

Ao criar um mapeamento da origem do evento para o 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 configurados para a Amazon VPC. 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.

Configure os grupos de segurança para a Amazon VPC que contém o cluster. Por padrão, o Amazon DocumentDB faz uso das seguintes portas: 27017.

Caso o cluster use autenticação, é possível restringir a política de endpoint 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.

{
      "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 você usa os endpoints da Amazon VPC, a AWS roteia suas chamadas de API para invocar sua função usando a interface de rede elástica (ENI) do endpoint. A entidade principal do serviço Lambda precisa chamar lambda:InvokeFunction para quaisquer perfis e funções que usem essas ENIs.

Por padrão, os endpoints da Amazon VPC têm políticas do IAM abertas que permitem amplo acesso aos recursos. A prática recomendada é restringir essas políticas para executar 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 sts:AssumeRole e lambda:InvokeFunction. A restrição de suas políticas de endpoint da VPC para permitir apenas chamadas de API originadas em sua organização impedirá o funcionamento adequado do mapeamento da origem do evento; portanto, "Resource": "*" é necessário nessas políticas.

O seguinte exemplo de políticas de endpoint da VPC mostra como conceder o acesso necessário à entidade principal do serviço Lambda para os endpoints do 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": "*"
          }
      ]
  }

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 Uso de métricas do CloudWatch com o 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.