View a markdown version of this page

Usar ambientes virtuais do Python com o AWS Glue - AWS Glue
Principais diferenças de --additional-python-modulesComo escolher uma abordagemUsar um ambiente virtual gerado pelo serviço com o armazenamento em cache do Amazon S3Compilar seu próprio ambiente virtualAutomatizar a migração com o KiroSolução de problemas

Usar ambientes virtuais do Python com o AWS Glue

A partir do AWS Glue 5.0, é possível executar trabalhos de ETL em um ambiente virtual do Python (venv). Os ambientes virtuais excluem das execuções de trabalhos a resolução de dependências no runtime, garantem que toda execução use os mesmos pacotes e evitam as falhas causadas por alterações em pacotes upstream.

O AWS Glue é compatível com duas maneiras de usar um ambiente virtual:

  • Ambiente virtual gerado pelo serviço: disponível no AWS Glue 6.0 e posteriores. Adicione o parâmetro --python-virtual-env-storage-prefix e o AWS Glue compilará o ambiente virtual para você e o armazenará em cache no Amazon S3 para posteriores execuções de trabalhos. Não é necessária nenhuma compilação local.

  • Ambiente virtual compilado manualmente: disponível no AWS Glue 5.0 e posteriores. Você compila o ambiente virtual na máquina local ou em um pipeline de CI/CD, o carrega no Amazon S3 e o referencia com o parâmetro --python-virtual-env.

Este tópico descreve como migrar trabalhos que usam --additional-python-modules para qualquer duas abordagens. Para saber mais sobre outros métodos de gerenciamento de dependências do Python, consulte Usar bibliotecas Python com o AWS Glue.

Principais diferenças de --additional-python-modules

A tabela a seguir compara os --additional-python-modules com um ambiente virtual compilado manualmente.

Recurso

--additional-python-modules

--python-virtual-env

Bibliotecas de contêineres básicas (boto3, numpy, pandas e outras)

Disponível automaticamente

Não disponível. Inclua incluir todos os pacotes necessários no venv.

Resolução de dependências

Ocorre no runtime

Ocorre no momento da compilação na sua máquina

Isolamento de runtime

Parcial. Os pacotes são instalados em cima das bibliotecas básicas.

Total. Substitui totalmente o ambiente do Python.
Importante

Ao migrar para o --python-virtual-env, inclua todos os pacotes do Python necessários para o trabalho no ambiente virtual. Isso inclui os pacotes que estavam disponíveis anteriormente no contêiner básico do AWS Glue, como boto3, numpy e pandas. Esses pacotes não estão mais implicitamente disponíveis.

Como escolher uma abordagem

Use a tabela a seguir para decidir qual é a melhor abordagem para o trabalho.

Cenário

(Abordagem recomendada)

Trabalhos simples com poucos pacotes de pip, quando você não quer ter sobrecarga de compilação

Venv gerado pelo serviço (adicione --python-virtual-env-storage-prefix). Requer o AWS Glue 6.0 ou posterior.

Árvores de dependência complexas, reprodutibilidade total ou um pipeline de CI/CD que compila o venv

Venv (--python-virtual-env) compilado manualmente. Requer o AWS Glue 5.0 ou posterior.

Migrar dos --additional-python-modules com o mínimo de alterações

Venv gerado pelo serviço (adicione --python-virtual-env-storage-prefix). Requer o AWS Glue 6.0 ou posterior. No AWS Glue 5.0 e 5.1, use um ambiente virtual compilado manualmente.

Índice privado do PyPI com pacotes personalizados

Qualquer uma das duas abordagens. O venv gerado pelo serviço requer o AWS Glue 6.0 ou posterior e funciona com --python-modules-installer-option.

Usar um ambiente virtual gerado pelo serviço com o armazenamento em cache do Amazon S3

A partir do AWS Glue 6.0, é possível usar o parâmetro --python-virtual-env-storage-prefix para fazer com que o AWS Glue compile o ambiente virtual e o armazene em cache no Amazon S3. Essa abordagem combina a simplicidade dos --additional-python-modules com o benefício de desempenho de um ambiente virtual em cache.

Como funciona

