Instalar dependências do Python

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Nesta página, descrevemos como instalar pacotes Python no ambiente do Cloud Composer.

Sobre pacotes no Cloud Composer

Esta seção explica como os pacotes do PyPI funcionam no Cloud Composer.

Pacotes PyPI pré-instalados e personalizados em imagens do Cloud Composer

As imagens do Cloud Composer contêm pacotes PyPI pré-instalados e personalizados.

• Os pacotes PyPI pré-instalados são aqueles incluídos na imagem do Cloud Composer do seu ambiente. Cada imagem do Cloud Composer contém pacotes PyPI específicos para sua versão do Cloud Composer e do Airflow.

• Pacotes PyPI personalizados são pacotes que podem ser instalados no ambiente além dos pacotes pré-instalados.

Observação: se você planeja fazer upgrade do ambiente, faça uma verificação de upgrade. Essa verificação informa se os pacotes PyPI personalizados no seu ambiente têm conflitos com pacotes pré-instalados em uma imagem posterior do Cloud Composer.

Opções para gerenciar pacotes PyPI em ambientes do Cloud Composer

Opção	Use se
Instalar do PyPI	A maneira padrão de instalar pacotes no seu ambiente
Instalar de um repositório com um endereço IP público	O pacote está hospedado em um repositório diferente do PyPI. Este repositório tem um endereço IP público
Instalar de um repositório do Artifact Registry	O pacote é hospedado em um repositório do Artifact Registry.
Instalar de um repositório na rede do projeto	Seu ambiente não tem acesso à Internet pública. O pacote é hospedado em um repositório de pacotes na rede do seu projeto.
Instalar como uma biblioteca local do Python	O pacote não for encontrado no PyPI, e a biblioteca não tiver dependências externas, como dist-packages.
Instalar um plug-in	O pacote oferece funcionalidades específicas do plug-in, como modificar a interface da Web do Airflow.
PythonVirtualenvOperator	Você não quer que o pacote seja instalado em todos os workers do Airflow ou a dependência entra em conflito com pacotes pré-instalados. O pacote pode ser encontrado no PyPI e não tem dependências externas.
KubernetesPodOperator e operadores do GKE	Você precisa de dependências externas que não podem ser instaladas usando pip, como dist-packages, ou estão em um servidor pip interno. Essa opção requer mais configuração e manutenção. Considere essa opção apenas se as outras não funcionarem.

Antes de começar

• Você precisa ter um papel que acione operações de atualização do ambiente. Além disso, a conta de serviço do ambiente precisa ter um papel com permissões suficientes para realizar operações de atualização.

  Importante: quando você instala pacotes PyPI no ambiente, o Airflow executa o código Python do pacote instalado. Instale pacotes de fontes confiáveis. Os usuários com a permissão composer.environments.update podem executar código Python em nome da conta de serviço do ambiente ao instalar pacotes nele. Para mais informações, consulte Controle de acesso.

• Se o ambiente for protegido por um perímetro do VPC Service Controls, antes de instalar dependências PyPI, será necessário conceder identidades de usuário adicionais com acesso a serviços que o perímetro de serviço protege e ativar o suporte a um repositório PyPI particular.

• Os requisitos precisam seguir o formato especificado no PEP-508. Nele, cada requisito é especificado em letras minúsculas e consiste no nome do pacote com especificadores de versão e atributos extras opcionais.

• As atualizações de dependência do PyPI geram imagens do Docker no Artifact Registry.

  Aviso: não modifique nem exclua as imagens criadas pelo Cloud Composer no Artifact Registry ou no próprio repositório. Não faça upload das suas próprias imagens para o repositório. Em vez disso, crie e mantenha seu próprio repositório para as imagens (por exemplo, para imagens usadas pelo KubernetesPodOperator). Não exclua o repositório por conta própria. O repositório é excluído depois que você exclui o ambiente.

