자습서: Amazon DocumentDB Streams와 함께 AWS Lambda 사용
이 자습서에서는 Amazon DocumentDB(MongoDB 호환) 변경 스트림의 이벤트를 사용하는 기본 Lambda 함수를 생성합니다. 이 자습서를 완료하는 과정에서 다음 단계를 거치게 됩니다.
-
Amazon DocumentDB 클러스터를 설정하고, 연결하고, 변경 스트림을 활성화합니다.
-
Lambda 함수를 생성하고 Amazon DocumentDB 클러스터를 함수의 이벤트 소스로 구성합니다.
-
Amazon DocumentDB 데이터베이스에 항목을 삽입하여 설정을 테스트합니다.
Amazon DocumentDB 클러스터 생성
-
Amazon DocumentDB 콘솔
을 엽니다. 클러스터에서 생성을 선택합니다. -
다음 구성을 사용하여 클러스터를 생성합니다.
-
클러스터 유형에서 인스턴스 기반 클러스터를 선택합니다. 이는 기본 옵션입니다.
-
클러스터 구성에서 엔진 버전 5.0.0이 선택되어 있는지 확인합니다. 이는 기본 옵션입니다.
-
인스턴스 구성에서
-
DB 인스턴스 클래스에서 메모리 최적화 클래스를 선택합니다. 이는 기본 옵션입니다.
-
일반 복제본 인스턴스 수에서 1을 선택합니다.
-
인스턴스 클래스에서 기본 선택을 사용합니다.
-
-
인증에 기본 사용자 이름을 입력하고 자체 관리형을 선택합니다. 암호를 입력한 다음 확인합니다.
-
다른 기본 설정을 모두 유지합니다.
-
-
클러스터 생성을 선택합니다.
Secrets Manager에서 보안 암호 생성
Amazon DocumentDB에서 클러스터를 생성하는 동안 AWS Secrets Manager 보안 암호를 생성하여 데이터베이스 자격 증명을 저장합니다. 이후 단계에서 Lambda 이벤트 소스 매핑을 생성할 때 이 보안 암호를 제공합니다.
Secrets Manager에서 보안 암호 생성
-
Secrets Manager
콘솔을 열고 새 보안 암호 저장을 선택합니다. -
보안 암호 유형 선택)에서 다음 옵션을 선택합니다.
-
기본 세부 정보에서
-
보안 암호 유형: Amazon DocumentDB 데이터베이스의 자격 증명
-
자격 증명에 Amazon DocumentDB 클러스터를 생성하는 데 사용한 동일한 사용자 이름과 암호를 입력합니다.
-
데이터베이스: Amazon DocumentDB 클러스터를 선택합니다.
-
다음을 선택합니다.
-
-
-
보안 암호 구성에서 다음 옵션을 선택합니다.
-
비밀 이름:
DocumentDBSecret
-
다음을 선택합니다.
-
-
다음을 선택합니다.
-
저장(Store)을 선택합니다.
-
콘솔을 새로 고쳐
DocumentDBSecret
보안 암호가 성공적으로 저장되었는지 확인합니다.
보안 ARN을 기록해 둡니다. 이는 이후 단계에서 필요합니다.
클러스터에 연결
AWS CloudShell을 사용하여 Amazon DocumentDB 클러스터에 연결
-
Amazon DocumentDB 관리 콘솔의 클러스터에서 생성한 클러스터를 찾습니다. 클러스터 옆의 확인란을 클릭하여 클러스터를 선택합니다.
-
클러스터에 연결을 선택합니다. CloudShell 명령 실행 화면이 나타납니다.
-
새 환경 이름 필드에 ‘테스트’와 같은 고유한 이름을 입력하고 생성 및 실행을 선택합니다.
-
메시지가 표시되면 암호를 입력합니다. 프롬프트가
rs0 [direct: primary] <env-name>>
이 되면 Amazon DocumentDB 클러스터에 성공적으로 연결된 것입니다.
변경 스트림 활성화
이 자습서에서는 Amazon DocumentDB 클러스터에 있는 docdbdemo
데이터베이스의 products
컬렉션에 대한 변경 사항을 추적합니다. 변경 스트림을 활성화하면 됩니다.
클러스터 내에 새 데이터베이스 생성
-
다음 명령을 실행하여
docdbdemo
이라는 새 데이터베이스를 생성합니다.use docdbdemo
-
터미널 창에서 다음 명령을 사용하여
docdbdemo
에 레코드를 삽입합니다.db.products.insertOne({"hello":"world"})
다음과 같이 출력되어야 합니다.
{ acknowledged: true, insertedId: ObjectId('67f85066ca526410fd531d59') }
-
그리고 다음 명령을 사용하여
docdbdemo
데이터베이스의products
컬렉션에서 변경 스트림을 활성화합니다.db.adminCommand({modifyChangeStreams: 1, database: "docdbdemo", collection: "products", enable: true});
다음과 유사한 출력 화면이 표시되어야 합니다.
{ "ok" : 1, "operationTime" : Timestamp(1680126165, 1) }
인터페이스 VPC 엔드포인트 생성
다음으로 인터페이스 VPC 엔드포인트를 생성하여 Lambda와 Secrets Manager(나중에 클러스터 액세스 자격 증명을 저장하는 데 사용됨)가 기본 VPC에 연결할 수 있는지 확인합니다.
인터페이스 VPC 엔드포인트 생성
-
VPC 콘솔
을 엽니다. 왼쪽 메뉴의 Virtual Private Cloud에서 엔드포인트를 선택합니다. -
Create endpoint(엔드포인트 생성)을 선택합니다. 다음 구성으로 엔드포인트를 생성합니다.
-
이름 태그에
lambda-default-vpc
를 입력합니다. -
서비스 범주에서 AWS 서비스를 선택합니다.
-
서비스 검색 상자에
lambda
를 입력합니다.com.amazonaws.<region>.lambda
형식의 서비스를 선택합니다. -
VPC에서 Amazon DocumentDB 클러스터가 있는 VPC를 선택합니다. 이는 일반적으로 기본 VPC입니다.
-
서브넷에서 각 가용 영역 옆의 확인란을 선택합니다. 각 가용 영역에 대한 올바른 서브넷 ID를 선택합니다.
-
IP 주소 유형에서 IPv4를 선택합니다.
-
보안 그룹에서 Amazon DocumentDB 클러스터가 사용하는 보안 그룹을 선택합니다. 이는 일반적으로
default
보안 그룹입니다. -
다른 기본 설정을 모두 유지합니다.
-
Create endpoint(엔드포인트 생성)을 선택합니다.
-
-
다시 엔드포인트 생성을 선택합니다. 다음 구성으로 엔드포인트를 생성합니다.
-
이름 태그에
secretsmanager-default-vpc
를 입력합니다. -
서비스 범주에서 AWS 서비스를 선택합니다.
-
서비스 검색 상자에
secretsmanager
를 입력합니다.com.amazonaws.<region>.secretsmanager
형식의 서비스를 선택합니다. -
VPC에서 Amazon DocumentDB 클러스터가 있는 VPC를 선택합니다. 이는 일반적으로 기본 VPC입니다.
-
서브넷에서 각 가용 영역 옆의 확인란을 선택합니다. 각 가용 영역에 대한 올바른 서브넷 ID를 선택합니다.
-
IP 주소 유형에서 IPv4를 선택합니다.
-
보안 그룹에서 Amazon DocumentDB 클러스터가 사용하는 보안 그룹을 선택합니다. 이는 일반적으로
default
보안 그룹입니다. -
다른 기본 설정을 모두 유지합니다.
-
Create endpoint(엔드포인트 생성)을 선택합니다.
-
이것으로 이 자습서의 클러스터 설정 부분이 완료되었습니다.
실행 역할 생성
다음 단계에서는 Lambda 함수를 생성합니다. 먼저 함수에 클러스터에 액세스할 수 있는 권한을 제공하는 실행 역할을 생성해야 합니다. 이 작업을 수행하려면 먼저 IAM 정책을 생성한 다음 이 정책을 IAM 역할에 연결합니다.
IAM 정책 생성
-
IAM 콘솔에서 정책 페이지
를 열고 정책 생성을 선택합니다. -
JSON 탭을 선택합니다. 다음 정책에서 명령문의 마지막 줄에 있는 Secrets Manager 리소스 ARN을 이전의 보안 암호 ARN으로 바꾸고 정책을 편집기에 복사합니다.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "LambdaESMNetworkingAccess", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DescribeVpcs", "ec2:DeleteNetworkInterface", "ec2:DescribeSubnets", "ec2:DescribeSecurityGroups", "kms:Decrypt" ], "Resource": "*" }, { "Sid": "LambdaDocDBESMAccess", "Effect": "Allow", "Action": [ "rds:DescribeDBClusters", "rds:DescribeDBClusterParameters", "rds:DescribeDBSubnetGroups" ], "Resource": "*" }, { "Sid": "LambdaDocDBESMGetSecretValueAccess", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": "
arn:aws:secretsmanager:us-east-1:123456789012:secret:DocumentDBSecret
" } ] } -
다음: 태그를 선택하고 다음: 검토를 선택합니다.
-
이름에서
AWSDocumentDBLambdaPolicy
을 입력합니다. -
Create policy(정책 생성)를 선택합니다.
IAM 역할을 만들려면
-
IAM 콘솔에서 역할 페이지
를 열고 역할 생성을 선택합니다. -
신뢰할 수 있는 엔터티 선택에서 다음 옵션을 선택합니다.
-
신뢰할 수 있는 엔티티 유형: AWS 서비스
-
서비스 또는 사용 사례: Lambda
-
다음을 선택합니다.
-
-
권한 추가에서 방금 생성한
AWSDocumentDBLambdaPolicy
정책과AWSLambdaBasicExecutionRole
을 선택하여 함수에 Amazon CloudWatch Logs에 쓸 수 있는 권한을 부여합니다. -
다음을 선택합니다.
-
역할 이름에
AWSDocumentDBLambdaExecutionRole
을 입력합니다. -
역할 생성을 선택합니다.
Lambda 함수 생성
이 자습서에서는 Python 3.13 런타임을 사용하지만 다른 런타임의 예시 코드 파일도 제공했습니다. 다음 상자에서 탭을 선택하여 관심 있는 런타임에 대한 코드를 볼 수 있습니다.
코드가 Amazon DocumentDB 이벤트 입력을 수신하고 이벤트에 포함된 메시지를 처리합니다.
Lambda 함수를 만들려면
-
Lambda 콘솔의 함수 페이지
를 엽니다. -
함수 생성을 선택합니다.
-
새로 작성을 선택합니다.
-
기본 정보에서 다음과 같이 합니다.
-
함수 이름에
ProcessDocumentDBRecords
을 입력합니다. -
런타임에서 Python 3.13을 선택합니다.
-
아키텍처에서는 x86_64를 선택합니다.
-
-
기본 실행 역할 변경 탭에서 다음을 수행합니다.
-
탭을 확장한 다음 기존 역할 사용을 선택합니다.
-
이전에 생성한
AWSDocumentDBLambdaExecutionRole
을 선택합니다.
-
-
함수 생성을 선택합니다.
함수 코드 배포
-
다음 상자에서 Python 탭을 선택하고 코드를 복사합니다.
-
Lambda 콘솔의 코드 소스 창에서 코드 편집기에 코드를 붙여넣고 Lambda가 생성한 코드를 바꿉니다.
-
배포 섹션에서 배포를 선택하여 함수의 코드를 업데이트하세요.
Lambda 이벤트 소스 매핑 생성
Amazon DocumentDB 변경 스트림을 Lambda 함수와 연결하는 이벤트 소스 매핑을 생성합니다. 이 이벤트 소스 매핑을 생성하면 AWS Lambda가 스트림 폴링을 즉시 시작합니다.
이벤트 소스 매핑 생성
-
Lambda 콘솔에서 함수 페이지
를 엽니다. -
앞에서 생성한
ProcessDocumentDBRecords
함수를 선택합니다. -
구성 탭을 선택한 다음 왼쪽 메뉴에서 트리거를 선택합니다.
-
트리거 추가를 선택합니다.
-
트리거 구성에서 소스로 Amazon DocumentDB를 선택합니다.
-
다음 구성으로 이벤트 소스 매핑을 생성합니다.
-
Amazon DocumentDB 클러스터: 이전에 생성한 클러스터를 선택합니다.
-
데이터베이스 이름: docdbdemo
-
컬렉션 이름: 제품
-
배치 크기: 1
-
시작 위치: 최신
-
인증: BASIC_AUTH
-
Secrets Manager 키: Amazon DocumentDB 클러스터의 보안 암호를 선택합니다. 예를 들어,
rds!cluster-12345678-a6f0-52c0-b290-db4aga89274f
라고 합니다. -
배치 창: 1
-
전체 문서 구성: UpdateLookup
-
-
추가를 선택합니다. 이벤트 소스 매핑을 생성하는 데 몇 분 정도 걸릴 수 있습니다.
함수 테스트
이벤트 소스 매핑이 활성화됨 상태가 될 때까지 기다립니다. 몇 분 정도 걸릴 수 있습니다. 그런 다음 데이터베이스 레코드를 삽입, 업데이트 및 삭제하여 엔드 투 엔드 설정을 테스트합니다. 시작하기 전:
-
CloudShell 환경에서 Amazon DocumentDB 클러스터에 다시 연결합니다.
-
다음 명령을 실행하여
docdbdemo
데이터베이스를 사용하고 있는지 확인합니다.use docdbdemo
docdbdemo
데이터베이스의 products
컬렉션에 레코드 삽입:
db.products.insertOne({"name":"Pencil", "price": 1.00})
CloudWatch Logs를 확인하여 함수가 이 이벤트를 성공적으로 처리했는지 확인합니다. 다음과 같은 로그 항목이 표시되어야 합니다.

