Lambda로 Amazon DocumentDB 이벤트 처리 - AWS Lambda

Lambda로 Amazon DocumentDB 이벤트 처리

Amazon DocumentDB 클러스터를 이벤트 소스로 구성하면 Lambda 함수를 사용하여 Amazon DocumentDB(MongoDB 호환) 변경 스트림의 이벤트를 처리할 수 있습니다. 그런 다음 Amazon DocumentDB 클러스터에서 데이터가 변경될 때마다 Lambda 함수를 호출하여 이벤트 기반 워크로드를 자동화할 수 있습니다.

참고

Lambda는 Amazon DocumentDB 버전 4.0 및 5.0만 지원합니다. Lambda는 버전 3.6을 지원하지 않습니다.

또한 이벤트 소스 매핑의 경우 Lambda는 인스턴스 기반 클러스터와 리전 클러스터만 지원합니다. Lambda는 탄력적 클러스터 또는 글로벌 클러스터를 지원하지 않습니다. Lambda를 클라이언트로 사용하여 Amazon DocumentDB에 연결할 때는 이 제한이 적용되지 않습니다. Lambda는 모든 클러스터 유형에 연결하여 CRUD 작업을 수행할 수 있습니다.

Lambda는 Amazon DocumentDB 변경 스트림의 이벤트를 도착 순서대로 순차적으로 처리합니다. 따라서 함수는 DocumentDB에서 한 번에 하나의 동시 호출만 처리할 수 있습니다. 함수를 모니터링하기 위해 함수의 동시성 지표를 추적할 수 있습니다.

주의

Lambda 이벤트 소스 매핑은 각 이벤트를 한 번 이상 처리하므로 레코드가 중복될 수 있습니다. 중복 이벤트와 관련된 잠재적 문제를 방지하려면 함수 코드를 멱등성으로 만드는 것이 좋습니다. 자세한 내용은 AWS 지식 센터의 멱등성 Lambda 함수를 만들려면 어떻게 해야 합니까?를 참조하세요.

예시 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" }

이 예제의 이벤트와 해당 셰이프에 대한 자세한 내용은 MongoDB Documentation 웹 사이트의 Change Events를 참조하세요.

사전 조건 및 권한

Lambda 함수에 Amazon DocumentDB를 이벤트 소스로 사용하기 전에 다음 사전 요구 사항을 확인하세요. 다음을 수행해야 합니다.

  • 함수와 동일한 AWS 계정 및 AWS 리전에 기존 Amazon DocumentDB 클러스터가 있어야 합니다. 기존 클러스터가 없다면 Amazon DocumentDB 개발자 안내서의 Get Started with Amazon DocumentDB에 나와 있는 단계에 따라 하나 생성하면 됩니다. 또는 자습서: Amazon DocumentDB Streams와 함께 AWS Lambda 사용 안내서의 첫 번째 단계 집합은 필요한 모든 사전 조건이 있는 DocumentDB 클러스터를 생성하는 과정을 안내합니다.

  • Lambda가 Amazon DocumentDB 클러스터와 연결된 Amazon Virtual Private Cloud(Amazon VPC) 리소스에 액세스할 수 있도록 허용해야 합니다. 자세한 내용은 네트워크 구성 단원을 참조하십시오.

  • Amazon DocumentDB 클러스터에서 TLS를 활성화합니다. 이것이 기본 설정입니다. TLS를 사용하지 않도록 설정하면 Lambda가 클러스터와 통신할 수 없습니다.

  • Amazon DocumentDB 클러스터에서 변경 스트림을 활성화해야 합니다. 자세한 내용은 Amazon DocumentDB 개발자 안내서의 Using Change Streams with Amazon DocumentDB를 참조하세요.

  • Amazon DocumentDB 클러스터에 액세스할 수 있도록 Lambda에 보안 인증을 제공해야 합니다. 이벤트 소스를 설정할 때 클러스터에 액세스하는 데 필요한 인증 세부 정보(사용자 이름 및 암호)가 포함된 AWS Secrets Manager 키를 제공합니다. 설치 중 이 키를 제공하려면 다음 중 하나를 수행합니다.

    • 설정에 Lambda 콘솔을 사용하는 경우 Secrets Manager 키 필드에 키를 제공합니다.

    • 설정에 AWS Command Line Interface(AWS CLI)를 사용하는 경우 source-access-configurations 옵션에 이 키를 제공합니다. create-event-source-mapping 명령 또는 update-event-source-mapping 명령과 함께 이 옵션을 포함할 수 있습니다. 예:

      aws lambda create-event-source-mapping \ ... --source-access-configurations '[{"Type":"BASIC_AUTH","URI":"arn:aws:secretsmanager:us-west-2:123456789012:secret:DocDBSecret-AbC4E6"}]' \ ...
  • Amazon DocumentDB 스트림과 관련된 리소스를 관리할 수 있는 권한을 Lambda에 부여해야 합니다. 함수의 실행 역할에 다음 권한을 수동으로 추가합니다.

  • Lambda로 전송하는 Amazon DocumentDB 변경 스트림 이벤트의 크기를 6MB 미만으로 유지해야 합니다. Lambda는 최대 6MB의 페이로드 크기를 지원합니다. 변경 스트림이 Lambda에 6MB보다 큰 이벤트를 전송하려고 하면 Lambda는 메시지를 삭제하고 OversizedRecordCount 지표를 내보냅니다. Lambda는 최대한 모든 지표를 전송합니다.