Quando você fornece o --python-virtual-env-storage-prefix, o AWS Glue faz o seguinte:

  • Na primeira execução (cache miss): o AWS Glue cria um ambiente virtual com --system-site-packages, que herda pacotes de contêiner como numpy, pandas e pyarrow. O AWS Glue então instala os pacotes dos --additional-python-modules com o pip, empacota o ambiente virtual como um arquivo .tar.gz e o carrega com o prefixo do Amazon S3 para reutilização posterior.

  • Em execuções posteriores (cache hit): o AWS Glue baixa o arquivo .tar.gz em cache do Amazon S3, o extrai e configura o driver e os executores do Spark para usar o ambiente virtual. Não ocorre nenhuma instalação de pip.

Diferenças de um ambiente virtual compilado manualmente

A tabela a seguir compara o ambiente virtual gerado pelo serviço com a abordagem de compilação manual.

Recurso

Venv gerado pelo serviço

Venv compilado manualmente

Responsabilidade pela compilação

O AWS Glue compila o venv automaticamente

Você compila o venv no Docker

Pacotes de contêiner

Herdado por meio de --system-site-packages

Você deve incluir todos os pacotes explicitamente

Latência na primeira execução

Tempo adicional para instalação, empacotamento e carregamento do pip no Amazon S3

Nenhuma, porque o venv é pré-compilado

Latência em execução posterior

Tempo adicional para download e extração do Amazon S3

Tempo adicional para download e extração do Amazon S3

Determinismo

É recomendável fixar as versões de pacote

Totalmente determinístico, porque as versões são bloqueadas no momento da compilação

PyPIacesso do

Obrigatório na primeira execução

Não obrigatório, porque o venv é compilado offline

Configurar um ambiente virtual gerado pelo serviço

O parâmetro --python-virtual-env-storage-prefix especifica o local no Amazon S3 onde o AWS Glue armazena o ambiente virtual que compila, no formato s3://path/. O AWS Glue armazena o ambiente virtual em cache com esse prefixo na primeira execução do trabalho e o reutiliza nas execuções posteriores.

Para habilitar um ambiente virtual gerado pelo serviço, adicione o parâmetro --python-virtual-env-storage-prefix ao trabalho e mantenha o parâmetro --additional-python-modules existente.

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

Você também pode usar os seguintes parâmetros opcionais:

  • --python-virtual-env-version: um identificador de versão do ambiente virtual em cache. Altere esse valor para invalidar o cache e forçar o AWS Glue a recompilar o ambiente virtual. O valor é uma string, então você pode usar qualquer esquema de versionamento adequado ao fluxo de trabalho, como um número incremental, uma data ou um identificador de compilação. O valor padrão é 0.

  • --python-modules-installer-option: passe as opções para o pip, como --no-deps ou --index-url.

Para habilitar armazenamento em cache para um trabalho existente, adicione o parâmetro de prefixo de armazenamento. A primeira execução demora mais porque o AWS Glue compila e carrega o ambiente virtual, mas as execuções posteriores usam o ambiente virtual em cache e não realizam resolução 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/"

Como o AWS Glue armazena em cache o ambiente virtual

O AWS Glue identifica o cache pela configuração do trabalho. A configuração inclui os módulos de --additional-python-modules, o valor de --python-modules-installer-option, a versão do AWS Glue e o valor de --python-virtual-env-version.

Uma configuração inalterada resulta em um hit de cache. Se você alterar qualquer desses valores, o AWS Glue compilará um novo ambiente virtual e criará uma nova entrada de cache.

O AWS Glue armazena cada ambiente virtual em cache com uma chave separada no seu prefixo de armazenamento. Os trabalhos que usam os mesmos módulos e opções de instalação compartilham a mesma entrada de cache.

Limitações

  • Requer o AWS Glue 6.0 ou posterior.

  • A primeira execução requer acesso ao PyPI ou ao seu índice privado para resolução de dependências.

  • Pacotes de contêiner, como numpy e pandas, são herdados, mas não fixados por versão. Se o trabalho exigir as versões exatas dos pacotes de contêiner, use --python-virtual-env em vez disso.

  • O cache é identificado pela configuração. A alteração de qualquer módulo ou versão cria uma nova entrada de cache, e as entradas anteriores permanecem no Amazon S3 até serem removidas.

Compilar seu próprio ambiente virtual

No AWS Glue 5.0 e versões posteriores, você mesmo pode compilar um ambiente virtual e referenciá-lo com o parâmetro --python-virtual-env. Use essa abordagem quando precisar de reprodutibilidade total, versões exatas dos pacotes de contêiner ou uma compilação executada em um pipeline de CI/CD.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

  • Docker do site do Docker, instalado na máquina local, para que você possa compilar o ambiente virtual em um ambiente compatível com o AWS Glue

  • Um bucket do Amazon S3 no qual o ambiente virtual empacotado será carregado

  • A AWS CLI configurada com permissões para carregar no Amazon S3 e atualizar os parâmetros de trabalho do AWS Glue

