Node.js Lambda 함수를 .zip 파일 아카이브로 배포하기

Node.js Lambda 함수를 .zip 파일 아카이브로 배포하기 (Deploy Node.js Lambda functions with .zip file archives)

AWS Lambda 함수의 코드는 핸들러 코드가 담긴 .js 또는 .mjs 파일과, 코드가 의존하는 추가 패키지·모듈로 구성돼요. 이 함수 코드를 Lambda에 배포하려면 *배포 패키지(deployment package)*를 사용해요. 배포 패키지는 .zip 파일 아카이브이거나 컨테이너 이미지일 수 있어요. Node.js에서 컨테이너 이미지를 쓰는 방법은 Node.js Lambda 함수를 컨테이너 이미지로 배포하기를 참고하세요.

배포 패키지를 .zip 파일 아카이브로 만들려면 명령줄 도구 내장 .zip 유틸리티나 7zip 같은 다른 .zip 유틸리티를 사용하면 돼요. 아래 섹션의 예시는 Linux나 MacOS 환경에서 명령줄 zip 도구를 쓴다고 가정해요. Windows에서 같은 명령을 쓰려면 Windows Subsystem for Linux를 설치해서 Windows와 통합된 Ubuntu와 Bash를 이용할 수 있어요.

Lambda는 POSIX 파일 권한을 사용하므로, .zip 파일 아카이브를 만들기 전에 배포 패키지 폴더에 권한을 설정해야 할 수도 있어요.

Topics

Node.js 런타임의 의존성

의존성 없는 .zip 배포 패키지 만들기

의존성이 있는 .zip 배포 패키지 만들기

의존성용 Node.js 레이어 만들기

의존성 검색 경로와 런타임 포함 라이브러리

.zip 파일로 Node.js Lambda 함수 만들기·업데이트하기

출처: AWS Lambda 개발자 안내서

본문

Node.js 런타임의 의존성

Node.js 런타임을 쓰는 Lambda 함수에서 의존성(dependency)은 어떤 Node.js 모듈이든 될 수 있어요. Node.js 런타임에는 많은 공통 라이브러리와 함께 JavaScript용 AWS SDK 버전이 포함돼 있어요. 지원되는 모든 Node.js 런타임에는 SDK 3버전이 포함돼 있죠. SDK 2버전을 쓰려면 SDK를 .zip 파일 배포 패키지에 추가해야 해요. 쓰고 있는 런타임에 포함된 SDK의 정확한 버전을 확인하려면 런타임 포함 SDK 버전을 참고하세요.

Lambda는 Node.js 런타임의 SDK 라이브러리를 정기적으로 업데이트해서 최신 기능과 보안 업그레이드를 포함해요. 런타임에 포함된 다른 라이브러리에도 보안 패치와 업데이트를 적용하죠. 패키지의 의존성을 완전히 제어하고 싶다면 런타임 포함 의존성 중 원하는 버전을 배포 패키지에 추가하면 돼요. 예를 들어 JavaScript용 SDK의 특정 버전을 쓰고 싶다면 .zip 파일에 의존성으로 포함할 수 있어요. 런타임 포함 의존성을 .zip 파일에 추가하는 방법은 '의존성 검색 경로와 런타임 포함 라이브러리'를 참고하세요.

AWS 공동 책임 모델(shared responsibility model)에 따라 함수 배포 패키지의 모든 의존성 관리는 여러분 책임이에요. 여기에는 업데이트와 보안 패치 적용도 포함돼요. 함수 배포 패키지의 의존성을 업데이트하려면 먼저 새 .zip 파일을 만들고 Lambda에 업로드하면 돼요. 자세한 내용은 '의존성이 있는 .zip 배포 패키지 만들기'와 '.zip 파일로 Node.js Lambda 함수 만들기·업데이트하기'를 참고하세요.

의존성 없는 .zip 배포 패키지 만들기

