View a markdown version of this page

Utilizzo di ambienti virtuali Python con AWS Aderenza - AWS Aderenza
Principali differenze rispetto a --additional python-modulesScelta di un approccioUtilizzo di un ambiente virtuale generato dai servizi con caching di Amazon S3Creazione del proprio ambiente virtualeAutomatizzare la migrazione con KiroRisoluzione dei problemi

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Utilizzo di ambienti virtuali Python con AWS Aderenza

A partire da AWS Glue 5.0, puoi eseguire i tuoi lavori ETL in un ambiente virtuale Python (venv). Gli ambienti virtuali rimuovono la risoluzione delle dipendenze di runtime dalle esecuzioni dei processi, assicurano che ogni esecuzione utilizzi gli stessi pacchetti e prevengono gli errori causati dalle modifiche ai pacchetti a monte.

AWS Glue supporta due modi per utilizzare un ambiente virtuale:

  • Service-generated ambiente virtuale: disponibile in AWS Glue 6.0 e versioni successive. Aggiungi il --python-virtual-env-storage-prefix parametro e AWS Glue crea l'ambiente virtuale per te e lo memorizza nella cache in Amazon S3 per le successive esecuzioni dei lavori. Non è richiesta alcuna compilazione locale.

  • Ambiente virtuale creato manualmente: disponibile in AWS Glue 5.0 e versioni successive. Crei l'ambiente virtuale sul tuo computer locale o in una CI/CD pipeline, lo carichi su Amazon S3 e lo fai riferimento con il --python-virtual-env parametro.

Questo argomento descrive come migrare i lavori che utilizzano entrambi --additional-python-modules gli approcci. Per informazioni su altri metodi di gestione delle dipendenze Python, vedere. Usare le librerie Python con AWS Aderenza

Principali differenze rispetto a --additional python-modules

La tabella seguente viene confrontata con un ambiente virtuale creato manualmente--additional-python-modules.

Funzionalità

--additional-python-modules

--python-virtual-env

Librerie di contenitori di base (boto3numpy,pandas, e altre)

Disponibile automaticamente

Non disponibile. È necessario includere tutti i pacchetti richiesti nel venv.

Risoluzione delle dipendenze

Si verifica in fase di esecuzione

Si verifica in fase di compilazione sul computer

Isolamento del runtime

Parziale I pacchetti vengono installati sopra le librerie di base.

Completo. Sostituisce completamente l'ambiente Python.
Importante

Quando esegui la migrazione a--python-virtual-env, devi includere tutti i pacchetti Python necessari al tuo lavoro nell'ambiente virtuale. Ciò include i pacchetti precedentemente disponibili nel contenitore base di AWS Glue, come boto3numpy, e. pandas Questi pacchetti non sono più implicitamente disponibili.

Scelta di un approccio

Utilizzate la tabella seguente per decidere quale approccio è adatto al vostro lavoro.

Scenario

Approccio consigliato

Lavori semplici con pochi pacchetti pip, in cui non si desidera alcun sovraccarico di compilazione

Service-generated venv (aggiungi). --python-virtual-env-storage-prefix Richiede AWS Glue 6.0 o successivo.

Alberi di dipendenza complessi, riproducibilità completa o una CI/CD pipeline che costruisca il venv

Venv () costruito manualmente. --python-virtual-env Richiede AWS Glue 5.0 o successivo.

Migrazione da --additional-python-modules con modifiche minime

Service-generated venv (aggiungi--python-virtual-env-storage-prefix). Richiede AWS Glue 6.0 o successivo. Su AWS Glue 5.0 e 5.1, utilizza invece un ambiente virtuale creato manualmente.

PyPIIndice privato con pacchetti personalizzati

Entrambi gli approcci. Il venv generato dal servizio richiede AWS Glue 6.0 o successivo e funziona con. --python-modules-installer-option