다음 명령을 사용하여 방금 삽입한 레코드를 업데이트합니다.
db.products.updateOne( { "name": "Pencil" }, { $set: { "price": 0.50 }} )
CloudWatch Logs를 확인하여 함수가 이 이벤트를 성공적으로 처리했는지 확인합니다. 다음과 같은 로그 항목이 표시되어야 합니다.

다음 명령을 사용하여 방금 업데이트한 레코드를 삭제합니다.
db.products.deleteOne( { "name": "Pencil" } )
CloudWatch Logs를 확인하여 함수가 이 이벤트를 성공적으로 처리했는지 확인합니다. 다음과 같은 로그 항목이 표시되어야 합니다.

문제 해결
함수의 CloudWatch 로그에 데이터베이스 이벤트가 없으면 다음을 확인합니다.
-
Lambda 이벤트 소스 매핑(트리거라고도 함)이 활성화됨 상태인지 확인합니다. 이벤트 소스 매핑을 생성하는 데 몇 분 정도 걸릴 수 있습니다.
-
이벤트 소스 매핑이 활성화됨 상태이지만 여전히 CloudWatch에 데이터베이스 이벤트가 표시되지 않는 경우
-
이벤트 소스 매핑의 데이터베이스 이름이
docdbdemo
로 설정되어 있는지 확인합니다. -
이벤트 소스 매핑의 마지막 처리 결과 필드에 ‘문제: 연결 오류. 인증이 필요한 경우 VPC가 Secrets Manager뿐만 아니라 Lambda 및 STS에 연결할 수 있어야 합니다.’라는 메시지가 표시되는지 확인합니다. 이 오류가 표시되면 Lambda 및 Secrets Manager VPC 인터페이스 엔드포인트를 생성했는지, 그리고 엔드포인트가 Amazon DocumentDB 클러스터에서 사용하는 것과 동일한 VPC 및 서브넷을 사용하는지 확인합니다.
-
리소스 정리
이 자습서 용도로 생성한 리소스를 보관하고 싶지 않다면 지금 삭제할 수 있습니다. 더 이상 사용하지 않는 AWS 리소스를 삭제하면 AWS 계정에 불필요한 요금이 발생하는 것을 방지할 수 있습니다.
Lambda 함수를 삭제하려면
-
Lambda 콘솔의 함수 페이지
를 엽니다. -
생성한 함수를 선택합니다.
-
작업, 삭제를 선택합니다.
-
텍스트 입력 필드에
confirm
를 입력하고 Delete(삭제)를 선택합니다.
집행 역할 삭제
-
IAM 콘솔에서 역할 페이지
를 엽니다. -
생성한 실행 역할을 선택합니다.
-
삭제를 선택합니다.
-
텍스트 입력 필드에 역할의 이름을 입력하고 Delete(삭제)를 선택합니다.
VPC 엔드포인트 삭제
-
VPC 콘솔
을 엽니다. 왼쪽 메뉴의 Virtual Private Cloud에서 엔드포인트를 선택합니다. -
생성한 엔드포인트를 선택합니다.
-
작업(Actions), VPC 엔드포인트 삭제(Delete VPC endpoints)를 차례로 선택합니다.
-
텍스트 입력 필드에
delete
을 입력합니다. -
삭제를 선택합니다.
Amazon DocumentDB 클러스터 삭제
-
Amazon DocumentDB 콘솔
을 엽니다. -
이 자습서용으로 생성한 Amazon DocumentDB 클러스터를 선택하고 삭제 방지를 비활성화합니다.
-
기본 클러스터 페이지에서 Amazon DocumentDB 클러스터를 다시 선택합니다.
-
작업, 삭제를 선택합니다.
-
최종 클러스터 스냅샷 생성에서 아니요를 선택합니다.
-
텍스트 입력 필드에
delete
을 입력합니다. -
삭제를 선택합니다.
Secrets Manager에서 보안 암호 삭제
-
Secrets Manager 콘솔
을 엽니다. -
이 자습서용으로 생성한 보안 암호를 선택합니다.
-
작업, 보안 암호 삭제를 선택합니다.
-
삭제 예약(Schedule deletion)을 선택합니다.