.zip 파일 아카이브를 사용하여 Node.js Lambda 함수 배포

AWS Lambda 함수의 코드는 코드가 의존하는 추가 패키지 및 모듈과 함께 함수의 핸들러 코드를 포함하는 .js 또는 .mjs 파일로 구성됩니다. Lambda에 이 함수 코드를 배포하려면 배포 패키지를 사용합니다. 이 패키지는 .zip 파일 아카이브 또는 컨테이너 이미지일 수 있습니다. Node.js에서 컨테이너 이미지를 사용하는 방법에 대한 자세한 내용은 컨테이너 이미지를 사용하여 Node.js Lambda 함수 배포를 참조하세요.

배포 패키지를 .zip 파일 아카이브로 생성하려면 명령줄 도구의 기본 제공 .zip 파일 아카이브 유틸리티 또는 7zip과 같은 기타 .zip 파일 유틸리티를 사용합니다. 다음 섹션에 표시된 예제에서는 Linux 또는 MacOS 환경에서 명령줄 zip 도구를 사용한다고 가정합니다. Windows에서 동일한 명령을 사용하려면 Windows Subsystem for Linux를 설치하여 Ubuntu 및 Bash의 Windows 통합 버전을 가져옵니다.

Lambda는 POSIX 파일 권한을 사용하므로 .zip 파일 아카이브를 생성하기 전에 배포 패키지 폴더에 대한 권한을 설정해야 할 수 있습니다.

Node.js의 런타임 종속 항목

Node.js 런타임을 사용하는 Lambda 함수의 경우 종속 항목은 모든 Node.js 모듈일 수 있습니다. Node.js 런타임에는 여러 공통 라이브러리와 AWS SDK for JavaScript의 버전이 포함되어 있습니다. nodejs16.x Lambda 런타임에는 SDK 버전 2.x가 포함됩니다. 런타임 버전 nodejs18.x 및 그 이상에는 SDK 버전 3이 포함됩니다. 런타임 버전 nodejs18.x 및 그 이상에서 SDK 버전 2를 사용하려면 .zip 파일 배포 패키지에 SDK를 추가하십시오. 선택한 런타임에 사용 중인 SDK 버전이 포함된 경우 .zip 파일에 SDK 라이브러리를 포함할 필요가 없습니다. 사용 중인 런타임에 포함된 SDK 버전을 찾으려면 런타임에 포함된 SDK 버전 섹션을 참조하세요.

Lambda는 최신 기능 및 보안 업그레이드를 포함하도록 Node.js 런타임에서 SDK 라이브러리를 주기적으로 업데이트합니다. Lambda는 런타임에 포함된 다른 라이브러리에도 보안 패치와 업데이트를 적용합니다. 패키지의 종속 항목을 완벽하게 제어하려면 런타임에 포함된 종속 항목의 원하는 버전을 배포 패키지에 추가하면 됩니다. 예를 들어 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 계층을 사용할 수 있습니다. 이 섹션의 지침에서는 .zip 배포 패키지에 종속 항목을 포함하는 방법을 보여줍니다. 계층에 종속 항목을 포함하는 방법에 대한 지침은 종속 항목을 위한 Node.js 계층 생성 섹션을 참조하세요.

다음 예제 CLI 명령은 함수의 핸들러 코드와 해당 종속 항목이 포함된 index.js 또는 index.mjs 파일이 포함된 my_deployment_package.zip이라는 이름의 .zip 파일을 생성합니다. 이 예제에서는 npm 패키지 관리자를 사용하여 종속 항목을 설치합니다.

종속 항목을 위한 Node.js 계층 생성

이 섹션의 지침은 계층에 종속 항목을 포함하는 방법을 보여줍니다. 배포 패키지에 종속 항목을 포함하는 방법에 대한 지침은 종속 항목이 있는 .zip 배포 패키지 생성 섹션을 참조하세요.

함수에 계층을 추가하면 Lambda는 계층 콘텐츠를 해당 실행 환경의 /opt 디렉터리로 추출합니다. 각 Lambda 런타임에 대해 PATH 변수에는 /opt 디렉터리 내의 특정 폴더 경로가 이미 포함되어 있습니다. PATH 변수가 계층 콘텐츠를 가져오도록 하려면 계층 .zip 파일의 종속성이 다음 폴더 경로에 있어야 합니다.

