RDS for PostgreSQL DB 인스턴스에서 AWS Lambda 함수 호출 - Amazon Relational Database Service

RDS for PostgreSQL DB 인스턴스에서 AWS Lambda 함수 호출

AWS Lambda는 서버를 프로비저닝하거나 관리하지 않고도 코드를 실행할 수 있는 이벤트 기반 컴퓨팅 서비스입니다. RDS for PostgreSQL을 비롯한 많은 AWS 서비스에서 사용할 수 있습니다. 예를 들어 Lambda 함수를 사용하여 데이터베이스의 이벤트 알림을 처리하거나 새 파일이 Amazon S3에 업로드될 때마다 파일에서 데이터를 로드할 수 있습니다. Lambda에 대한 자세한 내용은 AWS Lambda 개발자 안내서에서 AWS Lambda란 무엇입니까?를 참조하세요.

참고

AWS Lambda 함수 호출은 다음 RDS for PostgreSQL 버전에서 지원됩니다.

  • 모든 PostgreSQL 16 버전

  • 모든 PostgreSQL 15 버전

  • PostgreSQL 14.1 이상의 마이너 버전

  • PostgreSQL 13.2 이상의 마이너 버전

  • PostgreSQL 12.6 이상의 마이너 버전

Lambda 함수와 함께 작동하도록 RDS for PostgreSQL을 설정하는 것은 AWS Lambda, IAM, VPC, RDS for PostgreSQL DB 인스턴스를 포괄하는 다단계 프로세스입니다. 다음에서 필요한 단계에 대한 요약을 찾을 수 있습니다.

Lambda 함수에 대한 자세한 내용은 AWS Lambda 개발자 안내서의 Lambda 시작하기AWS Lambda 기본을 참조하세요.

1단계: AWS Lambda에 대한 아웃바운드 연결을 위해 RDS for PostgreSQL DB 인스턴스 구성

Lambda 함수는 항상 AWS Lambda 서비스가 소유한 Amazon VPC 내에서 실행됩니다. Lambda는 이 VPC에 네트워크 액세스 및 보안 규칙을 적용하고 VPC를 자동으로 유지 관리 및 모니터링합니다. RDS for PostgreSQL DB 인스턴스는 네트워크 트래픽을 Lambda 서비스의 VPC로 전송합니다. 이를 구성하는 방법은 DB 인스턴스가 퍼블릭인지 프라이빗인지에 따라 다릅니다.

  • 퍼블릭 RDS for PostgreSQL DB 인스턴스DB 인스턴스는 VPC의 퍼블릭 서브넷에 있고 인스턴스의 "PubliclyAccessible" 속성이 true인 경우 퍼블릭입니다. 이 속성의 값을 찾으려면 describe-db-instances AWS CLI 명령을 사용합니다. 또는 AWS Management Console을 사용하여 연결 및 보안 탭을 열고 퍼블릭 액세스 가능인지 확인할 수 있습니다. 인스턴스가 VPC의 퍼블릭 서브넷에 있는지 확인하려면 AWS Management Console 또는 AWS CLI를 사용할 수 있습니다.

    Lambda에 대한 액세스를 설정하려면 AWS Management Console 또는AWS CLI를 사용하여 VPC의 보안 그룹에 대한 아웃바운드 규칙을 생성합니다. 아웃바운드 규칙은 TCP가 포트 443을 사용하여 IPv4 주소(0.0.0.0/0)로 패킷을 보낼 수 있도록 지정합니다.

  • 프라이빗 RDS for PostgreSQL DB 인스턴스 – 이 경우 인스턴스의 "PubliclyAccessible" 속성은 false이거나 프라이빗 서브넷에 있습니다. 인스턴스가 Lambda와 함께 작동하도록 허용하려면 Network Address Translation)NAT 게이트웨이를 사용할 수 있습니다. 자세한 내용은 NAT 게이트웨이 단원을 참조하세요. 또는 Lambda용 VPC 엔드포인트로 VPC를 구성합니다. 자세한 내용은 Amazon VPC 사용 설명서VPC 엔드포인트를 참조하세요. 엔드포인트는 RDS for PostgreSQL DB 인스턴스의 Lambda 함수 호출에 대한 응답을 반환합니다. VPC 엔드포인트는 자체 프라이빗 DNS 확인을 사용합니다. RDS for PostgreSQL은 rds.custom_dns_resolution 값을 기본값 0(사용 설정되지 않음)에서 1로 변경할 때까지 Lambda VPC 엔드포인트를 사용할 수 없습니다. 그렇게 하려면 다음을 수행하세요.

    • 사용자 지정 DB 파라미터 그룹을 생성합니다.

    • rds.custom_dns_resolution 파라미터 값을 기본값인 0에서 1로 변경합니다.

    • 사용자 정의 DB 파라미터 그룹을 사용하도록 DB 인스턴스를 수정합니다.

    • 수정된 파라미터가 적용되도록 인스턴스를 재부팅합니다.

