Instalar dependências do Python para o Cloud Composer

Cloud Composer 1 | Cloud Composer 2

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

Sobre pacotes PyPI pré-instalados e personalizados nas imagens do Cloud Composer

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

  • Os pacotes PyPI pré-instalados são pacotes 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 você pode instalar no seu ambiente, além dos pacotes pré-instalados.

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

Opção Use se
Instalar usando o 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 de pacotes diferente do PyPI. Este repositório tem um endereço IP público
Instalar de um repositório do Artifact Registry O pacote está 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 na rede do projeto.
Instalar como uma biblioteca local do Python O pacote não pode ser encontrado no PyPI, e a biblioteca não tem dependências externas, como dist-packages.
Instalar um plug-in O pacote fornece funcionalidades específicas do plug-in, como a modificação da interface da Web do Airflow.
PythonVirtualenvOperator Você não quer que o pacote seja instalado para todos os workers do Airflow ou que a dependência entre em conflito com os 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 de pip, como dist-packages, ou que estão em um servidor pip interno. Essa opção requer mais configuração e manutenção. Considere isso apenas se outras opções 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 executar operações de atualização. Consulte Controle de acesso para mais informações.
  • Se o ambiente estiver protegido por um perímetro do VPC Service Controls, antes de instalar dependências PyPI, conceda outras identidades de usuário com acesso a serviços protegidos pelo perímetro de serviço e ative 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 PyPI geram imagens do Docker no Artifact Registry.

  • 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.

Conferir a lista de pacotes PyPI

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

Conferir pacotes pré-instalados

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

Ver todos os pacotes

Para ver 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. É possível usar o argumento --tree para obter 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;

Conferir pacotes PyPI personalizados

Console

  1. No console do 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 a partir do Índice de pacotes do Python se não tiver dependências externas ou entrar em conflito com pacotes pré-instalados.

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

Console

  1. No console do 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 PyPI, especifique nomes de pacotes, com especificadores de versão e extras opcionais.

    Exemplo:

    • scikit-learn
    • scipy, >=0.13.3
    • nltk, [machine_learning]
  7. Clique em Save.

gcloud

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

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

Como instalar requisitos usando um arquivo

O arquivo requirements.txt precisa ter cada especificador de requisitos 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;

Como 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 pelo nome do pacote.
  • EXTRAS_AND_VERSION com a versão opcional e o especificador de extras. Para omitir versões e extras, especifique um valor vazio.

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 separada 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 pacotes 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 pelo nome do pacote.
    • EXTRAS_AND_VERSION com a versão opcional e o especificador de extras. Para omitir versões e extras, especifique um valor vazio.
    • Para incluir mais de um pacote, adicione mais entradas 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" {
  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 pelo nome do pacote.
  • EXTRAS_AND_VERSION com a versão opcional e o especificador de extras. Para omitir versões e extras, especifique um valor vazio.
  • Para incluir mais de um pacote, adicione mais entradas para pacotes em pypi_packages.

Exemplo:

resource "google_composer_environment" "example" {
  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 que tenham um endereço IP público.

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

Para instalar a partir de um repositório de pacotes que tenha 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
    • Acessar as credenciais do repositório
    • Opções de instalação do pip não padrão

    Exemplo:

    [global]
    extra-index-url=https://example.com/
    
  2. Determine o URI do bucket do ambiente.

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

  4. 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 projeto e configurar o ambiente para instalar a partir dele.

Configure papéis e permissões:

  1. A conta de serviço do ambiente precisa ter o papel iam.serviceAccountUser.

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

  3. Se o ambiente restringir o acesso 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 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
    • Acessar as credenciais do repositório
    • Opções de instalação do pip não padrão
    • Se você quiser usar apenas seu repositório do Artifact Registry como origem de pacotes, redefina o parâmetro index-url. Caso contrário, o repositório especificado no parâmetro extra-index-url será usado além do índice do pacote PyPI padrão (pypi.python.org).

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

    [global]
    extra-index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
    
  2. Faça o 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.

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

Instalar pacotes de um repositório privado

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

Configure papéis e permissões:

  1. A conta de serviço do ambiente do Cloud Composer precisa ter o papel iam.serviceAccountUser.

  2. 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 para acessar o repositório na conta de serviço do ambiente.

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

Para instalar pacotes de um repositório privado hospedado na rede do seu projeto, siga estas etapas:

  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 seu projeto
    • Acessar as credenciais do repositório
    • Opções de instalação do pip não padrão

    Exemplo:

    [global]
    extra-index-url=https://192.0.2.10/
    
  2. 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.

  3. 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/ no 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

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 de sistema não atendida, use essa opção.

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

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

Instalar pacotes em ambientes de IP particular

Nesta seção, explicamos como instalar pacotes em ambientes de IP particulares.

Dependendo de como você configurar o projeto, o ambiente poderá não ter acesso à Internet pública.

Ambiente IP privado com acesso público à Internet

Se o ambiente de IP particular tiver acesso à Internet pública, será possível instalar pacotes usando opções para ambientes de IP públicos:

Ambiente IP particular sem acesso à Internet

Se o ambiente de IP privado não tiver acesso à Internet pública, será possível instalar pacotes usando uma das seguintes maneiras:

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

Instalar em um ambiente de IP privado com restrições de local do recurso

Manter seu projeto de acordo com os requisitos de restrição de localização de recursos proíbe o uso de algumas ferramentas. Especificamente, o Cloud Build não pode ser usado para 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 particulares 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. Especificamente, o Cloud Build não pode ser usado para instalação de pacotes, impedindo o acesso direto a repositórios na Internet pública.

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

A seguir