Para ver detalhes de versão do Python e de compatibilidade de plataforma para cada versão do AWS Glue, consulte Apêndice B: Detalhes do ambiente AWS Glue.

Etapa 1: compilar os arquivos de requisitos

Crie dois arquivos de requisitos que definam os pacotes para o ambiente virtual.

  1. Baixe o arquivo base-requirements.txt para a versão do AWS Glue no repositório aws-glue-libs no site do GitHub. Esse arquivo lista os pacotes fornecidos pelo contêiner padrão do AWS Glue. Para obter a mesma lista deste guia, consulte Módulos do Python já fornecidos no AWS Glue.

  2. Create additional-requirements.txt. Adicione os pacotes do parâmetro --additional-python-modules existente, um por linha. Por exemplo:

    cryptography
requests-oauthlib
sqlalchemy
Importante

Se o trabalho usar a biblioteca do AWS Glue Python, como GlueContext ou DynamicFrame, inclua também o pacote AWSGlueDataplanePython do site do PyPI. Use a versão correspondente à versão do AWS Glue, como mostrado na tabela a seguir.

AWSVersão do Glue

Versão do pacote

5,0

AWSGlueDataplanePython==5.0.0

5.1

AWSGlueDataplanePython==5.1.0

6.0

AWSGlueDataplanePython==6.0.0

Etapa 2: Criar um destino Dockerfile

Crie um Dockerfile que corresponda ao ambiente da versão de destino do AWS Glue. Para obter detalhes sobre plataforma e versão do Python, consulte Apêndice B: Detalhes do ambiente AWS Glue.

Os AWS Glue 5.0 e 5.1 usam o Python 3.11 no 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

O AWS Glue 6.0 usa o Python 3.13 no 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

Etapa 3: compilar e iniciar o contêiner

Compile a imagem do Docker. Depois, inicie um contêiner com os arquivos de requisitos e o script de trabalho 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

Esse comando monta os arquivos de requisitos e o diretório de scripts de trabalho do AWS Glue. A etapa a seguir usa o diretório de scripts para análise de importação.

Etapa 4: compile um venv temporário e descubra quais são os pacotes necessários

Dentro do contêiner, compile um venv temporário que espelhe o runtime do AWS Glue. Depois, use a análise estática para encontrar o conjunto mínimo de pacotes necessários para o trabalho.

Para os AWS Glue 5.0 e 5.1, que usam o Python 3.11, execute os comandos a seguir.

# 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 o AWS Glue 6.0, que usa o Python 3.13, execute os comandos a seguir.

# 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 verificar se parece correto. Se o trabalho usar importações dinâmicas ou condicionais, o pipreqs talvez não as detecte. Adicione esses pacotes ao arquivo manualmente.

Etapa 5: compilar o venv de produção

Crie o venv final apenas com os pacotes necessários para o trabalho. Em seguida, empacote-o como um tarball.

Para os AWS Glue 5.0 e 5.1, que usam o Python 3.11, execute os comandos a seguir.

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 o AWS Glue 6.0, que usa o Python 3.13, execute os comandos a seguir.

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

Etapa 6: fazer upload no Amazon S3

Carregue o ambiente virtual empacotado no bucket do Amazon S3.

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

Etapa 7: atualizar os parâmetros de trabalho

Atualize a configuração de trabalho do AWS Glue para que use --python-virtual-env em vez de --additional-python-modules.

Remova o parâmetro --additional-python-modules e adicione o parâmetro --python-virtual-env apontando para o tarball carregado.

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

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

Automatizar a migração com o Kiro

Se preferir uma abordagem automatizada, você pode usar o Kiro, disponível no site do Kiro, para executar a migração descrita no Compilar seu próprio ambiente virtual da linha de comando. Com uma habilidade do Kiro, o Kiro analisa a configuração de trabalho do AWS Glue, compila o ambiente virtual no Docker e gera o tarball empacotado.

Como funciona

