Cloud Composer 1 | Cloud Composer 2
Nesta página, descrevemos como instalar pacotes Python para seu ambiente do Cloud Composer.
Sobre 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.
Os pacotes PyPI personalizados são aqueles que podem ser instalados no seu ambiente, além dos pré-instalados.
Opções para gerenciar pacotes PyPI para ambientes do Cloud Composer
Opção | Use se |
---|---|
Instalar usando o PyPI | A maneira padrão de instalar pacotes no seu ambiente |
Instalar a partir 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 seu projeto | Seu ambiente não tem acesso à Internet pública. O pacote está hospedado em um repositório de pacotes na rede do seu projeto. |
Instalar como uma biblioteca local do Python |
O pacote não pode ser encontrado em 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 modificar a interface da Web do Airflow. |
PythonVirtualenvOperator | Você não quer que o pacote seja instalado para todos os workers do Airflow ou que haja conflitos de dependência 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 usando 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 as 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 para um repositório PyPI particular.
- Os requisitos precisam seguir o formato especificado no PEP-508 (link em inglês), em que cada requisito é especificado em letras minúsculas e consiste no nome do pacote com especificadores de versão e 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.
Projetos em que a API Cloud Composer está ativada a partir de 29 de abril de 2024. A menos que sua organização modifique 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 na instalação de 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 no lugar. Portanto, conceda todas as permissões necessárias para acessar os pacotes particulares também para essa conta de serviço. Se você quiser que seus builds sejam executados com uma conta diferente, é possível substituir a variável de ambienteCOMPOSER_AGENT_BUILD_SERVICE_ACCOUNT
pela 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 precisa ter a permissãoiam.serviceAccounts.actAs
.
Ver a lista de pacotes PyPI
É possível conseguir a lista de pacotes para seu ambiente em vários formatos.
Ver pacotes pré-instalados
Para ver a lista de pacotes pré-instalados para 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 conseguir o resultado do
comando python -m pipdeptree --warn
.
gcloud beta composer environments list-packages \
ENVIRONMENT_NAME \
--location LOCATION
Substitua:
ENVIRONMENT_NAME
pelo nome do ambienteLOCATION
pela região em que o ambiente está localizado;
Conferir pacotes PyPI personalizados
Console
No console do Google Cloud, acesse a página Ambientes.
Na lista de ambientes, clique no nome do ambiente. A página Detalhes do ambiente é aberta.
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 ambienteLOCATION
pela região em que o ambiente está localizado;
Instalar pacotes personalizados em um ambiente do Cloud Composer
Esta seção descreve métodos diferentes para instalar pacotes personalizados no seu ambiente.
Instalar pacotes do PyPI
Um pacote poderá ser instalado a partir do Índice de pacotes Python se não tiver dependências externas ou entrar em conflito com os pacotes pré-instalados.
Para adicionar, atualizar ou excluir as dependências do Python no ambiente, faça o seguinte:
Console
No console do Google Cloud, acesse a página Ambientes.
Na lista de ambientes, clique no nome do ambiente. A página Detalhes do ambiente é aberta.
Acesse a guia Pacotes PyPI.
Clique em Editar.
Clique em Adicionar pacote.
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]
Clique em Salvar.
gcloud
CLI gcloud tem vários benefícios para trabalhar com pacotes PyPI personalizados:
--update-pypi-packages-from-file
substitui todos os pacotes PyPI personalizados atuais 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.
Requisitos de instalação usando 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 ambienteLOCATION
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 ambienteLOCATION
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 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 ambienteLOCATION
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:
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 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.
- Use a máscara
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 extras. Para omitir versões e extras, especifique um valor vazio.- Para adicionar mais de um pacote, adicione entradas extras para pacotes
a
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 ambienteLOCATION
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 extras. Para omitir versões e extras, especifique um valor vazio.- Para adicionar mais de um pacote, adicione entradas extras para pacotes
a
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 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 que tenha um endereço público:
Crie um arquivo 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/
- URL do repositório (no parâmetro
(Opcional) Em alguns casos, convém 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:
- Configure um repositório virtual do Artifact Registry.
- Adicione configuração para vários repositórios (incluindo PyPI, se necessário)
e defina a ordem em que
pip
pesquisa os repositórios. - Especifique o URL do repositório virtual no parâmetro
index-url
.
Faça upload do arquivo pip.conf para a pasta
/config/pip/
no bucket do ambiente.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 instalar a partir dele.
Configure papéis e permissões:
A conta de serviço do ambiente precisa ter o papel
iam.serviceAccountUser
.Verifique se a conta de serviço do Cloud Build tem permissões para ler o repositório do Artifact Registry.
Se o ambiente tiver restringido o acesso a outros serviços no projeto, por exemplo, se você usar o VPC Service Controls:
Atribua permissões para acessar o repositório do Artifact Registry na conta de serviço do ambiente em vez da conta de serviço do Cloud Build.
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:
Crie um arquivo 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, anexe
/simple/
ao URL do repositório:[global] index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
- URL do repositório do Artifact Registry (no parâmetro
(Opcional) Em alguns casos, convém 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:
- Configure um repositório virtual do Artifact Registry.
- Adicione configuração para vários repositórios (incluindo PyPI, se necessário)
e defina a ordem em que
pip
pesquisa os repositórios. - Especifique o URL do repositório virtual no parâmetro
index-url
.
Faça upload desse arquivo pip.conf para a pasta
/config/pip/
no bucket do ambiente. Por exemplo:gs://us-central1-example-bucket/config/pip/pip.conf
.Instale os 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 o ambiente para instalar pacotes Python a partir dele.
Configure papéis e permissões:
A conta de serviço do ambiente do Cloud Composer precisa ter o papel
iam.serviceAccountUser
.Se você instalar pacotes PyPI personalizados de um repositório na rede do projeto e esse repositório não tiver um endereço IP público:
Atribua permissões para acessar esse repositório para a conta de serviço do ambiente.
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:
Crie um arquivo pip.conf e inclua as seguintes informações no arquivo, 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/
(Opcional) Em alguns casos, convém buscar pacotes de vários repositórios, como quando o repositório privado contém alguns pacotes específicos que você quer instalar e você quer instalar todos os outros pacotes do PyPI:
- Configure um repositório virtual do Artifact Registry.
- Adicione configuração para vários repositórios (incluindo PyPI, se necessário)
e defina a ordem em que
pip
pesquisa os repositórios. - Especifique o URL do repositório virtual no parâmetro
index-url
.
(Opcional) Nas versões 2.2.1 e posteriores do Cloud Composer, é possível usar um certificado personalizado ao instalar pacotes do seu repositório particular. Para fazer isso, siga estas etapas:
Faça upload do arquivo de certificado para a pasta
/config/pip/
no bucket do ambiente.Em 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
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
.Instale os 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:
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 abaixo, a dependência é
coin_module.py
:dags/ use_local_deps.py # A DAG file. dependencies/ __init__.py coin_module.py
Importe a dependência do arquivo de definição do DAG.
Exemplo:
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 Operator 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 seu ambiente. Se os pacotes PyPI foram instalados, mas falharam no ambiente de execução, use esta opção.
- Encontre manualmente as bibliotecas de objetos compartilhados para a dependência PyPI (um arquivo .so).
- Faça o upload das bibliotecas de objetos compartilhados para a pasta
/plugins
no bucket do ambiente. - 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ê configurar 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:
- Instalar usando o 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 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 pacotes usando uma das maneiras a seguir:
- Use um repositório PyPI privado hospedado na rede do seu 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 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, ative a instalação de pacotes de repositórios na Internet pública configurando o Cloud NAT.
- Coloque 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 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. 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 mais 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 para um ambiente de IP particular dentro de um perímetro, siga as orientações para ambientes de IP particular sem acesso à Internet.