Utilizzo di un ambiente virtuale generato dai servizi con caching di Amazon S3

A partire da AWS Glue 6.0, puoi utilizzare il --python-virtual-env-storage-prefix parametro per fare in modo che AWS Glue crei l'ambiente virtuale e lo memorizzi nella cache in Amazon S3. Questo approccio combina la semplicità --additional-python-modules con i vantaggi prestazionali di un ambiente virtuale memorizzato nella cache.

Come funziona

Quando fornisci--python-virtual-env-storage-prefix, AWS Glue esegue le seguenti operazioni:

  • Alla prima esecuzione (cache miss): AWS Glue crea un ambiente virtuale con--system-site-packages, che eredita pacchetti contenitore come numpypandas, epyarrow. AWS Glue installa quindi i pacchetti da --additional-python-modules with pip, impacchetta l'ambiente virtuale come .tar.gz file e lo carica nel prefisso Amazon S3 per un successivo riutilizzo.

  • Nelle esecuzioni successive (cache hit): AWS Glue scarica il .tar.gz file memorizzato nella cache da Amazon S3, lo estrae e configura il driver e gli esecutori Spark per utilizzare l'ambiente virtuale. Non si verifica alcuna installazione di pip.

Differenze rispetto a un ambiente virtuale creato manualmente

La tabella seguente confronta l'ambiente virtuale generato dal servizio con l'approccio creato manualmente.

Funzionalità

Service-generated venv

Venv costruito manualmente

Costruisci responsabilità

AWS Glue costruisce automaticamente il venv

Tu costruisci il venv Docker

Pacchetti container

Ereditato tramite --system-site-packages

È necessario includere tutti i pacchetti in modo esplicito

First-run latenza

Tempo aggiuntivo per l'installazione di pip, il confezionamento e il caricamento di Amazon S3

Nessuno, perché venv è precompilato

Later-run latenza

Tempo aggiuntivo per il download e l'estrazione di Amazon S3

Tempo aggiuntivo per il download e l'estrazione di Amazon S3

Determinismo

Ti consigliamo di bloccare le versioni dei pacchetti

Completamente deterministico, perché le versioni sono bloccate in fase di compilazione

Accesso a PyPI

Richiesto alla prima esecuzione

Non richiesto, perché venv è costruito offline

Configurazione di un ambiente virtuale generato dal servizio

Il --python-virtual-env-storage-prefix parametro specifica la posizione di Amazon S3 in cui AWS Glue archivia l'ambiente virtuale che crea, nel modulo. s3://path/ AWS Glue memorizza nella cache l'ambiente virtuale con questo prefisso alla prima esecuzione del processo e lo riutilizza nelle esecuzioni successive.

Per abilitare un ambiente virtuale generato dai servizi, aggiungete il --python-virtual-env-storage-prefix parametro al job e mantenete il parametro esistente. --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/"

Puoi anche utilizzare i seguenti parametri opzionali:

  • --python-virtual-env-version— Un identificatore di versione per l'ambiente virtuale memorizzato nella cache. Modificate questo valore per invalidare la cache e forzare AWS Glue a ricostruire l'ambiente virtuale. Il valore è una stringa, quindi puoi utilizzare qualsiasi schema di versione adatto al tuo flusso di lavoro, ad esempio un numero incrementale, una data o un identificatore di build. Il valore predefinito è 0.

  • --python-modules-installer-option— Passa le opzioni a pip, ad esempio o. --no-deps --index-url

Per abilitare la memorizzazione nella cache per un processo esistente, aggiungete il parametro del prefisso di archiviazione. La prima esecuzione richiede più tempo perché AWS Glue crea e carica l'ambiente virtuale, ma le esecuzioni successive utilizzano l'ambiente virtuale memorizzato nella cache e non eseguono alcuna risoluzione in 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/"

In che modo AWS Glue memorizza nella cache l'ambiente virtuale