• Se a atualização falhar por conta de um conflito de dependências, o ambiente continuará sendo executado com as dependências atuais. Se a operação for concluída, será possível usar as dependências recém-instaladas do Python nos DAGs.

• O Cloud Composer usa a conta de serviço padrão do Cloud Build para criar imagens com pacotes PyPI instalados. Se a conta de serviço padrão do Cloud Build não estiver configurada, a conta de serviço do ambiente será usada.

  Descontinuado: se a conta de serviço legada do Cloud Build estiver disponível no seu projeto, o ambiente a usará para criar imagens. Recomendamos configurar uma conta de serviço especificada pelo usuário em vez disso, conforme descrito em Mudança na conta de serviço padrão do Cloud Build.

• Projetos em que a API Cloud Composer foi ativada em 29 de abril de 2024 ou depois. A menos que sua organização substitua a política constraints/cloudbuild.disableCreateDefaultServiceAccount, os novos projetos não vão provisionar a conta de serviço legada do Cloud Build ao ativar a API. Como o Cloud Build é usado por padrão ao instalar pacotes PyPI personalizados no ambiente do Cloud Composer, a instalação de pacotes pode falhar. Por padrão, a conta de serviço do ambiente será usada. Portanto, conceda a essa conta de serviço todas as permissões adicionais necessárias para acessar seus pacotes particulares.

• O PythonVirtualenvOperator não usa a configuração do arquivo pip.conf do seu ambiente. Se você quiser usar dependências específicas, incluindo a instalação delas em um índice personalizado, transmita os requisitos no parâmetro requirements como uma lista de strings. Para mais informações sobre o formato, consulte Formato do arquivo de requisitos na documentação do pip.

Ver a lista de pacotes PyPI

É possível acessar a lista de pacotes do seu ambiente em vários formatos.

Ver pacotes pré-instalados

Para conferir a lista de pacotes pré-instalados no seu ambiente, consulte a lista de pacotes da imagem do Cloud Composer do seu ambiente.

Ver todos os pacotes

Para conferir todos os pacotes (pré-instalados e personalizados) no seu ambiente:

gcloud

O comando da CLI gcloud a seguir retorna o resultado do comando python -m pip list para um worker do Airflow no seu ambiente. Você pode usar o argumento --tree para receber o resultado do comando python -m pipdeptree --warn.

gcloud beta composer environments list-packages \
    ENVIRONMENT_NAME \
    --location LOCATION

Substitua:

• ENVIRONMENT_NAME pelo nome do ambiente
• LOCATION pela região em que o ambiente está localizado;

Ver pacotes PyPI personalizados

Console

1. No console Google Cloud , acesse a página Ambientes.

   Acessar "Ambientes"

2. Na lista de ambientes, clique no nome do seu ambiente. A página Detalhes do ambiente é aberta.

3. Acesse a guia Pacotes PyPI.

gcloud

gcloud composer environments describe ENVIRONMENT_NAME \
  --location LOCATION \
  --format="value(config.softwareConfig.pypiPackages)"

Substitua:

• ENVIRONMENT_NAME pelo nome do ambiente
• LOCATION pela região em que o ambiente está localizado;

Instalar pacotes personalizados em um ambiente do Cloud Composer

Nesta seção, descrevemos diferentes métodos para instalar pacotes personalizados no seu ambiente.

Instalar pacotes do PyPI

Um pacote pode ser instalado do Índice de pacotes Python se não tiver dependências externas ou conflitos com pacotes pré-instalados.

Observação: é possível reduzir as restrições de versão para pacotes PyPI personalizados instalados. Por exemplo, em vez de especificar uma versão como ==1.0.1, especifique-a como >=1.0.1.

Para adicionar, atualizar ou excluir as dependências do Python no ambiente, faça o seguinte:

Console

1. No console Google Cloud , acesse a página Ambientes.

   Acessar "Ambientes"

2. Na lista de ambientes, clique no nome do seu ambiente. A página Detalhes do ambiente é aberta.