함수 코드에 Lambda 런타임에 포함된 라이브러리 외의 의존성이 없다면, .zip 파일에는 핸들러 코드가 담긴 index.js나 index.mjs 파일 하나만 들어가요. 원하는 zip 유틸리티로 index.js 또는 index.mjs 파일이 루트에 오도록 .zip 파일을 만들면 돼요. 핸들러 코드가 담긴 파일이 .zip 파일의 루트에 있지 않으면 Lambda가 코드를 실행할 수 없어요.

.zip 파일을 배포해서 새 Lambda 함수를 만들거나 기존 함수를 업데이트하는 방법은 '.zip 파일로 Node.js Lambda 함수 만들기·업데이트하기'를 참고하세요.

의존성이 있는 .zip 배포 패키지 만들기

함수 코드가 Lambda Node.js 런타임에 포함되지 않은 패키지나 모듈에 의존한다면, 이 의존성들을 함수 코드와 함께 .zip 파일에 추가하거나 Lambda 레이어(layer)를 사용하면 돼요. 이 섹션의 지침은 의존성들을 .zip 배포 패키지에 포함하는 방법을 보여줘요. 레이어에 의존성을 포함하는 방법은 '의존성용 Node.js 레이어 만들기'를 참고하세요.

아래 예시 CLI 명령은 핸들러 코드가 담긴 index.js 또는 index.mjs 파일과 의존성들을 포함하는 my_deployment_package.zip 파일을 만들어요. 예시에서는 npm 패키지 매니저로 의존성을 설치해요.

배포 패키지를 만들려면

index.js 또는 index.mjs 소스 코드 파일이 있는 프로젝트 디렉터리로 이동해요. 이 예시에서 디렉터리 이름은 my_function이에요.

cd my_function

npm install 명령으로 함수에 필요한 라이브러리를 node_modules 디렉터리에 설치해요. 이 예시에서는 Node.js용 AWS X-Ray SDK를 설치해요.

npm install aws-xray-sdk

그러면 다음과 비슷한 폴더 구조가 만들어져요.

~/my_function
├── index.mjs
└── node_modules
    ├── async
    ├── async-listener
    ├── atomic-batcher
    ├── aws-sdk
    ├── aws-xray-sdk
    ├── aws-xray-sdk-core

직접 만든 커스텀 모듈도 배포 패키지에 추가할 수 있어요. node_modules 아래에 모듈 이름으로 디렉터리를 만들고 커스텀 패키지를 저장하면 돼요.

프로젝트 폴더의 내용물을 루트에 포함하는 .zip 파일을 만들어요. 하위 폴더까지 압축되도록 r(recursive) 옵션을 사용해요.

zip -r my_deployment_package.zip .

의존성용 Node.js 레이어 만들기

이 섹션의 지침은 의존성들을 레이어에 포함하는 방법을 보여줘요. 배포 패키지에 의존성을 포함하는 방법은 '의존성이 있는 .zip 배포 패키지 만들기'를 참고하고, Node.js 레이어를 만들고 관리하는 자세한 방법은 Node.js Lambda 함수용 레이어 작업하기를 참고하세요.

함수에 레이어를 추가하면 Lambda가 레이어 내용물을 해당 실행 환경의 /opt 디렉터리에 로드해요. 각 Lambda 런타임에서 PATH 변수에는 /opt 디렉터리 안의 특정 폴더 경로가 이미 포함돼 있어요. Lambda가 레이어 내용물을 찾도록 하려면 레이어 .zip 파일의 의존성이 다음 폴더 경로 중 하나에 있어야 해요.

nodejs/node_modules
nodejs/node18/node_modules (NODE_PATH)
nodejs/node20/node_modules (NODE_PATH)
nodejs/node22/node_modules (NODE_PATH)

예를 들어 레이어 .zip 파일 구조는 다음과 같을 수 있어요.