이제 VPC가 네트워크 수준에서 AWS Lambda VPC와 상호 작용할 수 있습니다. 다음으로 IAM을 사용하여 권한을 구성합니다.

2단계: RDS for PostgreSQL DB 인스턴스 및 AWS Lambda에 대한 IAM 구성

RDS for PostgreSQL DB 인스턴스에서 Lambda 함수를 호출하려면 특정 권한이 필요합니다. 필요한 권한을 구성하려면 Lambda 함수 호출을 허용하는 IAM 정책을 생성하고 해당 정책을 역할에 할당한 다음 DB 인스턴스에 그 역할을 적용하는 것이 좋습니다. 이 접근 방식은 DB 인스턴스에 사용자를 대신하여 지정된 Lambda 함수를 호출할 수 있는 권한을 부여합니다. 다음 단계에서는 AWS CLI를 사용하여 이를 수행하는 방법을 보여줍니다.

Lambda와 함께 Amazon RDS 인스턴스를 사용하기 위한 IAM 권한 구성
  1. create-policy AWS CLI 명령을 사용하여 RDS for PostgreSQL DB 인스턴스가 지정된 Lambda 함수를 호출하도록 허용하는 IAM 정책을 생성합니다. 문 ID(Sid)는 정책 문에 대한 선택적 설명이며 사용량에 영향을 미치지 않습니다. 이 정책은 DB 인스턴스에 지정된 Lambda 함수를 호출하는 데 필요한 최소 권한을 부여합니다.

    aws iam create-policy --policy-name rds-lambda-policy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAccessToExampleFunction", "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:aws-region:444455556666:function:my-function" } ] }'

    또는 모든 Lambda 함수를 호출할 수 있도록 미리 정의된 AWSLambdaRole 정책을 사용할 수 있습니다. 자세한 내용은 Lambda에 대한 자격 증명 기반 IAM 정책을 참조하세요.

  2. create-role AWS CLI 명령을 사용하여 정책이 런타임에 수임할 수 있는 IAM 역할을 생성합니다.

    aws iam create-role --role-name rds-lambda-role --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }'
  3. attach-role-policy AWS CLI 명령을 사용하여 역할에 정책을 적용합니다.

    aws iam attach-role-policy \ --policy-arn arn:aws:iam::444455556666:policy/rds-lambda-policy \ --role-name rds-lambda-role --region aws-region
  4. add-role-to-db-instance AWS CLI 명령을 사용하여 RDS for PostgreSQL DB 인스턴스에 역할을 적용합니다. 이 마지막 단계를 통해 DB 인스턴스의 데이터베이스 사용자가 Lambda 함수를 호출할 수 있습니다.

    aws rds add-role-to-db-instance \ --db-instance-identifier my-instance-name \ --feature-name Lambda \ --role-arn arn:aws:iam::444455556666:role/rds-lambda-role \ --region aws-region

VPC 및 IAM 구성이 완료되면 이제 aws_lambda 확장을 설치할 수 있습니다. 확장은 언제든지 설치할 수 있지만 올바른 VPC 지원 및 IAM 권한을 설정할 때까지 aws_lambda 확장은 RDS for PostgreSQL DB 인스턴스의 기능에 아무 것도 추가하지 않습니다.

3단계: RDS for PostgreSQL DB 인스턴스aws_lambda 확장 설치

AWS Lambda을 RDS for PostgreSQL DB 인스턴스와 사용하려면 RDS for PostgreSQL DB 인스턴스aws_lambda PostgreSQL 확장을 추가합니다. 이 확장은 RDS for PostgreSQL DB 인스턴스에 PostgreSQL에서 Lambda 함수를 호출할 수 있는 기능을 제공합니다.

RDS for PostgreSQL DB 인스턴스aws_lambda 확장 설치

