Instalar dependências do Python para o Cloud Composer

Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3

Esta página descreve como instalar pacotes Python para seu ambiente do Cloud Composer.

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

As imagens do Cloud Composer contêm PyPI pré-instalado e personalizado pacotes.

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

• Os pacotes PyPI personalizados podem ser instalados no seu ambiente em além dos pacotes pré-instalados.

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

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 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 para um repositório PyPI particular.
• Os requisitos precisam seguir o formato especificado no PEP-508, em que cada requisito é especificado em letras minúsculas e consiste no nome do pacote com extras opcionais e especificadores de versão.

• As atualizações de dependência do 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.

• Se você quiser que seus builds com uma conta de serviço personalizada, modifique o variável de ambiente COMPOSER_AGENT_BUILD_SERVICE_ACCOUNT com a conta de serviço escolhida. Essa conta de serviço precisa ser configurada para executar builds de acordo com a documentação do Cloud Build. e a conta de serviço do ambiente precisam ter os iam.serviceAccounts.actAs.

• Projetos em que A API Cloud Composer será ativada a partir de 29 de abril de 2024. A menos que sua organização modifique o constraints/cloudbuild.disableCreateDefaultServiceAccount política, novos projetos não vai provisionar a conta de serviço legada do Cloud Build sobre como 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 também as permissões adicionais necessárias para acessar os pacotes privados a essa conta de serviço.

Ver a lista de pacotes PyPI

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

Conferir pacotes pré-instalados

Para conferir 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 beta composer environments list-packages \
    ENVIRONMENT_NAME \
    --location LOCATION

Conferir pacotes PyPI personalizados

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

Instalar pacotes personalizados em um ambiente do Cloud Composer

Esta seção descreve métodos diferentes para instalar pacotes personalizados em seu de nuvem.

Instalar pacotes do PyPI

Um pacote pode ser instalado do Índice de pacotes 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:

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

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

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

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

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

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

// 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"
      }
    }
  }
}

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

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

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 que tenham um endereço IP público.

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

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

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

   • URL do repositório (no parâmetro index-url)
   • Acessar as credenciais do repositório
   • Opções de instalação do 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 todos os outros pacotes do PyPI:

   1. Configure um repositório virtual do Artifact Registry.
   2. Adicionar configuração para vários repositórios (incluindo PyPI, se necessário) e defina a ordem em que o 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 seu ambiente.

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

5. Instale os 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 fazer a instalação.

Configure papéis e permissões:

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

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

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 para a conta de serviço do ambiente em vez 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 pip.conf. e inclua as seguintes informações no arquivo, 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 do 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 você queira buscar pacotes em várias repositórios, como quando o repositório do Artifact Registry contém alguns pacotes específicos que você deseja instalar e deseja instalar Todos os outros pacotes do PyPI:

   1. Configure um repositório virtual do Artifact Registry.
   2. Adicionar configuração para vários repositórios (incluindo PyPI, se necessário) e defina a ordem em que o 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 o /config/pip/ no bucket do 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 privado na rede do seu projeto e configurar seu para instalar pacotes Python a partir dele.

Configurar funções e permissões:

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

2. Se você instalar pacotes PyPI personalizados de um repositório no arquivo e esse repositório não tem um endereço IP público:

   1. Atribua permissões para acessar esse repositório para o conta de serviço.

   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:

1. Crie um arquivo pip.conf e inclua as seguintes informações, 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]
   index-url=https://192.0.2.10/
   

2. (Opcional) Em alguns casos, convém buscar pacotes de vários repositórios, como quando o repositório particular contém alguns pacotes específicos que você quer instalar e 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 o PyPI, se necessário) e defina a ordem em que o pip pesquisa os repositórios.
   3. Especifique o URL do repositório virtual no parâmetro index-url.

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

   1. Faça upload do arquivo do certificado /config/pip/ no bucket do ambiente.

   2. Em pip.conf, especifique o nome do arquivo do certificado no cert . Não altere a pasta /etc/pip/.

      Exemplo:

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

4. Faça upload do arquivo pip.conf para o /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/ no bucket do seu 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 um imagem de build. 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 essa 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

Instalar pacotes em ambientes de IP particular

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

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 do PyPI. Nesse caso, nenhuma configuração especial é necessária. Siga o procedimento descrito em Instalar um pacote do PyPI.
• Instalar a partir 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 a partir de um repositório PyPI particular hospedado no seu na rede do projeto.

Ambiente de IP privado sem acesso à Internet

Se o ambiente de IP particular não tiver acesso à Internet pública, é possível instalar pacotes de 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 em um repositório PyPI na Internet pública. Especifique o endereço do proxy em o 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 o acesso a endereços IP externos da sua rede VPC, ative a instalação de pacotes de repositórios na Internet pública ao configurar o Cloud NAT.
• Coloque as dependências do Python na pasta /dags do bucket do seu 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 particular com 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. Especificamente, o Cloud Build não pode ser utilizada para instalação do pacote, impedindo o acesso direto a na Internet pública.

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

Instalar uma dependência do Python em um ambiente de IP privado 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 utilizada para instalação do pacote, impedindo o acesso direto a na Internet pública.

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

A seguir

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