3. Acesse a guia Pacotes PyPI.

4. Clique em Editar.

5. Clique em Adicionar pacote.

6. Na seção Pacotes do PyPI, especifique os nomes dos pacotes, com especificadores de versão e extras opcionais.

   Exemplo:

   • scikit-learn
   • scipy, >=0.13.3
   • nltk, [machine_learning]

7. Clique em Salvar.

gcloud

A CLI gcloud tem vários argumentos para trabalhar com pacotes personalizados do PyPI:

• O --update-pypi-packages-from-file substitui todos os pacotes personalizados do PyPI pelos pacotes especificados. Os pacotes que não forem especificados serão removidos.
• O --update-pypi-package atualiza ou instala um pacote.
• --remove-pypi-packages remove os pacotes especificados.
• --clear-pypi-packages remove todos os pacotes.

Instalar requisitos de um arquivo

O arquivo requirements.txt precisa ter cada especificador de requisito em uma linha separada.

Exemplo:

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

Atualize o ambiente e especifique o arquivo requirements.txt no argumento --update-pypi-packages-from-file.

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-packages-from-file requirements.txt

Substitua:

• ENVIRONMENT_NAME pelo nome do ambiente
• LOCATION pela região em que o ambiente está localizado;

Instalar um pacote

Atualize o ambiente e especifique o pacote, a versão e os extras no argumento --update-pypi-package.

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-package PACKAGE_NAMEEXTRAS_AND_VERSION

Substitua:

• ENVIRONMENT_NAME pelo nome do ambiente
• LOCATION pela região em que o ambiente está localizado;
• PACKAGE_NAME com o nome do pacote.
• EXTRAS_AND_VERSION com o especificador opcional de versão e extras. Para omitir versões e extras, especifique um valor vazio.

Observação: dependendo do seu ambiente de execução, talvez seja necessário inserir caracteres de escape especiais, como >. Para evitar possíveis problemas, coloque o nome e a versão do pacote entre aspas. Por exemplo: "scipy>=0.13.0".

Exemplo:

gcloud composer environments update example-environment \
    --location us-central1 \
    --update-pypi-package "scipy>=0.13.3"

Como remover pacotes

Atualize seu ambiente e especifique os pacotes que você quer excluir no argumento --remove-pypi-packages:

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --remove-pypi-packages PACKAGE_NAMES

Substitua:

• ENVIRONMENT_NAME pelo nome do ambiente
• LOCATION pela região em que o ambiente está localizado;
• PACKAGE_NAMES por uma lista de pacotes separados por vírgulas.

Exemplo:

gcloud composer environments update example-environment \
    --location us-central1 \
    --remove-pypi-packages scipy,scikit-learn

API

Crie uma solicitação de API environments.patch.

Nesta solicitação:

1. No parâmetro updateMask, especifique a máscara:

   • Use a máscara config.softwareConfig.pypiPackages para substituir todos os pacotes atuais pelos especificados. Os pacotes que você não especificar serão excluídos.
   • Use config.softwareConfig.envVariables.PACKAGE_NAME para adicionar ou atualizar um pacote específico. Para adicionar ou atualizar vários pacotes, especifique várias máscaras com vírgulas.

2. No corpo da solicitação, especifique pacotes e valores para versões e extras:

   {
     "config": {
       "softwareConfig": {
         "pypiPackages": {
           "PACKAGE_NAME": "EXTRAS_AND_VERSION"
         }
       }
     }
   }
   

   Substitua:

   • PACKAGE_NAME com o nome do pacote.
   • EXTRAS_AND_VERSION com o especificador opcional de versão e extras. Para omitir versões e extras, especifique um valor vazio.
   • Para adicionar mais de um pacote, adicione entradas extras para pacotes em pypiPackages.

