Python Lambda 함수의 .zip 파일 아카이브 다루기
Python Lambda 함수의 .zip 파일 아카이브 다루기 (Working with .zip file archives for Python Lambda functions)
AWS Lambda 함수의 코드는 함수의 핸들러 코드가 담긴 .py 파일과, 코드가 의존하는 추가 패키지·모듈로 구성돼요. 이 함수 코드를 Lambda에 배포하려면 배포 패키지(deployment package)를 사용해요. 이 패키지는 .zip 파일 아카이브 또는 컨테이너 이미지일 수 있어요.
배포 패키지를 .zip 파일 아카이브로 만들려면 명령줄 도구의 내장 .zip 파일 아카이브 유틸리티나 7zip 같은 다른 .zip 유틸리티를 사용할 수 있어요. 다음 섹션의 예시는 Linux나 macOS 환경의 명령줄 zip 도구를 사용한다고 가정해요. Windows에서 같은 명령을 사용하려면 Windows Subsystem for Linux를 설치해 Windows 통합 버전의 Ubuntu와 Bash를 얻을 수 있어요.
Lambda는 POSIX 파일 권한을 사용하므로 .zip 파일 아카이브를 만들기 전에 배포 패키지 폴더의 권한을 설정해야 할 수 있어요.
본문
Python 런타임 의존성
Python 런타임을 사용하는 Lambda 함수의 의존성은 모든 Python 패키지·모듈일 수 있어요. .zip 아카이브로 함수를 배포할 때 함수 코드와 함께 이 의존성을 .zip 파일에 추가하거나 Lambda 레이어를 사용할 수 있어요. 레이어는 추가 코드와 기타 콘텐츠를 담을 수 있는 별도의 .zip 파일이에요.
Lambda Python 런타임에는 AWS SDK for Python(Boto3)과 그 의존성이 포함돼 있어요. Lambda는 자체 의존성을 추가할 수 없는 배포 시나리오를 위해 런타임에 SDK를 제공해요. 이런 시나리오에는 콘솔의 내장 코드 편집기로 함수를 만들거나, AWS Serverless Application Model(AWS SAM)·CloudFormation 템플릿에서 인라인 함수를 사용하는 경우가 포함돼요.
Lambda는 최신 업데이트와 보안 패치를 포함하도록 Python 런타임의 라이브러리를 주기적으로 업데이트해요. 함수가 런타임에 포함된 Boto3 SDK 버전을 사용하지만 배포 패키지가 SDK 의존성을 포함한다면 버전 불일치 문제가 생길 수 있어요. 예를 들어 배포 패키지가 SDK 의존성 urllib3를 포함할 수 있어요. Lambda가 런타임의 SDK를 업데이트하면 런타임의 새 버전과 배포 패키지의 urllib3 버전 사이의 호환성 문제로 함수가 실패할 수 있어요.
중요
의존성을 완전히 제어하고 가능한 버전 불일치 문제를 피하려면 런타임에 포함된 버전이 있어도 함수의 모든 의존성(반드시 Boto3 SDK 포함)을 배포 패키지에 추가할 것을 권장해요.
AWS 공동 책임 모델 아래에서 함수 배포 패키지의 모든 의존성 관리는 사용자 책임이에요. 업데이트와 보안 패치 적용이 포함돼요.
의존성이 없는 .zip 배포 패키지 만들기
함수 코드에 의존성이 없다면 .zip 파일에는 함수 핸들러 코드가 담긴 .py 파일만 들어 있어요. .py 파일을 루트에 두고 선호하는 zip 유틸리티로 .zip 파일을 만들어요. .py 파일이 .zip 파일의 루트에 없으면 Lambda가 코드를 실행할 수 없어요.
의존성이 있는 .zip 배포 패키지 만들기
함수 코드가 추가 패키지·모듈에 의존한다면 이 의존성을 함수 코드와 함께 .zip 파일에 추가하거나 Lambda 레이어를 사용할 수 있어요. Lambda가 코드를 실행하려면 핸들러 코드가 담긴 .py 파일과 함수의 모든 의존성이 .zip 파일의 루트에 설치되어야 해요.
함수 코드가 lambda_function.py 파일에 저장되어 있다고 가정해요. 다음 예시 CLI 명령은 함수 코드와 그 의존성을 담은 my_deployment_package.zip 파일을 만들어요. 의존성을 프로젝트 디렉토리의 폴더에 직접 설치하거나 Python 가상 환경을 사용할 수 있어요.
배포 패키지 만들기(프로젝트 디렉토리)
- lambda_function.py 소스 코드 파일이 있는 프로젝트 디렉토리로 이동합니다. 예시에서 디렉토리 이름은 my_function입니다.
cd my_function - 의존성을 설치할
package라는 새 디렉토리를 만듭니다.
.zip 배포 패키지의 경우 Lambda는 소스 코드와 그 의존성이 모두 .zip 파일의 루트에 있기를 기대합니다. 그러나 프로젝트 디렉토리에 직접 의존성을 설치하면 많은 새 파일·폴더가 생겨 IDE 탐색이 어려울 수 있습니다. 여기서는 의존성을 소스 코드와 분리하기 위해 별도 package 디렉토리를 만듭니다.mkdir package - package 디렉토리에 의존성을 설치합니다. 예시는 pip를 사용해 Python Package Index에서 Boto3 SDK를 설치합니다. 직접 만든 Python 패키지를 사용한다면 package 디렉토리에 저장하세요.
pip install --target ./package boto3 - 설치된 라이브러리를 루트로 하는 .zip 파일을 만듭니다.
그러면 프로젝트 디렉토리에 my_deployment_package.zip 파일이 생성됩니다.cd package zip -r ../my_deployment_package.zip . - lambda_function.py 파일을 .zip 파일의 루트에 추가합니다.
.zip 파일은 함수의 핸들러 코드와 모든 의존성 폴더가 루트에 설치된 평평한 디렉토리 구조를 가져야 합니다.cd .. zip my_deployment_package.zip lambda_function.py
함수 핸들러 코드가 담긴 .py 파일이 .zip 파일의 루트에 없으면 Lambda가 코드를 실행할 수 없습니다.my_deployment_package.zip |- bin | |-jp.py |- boto3 | |-compat.py | |-data | |-docs ... |- lambda_function.py
배포 패키지 만들기(가상 환경)
- 프로젝트 디렉토리에 가상 환경을 만들고 활성화합니다. 예시에서 프로젝트 디렉토리 이름은 my_function입니다.
~$ cd my_function ~/my_function$ python3.14 -m venv my_virtual_env ~/my_function$ source ./my_virtual_env/bin/activate - pip로 필요한 라이브러리를 설치합니다. 다음 예시는 Boto3 SDK를 설치합니다.
(my_virtual_env) ~/my_function$ pip install boto3 - pip show로 가상 환경에서 pip가 의존성을 설치한 위치를 찾습니다.
pip가 라이브러리를 설치하는 폴더 이름은 site-packages 또는 dist-packages일 수 있습니다. 이 폴더는 lib/python3.x 또는 lib64/python3.x 디렉토리에 있을 수 있습니다. pip는 의존성을 my_virtual_env/lib/python3.14/site-packages에 설치합니다.(my_virtual_env) ~/my_function$ pip show <package_name> - 가상 환경을 비활성화합니다.
(my_virtual_env) ~/my_function$ deactivate - pip로 설치한 의존성이 있는 디렉토리로 이동해 프로젝트 디렉토리에 설치된 의존성을 루트로 하는 .zip 파일을 만듭니다.
~/my_function$ cd my_virtual_env/lib/python3.14/site-packages ~/my_function/my_virtual_env/lib/python3.14/site-packages$ zip -r ../../../../my_deployment_package.zip . - 핸들러 코드가 담긴 .py 파일이 있는 프로젝트 디렉토리의 루트로 이동해 그 파일을 .zip 패키지의 루트에 추가합니다. 예시에서 함수 코드 파일은 lambda_function.py입니다.
~/my_function/my_virtual_env/lib/python3.14/site-packages$ cd ../../../../../ ~/my_function$ zip my_deployment_package.zip lambda_function.py
의존성 검색 경로와 런타임 포함 라이브러리
코드에서 import 문을 사용하면 Python 런타임이 검색 경로의 디렉토리를 모듈이나 패키지를 찾을 때까지 검색해요. 기본적으로 런타임이 가장 먼저 검색하는 위치는 .zip 배포 패키지가 압축 해제·마운트되는 디렉토리(/var/task)예요. 배포 패키지에 런타임 포함 라이브러리 버전을 포함하면 내 버전이 런타임에 포함된 버전보다 우선해요. 배포 패키지의 의존성은 레이어의 의존성보다도 우선해요.
레이어에 의존성을 추가하면 Lambda가 이를 /opt/python/lib/python3.x/site-packages 또는 /opt/python에 추출해요. 검색 경로에서 이 디렉토리는 런타임 포함 라이브러리와 pip 설치 라이브러리가 있는 디렉토리(/var/runtime, /var/lang/lib/python3.x/site-packages)보다 우선해요. 따라서 함수 레이어의 라이브러리는 런타임에 포함된 버전보다 우선해요.
참고
Python 3.11 관리 런타임과 베이스 이미지에서 AWS SDK와 그 의존성은 /var/lang/lib/python3.11/site-packages 디렉토리에 설치돼요.
다음 코드 스니펫을 추가해 Lambda 함수의 전체 검색 경로를 볼 수 있어요.
import sys
search_path = sys.path
print(search_path)
참고
배포 패키지나 레이어의 의존성이 런타임 포함 라이브러리보다 우선하므로, SDK 없이 urllib3 같은 SDK 의존성만 패키지에 포함하면 버전 불일치 문제가 생길 수 있어요. Boto3 의존성의 자체 버전을 배포한다면 Boto3도 배포 패키지의 의존성으로 함께 배포해야 해요. 런타임에 포함된 버전이 있어도 함수의 모든 의존성을 패키징할 것을 권장해요.
.zip 패키지 안의 별도 폴더에 의존성을 추가할 수도 있어요. 예를 들어 .zip 패키지의 common이라는 폴더에 Boto3 SDK 버전을 추가할 수 있어요. .zip 패키지가 압축 해제·마운트되면 이 폴더는 /var/task 디렉토리 안에 배치돼요. .zip 배포 패키지의 폴더에서 의존성을 코드에서 사용하려면 import from 문을 사용해요. 예를 들어 .zip 패키지의 common 폴더에서 Boto3 버전을 사용하려면 다음 문을 사용해요.
from common import boto3
pycache 폴더 사용
함수의 배포 패키지에 __pycache__ 폴더를 포함하지 않는 것을 권장해요. 다른 아키텍처나 운영 체제의 빌드 머신에서 컴파일된 Python 바이트코드는 Lambda 실행 환경과 호환되지 않을 수 있어요.
네이티브 라이브러리가 있는 .zip 배포 패키지 만들기
함수가 순수 Python 패키지·모듈만 사용한다면 pip install 명령으로 로컬 빌드 머신 어디에서든 의존성을 설치하고 .zip 파일을 만들 수 있어요. NumPy와 Pandas를 포함한 많은 인기 Python 라이브러리는 순수 Python이 아니고 C나 C++로 작성된 코드가 있어요. C/C++ 코드가 있는 라이브러리를 배포 패키지에 추가할 때는 Lambda 실행 환경과 호환되도록 패키지를 올바르게 빌드해야 해요.
Python Package Index(PyPI)의 대부분 패키지는 "wheel"(.whl 파일)로 제공돼요. .whl 파일은 특정 운영 체제와 명령어 세트 아키텍처용 사전 컴파일 이진 파일이 포함된 내장 배포판을 담는 ZIP 파일 유형이에요. 배포 패키지를 Lambda와 호환되게 만들려면 Linux 운영 체제와 함수의 명령어 세트 아키텍처용 wheel을 설치해요.
일부 패키지는 소스 배포판으로만 제공될 수 있어요. 이런 패키지는 C/C++ 구성 요소를 직접 컴파일·빌드해야 해요.
내장 배포판(wheel) 다루기
Lambda와 호환되는 wheel을 다운로드하려면 pip --platform 옵션을 사용해요. 함수가 x86_64 명령어 세트 아키텍처를 사용한다면 다음 pip install 명령을 실행해 호환되는 wheel을 패키지 디렉토리에 설치해요. --python 3.x를 사용하는 Python 런타임 버전으로 바꾸세요.
pip install \
--platform manylinux2014_x86_64 \
--target=package \
--implementation cp \
--python-version 3.x \
--only-binary=:all: --upgrade \
<package_name>
함수가 arm64 명령어 세트 아키텍처를 사용한다면 다음 명령을 실행해요.
pip install \
--platform manylinux2014_aarch64 \
--target=package \
--implementation cp \
--python-version 3.x \
--only-binary=:all: --upgrade \
<package_name>
소스 배포판 다루기
패키지가 소스 배포판으로만 제공된다면 C/C++ 라이브러리를 직접 빌드해야 해요. 패키지를 Lambda 실행 환경과 호환되게 만들려면 같은 Amazon Linux 운영 체제를 사용하는 환경에서 빌드해야 해요. Amazon Elastic Compute Cloud(Amazon EC2) Linux 인스턴스에서 패키지를 빌드해 이렇게 할 수 있어요.
.zip 파일로 Python Lambda 함수 만들기·업데이트하기
.zip 배포 패키지를 만든 후 이를 사용해 새 Lambda 함수를 만들거나 기존 함수를 업데이트할 수 있어요. Lambda 콘솔, AWS Command Line Interface, Lambda API로 .zip 패키지를 배포할 수 있어요. 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>
참고
Lambda에 배포 패키지 디렉토리에 접근하는 데 필요한 권한을 주지 않으면 Lambda가 그 디렉토리의 권한을 755(rwxr-xr-x)로 설정해요.
콘솔에서 .zip 파일로 함수 만들기·업데이트하기
새 함수를 만들려면 먼저 콘솔에서 함수를 만든 다음 .zip 아카이브를 업로드해야 해요. 기존 함수를 업데이트하려면 함수 페이지를 열고 같은 절차로 업데이트된 .zip 파일을 추가해요.
.zip 파일이 50MB보다 작으면 로컬 머신에서 직접 업로드해 함수를 만들거나 업데이트할 수 있어요. 50MB보다 큰 .zip 파일은 먼저 Amazon S3 버킷에 업로드해야 해요.
참고
기존 함수의 배포 패키지 유형(.zip 또는 컨테이너 이미지)은 변경할 수 없어요. 컨테이너 이미지 함수를 .zip 파일 아카이브로 변환할 수 없어요. 새 함수를 만들어야 해요.
새 함수 만들기(콘솔)
- Lambda 콘솔의 Functions 페이지를 열고 Create Function을 선택합니다.
- Author from scratch를 선택합니다.
- Basic information 아래에서 다음을 수행합니다.
- Function name에 함수 이름을 입력합니다.
- Runtime에서 사용할 런타임을 선택합니다.
- (선택 사항) Architecture에서 함수의 명령어 세트 아키텍처를 선택합니다. 기본 아키텍처는 x86_64입니다. 함수의 .zip 배포 패키지가 선택한 명령어 세트 아키텍처와 호환되는지 확인하세요.
- (선택 사항) Permissions 아래에서 Change default 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 버킷에서 .zip 파일을 업로드하면 버킷이 함수와 같은 AWS 리전에 있어야 해요.
AWS CLI로 .zip 파일로 새 함수를 만들려면 다음을 지정해야 해요.
- 함수 이름(
--function-name) - 함수의 런타임(
--runtime) - 함수 실행 역할의 Amazon Resource Name(ARN)(
--role) - 함수 코드의 핸들러 메서드 이름(
--handler)
또한 .zip 파일의 위치를 지정해야 해요. .zip 파일이 로컬 빌드 머신의 폴더에 있다면 --zip-file 옵션으로 파일 경로를 지정해요.
aws lambda create-function --function-name myFunction \
--runtime python3.14 --handler lambda_function.lambda_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 python3.14 --handler lambda_function.lambda_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 파일의 위치도 지정해야 해요.
aws lambda update-function-code --function-name myFunction \
--zip-file fileb://myFunction.zip
Amazon S3 버킷의 .zip 파일 위치를 지정하려면 --s3-bucket과 --s3-key 옵션을 사용해요.
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 작업을 사용해요.
- CreateFunction
- UpdateFunctionCode
AWS SAM으로 .zip 파일로 함수 만들기·업데이트하기
AWS Serverless Application Model(AWS SAM)은 AWS에서 서버리스 애플리케이션을 빌드·실행하는 과정을 간소화하는 툴킷이에요. YAML 또는 JSON 템플릿으로 애플리케이션의 리소스를 정의하고 AWS SAM 명령줄 인터페이스(AWS SAM CLI)로 애플리케이션을 빌드·패키징·배포해요. AWS SAM 템플릿에서 Lambda 함수를 빌드하면 AWS SAM이 함수 코드와 지정한 의존성으로 .zip 배포 패키지나 컨테이너 이미지를 자동으로 만들어요.
AWS SAM으로 기존 .zip 파일 아카이브를 사용해 Lambda 함수를 만들 수도 있어요. .zip 파일을 Amazon S3 버킷이나 빌드 머신의 로컬 폴더에 저장할 수 있어요.
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 패키지를 업로드할 수 있어요.
CloudFormation으로 .zip 파일로 함수 만들기·업데이트하기
CloudFormation으로 .zip 파일 아카이브를 사용해 Lambda 함수를 만들 수 있어요. .zip 파일로 Lambda 함수를 만들려면 먼저 파일을 Amazon S3 버킷에 업로드해야 해요. Node.js와 Python 런타임의 경우 CloudFormation 템플릿에 인라인 소스 코드를 제공할 수도 있어요. 그러면 CloudFormation이 함수를 빌드할 때 코드를 담은 .zip 파일을 만들어요.
기존 .zip 파일 사용 — CloudFormation 템플릿에서 AWS::Lambda::Function 리소스가 Lambda 함수를 지정해요. 이 리소스에서 .zip 파일 아카이브로 함수를 만들려면 다음 속성을 설정해요.
PackageType– Zip으로 설정Code– S3Bucket과 S3Key 필드에 Amazon S3 버킷 이름과 .zip 파일 이름 입력Runtime– 선택한 런타임으로 설정
인라인 코드에서 .zip 파일 만들기 — Python이나 Node.js로 작성된 간단한 함수를 CloudFormation 템플릿에 인라인으로 선언할 수 있어요. 코드가 YAML이나 JSON에 포함되므로 배포 패키지에 외부 의존성을 추가할 수 없어요. 이는 함수가 런타임에 포함된 AWS SDK 버전을 사용해야 한다는 뜻이에요. 특정 문자를 이스케이프해야 하는 것 같은 템플릿 요구 사항은 IDE의 구문 검사와 코드 완성 기능을 사용하기 어렵게 만들어요. 따라서 템플릿에 추가 테스트가 필요할 수 있어요. 이런 제한 때문에 함수를 인라인으로 선언하는 것은 자주 변경되지 않는 매우 간단한 코드에 가장 적합해요.
Node.js와 Python 런타임에서 인라인 코드로 .zip 파일을 만들려면 템플릿의 AWS::Lambda::Function 리소스에서 다음 속성을 설정해요.
PackageType– Zip으로 설정Code– ZipFile 필드에 함수 코드 입력Runtime– 선택한 런타임으로 설정
CloudFormation이 생성하는 .zip 파일은 4MB를 초과할 수 없어요.