Node.js를 사용하여 Lambda 함수 빌드

AWS Lambda에서 Node.js로 JavaScript 코드를 실행할 수 있습니다. Lambda는 이벤트 처리를 위해 코드를 실행하는 Node.js를 위한 런타임을 제공합니다. 코드는 사용자가 관리하는 AWS Identity and Access Management(IAM) 역할의 자격 증명을 사용하여 AWS SDK for JavaScript가 포함된 환경에서 실행됩니다. Node.js 런타임에 포함된 SDK 버전에 대해 자세히 알아보려면 런타임에 포함된 SDK 버전 섹션을 참조하세요.

Lambda는 다음과 같은 Node.js 런타임을 지원합니다.

Node.js
명칭	식별자	운영 체제	사용 중단 날짜	블록 함수 생성	블록 함수 업데이트
Node.js 20	nodejs20.x	Amazon Linux 2023
Node.js 18	nodejs18.x	Amazon Linux 2
Node.js 16	nodejs16.x	Amazon Linux 2	2024년 6월 12일	2024년 7월 15일	2024년 8월 15일

참고

Node.js 18 및 이후의 런타임은 JavaScript v3용 AWS SDK를 사용합니다. 이전 런타임에서 함수를 마이그레이션하려면 GitHub에서 마이그레이션 워크숍을 따르세요. JavaScript 버전 3용 AWS SDK에 대한 자세한 내용은 모듈식 AWS SDK for JavaScript 정식 출시 블로그 게시물을 참조하세요.

Node.js 함수를 만들려면

1. Lambda 콘솔을 엽니다.

2. 함수 생성을 선택합니다.

3. 다음 설정을 구성합니다:

   • 함수 이름: 함수의 이름을 입력합니다.

   • 런타임: Node.js 20.x를 선택합니다.

4. 함수 생성을 선택합니다.

5. 테스트 이벤트를 구성하려면 테스트를 선택합니다.

6. 이벤트 이름에 test를 입력합니다.

7. Save changes(변경 사항 저장)를 선택합니다.

8. 함수를 호출하려면 테스트를 선택합니다.

콘솔은 index.js 또는 index.mjs(이)라는 단일 소스 파일로 Lambda 함수를 생성합니다. 이 파일을 편집하고 기본 제공 코드 편집기에서 더 많은 파일을 추가할 수 있습니다. 변경 사항을 저장하려면 [Save]를 선택합니다. 그런 다음 코드를 실행하려면 테스트를 선택합니다.

참고

Lambda 콘솔은 AWS Cloud9를 사용하여 브라우저에서 통합 개발 환경(IDE)을 제공합니다. AWS Cloud9을 사용하면 자신의 환경에서 Lambda 함수를 개발할 수도 있습니다. 자세한 내용은 AWS Cloud9 사용 설명서의 Working with AWS Lambda functions using the AWS Toolkit을 참조하세요.

index.js 또는 index.mjs 파일은 이벤트 객체와 컨텍스트 객체를 취하는 handler라는 이름의 함수를 내보냅니다. 이는 함수가 호출될 때 Lambda가 호출하는 핸들러 함수입니다. Node.js 함수 런타임은 Lambda에서 호출 이벤트를 가져와 핸들러로 전달합니다. 함수 구성에서 핸들러 값은 index.handler입니다.

함수 코드를 저장하면 Lambda 콘솔에서 .zip 파일 아카이브 배포 패키지를 만듭니다. 콘솔 외부에서 (IDE를 사용해) 함수 코드를 개발하는 경우 Lambda 함수에 코드를 업로드하려면 배포 패키지를 생성해야 합니다.

참고

로컬 환경에서 애플리케이션 개발을 시작하려면 이 가이드의 GitHub 리포지토리에서 사용할 수 있는 샘플 애플리케이션 중 하나를 배포하세요.

Node.js의 샘플 Lambda 애플리케이션

• blank-nodejs – 로깅, 환경 변수, AWS X-Ray 추적, 계층, 단위 테스트 및 AWS SDK를 사용하는 방법을 보여주는 Node.js 함수입니다.

• nodejs-apig - API Gateway의 이벤트를 처리하고 HTTP 응답을 반환하는 퍼블릭 API 엔드포인트가 있는 함수입니다.

• rds-mysql – 쿼리를 RDS 데이터베이스용 MySQL로 전달하는 함수입니다. 이 샘플에는 AWS Secrets Manager의 암호로 구성된 프라이빗 VPC 및 데이터베이스 인스턴스가 포함되어 있습니다.

• efs-nodejs – Amazon VPC에서 Amazon EFS 파일 시스템을 사용하는 함수입니다. 이 샘플에는 Lambda와 함께 사용하도록 구성된 VPC, 파일 시스템, 마운트 대상 및 액세스 포인트가 포함되어 있습니다.