Exemplo:

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.pypiPackages.EXAMPLE_PACKAGE,
// config.softwareConfig.pypiPackages.ANOTHER_PACKAGE
{
  "config": {
    "softwareConfig": {
      "pypiPackages": {
        "EXAMPLE_PACKAGE": "",
        "ANOTHER_PACKAGE": ">=1.10.3"
      }
    }
  }
}

Terraform

O bloco pypi_packages no bloco software_config especifica pacotes.

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

Substitua:

• ENVIRONMENT_NAME pelo nome do ambiente
• LOCATION pela região em que o ambiente está localizado;
• PACKAGE_NAME com o nome do pacote.
• EXTRAS_AND_VERSION com o especificador opcional de versão e extras. Para omitir versões e extras, especifique um valor vazio.
• Para adicionar mais de um pacote, adicione entradas extras para pacotes em pypi_packages.

Exemplo:

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "example-environment"
  region = "us-central1"

  config {

    software_config {
      pypi_packages = {
          scipy = ">=1.10.3"
          scikit-learn = ""
          nltk = "[machine_learning]"
      }
    }
  }
}

Instalar pacotes de um repositório público

É possível instalar pacotes hospedados em outros repositórios com um endereço IP público.

Os pacotes precisam ser configurados corretamente para que a ferramenta padrão pip possa instalá-los.

Observação: o Cloud Composer não é compatível com a personalização do pip e não resolve dependências de pacote e conflitos fora dos mecanismos de resolução fornecidos pela ferramenta pip padrão.

Para instalar de um repositório de pacotes com um endereço público:

1. Crie um arquivo pip.conf e inclua as seguintes informações nele, se aplicável:

   • URL do repositório (no parâmetro index-url)
   • Acessar as credenciais do repositório
   • Opções de instalação de pip não padrão

   Exemplo:

   [global]
   index-url=https://example.com/
   

2. (Opcional) Em alguns casos, talvez seja necessário buscar pacotes de vários repositórios, como quando o repositório público contém alguns pacotes específicos que você quer instalar, e você quer instalar todos os outros pacotes do PyPI:

   1. Configure um repositório virtual do Artifact Registry.
   2. Adicione a configuração para vários repositórios (incluindo PyPI, se necessário) e defina a ordem em que pip pesquisa os repositórios.
   3. Especifique o URL do repositório virtual no parâmetro index-url.

3. Determine o URI do bucket do ambiente.

4. Faça upload do arquivo pip.conf para a pasta /config/pip/ no bucket do ambiente.

5. Instale pacotes usando um dos métodos disponíveis.

Instalar pacotes de um repositório do Artifact Registry

É possível armazenar pacotes em um repositório do Artifact Registry no seu projeto e configurar o ambiente para instalar dele.

Observação: se você usa o VPC Service Controls, é possível criar um repositório PyPI do Artifact Registry no modo VPC. Nesse caso, siga o procedimento para repositórios particulares ao atribuir permissões.

Configure papéis e permissões:

1. Verifique se a conta de serviço do Cloud Build tem permissões para ler do repositório do Artifact Registry.

2. Conceda permissões adicionais para instalar pacotes dos repositórios do Artifact Registry à conta de serviço do seu ambiente, conforme descrito em Controle de acesso.

3. Se o ambiente tiver acesso restrito a outros serviços no projeto, por exemplo, se você usar o VPC Service Controls:

   1. Atribua permissões para acessar o repositório do Artifact Registry à conta de serviço do ambiente em vez da conta de serviço do Cloud Build.

   2. Verifique se a conectividade com o repositório do Artifact Registry está configurada no seu projeto.

Para instalar pacotes PyPI personalizados de um repositório do Artifact Registry:

1. Crie um arquivo pip.conf e inclua as seguintes informações nele, se aplicável:

   • URL do repositório do Artifact Registry (no parâmetro index-url)
   • Acessar as credenciais do repositório
   • Opções de instalação de pip não padrão

   Para um repositório do Artifact Registry, adicione /simple/ ao URL do repositório:

   [global]
   index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
   

