Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Verwenden von virtuellen Python-Umgebungen mit AWS Glue

Ab AWS Glue 5.0 können Sie Ihre ETL-Jobs in einer virtuellen Python-Umgebung (venv) ausführen. Virtuelle Umgebungen entfernen die Auflösung von Laufzeitabhängigkeiten aus Ihren Jobausführungen, stellen sicher, dass bei jeder Ausführung dieselben Pakete verwendet werden, und verhindern Fehler, die durch Upstream-Paketänderungen verursacht werden.

AWS Glue unterstützt zwei Möglichkeiten, eine virtuelle Umgebung zu verwenden:

In diesem Thema wird beschrieben, wie Jobs migriert werden, --additional-python-modules die beide Methoden verwenden. Hinweise zu anderen Methoden zur Verwaltung von Python-Abhängigkeiten finden Sie unterVerwenden von Python-Bibliotheken mit AWS Glue.

Hauptunterschiede zu --additional-python-modules

Die folgende Tabelle wird --additional-python-modules mit einer manuell erstellten virtuellen Umgebung verglichen.

Auswahl des Ansatzes

Entscheiden Sie anhand der folgenden Tabelle, welcher Ansatz für Ihre Aufgabe geeignet ist.

Verwendung einer vom Service generierten virtuellen Umgebung mit Amazon S3-Caching

Ab AWS Glue 6.0 können Sie den --python-virtual-env-storage-prefix Parameter verwenden, damit AWS Glue die virtuelle Umgebung erstellt und in Amazon S3 zwischenspeichert. Dieser Ansatz kombiniert die Einfachheit einer zwischengespeicherten virtuellen Umgebung --additional-python-modules mit dem Leistungsvorteil.

Funktionsweise

Wenn Sie etwas angeben--python-virtual-env-storage-prefix, geht AWS Glue wie folgt vor:

Unterschiede zu einer manuell erstellten virtuellen Umgebung

In der folgenden Tabelle wird die vom Dienst generierte virtuelle Umgebung mit dem manuell erstellten Ansatz verglichen.

Konfiguration einer dienstgenerierten virtuellen Umgebung

Der --python-virtual-env-storage-prefix Parameter gibt den Amazon S3-Speicherort an, an dem AWS Glue die virtuelle Umgebung, die es erstellt, im Formular s3://path/ speichert. AWS Glue speichert die virtuelle Umgebung bei der ersten Auftragsausführung unter diesem Präfix im Cache und verwendet sie bei späteren Ausführungen wieder.

Um eine vom Dienst generierte virtuelle Umgebung zu aktivieren, fügen Sie den --python-virtual-env-storage-prefix Parameter zu Ihrem Job hinzu und behalten Sie Ihren vorhandenen Parameter bei. --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/"

Sie können auch die folgenden optionalen Parameter verwenden:

Um das Caching für einen vorhandenen Job zu aktivieren, fügen Sie den Parameter für das Speicherpräfix hinzu. Die erste Ausführung dauert länger, da AWS Glue die virtuelle Umgebung erstellt und hochlädt. Spätere Läufe verwenden jedoch die zwischengespeicherte virtuelle Umgebung und führen keine Pip-Auflösung durch.

# 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/"

Wie AWS Glue speichert die virtuelle Umgebung im Cache

AWS Glue speichert den Cache entsprechend Ihrer Jobkonfiguration. Die Konfiguration beinhaltet die Module von--additional-python-modules, den Wert von--python-modules-installer-option, die AWS Glue-Version und den Wert von--python-virtual-env-version.

Eine unveränderte Konfiguration führt zu einem Cache-Treffer. Wenn Sie einen dieser Werte ändern, erstellt AWS Glue eine neue virtuelle Umgebung und erstellt einen neuen Cache-Eintrag.

AWS Glue speichert jede zwischengespeicherte virtuelle Umgebung unter einem separaten Schlüssel in Ihrem Speicherpräfix. Jobs, die dieselben Module und Installationsoptionen verwenden, verwenden denselben Cache-Eintrag.

Einschränkungen

Erstellen Sie Ihre eigene virtuelle Umgebung

In AWS Glue 5.0 und höher können Sie selbst eine virtuelle Umgebung erstellen und sie mit dem --python-virtual-env Parameter referenzieren. Verwenden Sie diesen Ansatz, wenn Sie vollständige Reproduzierbarkeit, exakte Versionen von Containerpaketen oder einen Build benötigen, der in einer CI/CD Pipeline ausgeführt wird.

Voraussetzungen

Stellen Sie vor dem Beginn sicher, dass Sie über Folgendes verfügen:

Einzelheiten zur Python-Version und Plattformkompatibilität für jede AWS Glue-Version finden Sie unterAnhang B: AWS Einzelheiten zur Umgebung von Glue.

Schritt 1: Erstellen Sie Ihre Anforderungsdateien

Erstellen Sie zwei Anforderungsdateien, die die Pakete für Ihre virtuelle Umgebung definieren.

Schritt 2: Erstellen Sie eine Dockerfile