xray-sdk.zip
└ nodejs/node_modules/aws-xray-sdk

또한 Lambda는 /opt/lib 디렉터리의 라이브러리와 /opt/bin 디렉터리의 바이너리를 자동으로 감지해요. Lambda가 레이어 내용물을 제대로 찾도록 다음 구조의 레이어를 만들 수도 있어요.

custom-layer.zip
└ lib
    | lib_1
    | lib_2
└ bin
    | bin_1
    | bin_2

레이어를 패키징한 다음에는 Lambda에서 레이어 만들기·삭제하기와 함수에 레이어 추가하기를 참고해 레이어 설정을 마무리하세요.

의존성 검색 경로와 런타임 포함 라이브러리

Node.js 런타임에는 많은 공통 라이브러리와 JavaScript용 AWS SDK 버전이 포함돼 있어요. 런타임 포함 라이브러리의 다른 버전을 쓰고 싶다면, 그 버전을 함수와 함께 번들(bundle)하거나 배포 패키지에 의존성으로 추가하면 돼요. 예를 들어 SDK의 다른 버전을 .zip 배포 패키지에 추가해서 쓸 수 있죠. 함수용 Lambda 레이어에도 포함할 수 있어요.

코드에서 import나 require 문을 쓰면 Node.js 런타임이 NODE_PATH의 디렉터리를 모듈을 찾을 때까지 검색해요. 기본적으로 런타임이 가장 먼저 검색하는 위치는 .zip 배포 패키지가 압축 해제되어 마운트되는 디렉터리(/var/task)예요. 배포 패키지에 런타임 포함 라이브러리의 버전을 포함했다면, 그 버전이 런타임에 포함된 버전보다 우선해요. 배포 패키지의 의존성은 레이어의 의존성보다도 우선해요.

의존성을 레이어에 추가하면 Lambda가 이를 /opt/nodejs/nodexx/node_modules로 추출하는데, 여기서 nodexx는 사용 중인 런타임 버전을 나타내요. 검색 경로에서 이 디렉터리는 런타임 포함 라이브러리가 들어 있는 디렉터리(/var/lang/lib/node_modules)보다 우선해요. 그래서 함수 레이어의 라이브러리가 런타임에 포함된 버전보다 우선하게 돼요.

다음 코드 한 줄을 추가하면 Lambda 함수의 전체 검색 경로를 볼 수 있어요.

console.log(process.env.NODE_PATH)

.zip 패키지 안의 별도 폴더에 의존성을 추가할 수도 있어요. 예를 들어 .zip 패키지에 common이라는 폴더에 커스텀 모듈을 넣을 수 있죠. .zip 패키지가 압축 해제되고 마운트되면 이 폴더는 /var/task 디렉터리 안에 놓여요. 코드에서 .zip 배포 패키지의 폴더에 있는 의존성을 쓰려면 CJS인지 ESM 모듈 해석인지에 따라 import { } from 또는 const { } = require() 문을 사용해요. 예를 들면 다음과 같아요.

import { myModule } from './common'

esbuild나 rollup 등으로 코드를 번들하면 함수가 쓰는 의존성이 하나 이상의 파일에 함께 묶여요. 가능하면 이 방법으로 의존성을 제공(vend)하는 걸 권장해요. 배포 패키지에 의존성을 추가하는 것과 비교해, 코드를 번들하면 I/O 연산이 줄어들어 성능이 좋아져요.

.zip 파일로 Node.js Lambda 함수 만들기·업데이트하기

.zip 배포 패키지를 만들었다면 그걸로 새 Lambda 함수를 만들거나 기존 함수를 업데이트할 수 있어요. .zip 패키지는 Lambda 콘솔, AWS Command Line Interface(CLI), Lambda API로 배포할 수 있어요. AWS Serverless Application Model(AWS SAM)과 CloudFormation으로도 Lambda 함수를 만들고 업데이트할 수 있어요.

