Node.js Lambda 함수용 레이어 작업

Lambda 레이어를 사용해 여러 함수에서 재사용하려는 코드와 의존성을 패키징하세요. 레이어에는 보통 라이브러리 의존성, 커스텀 런타임, 구성 파일이 들어 있습니다. 레이어를 만드는 과정은 크게 세 단계입니다.

출처: AWS Lambda 개발자 안내서

본문

레이어 콘텐츠를 패키징합니다. 즉, 함수에서 사용할 의존성을 담은 .zip 파일 아카이브를 만듭니다.
Lambda에서 레이어를 생성합니다.
함수에 레이어를 추가합니다.

이 페이지의 내용:

레이어 콘텐츠 패키징
Lambda에서 레이어 생성
함수에 레이어 추가
샘플 앱

레이어 콘텐츠 패키징

레이어를 만들려면 패키지를 다음 요구 사항을 충족하는 .zip 파일 아카이브로 묶으세요.

Lambda 함수에 사용할 계획인 것과 같은 Node.js 버전으로 레이어를 빌드하세요. 예를 들어 Node.js 24로 레이어를 빌드했다면 함수에도 Node.js 24 런타임을 사용하세요.
레이어의 .zip 파일은 다음 디렉터리 구조 중 하나를 사용해야 합니다.
- nodejs/node_modules
- nodejs/nodeX/node_modules (X는 Node.js 버전, 예: node22)
- 자세한 내용은 '각 Lambda 런타임의 레이어 경로' 문서를 참고하세요.
레이어의 패키지는 Linux와 호환되어야 합니다. Lambda 함수는 Amazon Linux에서 실행됩니다.

npm으로 설치한 서드파티 Node.js 라이브러리(예: axios, lodash)나 자체 JavaScript 모듈을 담는 레이어를 만들 수 있습니다.

필요한 디렉터리 구조를 만들고 거기에 패키지를 직접 설치합니다.

mkdir -p nodejs
npm install --prefix nodejs lodash axios

이 명령은 패키지를 Lambda가 요구하는 구조인 nodejs/node_modules 디렉터리에 직접 설치합니다.

네이티브 의존성이나 바이너리 구성 요소(예: sharp, bcrypt)가 있는 패키지는 Lambda Linux 환경과 함수의 아키텍처와 호환되는지 확인하세요. --platform 플래그가 필요할 수 있습니다.

npm install --prefix nodejs --platform=linux --arch=x64 sharp

더 복잡한 네이티브 의존성은 Lambda 런타임과 일치하는 Linux 환경에서 컴파일해야 할 수 있습니다. 이를 위해 Docker를 사용할 수 있습니다.

레이어 콘텐츠를 압축합니다.

zip -r layer.zip nodejs/

Compress-Archive -Path .\nodejs -DestinationPath .\layer.zip

.zip 파일의 디렉터리 구조는 다음과 같아야 합니다.

nodejs/
├── package.json
├── package-lock.json
└── node_modules/
    ├── lodash/
    ├── axios/
    └── (dependencies of the other packages)

.zip 파일 루트에 nodejs 디렉터리가 있고 그 안에 node_modules가 포함되어 있는지 확인하세요. 이 구조가 있어야 Lambda가 패키지를 찾고 import 할 수 있습니다.

nodejs/ 디렉터리의 package.json과 package-lock.json 파일은 npm이 의존성 관리에 사용하지만 Lambda 레이어 기능에는 필요하지 않습니다. 설치된 각 패키지에는 Lambda가 패키지를 import 하는 방식을 정의하는 자체 package.json 파일이 이미 들어 있습니다.

레이어에 필요한 디렉터리 구조를 만듭니다.

mkdir -p nodejs/node_modules/validator
cd nodejs/node_modules/validator

자체 모듈이 어떻게 import 되어야 하는지 정의하는 package.json 파일을 만듭니다.

{
  "name": "validator",
  "version": "1.0.0",
  "type": "module",
  "main": "index.mjs"
}

JavaScript 모듈 파일을 만듭니다.

export function validateOrder(orderData) {
  // Validates an order and returns formatted data
  const requiredFields = ['productId', 'quantity'];
  
  // Check required fields
  const missingFields = requiredFields.filter(field => !(field in orderData));
  if (missingFields.length > 0) {
    throw new Error(`Missing required fields: ${missingFields.join(', ')}`);
  }
  
  // Validate quantity
  const quantity = orderData.quantity;
  if (!Number.isInteger(quantity) || quantity < 1) {
    throw new Error('Quantity must be a positive integer');
  }
  
  // Format and return the validated data
  return {
    productId: String(orderData.productId),
    quantity: quantity,
    shippingPriority: orderData.priority || 'standard'
  };
}

