AWS Glue에서 Python 가상 환경 사용

AWS Glue 5.0부터 Python 가상 환경(venv)에서 ETL 작업을 실행할 수 있습니다. 가상 환경은 작업 실행에서 런타임 종속성 확인을 제거하고, 매 실행마다 동일한 패키지를 사용하도록 보장하고, 업스트림 패키지 변경으로 인한 장애를 방지합니다.

AWS Glue는 가상 환경을 사용하는 두 가지 방법을 지원합니다.

이 주제에서는 --additional-python-modules를 사용하는 작업을 두 접근 방식 중 하나로 마이그레이션하는 방법을 설명합니다. Python 종속성을 관리하는 다른 방법에 대한 자세한 내용은 AWS Glue와 함께 Python 라이브러리 사용 섹션를 참조하세요.

--additional-python-modules와의 주요 차이점

다음 표는 --additional-python-modules와 수동 빌드 가상 환경을 비교합니다.

접근 방식 선택

다음 표를 사용하여 작업에 적합한 접근 방식을 선택하세요.

Amazon S3 캐싱을 활용한 서비스 생성 가상 환경 사용

AWS Glue 6.0부터 --python-virtual-env-storage-prefix 파라미터를 사용해 AWS Glue가 가상 환경을 빌드하고 Amazon S3에 캐싱하도록 할 수 있습니다. 이 접근 방식은 --additional-python-modules의 단순성과 캐싱된 가상 환경의 성능 이점을 결합합니다.

작동 방식

--python-virtual-env-storage-prefix를 지정하면 AWS Glue는 다음을 수행합니다.

수동 빌드 가상 환경과의 차이점

다음 표에서는 서비스 생성 가상 환경을 수동 빌드 접근 방식과 비교합니다.

서비스 생성 가상 환경 구성

--python-virtual-env-storage-prefix 파라미터는 AWS Glue가 빌드하는 가상 환경을 저장하는 Amazon S3 위치를 s3://path/ 형식으로 지정합니다. AWS Glue는 첫 작업 실행 시 이 접두사에 가상 환경을 캐싱하고 이후 실행에서 재사용합니다.

서비스 생성 가상 환경을 활성화하려면 작업에 --python-virtual-env-storage-prefix 파라미터를 추가하고 기존 --additional-python-modules 파라미터를 유지합니다.

"--additional-python-modules": "requests==2.32.3,scikit-learn==1.5.0"
"--python-virtual-env-storage-prefix": "s3://amzn-s3-demo-bucket/venv-cache/"

다음과 같은 선택적 파라미터도 사용할 수 있습니다.

기존 작업에서 캐싱을 활성화하려면 스토리지 접두사 파라미터를 추가합니다. AWS Glue가 가상 환경을 빌드하고 업로드하기 때문에 첫 번째 실행은 더 오래 걸리지만, 이후 실행에서는 캐시된 가상 환경을 사용하고 pip 확인을 수행하지 않습니다.

# Before
"--additional-python-modules": "requests==2.32.3"

# After
"--additional-python-modules": "requests==2.32.3"
"--python-virtual-env-storage-prefix": "s3://amzn-s3-demo-bucket/venv-cache/"

AWS Glue가 가상 환경을 캐싱하는 방식

AWS Glue는 작업 구성을 기준으로 캐시에 키를 지정합니다. 해당 구성에는 --additional-python-modules의 모듈, --python-modules-installer-option의 값, AWS Glue 버전 및 --python-virtual-env-version의 값이 포함됩니다.

구성이 변경되지 않으면 캐시 적중이 발생합니다. 이 값 중 하나라도 변경하면 AWS Glue는 새 가상 환경을 빌드하고 새 캐시 항목을 생성합니다.

AWS Glue는 캐시된 각 가상 환경을 스토리지 접두사의 별도 키 아래에 저장합니다. 동일한 모듈과 설치 관리자 옵션을 사용하는 작업은 동일한 캐시 항목을 공유합니다.

제한 사항

자체 가상 환경 빌드

AWS Glue 5.0 이상에서는 가상 환경을 직접 빌드하고 --python-virtual-env 파라미터로 참조할 수 있습니다. 전체 재현성, 컨테이너 패키지의 정확한 버전 또는 CI/CD 파이프라인에서 실행되는 빌드가 필요한 경우 이 접근 방식을 사용하세요.

사전 조건

시작하기 전에 다음 사항을 갖췄는지 확인하세요.

각 AWS Glue 버전에 대한 Python 버전 및 플랫폼 호환성 세부 정보는 부록 B: AWS Glue 환경 세부 정보를 참조하세요.

1단계: 요구 사항 파일 생성

가상 환경에 대한 패키지를 정의하는 두 개의 요구 사항 파일을 생성합니다.

2단계: Dockerfile 생성