예를 들어, 계층.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 런타임에는 여러 공통 라이브러리와 AWS SDK for JavaScript의 버전이 포함되어 있습니다. 런타임에 포함된 라이브러리의 다른 버전을 사용하려면 함수와 함께 번들링하거나 배포 패키지에 종속 항목으로 추가하면 됩니다. 예를 들어 다른 버전의 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 등으로 번들링하는 경우 함수에서 사용하는 종속 항목이 하나 이상의 파일에 함께 번들링됩니다. 가급적 이 방법을 사용하여 종속 항목을 제공하는 것이 좋습니다. 코드를 번들링하면 배포 패키지에 종속 항목을 추가할 때보다 I/O 작업이 줄어들어 성능이 향상됩니다.

.zip 파일을 사용하여 Node.js Lambda 함수 생성 및 업데이트

.zip 배포 패키지를 생성한 후 이를 사용하여 새 Lambda 함수를 생성하거나 기존 함수를 업데이트할 수 있습니다. Lambda 콘솔, AWS Command Line Interface 및 Lambda API를 사용하여 .zip 패키지를 배포할 수 있습니다. AWS Serverless Application Model(AWS SAM) 및 AWS CloudFormation을 사용하여 Lambda 함수를 생성하고 업데이트할 수도 있습니다.

Lambda용 .zip 배포 패키지의 최대 크기는 250MB(압축 해제됨)입니다. 이 제한은 Lambda 계층을 포함하여 업로드하는 모든 파일의 합산 크기에 적용됩니다.

Lambda 런타임은 배포 패키지의 파일을 읽을 수 있는 권한이 필요합니다. Linux 권한 8진수 표기법에서는 Lambda에 실행 불가능한 파일(rw-r--r--)에 대한 644개의 권한과 디렉터리 및 실행 파일에 대한 755개의 권한(rwxr-xr-x)이 필요합니다.

Linux 및 MacOS에서는 chmod 명령을 사용하여 배포 패키지의 파일 및 디렉터리에 대한 파일 권한을 변경합니다. 예를 들어, 실행 파일에 올바른 권한을 부여하려면 다음 명령을 실행합니다.

chmod 755 <filepath>

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

콘솔을 사용하여.zip 파일로 함수 생성 및 업데이트

새 함수를 생성하려면 먼저 콘솔에서 함수를 생성한 다음.zip 아카이브를 업로드해야 합니다. 기존 함수를 업데이트하려면 함수에 대한 페이지를 연 다음 동일한 절차에 따라 업데이트된 .zip 파일을 추가합니다.

.zip 파일이 50MB 미만인 경우 로컬 컴퓨터에서 직접 파일을 업로드하여 함수를 생성하거나 업데이트할 수 있습니다. 50MB보다 큰 .zip 파일의 경우 먼저 패키지를 Amazon S3 버킷에 업로드해야 합니다. AWS Management Console을 사용하여 Amazon S3 버킷에 파일을 업로드하는 방법에 대한 지침은 Amazon S3 시작하기를 참조하세요. AWS CLI를 사용하여 파일을 업로드하려면 AWS CLI 사용 설명서의 객체 이동을 참조하세요.

콘솔 코드 편집기를 사용하여.zip 파일 함수 업데이트

.zip 배포 패키지를 사용하는 일부 함수의 경우 Lambda 콘솔의 기본 제공 코드 편집기를 사용하여 함수 코드를 직접 업데이트할 수 있습니다. 이 기능을 사용하려면 함수가 다음 조건을 충족해야 합니다.

컨테이너 이미지 배포 패키지가 있는 함수의 함수 코드는 콘솔에서 직접 편집할 수 없습니다.

AWS CLI를 사용하여.zip 파일로 함수 생성 및 업데이트

AWS CLI를 사용하여 새 함수를 생성하거나.zip 파일로 기존 함수를 업데이트할 수 있습니다. create-function 및 update-function-code 명령을 사용하여 .zip 패키지를 배포합니다. .zip 파일이 50MB보다 작은 경우 로컬 빌드 시스템의 파일 위치에서 .zip 패키지를 업로드할 수 있습니다. 더 큰 파일의 경우 Amazon S3 버킷에서 .zip 패키지를 업로드해야 합니다. AWS CLI를 사용하여 Amazon S3 버킷에 파일을 업로드하는 방법에 대한 지침은 AWS CLI 사용 설명서의 객체 이동을 참조하세요.

