View a markdown version of this page

Uso de entornos virtuales de Python con AWS Glue - AWS Glue
Diferencias clave con respecto a --additional-python-modulesElección de un enfoqueUso de un entorno virtual generado por el servicio con almacenamiento en caché de Amazon S3Creación de un entorno virtual propioAutomatización de la migración con KiroSolución de problemas

Uso de entornos virtuales de Python con AWS Glue

A partir de AWS Glue 5.0, puede ejecutar sus trabajos de ETL en un entorno virtual de Python (venv). Los entornos virtuales eliminan la resolución de dependencias en tiempo de ejecución de las ejecuciones de los trabajos, garantizan que cada ejecución utilice los mismos paquetes y evitan los errores provocados por cambios en los paquetes ascendentes.

AWS Glue admite dos formas de utilizar un entorno virtual:

  • Entorno virtual generado por el servicio: disponible en AWS Glue 6.0 y versiones posteriores. Agregue el parámetro --python-virtual-env-storage-prefix, y AWS Glue creará el entorno virtual por usted y lo guardará en caché en Amazon S3 para las ejecuciones de trabajos posteriores. No se requiere compilación local.

  • Entorno virtual creado de forma manual: disponible en AWS Glue 5.0 y versiones posteriores. Cree el entorno virtual en su máquina local o en una canalización de CI/CD, cárguelo en Amazon S3 y haga referencia a él con el parámetro --python-virtual-env.

En este tema se explica cómo migrar trabajos que utilizan --additional-python-modules a cualquiera de los dos enfoques. Para obtener información sobre otros métodos de administración de las dependencias de Python, consulte Uso de bibliotecas de Python con AWS Glue.

Diferencias clave con respecto a --additional-python-modules

En la siguiente tabla se compara --additional-python-modules con un entorno virtual creado manualmente.

Característica

--additional-python-modules

--python-virtual-env

Bibliotecas de contenedores base (boto3, numpy, pandas y otras)

Disponible automáticamente

No disponible. Debe incluir todos los paquetes necesarios en el entorno virtual.

Resolución de dependencias

Se produce en el tiempo de ejecución

Se produce en el momento de la compilación en su máquina

Aislamiento de tiempo de ejecución

Parcial. Los paquetes se instalan sobre las bibliotecas base.

Completa. Sustituye por completo el entorno de Python.
importante

Al migrar a --python-virtual-env, debe incluir todos los paquetes de Python que su trabajo necesite en el entorno virtual. Esto incluye los paquetes que anteriormente estaban disponibles en el contenedor base de AWS Glue, como boto3, numpy y pandas. Estos paquetes ya no están disponibles de forma implícita.

Elección de un enfoque

Utilice la siguiente tabla para decidir qué enfoque se adapta a su trabajo.

Escenario

Método recomendado

Trabajos sencillos con pocos paquetes de pip, sin sobrecargas de compilación

Venv generado por el servicio (agregar --python-virtual-env-storage-prefix). Requiere AWS Glue 6.0 o posterior.

Árboles de dependencias complejos, reproducibilidad completa o una canalización de CI/CD que crea el venv

Venv creado manualmente (--python-virtual-env). Requiere AWS Glue 5.0 o posterior.

Migrar desde --additional-python-modules con cambios mínimos

Venv generado por el servicio (agregar --python-virtual-env-storage-prefix). Requiere AWS Glue 6.0 o posterior. En AWS Glue 5.0 y 5.1, utilice mejor un entorno virtual creado manualmente.

Índice PyPI privado con paquetes personalizados

Cualquier enfoque. El venv generado por el servicio requiere AWS Glue 6.0 o posterior y funciona con --python-modules-installer-option.

Uso de un entorno virtual generado por el servicio con almacenamiento en caché de Amazon S3

A partir de AWS Glue 6.0, puede usar el parámetro --python-virtual-env-storage-prefix para que AWS Glue cree el entorno virtual y lo almacene en caché en Amazon S3. Este enfoque combina la simplicidad de --additional-python-modules con las ventajas de rendimiento de un entorno virtual en caché.

Funcionamiento

Cuando usted proporciona --python-virtual-env-storage-prefix, AWS Glue hace lo siguiente:

  • En la primera ejecución (error de caché): AWS Glue crea un entorno virtual con --system-site-packages, que hereda paquetes de contenedor como numpy, pandas y pyarrow. AWS Luego Glue instala los paquetes desde --additional-python-modules con pip, empaqueta el entorno virtual como un archivo .tar.gz y lo carga en el prefijo de Amazon S3 para volver a utilizarlo más adelante.

  • En ejecuciones posteriores (acierto de caché): AWS Glue descarga el archivo .tar.gz en caché de Amazon S3, lo extrae y configura el controlador y los ejecutores de Spark para que usen el entorno virtual. No se realiza ninguna instalación de pip.