참고

Lambda 함수의 최대 제한 시간은 일반적으로 15분이지만 Amazon MSK, 자체 관리형 Apache Kafka, Amazon DocumentDB, ActiveMQ 및 RabbitMQ용 Amazon MQ에 대한 이벤트 소스 매핑은 최대 제한 시간이 14분인 함수만 지원합니다. 이 제약 조건에 따라 이벤트 소스 매핑에서 함수 오류 및 재시도를 적절히 처리할 수 있습니다.

네트워크 구성

Lambda가 Amazon DocumentDB 클러스터를 이벤트 소스로 사용하려면 클러스터가 있는 Amazon VPC에 액세스해야 합니다. Lambda가 VPC에 액세스할 수 있도록 AWS PrivateLink VPC 엔드포인트를 배포하는 것이 좋습니다. Lambda용 VPC 엔드포인트를 배포하고, 클러스터가 인증을 사용하는 경우 Secrets Manager용 VPC 엔드포인트도 배포합니다.

또는 Amazon DocumentDB 클러스터와 연결된 VPC에 퍼블릭 서브넷당 하나의 NAT 게이트웨이가 포함되는지 확인합니다. 자세한 내용은 VPC 연결 Lambda 함수에 대한 인터넷 액세스 활성화 단원을 참조하십시오.

또한 VPC 엔드포인트를 사용하는 경우 프라이빗 DNS 이름을 활성화하도록 구성해야 합니다.

Amazon DocumentDB 클러스터에 대한 이벤트 소스 매핑을 생성하는 경우 Lambda는 클러스터 VPC의 서브넷 및 보안 그룹에 대해 ENI(탄력적 네트워크 인터페이스)가 이미 존재하는지 확인합니다. Lambda가 기존 ENI를 찾으면 이를 재사용하려고 시도합니다. 그렇지 않으면 Lambda가 이벤트 소스에 연결하고 함수를 호출하기 위해 새 ENI를 생성합니다.

참고

Lambda 함수는 항상 Lambda 서비스가 소유한 VPC 내에서 실행됩니다. 이러한 VPC는 서비스에 의해 자동으로 유지 관리되며 고객에게는 표시되지 않습니다. 또한 함수를 Amazon VPC에 연결할 수도 있습니다. 어느 경우든 함수의 VPC 구성은 이벤트 소스 매핑에 영향을 미치지 않습니다. 이벤트 소스의 VPC 구성에 따라 Lambda가 이벤트 소스에 연결되는 방식이 결정됩니다.

VPC 보안 그룹 규칙