Quando você pede ao Kiro para migrar o trabalho do AWS Glue dos --additional-python-modules para o --python-virtual-env, o Kiro faz o seguinte:

  1. Extrai a versão do AWS Glue, o valor dos --additional-python-modules e o script de trabalho da sua solicitação.

  2. Recupera a lista de módulos de contêiner básicos para a sua versão do AWS Glue da documentação do AWS Glue.

  3. Cria os artefatos de compilação em um diretório de trabalho, incluindo o base-requirements.txt, o additional-requirements.txt, um Dockerfile e um script de compilação.

  4. Compila a imagem do Docker para um ambiente compatível com o AWS Glue.

  5. Executa o fluxo de trabalho de descoberta e empacotamento em um contêiner não interativo.

  6. Gera o pyspark_venv.tar.gz, solicita um destino no Amazon S3 e carrega o tarball.

  7. Mostra os parâmetros de trabalho atualizados.

Exemplo de solicitação

Forneça a versão do AWS Glue, os módulos adicionais do Python e o script do trabalho. Por exemplo:

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.

Obter a habilidade do Kiro

O arquivo de habilidades venv-migration é mantido no repositório aws-glue-libs e não neste guia. Para ver o arquivo de habilidades e as instruções de instalação, consulte venv-migration skill no site do GitHub.

Limitações

  • O Kiro requer que o Docker esteja disponível no ambiente de linha de comando.

  • As importações dinâmicas e condicionais não visíveis na fonte do script não são detectadas automaticamente. Revise o arquivo final-requirements.txt gerado e adicione manualmente os pacotes que faltam.

  • Se o trabalho usar um índice de pip privado com --index-url, configure o acesso de rede a esse índice no contêiner do Docker.

  • Os conflitos de pip durante a compilação podem requerer resolução manual. Para obter mais informações, consulte Solução de problemas.

Solução de problemas

Use as seções a seguir para resolver problemas comuns ao usar ambientes virtuais do Python com o AWS Glue.

Resolver conflitos de versão de pip

Um conflito de versão de pip significa que dois pacotes exigem versões incompatíveis da mesma dependência. Para encontrar e corrigir o conflito, faça o seguinte:

  1. Leia a saída do erro de pip. Quando a resolução falha completamente, a saída nomeia cada requisito conflitante e o pacote que o introduziu.

  2. Visualize o que o pip resolveria sem instalar nada. Adicione --dry-run --report install-report.json ao comando de instalação, como no exemplo a seguir.

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

  3. Inspecione o install-report.json. O relatório lista todos os pacotes que o pip selecionou, o que revela se houve downgrades silenciosos.

  4. Relaxe as fixações de versão em pacotes não críticos ou remova as restrições.

Resolver ModuleNotFoundError

Esse erro indica que o ambiente virtual não inclui um pacote que seria obrigatório. Entre as causas comuns, temos:

  • Você não incluiu uma biblioteca de contêiners básica que o trabalho exige. Um ambiente virtual compilado manualmente não herda os pacotes de contêiner do AWS Glue.

  • O trabalho usa uma importação dinâmica não detectada por pipreqs durante a análise estática.

  • O trabalho exige uma dependência do PySpark nos nós executores.

Para resolver esse problema, adicione o pacote que falta e recompile o ambiente virtual. As etapas dependem de qual foi a abordagem usada pelo trabalho.

  • Venv compilado manualmente: adicione o pacote ao final-requirements.txt, recompile o ambiente virtual e carregue-o novamente.

  • Venv gerado pelo serviço: adicione o pacote aos --additional-python-modules. A nova lista de módulos altera a chave do cache e o AWS Glue compila um novo ambiente virtual na próxima execução do trabalho.

Reduzir o tamanho do tarball do venv

Se o ambiente virtual empacotado for muito grande, reduza seu tamanho com as seguintes abordagens:

  • Remova os pacotes desnecessários que o script não importa, como estruturas de teste e ferramentas de desenvolvimento.

  • Use pip install --no-deps para os pacotes cujas dependências transitivas você deseja controlar manualmente.

  • Inclua somente os pacotes que o script importa diretamente e deixe o pip-compile resolver as dependências transitivas mínimas necessárias.

Resolver erros de compatibilidade de plataforma

Esses erros ocorrem quando os pacotes no venv foram compilados para outro sistema operacional ou arquitetura. Para evitar esses erros:

  • Sempre compile o ambiente virtual dentro de um contêiner do Docker usando o sinalizador --platform linux/amd64.

  • Verifique se as tags de plataforma do wheel correspondem à versão de destino do AWS Glue. Por exemplo, os AWS Glue 5.0 e 5.1 exigem manylinux2014_x86_64 ou tags de plataforma compatíveis.

  • Não compile o ambiente virtual diretamente no macOS ou no Windows sem o Docker.