AWS Glue memorizza la cache in base alla configurazione del lavoro. La configurazione include i moduli di--additional-python-modules, il valore di--python-modules-installer-option, la versione di AWS Glue e il valore di--python-virtual-env-version.

Una configurazione invariata comporta un errore nella cache. Se modifichi uno di questi valori, AWS Glue crea un nuovo ambiente virtuale e crea una nuova voce della cache.

AWS Glue memorizza ogni ambiente virtuale memorizzato nella cache con una chiave separata nel prefisso di archiviazione. I job che utilizzano gli stessi moduli e le stesse opzioni di installazione condividono la stessa voce della cache.

Limitazioni

  • Richiede AWS Glue 6.0 o successivo.

  • La prima esecuzione richiede l'accesso o all'indice privato per la risoluzione delle dipendenze. PyPI

  • I pacchetti contenitore come numpy e pandas sono ereditati ma non aggiunti alla versione. Se il tuo lavoro richiede versioni esatte dei pacchetti container, usali invece. --python-virtual-env

  • La cache è codificata in base alla configurazione. La modifica di qualsiasi modulo o versione crea una nuova voce della cache e le voci precedenti rimangono in Amazon S3 finché non vengono rimosse.

Creazione del proprio ambiente virtuale

In AWS Glue 5.0 e versioni successive, puoi creare tu stesso un ambiente virtuale e farvi riferimento con il --python-virtual-env parametro. Utilizzate questo approccio quando avete bisogno di una completa riproducibilità, di versioni esatte dei pacchetti container o di una build eseguita in una pipeline. CI/CD

Prerequisiti

Prima di iniziare, assicurati di disporre di:

  • Dockerdal Docker sito Web, installato sul computer locale, in modo da poter creare l'ambiente virtuale in un ambiente AWS Glue-compatible

  • Un bucket Amazon S3 per caricare l'ambiente virtuale compresso

  • La AWS CLI configurata con le autorizzazioni per il caricamento su Amazon S3 e l'aggiornamento dei parametri del lavoro Glue AWS

Per i dettagli sulla compatibilità della versione Python e della piattaforma per ciascuna versione di AWS Glue, consulta. Appendice B: AWS Dettagli sull'ambiente di incollaggio

Passaggio 1: crea i file dei requisiti

Crea due file dei requisiti che definiscono i pacchetti per il tuo ambiente virtuale.

  1. Scaricate base-requirements.txt la versione di AWS Glue in uso dal aws-glue-libs repository sul GitHub sito web. Questo file elenca i pacchetti forniti dal contenitore AWS Glue standard. Per lo stesso elenco in questa guida, consultaModuli Python già forniti in AWS Aderenza.

  2. Creare il additional-requirements.txt. Aggiungi i pacchetti dal tuo --additional-python-modules parametro esistente, uno per riga. Ad esempio:

    cryptography
requests-oauthlib
sqlalchemy
Importante

Se il tuo lavoro utilizza la libreria AWS Glue Python, ad esempio GlueContext orDynamicFrame, devi includere anche il AWSGlueDataplanePython pacchetto dal PyPI sito web. Usa la versione che corrisponde alla tua versione di AWS Glue, come mostrato nella tabella seguente.

AWS Versione Glue

Versione del pacchetto

5.0

AWSGlueDataplanePython==5.0.0

5.1

AWSGlueDataplanePython==5.1.0

6.0

AWSGlueDataplanePython==6.0.0

Fase 2: Creare un Dockerfile

Creane una Dockerfile che corrisponda all'ambiente della tua versione di AWS Glue di destinazione. Per i dettagli sulla piattaforma e sulla versione di Python, consultaAppendice B: AWS Dettagli sull'ambiente di incollaggio.

AWS Glue 5.0 e 5.1 utilizzano Python 3.11 su 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 utilizza Python 3.13 su 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

Fase 3: Costruisci e avvia il contenitore