Diferencias con un entorno virtual creado manualmente

En la siguiente tabla se compara el entorno virtual generado por el servicio con el enfoque creado manualmente.

Característica

Venv generado por el servicio

Venv creado manualmente

Responsabilidad de la compilación

AWS Glue crea el venv automáticamente

Usted crea el venv en Docker

Paquetes de contenedores

Heredados mediante --system-site-packages

Debe incluir todos los paquetes de forma explícita

Latencia de primera ejecución

Tiempo adicional para instalar pip, empaquetar y cargar en Amazon S3

Ninguna, porque el venv está prediseñado

Latencia de ejecución posterior

Tiempo adicional para descargar y extraer Amazon S3

Tiempo adicional para descargar y extraer Amazon S3

Determinismo

Le recomendamos que fije las versiones del paquete

Totalmente determinista, porque las versiones se bloquean en el momento de la compilación

PyPI, , acceso

Necesario en la primera ejecución

No es necesario, porque el venv está creado sin conexión

Configuración de un entorno virtual generado por un servicio

El parámetro --python-virtual-env-storage-prefix especifica la ubicación de Amazon S3 en la que AWS Glue almacena el entorno virtual que crea, con el formato s3://path/. AWS Glue almacena en caché el entorno virtual con este prefijo en la primera ejecución del trabajo y lo reutiliza en las ejecuciones posteriores.

Para habilitar un entorno virtual generado por un servicio, agregue el parámetro --python-virtual-env-storage-prefix a su trabajo y conserve el parámetro existente --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/"

También puede usar los siguientes parámetros opcionales:

  • --python-virtual-env-version: un identificador de versión para el entorno virtual almacenado en caché. Cambie este valor para invalidar la caché y forzar a AWS Glue a reconstruir el entorno virtual. El valor es una cadena, por lo que puede usar el esquema de control de versiones que mejor se adapte a su flujo de trabajo, como un número incremental, una fecha o un identificador de compilación. El valor predeterminado es 0.

  • --python-modules-installer-option: transfiere opciones a pip, como --no-deps o --index-url.

Para habilitar el almacenamiento en caché de un trabajo existente, agregue el parámetro de prefijo de almacenamiento. La primera ejecución tarda más tiempo porque AWS Glue crea y carga el entorno virtual, pero las ejecuciones posteriores utilizan el entorno virtual en caché y no realizan ninguna resolución de 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/"

Cómo AWS Glue almacena en caché el entorno virtual

AWS Glue selecciona la caché según la configuración de su trabajo. La configuración incluye los módulos de --additional-python-modules, el valor de --python-modules-installer-option, la versión AWS Glue y el valor de --python-virtual-env-version.

Si la configuración no se modifica, se produce un acierto de caché. Si cambia alguno de estos valores, AWS Glue crea un nuevo entorno virtual y una nueva entrada de caché.

AWS Glue almacena cada entorno virtual en caché con una clave independiente en el prefijo de almacenamiento. Los trabajos que utilizan los mismos módulos y opciones de instalación comparten la misma entrada de caché.

Limitaciones

  • Requiere AWS Glue 6.0 o posterior.

  • La primera ejecución requiere acceso a PyPI, o a su índice privado, para resolver las dependencias.

  • Los paquetes contenedores, como numpy y pandas, se heredan, pero no están anclados en sus versiones. Si su trabajo requiere versiones exactas de los paquetes contenedores, utilice --python-virtual-env en su lugar.

  • La caché está codificada según la configuración. Al cambiar cualquier módulo o versión, se crea una nueva entrada de caché y las entradas anteriores permanecen en Amazon S3 hasta que las elimine.

Creación de un entorno virtual propio

En AWS Glue 5.0 y versiones posteriores, puede crear un entorno virtual usted mismo y hacer referencia a él con el parámetro --python-virtual-env. Utilice este enfoque cuando necesite una reproducibilidad completa, versiones exactas de paquetes contenedores o una compilación que se ejecute en una canalización de CI/CD.

Requisitos previos

Antes de comenzar, asegúrese de que dispone de lo siguiente:

  • Docker desde el sitio web de Docker, instalado en su máquina local, para que pueda crear el entorno virtual en un entorno compatible con AWS Glue

  • Un bucket de Amazon S3 para cargar el entorno virtual empaquetado

  • La AWS CLI configurada con permisos para cargar en Amazon S3 y actualizar los parámetros del trabajo de AWS Glue

Para obtener información sobre la compatibilidad de plataformas y versiones de Python para cada versión de AWS Glue, consulte Apéndice B: Detalles del entorno de AWS Glue.

Paso 1: crear archivos de requisitos

Cree dos archivos de requisitos que definan los paquetes para su entorno virtual.

  1. Descargue base-requirements.txt para su versión de AWS Glue desde el repositorio aws-glue-libs del sitio web de GitHub. En este archivo se enumeran los paquetes que proporciona el contenedor AWS Glue estándar. Para ver la misma lista en esta guía, consulte Módulos de Python que ya se proporcionaron en AWS.

  2. Cree additional-requirements.txt. Agregue los paquetes de su parámetro --additional-python-modules existente, uno por línea. Por ejemplo:

    cryptography
requests-oauthlib
sqlalchemy
importante

Si su trabajo utiliza la biblioteca AWS Glue Python, como GlueContext o DynamicFrame, también debe incluir el paquete AWSGlueDataPlanePython del sitio web de PyPI. Utilice la versión que se corresponda con su versión de AWS Glue, como se muestra en la siguiente tabla.

AWSVersión de Glue

Versión de un paquete

5.0

AWSGlueDataplanePython==5.0.0

5.1

AWSGlueDataplanePython==5.1.0

6.0

AWSGlueDataplanePython==6.0.0

Paso 2: crear un destino Dockerfile

Cree un Dockerfile que se corresponda con el entorno de su versión de AWS Glue de destino. Para obtener información sobre la plataforma y la versión de Python, consulte Apéndice B: Detalles del entorno de AWS Glue.

AWS Glue 5.0 y 5.1 utilizan Python 3.11 en 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 utiliza Python 3.13 en 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

Paso 3: crear e iniciar el contenedor

Cree la imagen del Docker. Luego, inicie un contenedor con los archivos de requisitos y el script de trabajo montados.

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

Este comando monta los archivos de requisitos y el directorio de scripts de trabajo de AWS Glue. En el siguiente paso, se utiliza el directorio de scripts para el análisis de importación.

Paso 4: crear un venv temporal y detectar los paquetes necesarios

Dentro del contenedor, cree un venv temporal que refleje el tiempo de ejecución de AWS Glue. Luego, utilice el análisis estático para encontrar el conjunto mínimo de paquetes que necesita su trabajo.

Para AWS Glue 5.0 y 5.1, que utilizan Python 3.11, ejecute los siguientes comandos.

# 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

Para AWS Glue 6.0, que utiliza Python 3.13, ejecute los siguientes comandos.

# 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

Revise final-requirements.txt para comprobar que tiene el aspecto correcto. Si su trabajo utiliza importaciones dinámicas o condicionales, es posible que pipreqs no las detecte. Agregue esos paquetes al archivo manualmente.

Paso 5: crear el venv de producción

Cree el venv final solo con los paquetes que su trabajo necesita. Luego empaquételo como un tarball.

Para AWS Glue 5.0 y 5.1, que utilizan Python 3.11, ejecute los siguientes comandos.

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

Para AWS Glue 6.0, que utiliza Python 3.13, ejecute los siguientes comandos.

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

Paso 6: cárguelo en Amazon S3

Cargue el entorno virtual empaquetado en el bucket de Amazon S3.

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

Paso 7: actualizar los parámetros del trabajo

Actualice la configuración de su trabajo de AWS Glue para utilizar --python-virtual-env en lugar de --additional-python-modules.

Elimine el parámetro --additional-python-modules y agregue el parámetro --python-virtual-env que apunta al tarball cargado.

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

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

Automatización de la migración con Kiro

Si prefiere un enfoque automatizado, puede utilizar Kiro, disponible en el sitio web de Kiro, para ejecutar la migración descrita en Creación de un entorno virtual propio desde la línea de comandos. Con una habilidad de Kiro, Kiro analiza la configuración de su trabajo de AWS Glue, crea el entorno virtual en Docker y produce el tarball empaquetado.

Funcionamiento