PostgreSQL psql 명령줄 또는 pgAdmin 도구를 사용하여 RDS for PostgreSQL DB 인스턴스에 연결합니다.

  1. rds_superuser 권한이 있는 사용자로 RDS for PostgreSQL DB 인스턴스에 연결합니다. 기본 postgres 사용자가 예제에 표시됩니다.

    psql -h instance.444455556666.aws-region.rds.amazonaws.com -U postgres -p 5432
  2. aws_lambda 확장을 설치합니다. aws_commons 확장도 필요합니다. 이 확장은 aws_lambda 및 기타 여러 PostgreSQL용 Aurora 확장에 대한 도우미 함수를 제공합니다. RDS for PostgreSQLDB 인스턴스에 아직 없는 경우 다음과 같이 aws_lambda와 함께 설치됩니다.

    CREATE EXTENSION IF NOT EXISTS aws_lambda CASCADE; NOTICE: installing required extension "aws_commons" CREATE EXTENSION

aws_lambda 확장이 DB 인스턴스에 설치됩니다. 이제 Lambda 함수를 호출하기 위한 편의 구조를 생성할 수 있습니다.

4단계: RDS for PostgreSQL DB 인스턴스와 함께 Lambda 도우미 함수 사용(선택 사항)

aws_commons 확장의 도우미 함수를 사용하여 PostgreSQL에서 보다 쉽게 호출할 수 있는 엔터티를 준비할 수 있습니다. 이렇게 하려면 Lambda 함수에 대한 다음 정보가 필요합니다.

  • 함수 이름(Function name) – Lambda 함수의 이름, Amazon 리소스 이름(ARN), 버전 또는 별칭입니다. 2단계: 인스턴스 및 Lambda에 대한 IAM 구성에서 생성한 IAM 정책에는 ARN이 필요하므로 함수의 ARN을 사용하는 것이 좋습니다.

  • AWS 리전 – (선택 사항) RDS for PostgreSQL DB 인스턴스와 동일한 리전에 있지 않은 경우 Lambda 함수가 있는 AWS 리전입니다.

Lambda 함수 이름 정보를 보관하려면 aws_commons.create_lambda_function_arn 함수를 사용합니다. 이 도우미 함수는 호출 함수에 필요한 세부 정보를 사용하여 aws_commons._lambda_function_arn_1 복합 구조를 생성합니다. 다음에서 이 복합 구조를 설정하는 세 가지 대안을 찾을 수 있습니다.

SELECT aws_commons.create_lambda_function_arn( 'my-function', 'aws-region' ) AS aws_lambda_arn_1 \gset
SELECT aws_commons.create_lambda_function_arn( '111122223333:function:my-function', 'aws-region' ) AS lambda_partial_arn_1 \gset
SELECT aws_commons.create_lambda_function_arn( 'arn:aws:lambda:aws-region:111122223333:function:my-function' ) AS lambda_arn_1 \gset

이러한 값은 aws_lambda.invoke 함수 호출에 사용할 수 있습니다. 예를 보려면 5단계: RDS for PostgreSQL DB 인스턴스에서 Lambda 함수 호출 섹션을 참조하세요.

5단계: RDS for PostgreSQL DB 인스턴스에서 Lambda 함수 호출

aws_lambda.invoke 함수는 invocation_type에 따라 동기식 또는 비동기식으로 작동합니다. 이 파라미터에 대한 두 가지 대안은 다음과 같이 RequestResponse(기본값) 및 Event입니다.

  • RequestResponse - 이 호출 유형은 동기식이며, 호출 유형을 지정하지 않고 호출할 때의 기본 동작입니다. 응답 페이로드에는 aws_lambda.invoke 함수의 결과가 포함됩니다. 워크플로가 진행하기 전에 Lambda 함수에서 결과를 수신해야 하는 경우 이 호출 유형을 사용합니다.

  • Event - 이 호출 유형은 비동기식이며, 응답에 결과가 포함된 페이로드가 포함되지 않습니다. 워크플로에서 처리를 계속하기 위해 Lambda 함수의 결과가 필요하지 않은 경우 이 호출 유형을 사용합니다.

설정에 대한 간단한 테스트로 psql을 사용하여 DB 인스턴스에 연결하고 명령줄에서 예제 함수를 호출할 수 있습니다. 다음 스크린샷에 표시된 간단한 Python 함수와 같이 Lambda 서비스에 기본 함수 중 하나가 설정되어 있다고 가정합니다.