Erstellen Sie eineDockerfile, die der Umgebung Ihrer AWS Glue-Zielversion entspricht. Einzelheiten zur Plattform und Python-Version finden Sie unterAnhang B: AWS Einzelheiten zur Umgebung von Glue.

AWS Glue 5.0 und 5.1 verwenden Python 3.11 auf Amazon Linux 2023.

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 verwendet Python 3.13 auf Amazon Linux 2023.

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

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

WORKDIR /build

Schritt 3: Erstellen und starten Sie den Container

Erstellen Sie das Docker Bild. Starten Sie dann einen Container mit Ihren Anforderungsdateien und dem gemounteten Job-Skript.

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

Dieser Befehl mountet Ihre Anforderungsdateien und Ihr AWS Glue-Job-Skriptverzeichnis. Im folgenden Schritt wird das Skriptverzeichnis für die Importanalyse verwendet.

Schritt 4: Erstellen Sie ein temporäres Venv und entdecken Sie die erforderlichen Pakete

Erstellen Sie innerhalb des Containers ein temporäres Venv, das die AWS Glue-Laufzeit widerspiegelt. Verwenden Sie dann die statische Analyse, um die Mindestmenge an Paketen zu finden, die Ihr Job benötigt.

Führen AWS Sie für Glue 5.0 und 5.1, die Python 3.11 verwenden, die folgenden Befehle aus.

# 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

Führen AWS Sie für Glue 6.0, das Python 3.13 verwendet, die folgenden Befehle aus.

# 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

Schritt 5: Erstellen Sie das Produktions-Venv

Erstellen Sie das endgültige Venv nur mit den Paketen, die Ihr Job benötigt. Dann verpacke es als Tarball.

Führen AWS Sie für Glue 5.0 und 5.1, die Python 3.11 verwenden, die folgenden Befehle aus.

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

Führen AWS Sie für Glue 6.0, das Python 3.13 verwendet, die folgenden Befehle aus.

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

Schritt 6: Auf Amazon S3 hochladen

Laden Sie die gepackte virtuelle Umgebung in Ihren Amazon S3-Bucket hoch.

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

Schritt 7: Jobparameter aktualisieren

Aktualisieren Sie Ihre AWS Glue-Jobkonfiguration, um sie --python-virtual-env stattdessen zu verwenden--additional-python-modules.

Entfernen Sie den --additional-python-modules Parameter und fügen Sie den --python-virtual-env Parameter hinzu, der auf Ihren hochgeladenen Tarball verweist.

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

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

Automatisierung der Migration mit Kiro

Wenn Sie einen automatisierten Ansatz bevorzugen, können Sie den auf der Kiro Website verfügbaren Befehl verwenden Kiro, um die unter beschriebene Migration Erstellen Sie Ihre eigene virtuelle Umgebung von der Befehlszeile aus auszuführen. KiroAnalysiert mit etwas Kiro Geschick Ihre AWS Glue-Job-Konfiguration, erstellt die virtuelle Umgebung darin Docker und erstellt den gepackten Tarball.

Funktionsweise

Wenn Sie Kiro bitten, Ihren AWS Glue-Job von nach --additional-python-modules zu migrieren--python-virtual-env, geht Kiro wie folgt vor:

Beispielanforderung

Geben Sie Ihre AWS Glue-Version, Ihre zusätzlichen Python-Module und Ihr Job-Skript an. Beispiel:

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.

Den Kiro-Skill erwerben

Die venv-migration Skill-Datei wird im aws-glue-libs Repository und nicht in diesem Handbuch verwaltet. Die Skill-Datei und Installationsanweisungen finden Sie unter venv-migration skill auf der GitHub Website.

Einschränkungen

Fehlerbehebung

Verwenden Sie die folgenden Abschnitte, um häufig auftretende Probleme bei der Verwendung virtueller Python-Umgebungen mit AWS Glue zu lösen.

Auflösen von Pip-Versionskonflikten

Ein Pip-Versionskonflikt bedeutet, dass zwei Pakete inkompatible Versionen derselben Abhängigkeit benötigen. Gehen Sie wie folgt vor, um den Konflikt zu finden und zu beheben:

Auflösen ModuleNotFoundError

Dieser Fehler weist darauf hin, dass Ihre virtuelle Umgebung kein erforderliches Paket enthält. Zu den häufigsten Ursachen gehören die folgenden:

Um dieses Problem zu beheben, fügen Sie das fehlende Paket hinzu und erstellen Sie die virtuelle Umgebung neu. Die Schritte hängen davon ab, welchen Ansatz Ihr Job verwendet.

Reduzierung der Venv-Tarballgröße

Wenn Ihre virtuelle Paketumgebung zu groß ist, reduzieren Sie ihre Größe mit den folgenden Ansätzen:

Behebung von Plattformkompatibilitätsfehlern

Diese Fehler treten auf, wenn Pakete im Venv für ein anderes Betriebssystem oder eine andere Architektur erstellt wurden. Um diese Fehler zu vermeiden: