Instale dependências do Python

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

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

Acerca dos pacotes no Cloud Composer

Esta secção explica como funcionam os pacotes PyPI 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 pacotes incluídos na imagem do Cloud Composer do seu ambiente. Cada imagem do Cloud Composer contém pacotes PyPI específicos da sua versão do Cloud Composer e do Airflow.

• Os pacotes PyPI personalizados são pacotes que pode instalar no seu ambiente, além dos pacotes pré-instalados.

Nota: se planeia atualizar o seu ambiente, pode fazer uma verificação de atualização. Esta verificação comunica se os pacotes PyPI personalizados no seu ambiente têm conflitos com pacotes pré-instalados numa imagem do Cloud Composer posterior.

Opções para gerir pacotes PyPI para ambientes do Cloud Composer

Opção	Use se
Instale a partir do PyPI	A forma predefinida de instalar pacotes no seu ambiente
Instale a partir de um repositório com um endereço IP público	O pacote está alojado num repositório de pacotes que não seja o PyPI. Este repositório tem um endereço IP público
Instale a partir de um repositório do Artifact Registry	O pacote está alojado num repositório do Artifact Registry
Instale a partir de um repositório na rede do seu projeto	O seu ambiente não tem acesso à Internet pública. O pacote está alojado num repositório de pacotes na rede do seu projeto.
Instale como uma biblioteca Python local	Não é possível encontrar o pacote no PyPI e a biblioteca não tem dependências externas, como dist-packages.
Instale um plugin	O pacote oferece funcionalidades específicas do plug-in, como a modificação da interface Web do Airflow.
PythonVirtualenvOperator	Não quer que o pacote seja instalado para todos os trabalhadores do Airflow ou a dependência entra 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	Precisa de dependências externas que não podem ser instaladas a partir do pip, como o dist-packages, ou estão num servidor pip interno. Esta opção requer mais configuração e manutenção. Considere esta opção apenas se outras opções não funcionarem.

Antes de começar

• Tem de ter uma função que possa acionar operações de atualização do ambiente. Além disso, a conta de serviço do ambiente tem de ter uma função com autorizações suficientes para realizar operações de atualização.

  Importante: quando instala pacotes PyPI no seu ambiente, o Airflow executa código Python a partir do pacote instalado. Certifique-se de que instala pacotes provenientes de fontes fidedignas. Os utilizadores com a autorização composer.environments.update podem executar código Python em nome da conta de serviço do ambiente quando instalam pacotes no seu ambiente. Para mais informações, consulte o artigo Controlo de acesso.

• Se o seu ambiente estiver protegido por um perímetro dos VPC Service Controls, antes de instalar dependências do PyPI, tem de conceder identidades de utilizador adicionais com acesso a serviços que o perímetro de serviço protege e ativar o suporte para um repositório privado do PyPI.

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

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

  Aviso: não modifique nem elimine as imagens criadas pelo Cloud Composer no Artifact Registry ou no próprio repositório. Não carregue as suas próprias imagens para o repositório. Em alternativa, crie e mantenha o seu próprio repositório para as suas imagens (por exemplo, para imagens usadas pelo KubernetesPodOperator). Não elimine este repositório por sua conta. O repositório é eliminado depois de eliminar o ambiente.

• Se um conflito de dependências fizer com que a atualização falhe, o seu ambiente continua a ser executado com as dependências existentes. Se a operação for bem-sucedida, pode começar a usar as dependências do Python recém-instaladas nos seus DAGs.

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

  Obsoleto: se a conta de serviço antiga do Cloud Build estiver disponível no seu projeto, o seu ambiente usa-a para criar imagens. Recomendamos vivamente que configure uma conta de serviço especificada pelo utilizador em vez disso, conforme descrito no artigo Alteração da conta de serviço predefinida do Cloud Build.

• Projetos em que a API Cloud Composer está ativada a 29 de abril de 2024 ou posteriormente. A menos que a sua organização substitua a política, os novos projetos não aprovisionam a conta de serviço do Cloud Build antiga quando a API é ativada.constraints/cloudbuild.disableCreateDefaultServiceAccount Uma vez que o Cloud Build é usado por predefinição quando instala pacotes PyPI personalizados no ambiente do Cloud Composer, a instalação de pacotes pode falhar. Por predefinição, é usada a conta de serviço do ambiente. Por isso, certifique-se de que concede também a essa conta de serviço todas as autorizações adicionais necessárias para aceder aos seus pacotes privados.

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

Veja a lista de pacotes PyPI

Pode obter a lista de pacotes para o seu ambiente em vários formatos.

Veja pacotes pré-instalados

Para ver a lista de pacotes pré-instalados para o seu ambiente, consulte a lista de pacotes para a 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 seguinte comando da CLI gcloud devolve o resultado do comando python -m pip list para um trabalhador do Airflow no seu ambiente. Pode usar o argumento --tree para obter o resultado do comando python -m pipdeptree --warn.

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

Substituir:

• ENVIRONMENT_NAME com o nome do ambiente.
• LOCATION com a região onde o ambiente está localizado.

Veja pacotes PyPI personalizados

Consola

1. Na Google Cloud consola, aceda à página Ambientes.

   Aceder a Ambientes

2. Na lista de ambientes, clique no nome do seu ambiente. É apresentada a página Detalhes do ambiente.

3. Aceda ao separador Pacotes do PyPI.

gcloud

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

Substituir:

• ENVIRONMENT_NAME com o nome do ambiente.
• LOCATION com a região onde o ambiente está localizado.

Instale pacotes personalizados num ambiente do Cloud Composer

Esta secção descreve diferentes métodos de instalação de pacotes personalizados no seu ambiente.

Instale pacotes a partir do PyPI

Pode instalar um pacote a partir do Python Package Index se não tiver dependências externas nem conflitos com pacotes pré-instalados.

Nota: pode relaxar 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 eliminar as dependências do Python para o seu ambiente:

Consola

1. Na Google Cloud consola, aceda à página Ambientes.

   Aceder a Ambientes

2. Na lista de ambientes, clique no nome do seu ambiente. É apresentada a página Detalhes do ambiente.

3. Aceda ao separador Pacotes PyPI.

4. Clique em Editar

5. Clique em Adicionar pacote.

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

   Por exemplo:

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

7. Clique em Guardar.

gcloud

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

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

Instalar requisitos a partir de um ficheiro

O ficheiro requirements.txt tem de ter cada especificador de requisito numa linha separada.

Por exemplo:

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

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

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

Substituir:

• ENVIRONMENT_NAME com o nome do ambiente.
• LOCATION com a região onde o ambiente está localizado.

Instalar um pacote

Atualize o seu 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

Substituir:

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

Nota: consoante o seu ambiente de execução, pode ter de interpretar de forma literal carateres especiais, como >. Para evitar potenciais problemas, coloque o nome do pacote e a versão 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"

Remover pacotes

Atualize o seu ambiente e especifique os pacotes que quer eliminar no argumento --remove-pypi-packages:

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

Substituir:

• ENVIRONMENT_NAME com o nome do ambiente.
• LOCATION com a região onde o ambiente está localizado.
• PACKAGE_NAMES com 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

Construa um pedido de API environments.patch.

Neste pedido:

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

   • Use a máscara config.softwareConfig.pypiPackages para substituir todos os pacotes existentes pelos pacotes especificados. Os pacotes que não especificar são eliminados.
   • 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 do pedido, especifique pacotes e valores para versões e extras:

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

   Substituir:

   • PACKAGE_NAME com o nome do pacote.
   • EXTRAS_AND_VERSION com o especificador de versão e extras opcional. Para omitir versões e extras, especifique um valor vazio.
   • Para adicionar mais do que um pacote, adicione entradas adicionais para pacotes para 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 os pacotes.

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

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

Substituir:

• ENVIRONMENT_NAME com o nome do ambiente.
• LOCATION com a região onde o ambiente está localizado.
• PACKAGE_NAME com o nome do pacote.
• EXTRAS_AND_VERSION com o especificador de versão e extras opcional. Para omitir versões e extras, especifique um valor vazio.
• Para adicionar mais do que um pacote, adicione entradas adicionais para pacotes para 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]"
      }
    }
  }
}

Instale pacotes a partir de um repositório público

Pode instalar pacotes alojados noutros repositórios que tenham um endereço IP público.

Os pacotes têm de estar corretamente configurados para que a ferramenta pip predefinida os possa instalar.

Nota: o Cloud Composer não suporta a personalização do pip e não resolve dependências nem conflitos de pacotes fora dos mecanismos de resolução que a ferramenta pip predefinida oferece.

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

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

   • URL do repositório (no parâmetro index-url)
   • Credenciais de acesso ao repositório
   • Opções de instalação não predefinidas pip

   Exemplo:

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

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

3. Determine o URI do contentor do seu ambiente.

4. Carregue o ficheiro pip.conf para a pasta /config/pip/ no contentor do seu ambiente.

5. Instale pacotes através de um dos métodos disponíveis.

Instale pacotes a partir de um repositório do Artifact Registry

Pode armazenar pacotes num repositório do Artifact Registry no seu projeto e configurar o seu ambiente para instalar a partir dele.

Nota: se usar o VPC Service Controls, pode criar um repositório PyPI do Artifact Registry no modo VPC. Neste caso, siga o procedimento para repositórios privados ao atribuir autorizações.

Configure funções e autorizações:

1. Certifique-se de que a conta de serviço do Cloud Build tem autorizações para ler a partir do seu repositório do Artifact Registry.

2. Conceda autorizações adicionais para instalar pacotes de repositórios do Artifact Registry na conta de serviço do seu ambiente, conforme descrito no artigo Controlo de acesso.

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

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

   2. Certifique-se de que a conetividade ao repositório do Artifact Registry está configurada no seu projeto.

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

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

   • URL do repositório do Artifact Registry (no parâmetro index-url)
   • Credenciais de acesso ao repositório
   • Opções de instalação não predefinidas pip

   Para um repositório do Artifact Registry, anexe /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, pode querer obter pacotes de vários repositórios, como quando o seu repositório do Artifact Registry contém alguns pacotes específicos que quer instalar e 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 o PyPI, se necessário) e defina a ordem pela qual o pip pesquisa os repositórios.
   3. Especifique o URL do repositório virtual no parâmetro index-url.

3. Carregue este ficheiro pip.conf para a pasta /config/pip/ no contentor do seu ambiente. Por exemplo: gs://us-central1-example-bucket/config/pip/pip.conf.

4. Instale pacotes através de um dos métodos disponíveis.

Instale pacotes a partir de um repositório privado

Pode alojar um repositório privado na rede do seu projeto e configurar o seu ambiente para instalar pacotes Python a partir dele.

Configure funções e autorizações:

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

   1. Atribua autorizações para aceder a este repositório à conta de serviço do ambiente.

   2. Certifique-se de que a conetividade a este repositório está configurada no seu projeto.

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

Para instalar pacotes a partir de um repositório privado alojado na rede do seu projeto:

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

   • Endereço IP do repositório na rede do seu projeto
   • Credenciais de acesso ao repositório
   • Opções de instalação não predefinidas pip

   Exemplo:

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

2. (Opcional) Em alguns casos, pode querer obter pacotes de vários repositórios, como quando o repositório privado contém alguns pacotes específicos que quer instalar e 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 o PyPI, se necessário) e defina a ordem pela qual 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 posteriores do Cloud Composer, pode usar um certificado personalizado ao instalar pacotes do seu repositório privado. Para isso:

   1. Carregue o ficheiro de certificado para a pasta /config/pip/ no contentor do seu ambiente.

      Aviso: não carregue chaves privadas. Carregue apenas um pacote de certificados públicos no formato PEM. Verifique se o pacote de certificados contém a AC raiz correta.

   2. Em pip.conf, especifique o nome do ficheiro de certificado no parâmetro cert. Não altere a pasta /etc/pip/.

      Exemplo:

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

4. Carregue o ficheiro pip.conf para a pasta /config/pip/ no contentor do seu ambiente. Por exemplo: gs://us-central1-example-bucket/config/pip/pip.conf.

5. Instale pacotes através de um dos métodos disponíveis.

Instale uma biblioteca Python local

Para instalar uma biblioteca Python interna ou local:

1. Coloque as dependências num subdiretório na pasta dags/ no contentor do seu ambiente. Para importar um módulo de um subdiretório, cada subdiretório no caminho do módulo tem de conter um ficheiro de marcador de pacote __init__.py.

   No exemplo seguinte, 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 ficheiro de definição do DAG.

   Por exemplo:

from dependencies import coin_module

Nota: ocorre um erro de importação se faltar um ficheiro __init__.py. Os nomes de diretórios e ficheiros têm de ser identificadores Python válidos.

Use pacotes que dependam de bibliotecas de objetos partilhados

Determinados pacotes do PyPI dependem de bibliotecas ao nível do sistema. Embora o Cloud Composer não suporte bibliotecas do sistema, pode usar as seguintes opções:

• Use o KubernetesPodOperator. Defina a imagem do operador para uma imagem de compilação personalizada. Se tiver pacotes que falham durante a instalação devido a uma dependência do sistema não cumprida, use esta opção.

• Carregue as bibliotecas de objetos partilhadas para o contentor do seu ambiente. Se os pacotes PyPI tiverem sido instalados com êxito, mas falharem no tempo de execução, use esta opção.

  1. Encontre manualmente as bibliotecas de objetos partilhados para a dependência do PyPI (um ficheiro .so).
  2. Carregue as bibliotecas de objetos partilhadas para a pasta /plugins no contentor do seu ambiente.
  3. Defina a seguinte variável de ambiente: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

Nota: os ficheiros nas pastas plugins/são sincronizados com o sistema de ficheiros local. O carregamento de ficheiros .so grandes pode afetar o desempenho do seu ambiente e do servidor Web do Airflow.

Instale pacotes em ambientes de IP privado

Consoante a forma como configura o seu projeto, o seu ambiente pode não ter acesso à Internet pública.

Ambiente de IP privado com acesso à Internet pública

Se o seu ambiente de IP privado puder aceder à Internet pública, pode instalar pacotes através de opções para ambientes de IP público:

• Instale a partir do PyPI. Neste caso, não é necessária nenhuma configuração especial. Siga o procedimento descrito no artigo Instale um pacote a partir do PyPI.
• Instale a partir de um repositório com um endereço IP público. Siga o procedimento descrito no artigo Instale um pacote a partir de um repositório privado.
• Instale a partir de um repositório PyPI privado alojado na rede do seu projeto.

Ambiente de IP privado sem acesso à Internet

Se o seu ambiente de IP privado não tiver acesso à Internet pública, pode instalar pacotes de uma das seguintes formas:

• Use um repositório PyPI privado alojado na rede do seu projeto.
• Use uma VM de servidor proxy na rede do seu projeto para se ligar a um repositório PyPI na Internet pública. Especifique o endereço do proxy no ficheiro /config/pip/pip.conf no contentor do seu ambiente.
• Use um repositório do Artifact Registry como a única origem de pacotes. Para tal, redefina o parâmetro index-url, conforme descrito.
• Se a sua política de segurança permitir o acesso a endereços IP externos a partir da sua rede VPC, pode 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 contentor do seu ambiente para as instalar como bibliotecas locais. Esta pode não ser uma boa opção se a árvore de dependências for grande.

Instale num ambiente de IP privado ao abrigo das restrições de localização de recursos

Manter o seu projeto em conformidade com os requisitos de restrição de localização de recursos proíbe a utilização de algumas ferramentas. Em particular, não é possível usar o Cloud Build para a instalação de pacotes, o que impede o acesso direto a repositórios na Internet pública.

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

Instale uma dependência do Python num ambiente de IP privado num perímetro do VPC Service Controls

A proteção do seu projeto com um perímetro dos VPC Service Controls resulta em restrições de segurança adicionais. Em particular, não é possível usar o Cloud Build para a instalação de pacotes, o que impede o acesso direto a repositórios na Internet pública.

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

O que se segue?

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