# 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](aws-glue-programming-python-libraries.md). ## 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](aws-glue-programming-etl-glue-arguments.md#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](aws-glue-programming-etl-glue-arguments.md#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](aws-glue-programming-etl-glue-arguments.md#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](https://docs.docker.com/get-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](aws-glue-programming-python-libraries.md#glue-python-libraries-environment-details). ### 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](aws-glue-programming-python-libraries.md#glue-modules-provided). + AWS Glue 5.0 – [base-requirements.txt](https://raw.githubusercontent.com/awslabs/aws-glue-libs/glue-5.0/base-requirements.txt) no site do GitHub + AWS Glue 5.1 – [base-requirements.txt](https://raw.githubusercontent.com/awslabs/aws-glue-libs/glue-5.1/base-requirements.txt) no site do GitHub + AWS Glue 6.0 – [base-requirements.txt](https://raw.githubusercontent.com/awslabs/aws-glue-libs/main/base-requirements.txt) no site do GitHub 1. 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](https://pypi.org/project/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](aws-glue-programming-python-libraries.md#glue-python-libraries-environment-details). 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](https://kiro.dev), disponível no site do Kiro, para executar a migração descrita no [Compilar seu próprio ambiente virtual](#python-venv-migration-procedure) 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. 1. 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. 1. 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. 1. Compila a imagem do Docker para um ambiente compatível com o AWS Glue. 1. Executa o fluxo de trabalho de descoberta e empacotamento em um contêiner não interativo. 1. Gera o `pyspark_venv.tar.gz`, solicita um destino no Amazon S3 e carrega o tarball. 1. 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](https://github.com/awslabs/aws-glue-libs/blob/main/.kiro/skills/venv-migration/skill.md) 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](#python-venv-troubleshooting). ## 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. 1. 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 ``` 1. Inspecione o `install-report.json`. O relatório lista todos os pacotes que o pip selecionou, o que revela se houve downgrades silenciosos. 1. 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.