Lambda로 Amazon Kinesis Data Streams 레코드 처리

Lambda로 Amazon Kinesis Data Streams 레코드를 처리하려면 Lambda 이벤트 소스 매핑을 만들어야 합니다. 표준 반복자(iterator) 또는 향상된 팬아웃(enhanced fan-out) 소비자에 Lambda 함수를 매핑할 수 있습니다. 자세한 내용은 '스트림 폴링 및 배칭'을 참고하세요.

출처: AWS Lambda 개발자 안내서

본문

Kinesis 이벤트 소스 매핑 만들기

데이터 스트림의 레코드로 Lambda 함수를 호출하려면 이벤트 소스 매핑을 만드세요. 여러 Lambda 함수로 같은 데이터를 처리하거나, 단일 함수로 여러 데이터 스트림의 항목을 처리하도록 여러 이벤트 소스 매핑을 만들 수 있습니다. 여러 스트림의 항목을 처리할 때 각 배치에는 단일 샤드 또는 스트림의 레코드만 포함됩니다.

다른 AWS 계정의 스트림에서 레코드를 처리하도록 이벤트 소스 매핑을 구성할 수 있습니다. 자세한 내용은 '크로스 계정 이벤트 소스 매핑 생성'을 참고하세요.

이벤트 소스 매핑을 만들기 전에 Lambda 함수에 Kinesis 데이터 스트림을 읽을 권한을 부여해야 합니다. Lambda는 Kinesis 데이터 스트림과 관련된 리소스를 관리하려면 다음 권한이 필요합니다.

kinesis:DescribeStream
kinesis:DescribeStreamSummary
kinesis:GetRecords
kinesis:GetShardIterator
kinesis:ListShards
kinesis:SubscribeToShard

AWS 관리형 정책 AWSLambdaKinesisExecutionRole에는 이 권한들이 포함되어 있습니다. 다음 절차에 따라 이 관리형 정책을 함수에 추가하세요.

kinesis:ListStreams 권한은 Kinesis 이벤트 소스 매핑을 만들고 관리하는 데 필요하지 않습니다. 다만 콘솔에서 이벤트 소스 매핑을 만들 때 이 권한이 없으면 드롭다운 목록에서 Kinesis 스트림을 선택할 수 없고 콘솔에 오류가 표시됩니다. 이벤트 소스 매핑을 만들려면 스트림의 Amazon Resource Name(ARN)을 수동으로 입력해야 합니다.
Lambda는 실패한 호출을 재시도할 때 kinesis:GetRecords와 kinesis:GetShardIterator API 호출을 합니다.

콘솔로 권한 추가:

Lambda 콘솔의 Functions 페이지를 열고 함수를 선택합니다.
Configuration 탭에서 Permissions를 선택합니다.
Execution role 창에서 Role name 아래의 함수 실행 역할 링크를 선택합니다. 이 링크는 IAM 콘솔에서 해당 역할의 페이지를 엽니다.
Permissions policies 창에서 Add permissions, Attach policies를 선택합니다.
검색 필드에 AWSLambdaKinesisExecutionRole을 입력합니다.
정책 옆의 체크박스를 선택하고 Add permission을 선택합니다.

CLI로 권한 추가:

함수의 실행 역할에 AWSLambdaKinesisExecutionRole 정책을 추가하려면 다음 CLI 명령을 실행하세요.

aws iam attach-role-policy \
--role-name MyFunctionRole \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaKinesisExecutionRole

함수 정의에 다음 예제처럼 Policies 속성을 추가하세요.

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./my-function/
      Handler: index.handler
      Runtime: nodejs24.x
      Policies:
        - AWSLambdaKinesisExecutionRole

필요한 권한을 구성한 뒤 이벤트 소스 매핑을 만드세요.

콘솔로 생성:

Lambda 콘솔의 Functions 페이지를 열고 함수를 선택합니다.
Function overview 창에서 Add trigger를 선택합니다.
Trigger configuration 아래에서 소스로 Kinesis를 선택합니다.
이벤트 소스 매핑을 만들 Kinesis 스트림과, 선택적으로 스트림의 소비자를 선택합니다.
(선택) 이벤트 소스 매핑의 Batch size, Starting position, Batch window를 편집합니다.
Add를 선택합니다.

콘솔에서 이벤트 소스 매핑을 만들 때 IAM 역할에 kinesis:ListStreams와 kinesis:ListStreamConsumers 권한이 있어야 합니다.

CLI로 생성:

사용 사례에 맞는 배치 크기와 시작 위치를 선택해 다음 CLI 명령으로 Kinesis 이벤트 소스 매핑을 만드세요.

aws lambda create-event-source-mapping \
--function-name MyFunction \
--event-source-arn arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream \
--starting-position LATEST \
--batch-size 100

배칭 창을 지정하려면 --maximum-batching-window-in-seconds 옵션을 추가하세요. 이 옵션과 다른 파라미터 사용에 대한 자세한 내용은 AWS CLI Command Reference의 create-event-source-mapping을 참고하세요.

함수 정의에 다음 예제처럼 KinesisEvent 속성을 추가하세요.

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./my-function/
      Handler: index.handler
      Runtime: nodejs24.x
      Policies:
        - AWSLambdaKinesisExecutionRole
      Events:
        KinesisEvent:
          Type: Kinesis
          Properties:
            Stream: !GetAtt MyKinesisStream.Arn
            StartingPosition: LATEST
            BatchSize: 100

  MyKinesisStream:
    Type: AWS::Kinesis::Stream
    Properties:
      ShardCount: 1

AWS SAM에서 Kinesis Data Streams 이벤트 소스 매핑을 만드는 방법에 대해 자세히 알아보려면 AWS Serverless Application Model Developer Guide의 'Kinesis'를 참고하세요.

폴링 및 스트림 시작 위치

이벤트 소스 매핑 생성·갱신 중의 스트림 폴링은 최종적으로 일관적(eventually consistent)이라는 점에 유의하세요.

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

이 동작은 스트림 시작 위치로 LATEST를 지정하면 이벤트 소스 매핑이 생성·갱신 중에 이벤트를 놓칠 수 있다는 뜻입니다. 어떤 이벤트도 놓치지 않도록 하려면 스트림 시작 위치를 TRIM_HORIZON 또는 AT_TIMESTAMP로 지정하세요.

크로스 계정 이벤트 소스 매핑 생성

Amazon Kinesis Data Streams는 리소스 기반 정책을 지원합니다. 이 때문에 한 AWS 계정의 스트림에 수집된 데이터를 다른 계정의 Lambda 함수로 처리할 수 있습니다.

다른 AWS 계정의 Kinesis 스트림을 사용해 Lambda 함수용 이벤트 소스 매핑을 만들려면 리소스 기반 정책으로 스트림을 구성해 Lambda 함수에 항목 읽기 권한을 부여해야 합니다. 스트림이 크로스 계정 접근을 허용하도록 구성하는 방법은 Amazon Kinesis Streams Developer guide의 'Sharing access with cross-account AWS Lambda functions'을 참고하세요.

스트림에 Lambda 함수에 필요한 권한을 부여하는 리소스 기반 정책을 구성한 뒤, 이전 섹션에서 설명한 방법 중 아무 것으로나 이벤트 소스 매핑을 만드세요.

Lambda 콘솔로 이벤트 소스 매핑을 만들기로 선택했다면 입력 필드에 스트림의 ARN을 직접 붙여넣으세요. 스트림의 소비자를 지정하려면 소비자의 ARN을 붙여넣으면 스트림 필드가 자동으로 채워집니다.

Lambda로 Amazon Kinesis Data Streams 레코드 처리