export function formatResponse(statusCode, body) {
  // Formats the API response
  return {
    statusCode: statusCode,
    body: JSON.stringify(body)
  };
}

레이어 콘텐츠를 압축합니다.

zip -r layer.zip nodejs/

Compress-Archive -Path .\nodejs -DestinationPath .\layer.zip

.zip 파일의 디렉터리 구조는 다음과 같아야 합니다.

nodejs/              
└── node_modules/
    └── validator/
        ├── package.json
        └── index.mjs

함수에서 모듈을 import 해 사용합니다. 예시:

import { validateOrder, formatResponse } from 'validator';

export const handler = async (event) => {
  try {
    // Parse the order data from the event body
    const orderData = JSON.parse(event.body || '{}');
    
    // Validate and format the order
    const validatedOrder = validateOrder(orderData);
    
    return formatResponse(200, {
      message: 'Order validated successfully',
      order: validatedOrder
    });
  } catch (error) {
    if (error instanceof Error && error.message.includes('Missing required fields')) {
      return formatResponse(400, {
        error: error.message
      });
    }
    
    return formatResponse(500, {
      error: 'Internal server error'
    });
  }
};

다음 테스트 이벤트로 함수를 호출할 수 있습니다.

{
    "body": "{\"productId\": \"ABC123\", \"quantity\": 2, \"priority\": \"express\"}"
}

기대 응답:

{
  "statusCode": 200,
  "body": "{\"message\":\"Order validated successfully\",\"order\":{\"productId\":\"ABC123\",\"quantity\":2,\"shippingPriority\":\"express\"}}"
}

Lambda에서 레이어 생성

AWS CLI 또는 Lambda 콘솔로 레이어를 게시할 수 있습니다.

publish-layer-version AWS CLI 명령을 실행해 Lambda 레이어를 만듭니다.

aws lambda publish-layer-version --layer-name my-layer --zip-file fileb://layer.zip --compatible-runtimes nodejs24.x

compatible-runtimes 파라미터는 선택 사항입니다. 지정하면 Lambda가 Lambda 콘솔에서 레이어를 필터링하는 데 이 파라미터를 사용합니다.

Lambda 콘솔의 Layers 페이지를 엽니다.

Create layer를 선택합니다.
Upload a .zip file을 선택한 뒤, 앞서 만든 .zip 아카이브를 업로드합니다.
(선택) Compatible runtimes에서 레이어를 빌드할 때 쓴 Node.js 버전에 해당하는 Node.js 런타임을 선택합니다.
Create를 선택합니다.

함수에 레이어 추가

레이어를 함수에 첨부하려면 update-function-configuration AWS CLI 명령을 실행합니다. --layers 파라미터에는 레이어 ARN을 사용합니다. ARN은 버전을 지정해야 합니다(예: arn:aws:lambda:us-east-1:123456789012:layer:my-layer:1). 자세한 내용은 '레이어와 레이어 버전' 문서를 참고하세요.

aws lambda update-function-configuration --function-name my-function --cli-binary-format raw-in-base64-out --layers "arn:aws:lambda:us-east-1:123456789012:layer:my-layer:1"

cli-binary-format 옵션은 AWS CLI 버전 2를 사용한다면 필수입니다. 이 옵션을 기본값으로 만들려면 aws configure set cli-binary-format raw-in-base64-out을 실행하세요. 자세한 내용은 AWS Command Line Interface User Guide for Version 2의 'AWS CLI supported global command line options'을 참고하세요.

Lambda 콘솔의 Functions 페이지를 엽니다.

함수를 선택합니다.
Layers 섹션까지 스크롤한 뒤 Add a layer를 선택합니다.
Choose a layer 아래에서 Custom layers를 선택한 뒤, 레이어를 선택합니다.
- 레이어를 만들 때 호환 런타임을 추가하지 않았다면 이 목록에 레이어가 나타나지 않습니다. 이 경우 레이어 ARN을 대신 지정할 수 있습니다.
Add를 선택합니다.

샘플 앱

Lambda 레이어 사용 예제를 더 보려면 AWS Lambda Developer Guide GitHub 저장소의 layer-nodejs 샘플 애플리케이션을 참고하세요. 이 애플리케이션에는 lodash 라이브러리를 담은 레이어가 포함됩니다. 레이어를 만든 뒤 해당 함수를 배포·호출해 레이어가 예상대로 작동하는지 확인할 수 있습니다.

Node.js Lambda 함수용 레이어 작업