최소한 다음 규칙을 사용하여 클러스터가 포함된 Amazon VPC의 보안 그룹을 구성합니다.

  • 인바운드 규칙 - 이벤트 소스에 대해 지정된 보안 그룹에 대해 Amazon DocumentDB 클러스터 포트의 모든 트래픽을 허용하세요. Amazon DocumentDB는 기본적으로 포트 27017을 사용합니다.

  • 아웃바운드 규칙 - 모든 대상에 대해 포트 443의 모든 트래픽을 허용합니다. Amazon DocumentDB 클러스터 포트에서 모든 트래픽을 허용하세요. Amazon DocumentDB는 기본적으로 포트 27017을 사용합니다.

  • NAT 게이트웨이 대신 VPC 엔드포인트를 사용하는 경우 VPC 엔드포인트와 연결된 보안 그룹은 이벤트 소스의 보안 그룹에서 포트 443의 모든 인바운드 트래픽을 허용해야 합니다.

VPC 엔드포인트 작업

VPC 엔드포인트를 사용하는 경우 함수를 호출하는 API 직접 호출은 ENI를 사용하여 이러한 엔드포인트를 통해 라우팅됩니다. Lambda 서비스 보안 주체는 해당 ENI를 사용하는 모든 함수에서 lambda:InvokeFunction을 호출해야 합니다.

기본적으로 VPC 엔드포인트에는 개방적인 IAM 정책이 있습니다. 모범 사례는 특정 보안 주체만 해당 엔드포인트를 사용하여 필요한 작업을 수행할 수 있도록 이러한 정책을 제한하는 것입니다. 이벤트 소스 매핑이 Lambda 함수를 호출할 수 있도록 하려면 VPC 엔드포인트 정책에서 Lambda 서비스 원칙이 lambda:InvokeFunction을 호출할 수 있도록 허용해야 합니다. 조직 내에서 발생하는 API 직접 호출만 허용하도록 VPC 엔드포인트 정책을 제한하면 이벤트 소스 매핑이 제대로 작동하지 않습니다.

다음 예제 VPC 엔드포인트 정책은 Lambda 엔드포인트에 필요한 액세스 권한을 부여하는 방법을 설명합니다.

예 VPC 엔드포인트 정책 - Lambda 엔드포인트
{ "Statement": [ { "Action": "lambda:InvokeFunction", "Effect": "Allow", "Principal": { "Service": [ "lambda.amazonaws.com" ] }, "Resource": "*" } ] }

Amazon DocumentDB 클러스터가 인증을 사용하는 경우 Secrets Manager 엔드포인트에 대한 VPC 엔드포인트 정책을 제한할 수도 있습니다. Secrets Manager API를 호출하기 위해 Lambda는 Lambda 서비스 보안 주체가 아닌 함수 역할을 사용합니다. 다음 예제는 Secrets Manager 엔드포인트 정책을 보여줍니다.

예 VPC 엔드포인트 정책 – Secrets Manager 엔드포인트
{ "Statement": [ { "Action": "secretsmanager:GetSecretValue", "Effect": "Allow", "Principal": { "AWS": [ "customer_function_execution_role_arn" ] }, "Resource": "customer_secret_arn" } ] }

Amazon DocumentDB 이벤트 소스 매핑 생성(콘솔)

Lambda 함수가 Amazon DocumentDB 클러스터의 변경 스트림에서 읽을 수 있도록 이벤트 소스 매핑을을 생성합니다. 이 섹션에서는 Lambda 콘솔에서 이를 수행하는 방법을 설명합니다. AWS SDK 및 AWS CLI 지침은 Amazon DocumentDB 이벤트 소스 매핑 생성(SDK 또는 CLI) 섹션을 참조하세요.

Amazon DocumentDB 이벤트 소스 매핑 생성(콘솔)
  1. Lambda 콘솔의 함수 페이지를 엽니다.

  2. 함수의 이름을 선택합니다.

  3. 함수 개요(Function overview)에서 트리거 추가(Add trigger)를 선택합니다.

  4. 트리거 구성 아래의 드롭다운 목록에서 DocumentDB를 선택합니다.

  5. 필요한 옵션을 구성한 다음 추가를 선택합니다.