Lambda의 .zip 배포 패키지 최대 크기는 250MB(압축 해제 기준)예요. 이 제한은 업로드하는 모든 파일의 합산 크기에 적용되며, Lambda 레이어도 포함해요.

Lambda 런타임은 배포 패키지의 파일을 읽을 권한이 필요해요. Linux 권한 8진수 표기에서 Lambda는 비실행 파일에 644(rw-r--r--), 디렉터리와 실행 파일에 755(rwxr-xr-x) 권한이 필요해요.

Linux와 MacOS에서는 chmod 명령으로 배포 패키지의 파일·디렉터리 권한을 바꿔요. 예를 들어 비실행 파일에 올바른 권한을 주려면 다음 명령을 실행해요.

chmod 644 <filepath>

Windows에서 파일 권한을 바꾸려면 Microsoft Windows 설명서의 Set, View, Change, or Remove Permissions on an Object를 참고하세요.

참고 배포 패키지의 디렉터리에 Lambda가 접근하는 데 필요한 권한을 주지 않으면, Lambda는 해당 디렉터리 권한을 755(rwxr-xr-x)로 설정해요.

콘솔로 .zip 파일로 함수 만들기·업데이트하기

새 함수를 만들려면 먼저 콘솔에서 함수를 만든 다음 .zip 아카이브를 업로드해야 해요. 기존 함수를 업데이트하려면 함수 페이지를 연 다음 같은 절차로 업데이트된 .zip 파일을 추가하면 돼요.

.zip 파일이 50MB 미만이면 로컬 머신에서 직접 파일을 업로드해 함수를 만들거나 업데이트할 수 있어요. 50MB보다 큰 .zip 파일은 먼저 패키지를 Amazon S3 버킷에 업로드해야 해요. AWS Management Console로 파일을 Amazon S3 버킷에 업로드하는 방법은 Amazon S3 시작하기를 참고하고, AWS CLI로 업로드하는 방법은 AWS CLI 사용자 안내서의 Move objects를 참고하세요.

참고 기존 함수의 배포 패키지 유형(.zip 또는 컨테이너 이미지)은 바꿀 수 없어요. 예를 들어 컨테이너 이미지 함수를 .zip 파일 아카이브로 변환할 수 없어요. 새 함수를 만들어야 해요.

새 함수를 만들려면 (콘솔)

Lambda 콘솔의 Functions 페이지를 열고 Create Function을 선택해요.
Author from scratch를 선택해요.
Basic information에서 다음을 수행해요. Function name에 함수 이름을 입력하고, Runtime에서 사용할 런타임을 선택해요. (선택 사항) Architecture에서 함수의 명령어 집합 아키텍처를 선택해요. 기본 아키텍처는 x86_64예요. 함수의 .zip 배포 패키지가 선택한 명령어 집합 아키텍처와 호환되는지 확인하세요.
(선택 사항) Permissions에서 Change default execution role을 펼쳐 새 Execution role을 만들거나 기존 역할을 사용할 수 있어요.
Create function을 선택해요. Lambda가 선택한 런타임으로 기본 'Hello world' 함수를 만들어요.

로컬 머신에서 .zip 아카이브 업로드하기 (콘솔)

Lambda 콘솔의 Functions 페이지에서 .zip 파일을 업로드할 함수를 선택해요.
Code 탭을 선택해요.
Code source 창에서 Upload from을 선택해요.
.zip file을 선택해요.
.zip 파일을 업로드하려면 다음을 수행해요. Upload를 선택하고 파일 선택기에서 .zip 파일을 고른 다음, Open, Save를 선택해요.

Amazon S3 버킷에서 .zip 아카이브 업로드하기 (콘솔)

Lambda 콘솔의 Functions 페이지에서 새 .zip 파일을 업로드할 함수를 선택해요.
Code 탭을 선택해요.
Code source 창에서 Upload from을 선택해요.
Amazon S3 location을 선택해요.
.zip 파일의 Amazon S3 링크 URL을 붙여넣고 Save를 선택해요.