Costruisci l'Dockerimmagine. Quindi avvia un contenitore con i file dei requisiti e lo script del lavoro montati.

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

Questo comando monta i file dei requisiti e la directory degli script di AWS Glue Job. Il passaggio successivo utilizza la directory degli script per l'analisi delle importazioni.

Fase 4: Crea un venv temporaneo e scopri i pacchetti richiesti

All'interno del contenitore, crea un venv temporaneo che rispecchi il runtime di AWS Glue. Quindi utilizza l'analisi statica per trovare il set minimo di pacchetti di cui hai bisogno per il tuo lavoro.

Per AWS Glue 5.0 e 5.1, che utilizzano Python 3.11, esegui i seguenti comandi.

# 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

Per AWS Glue 6.0, che utilizza Python 3.13, esegui i seguenti comandi.

# 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
Nota

Controlla final-requirements.txt per verificare che sia corretto. Se il tuo lavoro utilizza importazioni dinamiche o importazioni condizionali, pipreqs potresti non rilevarle. Aggiungete questi pacchetti al file manualmente.

Fase 5: Costruisci il venv di produzione

Crea il venv finale con solo i pacchetti di cui il tuo lavoro ha bisogno. Quindi impacchettalo come tarball.

Per AWS Glue 5.0 e 5.1, che utilizzano Python 3.11, esegui i seguenti comandi.

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

Per AWS Glue 6.0, che utilizza Python 3.13, esegui i seguenti comandi.

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

Passaggio 6: caricamento su Amazon S3

Carica l'ambiente virtuale in pacchetti nel tuo bucket Amazon S3.

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

Passaggio 7: aggiornamento dei parametri del lavoro

Aggiorna la configurazione del tuo lavoro AWS Glue per utilizzarlo --python-virtual-env al posto di--additional-python-modules.

Rimuovi il --additional-python-modules parametro e aggiungi il --python-virtual-env parametro che punta al tarball caricato.

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

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

Automatizzare la migrazione con Kiro

Se preferisci un approccio automatizzato, puoi utilizzare Kiro, disponibile sul Kiro sito Web, per eseguire la migrazione descritta in Creazione del proprio ambiente virtuale dalla riga di comando. Con Kiro competenza, Kiro analizza la configurazione del lavoro AWS Glue, crea l'ambiente virtuale e produce il Docker tarball impacchettato.

Come funziona

Quando chiedi a Kiro di migrare il tuo lavoro AWS Glue da --additional-python-modules a--python-virtual-env, Kiro fa quanto segue:

  1. Estrae la versione di AWS Glue, il valore e lo script del --additional-python-modules lavoro dalla richiesta.

  2. Recupera l'elenco dei moduli contenitore di base per la tua versione di AWS Glue dalla documentazione di AWS Glue.

  3. Crea gli artefatti di compilazione in una directory di lavoro base-requirements.txtadditional-requirements.txt, inclusi uno script di compilazione e uno script Dockerfile di compilazione.

  4. Crea l'Dockerimmagine per un ambiente. AWS Glue-compatible

  5. Esegue il flusso di lavoro di individuazione e creazione di pacchetti in un contenitore non interattivo.

  6. Producepyspark_venv.tar.gz, richiede una destinazione Amazon S3 e carica il tarball.

  7. Mostra i parametri del lavoro aggiornati.

Richiesta di esempio

Fornisci la tua versione di AWS Glue, i tuoi moduli Python aggiuntivi e il tuo job script. Ad esempio:

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.

Acquisire l'abilità Kiro

Il file venv-migration delle abilità viene mantenuto nel aws-glue-libs repository anziché in questa guida. Per il file delle abilità e le istruzioni di installazione, vedi venv-migration skill sul sito web. GitHub