AWS Lambda에 대해 AWS CLI에 표시된 예제 Lambda 함수
예제 함수 호출
  1. psql 또는 pgAdmin을 사용하여 DB 인스턴스에 연결합니다.

    psql -h instance.444455556666.aws-region.rds.amazonaws.com -U postgres -p 5432
  2. ARN을 사용하여 함수를 호출합니다.

    SELECT * from aws_lambda.invoke(aws_commons.create_lambda_function_arn('arn:aws:lambda:aws-region:444455556666:function:simple', 'us-west-1'), '{"body": "Hello from Postgres!"}'::json );

    응답은 다음과 같습니다.

    status_code | payload | executed_version | log_result -------------+-------------------------------------------------------+------------------+------------ 200 | {"statusCode": 200, "body": "\"Hello from Lambda!\""} | $LATEST | (1 row)

호출 시도가 성공하지 못한 경우 Lambda 함수 오류 메시지 섹션을 참조하세요.

6단계: 다른 사용자에게 Lambda 함수를 호출할 수 있는 권한 부여

이 시점에서는 자신만 rds_superuser 권한으로 Lambda 함수를 호출할 수 있습니다. 자신이 생성하는 함수를 다른 사용자가 호출할 수 있도록 허용하려면 권한을 부여해야 합니다.

Lambda 함수를 호출할 수 있는 권한을 부여하는 방법
  1. psql 또는 pgAdmin을 사용하여 DB 인스턴스에 연결합니다.

    psql -h instance.444455556666.aws-region.rds.amazonaws.com -U postgres -p 5432
  2. SQL 명령을 실행합니다.

    postgres=> GRANT USAGE ON SCHEMA aws_lambda TO db_username; GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA aws_lambda TO db_username;

예제: RDS for PostgreSQL DB 인스턴스에서 Lambda 함수 호출

다음에서 aws_lambda.invoke 함수를 호출하는 몇 가지 예를 찾을 수 있습니다. 예제 대부분은 4단계: RDS for PostgreSQL DB 인스턴스와 함께 Lambda 도우미 함수 사용(선택 사항)에서 생성한 복합 구조 aws_lambda_arn_1을 사용하여 함수 세부 정보 전달을 단순화합니다. 비동기 호출의 예는 예제: Lambda 함수의 비동기 (이벤트) 호출 섹션을 참조하세요. 나열된 다른 모든 예에서 동기 호출을 사용합니다.

Lambda 호출 유형에 대한 자세한 내용은 AWS Lambda 개발자 안내서Lambda 함수 호출을 참조하세요. aws_lambda_arn_1에 대한 자세한 정보는 aws_commons.create_lambda_function_arn 섹션을 참조하십시오.

예제: Lambda 함수의 동기(RequestResponse) 호출

다음은 동기식 Lambda 함수 호출의 두 가지 예입니다. 이러한 aws_lambda.invoke 함수 호출의 결과는 동일합니다.

SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json);
SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse');

파라미터는 다음과 같이 설명됩니다.

  • :'aws_lambda_arn_1' - 이 파라미터는 4단계: RDS for PostgreSQL DB 인스턴스와 함께 Lambda 도우미 함수 사용(선택 사항)에서 생성된 복합 구조를 aws_commons.create_lambda_function_arn 도우미 함수와 함께 식별합니다. 다음과 같이 aws_lambda.invoke 호출 내에서 이 구조를 인라인으로 생성할 수도 있습니다.

    SELECT * FROM aws_lambda.invoke(aws_commons.create_lambda_function_arn('my-function', 'aws-region'), '{"body": "Hello from Postgres!"}'::json );
  • '{"body": "Hello from PostgreSQL!"}'::json – Lambda 함수에 전달할 JSON 페이로드입니다.

  • 'RequestResponse' – Lambda 호출 유형.

예제: Lambda 함수의 비동기 (이벤트) 호출

다음은 비동기 Lambda 함수 호출의 일례입니다. Event 호출 유형은 지정된 입력 페이로드를 사용하여 Lambda 함수 호출을 예약하고 즉시 반환합니다. Lambda 함수 결과에 의존하지 않는 특정 워크플로에서 Event 호출 유형을 사용합니다.

SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'Event');

예: 함수 응답에서 Lambda 실행 로그 캡처

aws_lambda.invoke 함수 호출에서 log_type 파라미터를 사용하여 함수 응답에 실행 로그의 마지막 4KB를 포함할 수 있습니다. 기본적으로 이 파라미터는 None으로 설정되지만 다음과 같이 Tail을 지정하여 응답에서 Lambda 실행 로그의 결과를 캡처할 수 있습니다.