콘솔 코드 편집기로 .zip 파일 함수 업데이트하기

.zip 배포 패키지를 쓰는 일부 함수에서는 Lambda 콘솔의 내장 코드 편집기로 함수 코드를 직접 업데이트할 수 있어요. 이 기능을 쓰려면 함수가 다음 조건을 충족해야 해요.

해석형 언어 런타임(Python, Node.js, Ruby) 중 하나를 사용할 것
함수의 배포 패키지가 50MB(압축 해제 기준) 미만일 것

컨테이너 이미지 배포 패키지를 쓰는 함수의 코드는 콘솔에서 직접 편집할 수 없어요.

콘솔 코드 편집기로 함수 코드 업데이트하기

Lambda 콘솔의 Functions 페이지를 열고 함수를 선택해요.
Code 탭을 선택해요.
Code source 창에서 소스 코드 파일을 선택하고 통합 코드 편집기에서 편집해요.
DEPLOY 섹션에서 Deploy를 선택해 함수 코드를 업데이트해요.

AWS CLI로 .zip 파일로 함수 만들기·업데이트하기

AWS CLI로 .zip 파일을 사용해 새 함수를 만들거나 기존 함수를 업데이트할 수 있어요. create-function과 update-function-code 명령으로 .zip 패키지를 배포해요. .zip 파일이 50MB 미만이면 로컬 빌드 머신의 파일 위치에서 .zip 패키지를 업로드할 수 있어요. 더 큰 파일은 Amazon S3 버킷에서 .zip 패키지를 업로드해야 해요. AWS CLI로 파일을 Amazon S3 버킷에 업로드하는 방법은 AWS CLI User Guide의 Move objects를 참고하세요.

참고 AWS CLI로 Amazon S3 버킷에서 .zip 파일을 업로드할 때는 버킷이 함수와 같은 AWS 리전에 있어야 해요.

AWS CLI로 .zip 파일로 새 함수를 만들려면 다음을 지정해야 해요.

함수 이름(--function-name)
함수의 런타임(--runtime)
함수 실행 역할(execution role)의 Amazon Resource Name(ARN)(--role)
함수 코드의 핸들러 메서드 이름(--handler)

또한 .zip 파일의 위치를 지정해야 해요. .zip 파일이 로컬 빌드 머신의 폴더에 있다면 --zip-file 옵션으로 파일 경로를 지정해요.

aws lambda create-function --function-name myFunction \
--runtime nodejs24.x --handler index.handler \
--role arn:aws:iam::111122223333:role/service-role/my-lambda-role \
--zip-file fileb://myFunction.zip

Amazon S3 버킷의 .zip 파일 위치를 지정하려면 다음 예시 명령처럼 --code 옵션을 사용해요. 버전 관리되는 객체에서만 S3ObjectVersion 파라미터를 쓰면 돼요.

aws lambda create-function --function-name myFunction \
--runtime nodejs24.x --handler index.handler \
--role arn:aws:iam::111122223333:role/service-role/my-lambda-role \
--code S3Bucket=amzn-s3-demo-bucket,S3Key=myFileName.zip,S3ObjectVersion=myObjectVersion

CLI로 기존 함수를 업데이트하려면 --function-name 파라미터로 함수 이름을 지정해요. 함수 코드 업데이트에 쓸 .zip 파일의 위치도 지정해야 해요. .zip 파일이 로컬 빌드 머신의 폴더에 있다면 --zip-file 옵션으로 파일 경로를 지정해요.

aws lambda update-function-code --function-name myFunction \
--zip-file fileb://myFunction.zip

Amazon S3 버킷의 .zip 파일 위치를 지정하려면 다음 예시 명령처럼 --s3-bucket과 --s3-key 옵션을 사용해요. 버전 관리되는 객체에서만 --s3-object-version 파라미터를 쓰면 돼요.