AWS CLI에서 .zip 파일을 사용하여 새 함수를 생성하려면 다음을 지정해야 합니다.

.zip 파일의 위치도 지정해야 합니다. .zip 파일이 로컬 빌드 시스템의 폴더에 있는 경우 다음 예제 명령과 같이 --zip-file 옵션을 사용하여 파일 경로를 지정합니다.

aws lambda create-function --function-name myFunction \
--runtime nodejs22.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 nodejs22.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 myObject Version

Lambda API를 사용하여.zip 파일로 함수 생성 및 업데이트

.zip 파일 아카이브를 사용하여 함수를 생성하고 업데이트하려면 다음 API 작업을 사용합니다.

AWS SAM을 사용하여.zip 파일로 함수 생성 및 업데이트

AWS Serverless Application Model(AWS SAM)은 AWS에서 서버리스 애플리케이션을 빌드하고 실행하는 프로세스를 간소화하는 데 도움이 되는 도구 키트입니다. YAML 또는 JSON 템플릿에서 애플리케이션의 리소스를 정의하고 AWS SAM Command Line Interface(AWS SAM CLI)를 사용하여 애플리케이션을 빌드, 패키징 및 배포합니다. AWS SAM 템플릿에서 Lambda 함수를 빌드하면 AWS SAM은 함수 코드와 사용자가 지정하는 종속 항목을 사용하여 .zip 배포 패키지 또는 컨테이너 이미지를 자동으로 생성합니다. AWS SAM을 사용하여 Lambda 함수를 빌드하고 배포하는 방법에 대해 자세히 알아보려면 AWS Serverless Application Model 개발자 안내서의 Getting started with AWS SAM을 참조하세요.

AWS SAM을 사용하여 기존 .zip 파일 아카이브로 Lambda 함수를 생성할 수도 있습니다. AWS SAM을 사용하여 Lambda 함수를 생성하려면 Amazon S3 버킷 또는 빌드 시스템의 로컬 폴더에 .zip 파일을 저장할 수 있습니다. AWS CLI를 사용하여 Amazon S3 버킷에 파일을 업로드하는 방법에 대한 지침은 AWS CLI 사용 설명서의 객체 이동을 참조하세요.

AWS SAM 템플릿에서 AWS::Serverless::Function 리소스는 Lambda 함수를 지정합니다. 이 리소스에서 다음 속성을 설정하여 .zip 파일 아카이브로 함수를 생성합니다.

AWS SAM을 사용하면 .zip 파일이 50MB보다 큰 경우 Amazon S3 버킷에 먼저 파일을 업로드할 필요가 없습니다. AWS SAM은 로컬 빌드 시스템의 위치에서 허용되는 최대 크기 250MB(압축 해제)까지 .zip 패키지를 업로드할 수 있습니다.

AWS SAM에서 .zip 파일을 사용하여 함수를 배포하는 방법에 대해 자세히 알아보려면 AWS SAM 개발자 안내서의 AWS::Serverless::Function을 참조하세요.

AWS CloudFormation을 사용하여.zip 파일로 함수 생성 및 업데이트

AWS CloudFormation을 사용하여 .zip 파일 아카이브로 Lambda 함수를 생성할 수 있습니다. .zip 파일에서 Lambda 함수를 생성하려면 먼저 Amazon S3 버킷에 파일을 업로드해야 합니다. AWS CLI를 사용하여 Amazon S3 버킷에 파일을 업로드하는 방법에 대한 지침은 AWS CLI 사용 설명서의 객체 이동을 참조하세요.

AWS CloudFormation 템플릿에서 AWS::Lambda::Function 리소스는 Lambda 함수를 지정합니다. 이 리소스에서 다음 속성을 설정하여 .zip 파일 아카이브로 함수를 생성합니다.

AWS CloudFormation에서 생성하는 .zip 파일은 4MB를 초과할 수 없습니다. AWS CloudFormation에서 .zip 파일을 사용하여 함수를 배포하는 방법에 대해 자세히 알아보려면 AWS CloudFormation 사용 설명서의 AWS::Lambda::Function을 참조하세요.