2. (Opcional) Em alguns casos, talvez seja necessário buscar pacotes de vários repositórios, como quando o repositório do Artifact Registry contém alguns pacotes específicos que você quer instalar, e você quer instalar todos os outros pacotes do PyPI:

   1. Configure um repositório virtual do Artifact Registry.
   2. Adicione a configuração para vários repositórios (incluindo PyPI, se necessário) e defina a ordem em que pip pesquisa os repositórios.
   3. Especifique o URL do repositório virtual no parâmetro index-url.

3. Faça upload desse arquivo pip.conf para a pasta /config/pip/ no bucket do seu ambiente. Por exemplo, gs://us-central1-example-bucket/config/pip/pip.conf.

4. Instale pacotes usando um dos métodos disponíveis.

Instalar pacotes de um repositório particular

É possível hospedar um repositório particular na rede do projeto e configurar o ambiente para instalar pacotes Python dele.

Configure papéis e permissões:

1. Se você instalar pacotes PyPI personalizados de um repositório na rede do seu projeto e esse repositório não tiver um endereço IP público:

   1. Atribua permissões de acesso a esse repositório à conta de serviço do ambiente.

   2. Verifique se a conectividade com esse repositório está configurada no seu projeto.

2. Conceda permissões adicionais para instalar pacotes de repositórios particulares à conta de serviço do seu ambiente, conforme descrito em Controle de acesso.

Para instalar pacotes de um repositório particular hospedado na rede do seu projeto:

1. Crie um arquivo pip.conf e inclua as seguintes informações nele, se aplicável:

   • Endereço IP do repositório na rede do projeto
   • Acessar as credenciais do repositório
   • Opções de instalação de pip não padrão

   Exemplo:

   [global]
   index-url=https://192.0.2.10/
   

2. (Opcional) Em alguns casos, talvez seja necessário buscar pacotes de vários repositórios, como quando o repositório particular contém alguns pacotes específicos que você quer instalar, e você quer instalar todos os outros pacotes do PyPI:

   1. Configure um repositório virtual do Artifact Registry.
   2. Adicione a configuração para vários repositórios (incluindo PyPI, se necessário) e defina a ordem em que pip pesquisa os repositórios.
   3. Especifique o URL do repositório virtual no parâmetro index-url.

3. (Opcional) No Cloud Composer 2.2.1 e versões mais recentes, é possível usar um certificado personalizado ao instalar pacotes do seu repositório privado. Para fazer isso, siga estas etapas:

   1. Faça upload do arquivo de certificado para a pasta /config/pip/ no bucket do seu ambiente.

      Cuidado: não faça upload de chaves privadas. Faça upload apenas de um pacote de certificados públicos no formato PEM. Verifique se o pacote de certificados contém a CA raiz correta.

   2. No pip.conf, especifique o nome do arquivo de certificado no parâmetro cert. Não mude a pasta /etc/pip/.

      Exemplo:

      [global]
      cert =/etc/pip/example-certificate.pem
      

4. Faça upload do arquivo pip.conf para a pasta /config/pip/ no bucket do ambiente. Por exemplo, gs://us-central1-example-bucket/config/pip/pip.conf.

5. Instale pacotes usando um dos métodos disponíveis.

Instalar uma biblioteca local do Python

Para instalar uma biblioteca local ou interna do Python, faça o seguinte:

1. Coloque as dependências em um subdiretório na pasta dags/ do bucket do ambiente. Para importar um módulo de um subdiretório, cada subdiretório no caminho do módulo precisa conter um arquivo de marcador de pacote __init__.py.

   No exemplo a seguir, a dependência é coin_module.py:

   dags/
     use_local_deps.py  # A DAG file.
     dependencies/
       __init__.py
       coin_module.py
   

2. Importe a dependência do arquivo de definição do DAG.

   Exemplo:

from dependencies import coin_module