aws lambda update-function-code --function-name myFunction \
--s3-bucket amzn-s3-demo-bucket --s3-key myFileName.zip --s3-object-version myObjectVersion

Lambda API로 .zip 파일로 함수 만들기·업데이트하기

.zip 파일 아카이브로 함수를 만들고 업데이트하려면 다음 API 연산을 사용해요.

AWS SAM으로 .zip 파일로 함수 만들기·업데이트하기

AWS Serverless Application Model(AWS SAM)은 AWS에서 서버리스 애플리케이션을 만들고 실행하는 과정을 간소화하는 툴킷이에요. 애플리케이션의 리소스를 YAML이나 JSON 템플릿으로 정의하고, AWS SAM CLI로 애플리케이션을 빌드·패키징·배포해요. AWS SAM 템플릿에서 Lambda 함수를 빌드하면 AWS SAM이 함수 코드와 지정한 의존성을 포함한 .zip 배포 패키지나 컨테이너 이미지를 자동으로 만들어요. AWS SAM으로 Lambda 함수를 빌드하고 배포하는 방법은 AWS Serverless Application Model Developer Guide의 Getting started with AWS SAM을 참고하세요.

AWS SAM으로 기존 .zip 파일 아카이브를 사용해 Lambda 함수를 만들 수도 있어요. AWS SAM으로 Lambda 함수를 만들려면 .zip 파일을 Amazon S3 버킷이나 빌드 머신의 로컬 폴더에 저장하면 돼요. AWS CLI로 파일을 Amazon S3 버킷에 업로드하는 방법은 AWS CLI User Guide의 Move objects를 참고하세요.

AWS SAM 템플릿에서 AWS::Serverless::Function 리소스가 Lambda 함수를 나타내요. 이 리소스에서 다음 속성을 설정해 .zip 파일 아카이브로 함수를 만들어요.

PackageType — Zip으로 설정
CodeUri — 함수 코드의 Amazon S3 URI, 로컬 폴더 경로, 또는 FunctionCode 객체로 설정
Runtime — 선택한 런타임으로 설정

AWS SAM에서는 .zip 파일이 50MB보다 커도 먼저 Amazon S3 버킷에 업로드할 필요가 없어요. AWS SAM은 로컬 빌드 머신의 위치에서 최대 허용 크기인 250MB(압축 해제 기준)까지 .zip 패키지를 업로드할 수 있어요.

AWS SAM에서 .zip 파일로 함수를 배포하는 방법은 AWS SAM Developer Guide의 AWS::Serverless::Function을 참고하세요.

CloudFormation으로 .zip 파일로 함수 만들기·업데이트하기

CloudFormation으로 .zip 파일 아카이브를 사용해 Lambda 함수를 만들 수 있어요. .zip 파일로 Lambda 함수를 만들려면 먼저 파일을 Amazon S3 버킷에 업로드해야 해요. AWS CLI로 파일을 Amazon S3 버킷에 업로드하는 방법은 AWS CLI User Guide의 Move objects를 참고하세요.

CloudFormation 템플릿에서 AWS::Lambda::Function 리소스가 Lambda 함수를 나타내요. 이 리소스에서 다음 속성을 설정해 .zip 파일 아카이브로 함수를 만들어요.

PackageType — Zip으로 설정
Code — S3Bucket과 S3Key 필드에 Amazon S3 버킷 이름과 .zip 파일 이름을 입력
Runtime — 선택한 런타임으로 설정

CloudFormation이 생성하는 .zip 파일은 4MB를 넘을 수 없어요. CloudFormation에서 .zip 파일로 함수를 배포하는 자세한 방법은 CloudFormation User Guide의 AWS::Lambda::Function을 참고하세요.

Node.js Lambda 함수를 .zip 파일 아카이브로 배포하기