대상 AWS Glue 버전의 환경과 일치하는 Dockerfile을 생성합니다. 플랫폼 및 Python 버전에 대한 자세한 내용은 부록 B: AWS Glue 환경 세부 정보 섹션을 참조하세요.

AWS Glue 5.0 및 5.1은 Amazon Linux 2023에서 Python 3.11을 사용합니다.

FROM --platform=linux/amd64 public.ecr.aws/amazonlinux/amazonlinux:2023-minimal

RUN dnf install -y python3.11 zip && \
    dnf clean all

WORKDIR /build

AWS Glue 6.0은 Amazon Linux 2023에서 Python 3.13을 사용합니다.

FROM --platform=linux/amd64 public.ecr.aws/amazonlinux/amazonlinux:2023-minimal

RUN dnf install -y python3.13 zip && \
    dnf clean all

WORKDIR /build

3단계: 컨테이너 빌드 및 시작

Docker 이미지를 빌드합니다. 그런 다음 요구 사항 파일과 작업 스크립트가 마운트된 상태로 컨테이너를 시작합니다.

docker build --platform linux/amd64 -t glue-venv-builder .

docker run --platform linux/amd64 \
  -v $(pwd)/base-requirements.txt:/working_dir/base-requirements.txt:ro \
  -v $(pwd)/additional-requirements.txt:/working_dir/additional-requirements.txt:ro \
  -v $(pwd)/my_glue_script/:/working_dir/my_glue_script/:ro \
  -v $(pwd):/output \
  -w /working_dir \
  -it glue-venv-builder bash

이 명령은 요구 사항 파일과 AWS Glue 작업 스크립트 디렉터리를 마운트합니다. 다음 단계에서는 이 스크립트 디렉터리를 가져오기 분석에 사용합니다.

4단계: 임시 venv 빌드 및 필수 패키지 검색

컨테이너 내부에서 AWS Glue 런타임을 미러링하는 임시 venv를 빌드합니다. 그런 다음 정적 분석을 사용하여 작업에 필요한 최소 패키지 세트를 찾습니다.

Python 3.11을 사용하는 AWS Glue 5.0 및 5.1의 경우 다음 명령을 실행합니다.

# Create a temporary venv to reproduce the AWS Glue runtime environment
python3.11 -m venv temp_venv
source temp_venv/bin/activate

python3.11 -m pip install --upgrade pip

# Install base container libraries (mirrors what the AWS Glue container provides)
python3.11 -m pip install -r base-requirements.txt

# Install additional Python modules on top (mirrors how AWS Glue installs them at runtime)
python3.11 -m pip install -r additional-requirements.txt

# Freeze the full resolved environment
pip freeze > full-requirements.txt

# Install analysis tools
python3.11 -m pip install pipreqs pip-tools

# Use pipreqs to discover what the script actually imports
# --mode no-pin outputs package names without versions
pipreqs --mode no-pin --savepath discovered-requirements.txt /working_dir/my_glue_script

# Remove packages provided by the Spark runtime
sed -i '/pyspark/d' discovered-requirements.txt
sed -i '/py4j/d' discovered-requirements.txt

# Remove awsglue - install AWSGlueDataplanePython in Step 5 instead
sed -i '/awsglue/d' discovered-requirements.txt

# Use pip-compile to resolve the full dependency tree of the discovered packages,
# constrained to the versions from the temporary venv
pip-compile discovered-requirements.txt -c full-requirements.txt -o final-requirements.txt

echo "=== Final requirements.txt ==="
cat final-requirements.txt

# Deactivate and discard the temporary venv
deactivate
rm -rf temp_venv

Python 3.13을 사용하는 AWS Glue 6.0의 경우 다음 명령을 실행합니다.

# Create a temporary venv to reproduce the AWS Glue runtime environment
python3.13 -m venv temp_venv
source temp_venv/bin/activate

python3.13 -m pip install --upgrade pip

# Install base container libraries (mirrors what the AWS Glue container provides)
python3.13 -m pip install -r base-requirements.txt

# Install additional Python modules on top (mirrors how AWS Glue installs them at runtime)
python3.13 -m pip install -r additional-requirements.txt

# Freeze the full resolved environment
pip freeze > full-requirements.txt

# Install analysis tools
python3.13 -m pip install pipreqs pip-tools

# Use pipreqs to discover what the script actually imports
# --mode no-pin outputs package names without versions
pipreqs --mode no-pin --savepath discovered-requirements.txt /working_dir/my_glue_script

# Remove packages provided by the Spark runtime
sed -i '/pyspark/d' discovered-requirements.txt
sed -i '/py4j/d' discovered-requirements.txt

# Remove awsglue - install AWSGlueDataplanePython in Step 5 instead
sed -i '/awsglue/d' discovered-requirements.txt

# Use pip-compile to resolve the full dependency tree of the discovered packages,
# constrained to the versions from the temporary venv
pip-compile discovered-requirements.txt -c full-requirements.txt -o final-requirements.txt