Observação: ocorre um erro de importação se um arquivo __init__.py não estiver presente. Os nomes de diretório e arquivo precisam ser identificadores válidos do Python.

Usar pacotes que dependem de bibliotecas de objetos compartilhados

Alguns pacotes PyPI dependem de bibliotecas no nível do sistema. Embora o Cloud Composer não seja compatível com as bibliotecas do sistema, é possível usar as seguintes opções:

• Use o KubernetesPodOperator. Defina a imagem do operador como uma imagem de build personalizada. Se você encontrar pacotes que falham durante a instalação devido a uma dependência do sistema não atendida, use esta opção.

• Faça o upload das bibliotecas de objetos compartilhados no bucket do ambiente. Se os pacotes PyPI foram instalados com êxito, mas falham no ambiente de execução, use esta opção.

  1. Encontre manualmente as bibliotecas de objetos compartilhados para a dependência de PyPI (um arquivo ".so").
  2. Faça o upload das bibliotecas de objetos compartilhados para a pasta /plugins no bucket do seu ambiente.
  3. Defina a seguinte variável de ambiente: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

Observação: os arquivos nas pastas plugins/ são sincronizados com o sistema de arquivos local. Fazer o upload de arquivos .so grandes pode afetar o desempenho do ambiente e do servidor da Web do Airflow.

Instalar pacotes em ambientes de IP privado

Dependendo de como você configura o projeto, o ambiente pode não ter acesso à Internet pública.

Ambiente de IP privado com acesso à Internet pública

Se o ambiente de IP particular puder acessar a Internet pública, será possível instalar pacotes usando opções para ambientes de IP público:

• Instale pelo PyPI. Nesse caso, não é preciso fazer nenhuma configuração especial. Siga o procedimento descrito em Instalar um pacote do PyPI.
• Instale de um repositório com um endereço IP público. Siga o procedimento descrito em Instalar um pacote de um repositório particular.
• Instale de um repositório PyPI particular hospedado na rede do seu projeto.

Ambiente de IP privado sem acesso à Internet

Se o ambiente de IP particular não tiver acesso à Internet pública, instale os pacotes usando uma das seguintes maneiras:

• Use um repositório PyPI particular hospedado na rede do seu projeto.
• Use uma VM de servidor proxy na rede do seu projeto para se conectar a um repositório PyPI na Internet pública. Especifique o endereço de proxy no arquivo /config/pip/pip.conf no bucket do seu ambiente.
• Use um repositório do Artifact Registry como a única fonte de pacotes. Para fazer isso, redefina o parâmetro index-url, conforme descrito.
• Se a política de segurança permitir o acesso a endereços IP externo da rede VPC, configure o Cloud NAT para ativar a instalação de pacotes de repositórios na Internet pública.
• Coloque as dependências do Python na pasta /dags do bucket do ambiente para instalá-las como bibliotecas locais. Essa pode não ser uma boa opção se a árvore de dependência for grande.

Instalar em um ambiente de IP privado sob restrições de local de recursos

Manter seu projeto de acordo com os requisitos de restrição de localização de recursos proíbe o uso de algumas ferramentas. Em particular, o Cloud Build não pode ser usado para a instalação de pacotes, impedindo o acesso direto a repositórios na Internet pública.

Para instalar dependências do Python nesse ambiente, siga as orientações para ambientes de IP particular sem acesso à Internet.

Instalar uma dependência do Python em um ambiente de IP particular em um perímetro do VPC Service Controls

Proteger seu projeto com um perímetro do VPC Service Controls resulta em outras restrições de segurança. Em particular, o Cloud Build não pode ser usado para a instalação de pacotes, impedindo o acesso direto a repositórios na Internet pública.

Para instalar dependências do Python em um ambiente de IP privado dentro de um perímetro, siga as orientações para ambientes de IP privado sem acesso à Internet.

A seguir

• Solução de problemas na instalação de pacotes
• Solução de problemas de atualizações e upgrades