Limitazioni

  • Kiro deve Docker essere disponibile nell'ambiente a riga di comando.

  • Le importazioni dinamiche e le importazioni condizionali che non sono visibili nell'origine dello script non vengono rilevate automaticamente. Rivedi il final-requirements.txt file generato e aggiungi manualmente eventuali pacchetti mancanti.

  • Se il tuo lavoro utilizza un indice pip privato con--index-url, devi configurare l'accesso di rete a quell'indice nel Docker contenitore.

  • I conflitti di pip durante la compilazione potrebbero richiedere una risoluzione manuale. Per ulteriori informazioni, consulta Risoluzione dei problemi.

Risoluzione dei problemi

Usa le seguenti sezioni per risolvere i problemi più comuni quando usi ambienti virtuali Python con AWS Glue.

Risoluzione dei conflitti tra le versioni di pip

Un conflitto di versioni pip significa che due pacchetti richiedono versioni incompatibili della stessa dipendenza. Per trovare e risolvere il conflitto, procedi come segue:

  1. Leggete l'output dell'errore pip. Quando la risoluzione fallisce completamente, l'output nomina ogni requisito in conflitto e il pacchetto che lo ha introdotto.

  2. Visualizza un'anteprima di cosa pip risolverebbe senza installare nulla. Aggiungilo --dry-run --report install-report.json al tuo comando di installazione, come nell'esempio seguente.

    pip install -r additional-requirements.txt --dry-run --report install-report.json

  3. install-report.jsonIspeziona. Il rapporto elenca tutti i pacchetti selezionati da pip, il che rivela i downgrade silenziosi.

  4. Riduci i pin della versione sui pacchetti non critici o rimuovi i vincoli.

Risolvere ModuleNotFoundError

Questo errore indica che l'ambiente virtuale non include un pacchetto richiesto. Le cause più comuni sono le seguenti:

  • Non hai incluso una libreria di contenitori di base richiesta dal tuo lavoro. Un ambiente virtuale creato manualmente non eredita i pacchetti dal contenitore AWS Glue.

  • Il tuo lavoro utilizza un'importazione dinamica che non è pipreqs stata rilevata durante l'analisi statica.

  • Il tuo lavoro richiede una PySpark dipendenza dai nodi esecutori.

Per risolvere questo problema, aggiungi il pacchetto mancante e ricostruisci l'ambiente virtuale. I passaggi dipendono dall'approccio utilizzato dal lavoro.

  • Venv creato manualmente: aggiungi il pacchetto afinal-requirements.txt, quindi ricostruisci l'ambiente virtuale e caricalo nuovamente.

  • Service-generated venv — Aggiungi il pacchetto a. --additional-python-modules Il nuovo elenco dei moduli modifica la chiave della cache, quindi AWS Glue crea un nuovo ambiente virtuale alla successiva esecuzione del lavoro.

Ridurre la dimensione del tarball di venv

Se il tuo ambiente virtuale confezionato è troppo grande, riduci le sue dimensioni con i seguenti approcci:

  • Rimuovi i pacchetti non necessari che lo script non importa, come framework di test e strumenti di sviluppo.

  • Usalo pip install --no-deps per i pacchetti in cui desideri controllare manualmente le dipendenze transitive.

  • Includi solo i pacchetti che il tuo script importa direttamente e lascia pip-compile risolvere le dipendenze transitive minime richieste.

Risoluzione degli errori di compatibilità della piattaforma

Questi errori si verificano quando i pacchetti in venv sono stati compilati per un sistema operativo o un'architettura diversi. Per evitare questi errori:

  • Crea sempre l'ambiente virtuale all'interno di un Docker contenitore usando il --platform linux/amd64 flag.

  • Verifica che i tag delle piattaforme delle ruote corrispondano alla versione di AWS Glue di destinazione. Ad esempio, AWS Glue 5.0 e 5.1 richiedono manylinux2014_x86_64 o tag di piattaforma compatibili.

  • Non creare l'ambiente virtuale direttamente su macOS o Windows senzaDocker.