echo "=== Final requirements.txt ==="
cat final-requirements.txt

# Deactivate and discard the temporary venv
deactivate
rm -rf temp_venv

5단계: 프로덕션 venv 빌드

작업에 필요한 패키지만 사용하여 최종 venv를 생성합니다. 그런 다음 tarball로 패키징합니다.

Python 3.11을 사용하는 AWS Glue 5.0 및 5.1의 경우 다음 명령을 실행합니다.

python3.11 -m venv pyspark_venv
source pyspark_venv/bin/activate

python3.11 -m pip install --upgrade pip
python3.11 -m pip install -r final-requirements.txt

# Install the AWS Glue Python library that matches your AWS Glue version (see the version
# table in Step 1). Use 5.0.0 for AWS Glue 5.0, or 5.1.0 for AWS Glue 5.1.
python3.11 -m pip install AWSGlueDataplanePython==5.0.0

python3.11 -m pip install venv-pack
venv-pack -f -o pyspark_venv.tar.gz

cp pyspark_venv.tar.gz /output/
exit

Python 3.13을 사용하는 AWS Glue 6.0의 경우 다음 명령을 실행합니다.

python3.13 -m venv pyspark_venv
source pyspark_venv/bin/activate

python3.13 -m pip install --upgrade pip
python3.13 -m pip install -r final-requirements.txt

# Install the AWS Glue Python library (see version table in Step 1)
python3.13 -m pip install AWSGlueDataplanePython==6.0.0

python3.13 -m pip install venv-pack
venv-pack -f -o pyspark_venv.tar.gz

cp pyspark_venv.tar.gz /output/
exit

6단계: Amazon S3에 업로드

패키징된 가상 환경을 Amazon S3 버킷에 업로드합니다.

aws s3 cp pyspark_venv.tar.gz s3://amzn-s3-demo-bucket/path/pyspark_venv.tar.gz

7단계: 작업 파라미터 업데이트

--additional-python-modules 대신 --python-virtual-env를 사용하도록 AWS Glue 작업 구성을 업데이트합니다.

--additional-python-modules 파라미터를 제거하고 업로드된 tarball을 가리키는 --python-virtual-env 파라미터를 추가합니다.

# Before
"--additional-python-modules": "cryptography"

# After (remove --additional-python-modules entirely)
"--python-virtual-env": "s3://amzn-s3-demo-bucket/path/pyspark_venv.tar.gz"

Kiro를 사용하여 마이그레이션 자동화

자동화된 접근 방식을 선호하는 경우 Kiro 웹 사이트에서 사용할 수 있는 Kiro를 사용하여 명령줄에서 자체 가상 환경 빌드에 설명된 마이그레이션을 실행할 수 있습니다. Kiro 스킬을 사용하여 Kiro는 AWS Glue 작업 구성을 분석하고, Docker에서 가상 환경을 빌드하고, 패키징된 tarball을 생성합니다.

작동 방식

Kiro에 AWS Glue 작업을 --additional-python-modules에서 --python-virtual-env로 마이그레이션하도록 요청하면 Kiro는 다음을 수행합니다.

요청 예

AWS Glue 버전, 추가 Python 모듈 및 작업 스크립트를 제공합니다. 예제:

I have a Glue 5.1 job with the following:
--additional-python-modules: ephem, awscli

Glue job script:
import awscli
import ephem

Help me migrate to using --python-virtual-env.

Kiro 스킬 가져오기

venv-migration 스킬 파일은 이 가이드가 아니라 aws-glue-libs 리포지토리에 관리됩니다. 스킬 파일과 설치 지침은 GitHub 웹 사이트의 venv-migration 스킬을 참조하세요.

제한 사항

문제 해결

다음 섹션을 참고해 AWS Glue에서 Python 가상 환경을 사용할 때 발생하는 일반적인 문제를 해결하세요.

pip 버전 충돌 해결

pip 버전 충돌은 두 패키지가 동일한 종속성에 대해 서로 호환되지 않는 버전을 요구하는 상황을 의미합니다. 충돌을 찾아 해결하려면 다음을 수행하세요.

ModuleNotFoundError 해결

이 오류는 가상 환경에 필요한 패키지가 포함되어 있지 않음을 나타냅니다. 일반적인 원인은 다음과 같습니다.

이 문제를 해결하려면 누락된 패키지를 추가하고 가상 환경을 다시 빌드하세요. 단계는 작업에서 사용하는 접근 방식에 따라 달라집니다.

venv tarball 크기 축소

패키징된 가상 환경이 너무 큰 경우 다음 접근 방식을 사용하여 크기를 줄입니다.

플랫폼 호환성 오류 해결

이러한 오류는 venv의 패키지가 다른 운영 체제 또는 아키텍처용으로 빌드되었을 때 발생합니다. 해당 오류를 방지하려면 다음을 참고하세요.