SELECT *, select convert_from(decode(log_result, 'base64'), 'utf-8') as log FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'Tail');

응답에 실행 로그를 포함하도록 aws_lambda.invoke 함수의 log_type 파라미터를 Tail로 설정합니다. log_type 파라미터의 기본값은 None입니다.

반환 문자열 log_resultbase64 인코딩된 문자열입니다. decodeconvert_from PostgreSQL 함수의 조합을 사용하여 내용을 디코딩할 수 있습니다.

log_type에 대한 자세한 정보는 aws_lambda.invoke 섹션을 참조하십시오.

예제: Lambda 함수에 클라이언트 컨텍스트 포함

aws_lambda.invoke 함수에는 다음과 같이 페이로드와 별도로 정보를 전달하는 데 사용할 수 있는 context 파라미터가 있습니다.

SELECT *, convert_from(decode(log_result, 'base64'), 'utf-8') as log FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'Tail');

클라이언트 컨텍스트를 포함하려면 aws_lambda.invoke 함수의 context 파라미터에 JSON 객체를 사용하세요.

context 파라미터에 대한 자세한 내용은 aws_lambda.invoke 레퍼런스를 참조하세요.

예제: 특정 버전의 Lambda 함수 호출

aws_lambda.invoke 호출에 qualifier 파라미터를 포함하여 Lambda 함수의 특정 버전을 지정할 수 있습니다. 다음에서 버전의 별칭으로 'custom_version'을 사용하여 이를 수행하는 예를 찾을 수 있습니다.

SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'None', NULL, 'custom_version');

다음과 같이 대신 함수 이름 세부 정보와 함께 Lambda 함수 한정자를 제공할 수도 있습니다.

SELECT * FROM aws_lambda.invoke(aws_commons.create_lambda_function_arn('my-function:custom_version', 'us-west-2'), '{"body": "Hello from Postgres!"}'::json);

qualifier 및 기타 파라미터에 대한 자세한 내용은 aws_lambda.invoke 레퍼런스를 참조하세요.

Lambda 함수 오류 메시지

다음 목록에서 가능한 원인 및 해결 방법을 비롯하여 오류 메시지에 대한 정보를 찾을 수 있습니다.

  • VPC 구성 문제

    VPC 구성 문제로 인해 연결을 시도할 때 다음과 같은 오류 메시지가 발생할 수 있습니다.

    ERROR: invoke API failed DETAIL: AWS Lambda client returned 'Unable to connect to endpoint'. CONTEXT: SQL function "invoke" statement 1

    이 오류의 일반적인 원인은 잘못 구성된 VPC 보안 그룹입니다. VPC가 Lambda VPC에 연결할 수 있도록 VPC 보안 그룹의 포트 443에서 TCP에 대한 아웃바운드 규칙이 열려 있는지 확인합니다.

    DB 인스턴스가 프라이빗인 경우 VPC에 대한 프라이빗 DNS 설정을 확인합니다. 1단계: AWS Lambda에 대한 아웃바운드 연결을 위해 RDS for PostgreSQL DB 인스턴스 구성에 설명된 대로 rds.custom_dns_resolution 파라미터를 1로 설정하고 AWS PrivateLink를 설정했는지 확인합니다. 자세한 내용은 인터페이스 VPC 엔드포인트(AWS PrivateLink)를 참조하세요.

  • Lambda 함수를 호출하는 데 필요한 권한 부족

    다음 오류 메시지 중 하나가 표시되면 함수를 호출하는 사용자(역할)에 적절한 권한이 없는 것입니다.

    ERROR: permission denied for schema aws_lambda
    ERROR: permission denied for function invoke

    Lambda 함수를 호출하려면 사용자(역할)에게 특정 권한을 부여해야 합니다. 자세한 내용은 6단계: 다른 사용자에게 Lambda 함수를 호출할 수 있는 권한 부여을 참조하세요.

  • Lambda 함수의 잘못된 오류 처리

    요청 처리 중에 Lambda 함수가 예외를 발생키면, aws_lambda.invoke 는 다음과 같은 PostgreSQL 오류와 함께 실패합니다.

    SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json); ERROR: lambda invocation failed DETAIL: "arn:aws:lambda:us-west-2:555555555555:function:my-function" returned error "Unhandled", details: "<Error details string>".

    Lambda 함수 또는 PostgreSQL 애플리케이션의 오류를 처리해야 합니다.