Lambda는 Amazon DocumentDB 이벤트 소스에 대해 다음과 같은 옵션을 지원합니다.

  • DocumentDB 클러스터 - Amazon DocumentDB 클러스터를 선택합니다.

  • 트리거 활성화 - 즉시 트리거를 활성화할지 여부를 선택합니다. 이 확인란을 선택하면 이벤트 소스 매핑을 생성할 때 함수가 지정된 Amazon DocumentDB 변경 스트림으로부터 즉시 트래픽을 수신하기 시작합니다. 테스트할 이벤트 소스 매핑을 비활성화된 상태로 생성하려면 확인란 선택을 취소하는 것이 좋습니다. 생성 후에는 언제든지 이벤트 소스 매핑을 활성화할 수 있습니다.

  • 데이터베이스 이름 — 클러스터 내에서 사용할 데이터베이스의 이름을 입력합니다.

  • (선택 사항) 컬렉션 이름 - 사용할 데이터베이스 내의 컬렉션 이름을 입력합니다. 컬렉션을 지정하지 않으면 Lambda는 데이터베이스의 각 컬렉션에서 모든 이벤트를 수신합니다.

  • 배치 크기 — 단일 배치에서 검색할 최대 메시지 수를 설정합니다. 최대 10,000. 기본 크기는 100입니다.

  • 시작 위치 — 스트림에서 레코드 읽기를 시작할 위치를 선택합니다.

    • 최신 — 스트림에 추가된 새 레코드만 처리합니다. 함수는 Lambda가 이벤트 소스 생성을 완료한 후에만 레코드 처리를 시작합니다. 즉, 이벤트 소스가 성공적으로 생성될 때까지 일부 레코드가 삭제될 수 있습니다.

    • 수평 트리밍 – 스트림의 모든 레코드를 처리합니다. Lambda는 클러스터의 로그 보존 기간을 사용하여 이벤트 읽기를 시작할 위치를 결정합니다. 구체적으로 Lambda는 current_time - log_retention_duration에서 읽기를 시작합니다. Lambda가 모든 이벤트를 제대로 읽으려면 이 타임스탬프 전에 변경 스트림이 이미 활성화되어 있어야 합니다.

    • 타임스탬프 – 특정 시간에 시작하는 레코드를 시작합니다. Lambda가 모든 이벤트를 제대로 읽으려면 지정된 타임스탬프 전에 변경 스트림이 이미 활성화되어 있어야 합니다.

  • 인증 — 클러스터에서 브로커에 액세스하기 위한 인증 방법을 선택합니다.

    • BASIC_AUTH — 기본 인증을 사용하는 경우 클러스터에 액세스하기 위한 자격 증명이 포함된 Secrets Manager 키를 제공해야 합니다.

  • Secrets Manager 키 - Amazon DocumentDB 클러스터에 액세스하는 데 필요한 인증 세부 정보(사용자 이름 및 암호)가 포함된 Secrets Manager 키를 선택합니다.

  • (선택 사항) 배치 기간 – 함수를 호출하기 전에 레코드를 수집할 최대 시간(초)을 최대 300초로 설정합니다.

  • (선택 사항) 전체 문서 구성 - 문서 업데이트 작업의 경우 스트림으로 전송할 내용을 선택합니다. 기본값은 Default이며, 이는 각 변경 스트림 이벤트에 대해 Amazon DocumentDB가 변경 내용을 설명하는 델타만 전송한다는 것을 의미합니다. 이 필드에 대한 자세한 내용은 MongoDB Javadoc API 설명서의 FullDocument를 참조하세요.

    • 기본값 — Lambda는 변경 사항을 설명하는 문서의 일부만 전송합니다.

    • UpdateLookup — Lambda는 전체 문서의 복사본과 함께 변경 사항을 설명하는 델타를 전송합니다.

Amazon DocumentDB 이벤트 소스 매핑 생성(SDK 또는 CLI)

AWS SDK를 사용하여 Amazon DocumentDB 이벤트 소스 매핑을 생성하거나 관리하려면 다음 API 작업을 사용합니다.

AWS CLI를 사용하여 이벤트 소스 매핑을 생성하려면 create-event-source-mapping 명령을 사용합니다. 다음 예제에서는 이 명령을 사용하여 my-function이라는 함수를 Amazon DocumentDB 변경 스트림에 매핑합니다. 이벤트 소스는 Amazon 리소스 이름(ARN)으로 지정되고, 배치 크기는 500이며 Unix 시간의 타임스탬프부터 시작합니다. 또한 이 명령은 Lambda가 Amazon DocumentDB에 연결하는 데 사용하는 Secrets Manager 키를 지정합니다. 데이터베이스와 읽을 컬렉션을 지정하는 document-db-event-source-config 파라미터도 포함되어 있습니다.

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