Cuando le pide a Kiro que migre su trabajo de AWS Glue de --additional-python-modules a --python-virtual-env, Kiro hace lo siguiente:

  1. Extrae la versión de AWS Glue, el valor de --additional-python-modules y el script de trabajo de su solicitud.

  2. Recupera la lista de módulos del contenedor base para su versión de AWS Glue de la documentación de AWS Glue.

  3. Crea los artefactos de creación en un directorio de trabajo que incluye base-requirements.txt, additional-requirements.txt, un Dockerfile y un script de creación.

  4. Crea la imagen de Docker para un entorno compatible con AWS Glue.

  5. Ejecuta el flujo de trabajo de descubrimiento y empaquetado en un contenedor no interactivo.

  6. Produce pyspark_venv.tar.gz, solicita un destino de Amazon S3 y carga el tarball.

  7. Muestra los parámetros del trabajo actualizados.

Ejemplo de solicitud

Proporcione su versión de AWS Glue, sus módulos de Python adicionales y su script de trabajo. Por ejemplo:

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.

Cómo adquirir la habilidad de Kiro

El archivo de habilidades de venv-migration se conserva en el repositorio aws-glue-libs y no en esta guía. Para ver el archivo de habilidades y las instrucciones de instalación, consulte venv-migration skill en el sitio web de GitHub.

Limitaciones

  • Kiro requiere que Docker esté disponible en el entorno de línea de comandos.

  • Las importaciones dinámicas y condicionales que no están visibles en la fuente del script no se detectan automáticamente. Revise el archivo final-requirements.txt generado y agregue manualmente los paquetes que falten.

  • Si su trabajo utiliza un índice pip privado con --index-url, debe configurar el acceso de red a ese índice en el contenedor de Docker.

  • Es posible que los conflictos de pip durante la compilación requieran una resolución manual. Para obtener más información, consulte Solución de problemas.

Solución de problemas

Use las siguientes secciones para resolver problemas comunes al usar entornos virtuales de Python con AWS Glue.

Resolución de conflictos entre versiones de pip

Un conflicto de versiones de pip significa que dos paquetes requieren versiones incompatibles de la misma dependencia. Para buscar y solucionar el conflicto, haga lo siguiente:

  1. Lea el resultado del error de pip. Cuando la resolución falla por completo, el resultado indica cada requisito en conflicto y el paquete que lo introdujo.

  2. Obtenga una vista previa de lo que pip resolvería sin instalar nada. Agregue --dry-run --report install-report.json a su comando de instalación, como se muestra en el siguiente ejemplo.

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

  3. Inspeccione install-report.json. El informe muestra todos los paquetes que seleccionó pip, lo que revela las reducciones silenciosas.

  4. Flexibilice los límites de versión de los paquetes no críticos o elimine las restricciones.

Resolución de ModuleNotFoundError

Este error indica que su entorno virtual no incluye un paquete obligatorio. Entre las causas comunes se incluyen las siguientes:

  • No incluyó la biblioteca de contenedores base que su trabajo requiere. Un entorno virtual creado manualmente no hereda paquetes del contenedor de AWS Glue.

  • Su trabajo utiliza una importación dinámica que pipreqs no se pudo detectar durante el análisis estático.

  • Su trabajo requiere una dependencia de PySpark de los nodos ejecutores.

Para resolver este problema, agregue el paquete que falta y reconstruya el entorno virtual. Los pasos dependen del enfoque que utilice su trabajo.

  • Venv creado manualmente: agregue el paquete a final-requirements.txt, reconstruya el entorno virtual y vuelva a cargarlo.

  • Venv generado por el servicio: agregue el paquete a --additional-python-modules. La nueva lista de módulos cambia la clave de caché, por lo que AWS Glue crea un nuevo entorno virtual en la siguiente ejecución del trabajo.

Reducción del tamaño del tarball de venv

Si su entorno virtual empaquetado es demasiado grande, reduzca su tamaño con los siguientes enfoques:

  • Elimine los paquetes innecesarios que su script no importe, como los marcos de pruebas y las herramientas de desarrollo.

  • Utilice pip install --no-deps para los paquetes en los que desee controlar las dependencias transitivas de forma manual.

  • Incluya solo los paquetes que su script importe directamente y deje que pip-compile resuelva las dependencias transitivas mínimas requeridas.

Resolución de errores de compatibilidad de plataformas

Estos errores se producen cuando los paquetes del venv se crearon para un sistema operativo o una arquitectura diferentes. Cómo evitar que se produzcan estos errores:

  • Cree siempre el entorno virtual dentro de un contenedor de Docker con el indicador --platform linux/amd64.

  • Compruebe que las etiquetas de plataforma de las ruedas coincidan con la versión de AWS Glue de destino. Por ejemplo, AWS Glue 5.0 y 5.1 requieren etiquetas de plataforma manylinux2014_x86_64 o etiquetas compatibles.

  • No cree el entorno virtual directamente en macOS o Windows sin Docker.