AWS Glue での Python 仮想環境の使用

AWS Glue 5.0 以降では、Python 仮想環境 (venv) で ETL ジョブを実行できます。仮想環境を使用することで、ジョブ実行からランタイム依存関係の解決を切り離し、各実行で同じパッケージが使用されることを保証し、アップストリームパッケージの変更による障害を防止します。

AWS Glue は、仮想環境を使用する 2 つの方法をサポートしています。

このトピックでは、--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 が構築した仮想環境を s3://path/ 形式で保存する Amazon S3 の場所を指定します。AWSGlue は、最初のジョブ実行時にこのプレフィックスで仮想環境をキャッシュし、後の実行時に再利用します。

サービス生成仮想環境を有効にするには、--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 つ作成します。

ステップ 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: ジョブパラメータを更新する

AWS Glue ジョブ設定を更新して、--additional-python-modules の代わりに --python-virtual-env を使用します。

--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 を生成します。

仕組み

AWS Glue ジョブを --additional-python-modules から --python-virtual-env に移行するように Kiro に要求すると、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 skill を参照してください。

制限事項

トラブルシューティング

以下のセクションを使用して、AWS Glue で Python 仮想環境を使用する際の一般的な問題を解決します。

pip バージョンの競合の解決

pip バージョンの競合とは、2 つのパッケージに対して、同一の依存関係の非互換バージョンが必要になることを意味します。競合を見つけて修正するには、以下の手順を実行します。

ModuleNotFoundError の解決

このエラーは、仮想環境に必要なパッケージが含まれていないことを示します。一般的な原因は以下の通りです。

この問題を解決するには、不足しているパッケージを追加して仮想環境を再構築します。手順は、ジョブが使用しているアプローチによって異なります。

venv tarball サイズの縮小

パッケージ化された仮想環境が大きすぎる場合は、次の方法でサイズを縮小します。

プラットフォーム互換性エラーの解決

これらのエラーは、venv のパッケージが別のオペレーティングシステムまたはアーキテクチャ用に構築された場合に発生します。これらのエラーを回避する方法は以下の通りです。