• list-manager – Amazon Kinesis 데이터 스트림의 이벤트를 처리하고 Amazon DynamoDB에서 집계 목록을 업데이트하는 함수입니다. 이 함수는 프라이빗 VPC의 RDS 데이터베이스용 MySQL에 각 이벤트의 레코드를 저장합니다. 이 샘플에는 데이터베이스 인스턴스 및 DynamoDB용 VPC 엔드포인트와 함께 프라이빗 VPC가 포함되어 있습니다.

• error-processor – Node.js 함수는 지정된 비율의 요청에 대한 오류를 생성합니다. 오류가 기록될 때 CloudWatch Logs 구독은 두 번째 함수를 호출합니다. 이 프로세서 함수는 AWS SDK를 통해 요청에 대한 세부 정보를 수집하여 Amazon S3 버킷에 저장합니다.

함수 런타임은 호출 이벤트 외에도 컨텍스트 객체를 핸들러에 전달합니다. 컨텍스트 객체에는 호출, 함수 및 실행 환경에 관한 추가 정보가 포함되어 있습니다. 자세한 내용은 환경 변수에서 확인할 수 있습니다.

Lambda 함수는 CloudWatch Logs 로그 그룹을 함께 제공됩니다. 함수 런타임은 각 호출에 대한 세부 정보를 CloudWatch Logs에 보냅니다. 호출 중 함수가 출력하는 로그를 전달합니다. 함수가 오류를 반환하면 Lambda은 오류에 서식을 지정한 후 이를 호출자에게 반환합니다.

주제

• Node.js 초기화
• 런타임에 포함된 SDK 버전
• TCP 연결에 연결 유지 사용
• CA 인증서 로딩
• AWS Lambda 함수 핸들러(Node.js)
• .zip 파일 아카이브를 사용하여 Node.js Lambda 함수 배포
• 컨테이너 이미지를 사용하여 Node.js Lambda 함수 배포
• AWS Lambda 컨텍스트 객체(Node.js)
• AWS Lambda 함수 로깅(Node.js)
• AWS Lambda 함수 오류(Node.js)
• AWS Lambda에서 Node.js 코드 계측

Node.js 초기화

Node.js에는 초기화 동작을 다른 런타임과 다르게 만드는 고유한 이벤트 루프 모델이 있습니다. 구체적으로, Node.js는 비동기 작업을 지원하는 비차단 I/O 모델을 사용합니다. 이 모델을 사용하면 Node.js가 대부분의 워크로드에서 효율적으로 수행할 수 있습니다. 예를 들어, Node.js 함수가 네트워크 호출을 수행하는 경우 해당 요청이 비동기 작업으로 지정되어 콜백 대기열에 배치될 수 있습니다. 이 함수는 네트워크 호출이 반환될 때까지 기다림으로써 차단되는 경우 없이 기본 호출 스택 내의 다른 작업을 계속 처리할 수 있습니다. 네트워크 호출이 완료되면 해당 콜백이 실행된 다음 콜백 대기열에서 제거됩니다.

일부 초기화 태스크는 비동기로 실행될 수 있습니다. 이러한 비동기 태스크는 호출 전에 실행을 완료할 것을 보장하지 않습니다. 예를 들어, AWS 파라미터 스토어에서 파라미터를 가져오기 위해 네트워크 호출을 만드는 코드는 Lambda가 핸들러 함수를 실행할 때까지 완료되지 않을 수 있습니다. 따라서 호출하는 동안 변수가 null일 수 있습니다. 이를 방지하려면 나머지 함수의 핵심 비즈니스 로직을 계속하기 전에 변수 및 기타 비동기 코드가 완전히 초기화되었는지 확인하세요.

또는 함수 코드를 ES 모듈로 지정하여 함수 핸들러 범위 밖의 파일 최상위 레벨에서 await를 사용할 수 있습니다. 모든 Promise에 대해 await를 실행할 경우 핸들러 호출 전에 비동기 초기화 코드가 완료되어 콜드 스타트 대기 시간의 프로비저닝된 동시성이 가지는 효과를 극대화해 줍니다. 자세한 내용과 예제는 AWS Lambda에서 Node.js ES 모듈 및 최상위 레벨 대기를 참조하세요.

함수 핸들러를 ES 모듈로 지정

기본적으로 Lambda는 .js 접미사가 있는 파일을 CommonJS 모듈로 취급합니다. 선택적으로 코드를 ES 모듈로 지정할 수 있습니다. 이 작업은 두 가지 방법으로 수행할 수 있습니다. 즉, 함수의 package.json 파일에서 type을 module로 지정하거나 .mjs 파일명 확장자를 사용할 수 있습니다. 첫 번째 방법에서는 함수 코드가 모든 .js 파일을 ES 모듈로 취급하고, 두 번째 시나리오에서는 .mjs를 사용하여 지정한 파일만 ES 모듈입니다. .mjs 파일은 항상 ES 모듈이며 .cjs 파일은 항상 CommonJS 모듈이므로 ES 모듈과 CommonJS 모듈의 이름을 각각 .mjs 및 .cjs로 지정하여 모듈을 혼합할 수 있습니다.