다음과 유사한 출력 화면이 표시되어야 합니다.

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

생성 후 update-event-source-mapping 명령을 사용하여 Amazon DocumentDB 이벤트 소스에 대한 설정을 업데이트합니다. 다음 예제는 배치 크기를 1,000으로 업데이트하고 배치 기간을 10초로 업데이트합니다. 이 명령을 실행하려면 list-event-source-mapping 명령 또는 Lambda 콘솔을 사용하여 검색할 수 있는 이벤트 소스 매핑의 UUID가 필요합니다.

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

다음과 유사한 출력이 표시되어야 합니다.

{ "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는 설정을 비동기식으로 업데이트하므로 프로세스가 완료된 후에야 출력에 이러한 변경 사항이 표시되지 않을 수 있습니다. 이벤트 소스 매핑의 현재 설정을 보려면 get-event-source-mapping 명령을 사용합니다.

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

다음과 유사한 출력이 표시되어야 합니다.

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

Amazon DocumentDB 이벤트 소스 매핑을 삭제하려면 delete-event-source-mapping 명령을 사용합니다.

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

폴링 및 스트리밍 시작 위치

이벤트 소스 매핑 생성 및 업데이트 중 스트림 폴링은 최종적으로 일관됩니다.

  • 이벤트 소스 매핑 생성 중 스트림에서 이벤트 폴링을 시작하는 데 몇 분 정도 걸릴 수 있습니다.

  • 이벤트 소스 매핑 업데이트 중 스트림에서 이벤트 폴링을 중지했다가 다시 시작하는 데 몇 분 정도 걸릴 수 있습니다.

이 동작은 스트림의 시작 위치로 LATEST를 지정하면 이벤트 소스 매핑이 생성 또는 업데이트 중에 이벤트를 놓칠 수 있음을 의미합니다. 누락된 이벤트가 없도록 하기 위해서는 스트림 시작 위치를 TRIM_HORIZON 또는 AT_TIMESTAMP로 지정하세요.

Amazon DocumentDB 이벤트 소스 모니터링

Amazon DocumentDB 이벤트 소스를 모니터링하는 데 도움이 되도록 Lambda는 함수가 레코드 배치 처리를 완료할 때 IteratorAge 지표를 내보냅니다. 반복기 수명은 가장 최근 이벤트의 타임스탬프와 현재 타임스탬프 간의 차이입니다. 기본적으로 IteratorAge 지표는 배치에서 마지막으로 처리된 레코드가 얼마나 오래되었는지를 나타냅니다. 함수가 현재 새 이벤트를 처리하고 있다면 반복기 수명을 사용하여 레코드가 추가된 후 함수에서 레코드를 처리할 때까지 지연 시간을 추정할 수 있습니다. IteratorAge의 증가 추세는 함수에 문제가 있음을 나타낼 수 있습니다. 자세한 내용은 Lambda 함수 지표 작업 단원을 참조하십시오.

Amazon DocumentDB 변경 스트림은 이벤트 간의 큰 시간 간격을 처리하는 데 최적화되지 않았습니다. Amazon DocumentDB 이벤트 소스에서 오랜 기간 동안 이벤트가 수신되지 않으면 Lambda가 이벤트 소스 매핑을 비활성화할 수 있습니다. 이 기간은 클러스터의 크기와 기타 워크로드에 따라 몇 주에서 몇 개월까지 다양할 수 있습니다.

Lambda는 최대 6MB의 페이로드를 지원합니다. 하지만 Amazon DocumentDB 변경 스트림 이벤트의 크기는 최대 16MB일 수 있습니다. 변경 스트림이 Lambda에 6MB보다 큰 변경 스트림 이벤트를 전송하려고 하면 Lambda는 메시지를 삭제하고 OversizedRecordCount 지표를 내보냅니다. Lambda는 최대한 모든 지표를 전송합니다.