Node.js 16까지의 Node.js 런타임 버전에서 Lambda 런타임은 함수 핸들러와 동일한 폴더 또는 하위 폴더에서 ES 모듈을 로드합니다. Node.js 18부터는 Lambda가 ES 모듈을 로드할 때 NODE_PATH 환경 변수에서 폴더를 검색합니다. 또한 Node.js 18부터 ES 모듈 런타임에 포함된 AWS SDK를 import 명령문을 사용하여 로드할 수 있습니다. 계층에서 ES 모듈을 로드할 수도 있습니다.

런타임에 포함된 SDK 버전

Node.js 런타임에 포함된 AWS SDK 버전은 런타임 버전 및 사용자의 AWS 리전에 따라 달라집니다. 사용 중인 런타임에 포함된 SDK 버전을 찾으려면 다음 코드를 사용하여 Lambda 함수를 생성합니다.

참고

Node.js 버전 18 이상에 대한 아래 예제 코드에서는 commonJS 형식을 사용합니다. Lambda 콘솔에서 함수를 생성하는 경우 코드가 포함된 파일의 이름을 index.js으로 변경해야 합니다.

예 Node.js 16

const { version } = require("aws-sdk/package.json");

exports.handler = async () => ({ version });

다음과 같은 형식으로 응답을 반환합니다.

{
  "version": "2.1374.0"
}

예 Node.js 18 이상

const { version } = require("@aws-sdk/client-s3/package.json");

exports.handler = async () => ({ version });

다음과 같은 형식으로 응답을 반환합니다.

{
  "version": "3.462.0"
}

TCP 연결에 연결 유지 사용

기본 Node.js HTTP/HTTPS 에이전트는 모든 새 요청에 대해 새로운 TCP 연결을 생성합니다. 새 연결을 설정하는 데 드는 비용을 피하기 위해 keepAlive: true를 사용하여 함수가 AWS SDK for JavaScript로 만든 연결을 재사용할 수 있습니다. 연결 유지는 SDK를 사용하여 여러 API를 호출하는 Lambda 함수의 요청 시간을 줄일 수 있습니다. 연결 유지 동작은 사용 중인 SDK 버전에 따라 다릅니다.

• JavaScript 3.x용 AWS SDK(nodejs18.x 및 그 이후 Lambda 런타임에 포함)에서 keep-alive는 기본으로 활성화되어 있습니다. 연결 유지를 비활성화하려면 AWS SDK for JavaScript 3.x Developer Guide의 Reusing connections with keep-alive in Node.js를 참조하세요.

• JavaScript 2.x용 AWS SDK(nodejs16.x Lambda 런타임에 포함)에서 keep-alive는 기본적으로 비활성화되어 있습니다. 연결 유지를 활성화하려면 AWS SDK for JavaScript 2.x Developer Guide의 Reusing Connections with Keep-Alive in Node.js를 참조하세요.

연결 유지 사용에 대한 자세한 내용은 AWS Developer Tools Blog의 HTTP keep-alive is on by default in modular AWS SDK for JavaScript를 참조하세요.

CA 인증서 로딩

Node.js 18까지의 Node.js 런타임 버전에서, Lambda는 Amazon 전용 CA(인증 기관) 인증서를 자동으로 로딩하여 다른 AWS 서비스와 상호 작용하는 함수를 더 쉽게 생성할 수 있습니다. 예를 들어, Lambda에는 Amazon RDS 데이터베이스에 설치된 서버 ID 인증서를 검증하는 데 필요한 Amazon RDS 인증서가 포함되어 있습니다. 이 동작은 콜드 스타트 동안 성능에 영향을 미칠 수 있습니다.

Node.js 20부터 Lambda는 더 이상 기본적으로 추가 CA 인증서를 로딩하지 않습니다. Node.js 20 런타임에는 /var/runtime/ca-cert.pem에 위치한 모든 Amazon CA 인증서가 있는 인증서 파일이 들어 있습니다. Node.js 18 및 이전 런타임에서 동일한 동작을 복원하려면 NODE_EXTRA_CA_CERTS 환경 변수를 /var/runtime/ca-cert.pem에 설정하십시오.

최적의 성능을 위해 필요한 인증서만 배포 패키지와 함께 번들로 묶고 NODE_EXTRA_CA_CERTS 환경 변수를 통해 로딩하는 것이 좋습니다. 인증서 파일은 PEM 형식으로 된 하나 이상의 신뢰할 수 있는 루트 또는 중간 CA 인증서로 구성되어야 합니다. 예를 들어, RDS의 경우 코드 옆에 필수 인증서를 certificates/rds.pem으로 포함합니다. 그런 다음 NODE_EXTRA_CA_CERTS를 /var/task/certificates/rds.pem에 설정하여 인증서를 로딩합니다.