Cloud Composer 1 | Cloud Composer 2
Nesta seção, descrevemos como criar, configurar e executar um ambiente local do Airflow usando a ferramenta CLI de desenvolvimento local do Composer.
Sobre a ferramenta CLI de desenvolvimento local do Composer
A ferramenta de CLI de desenvolvimento local do Composer simplifica o desenvolvimento de DAGs do Apache Airflow para o Cloud Composer executando um ambiente do Airflow localmente. Esse ambiente local do Airflow usa uma imagem de uma versão específica do Cloud Composer.
É possível criar um ambiente local do Airflow com base em um ambiente atual do Cloud Composer. Nesse caso, o ambiente local do Airflow usa a lista de pacotes PyPI instalados e nomes variável de ambiente do ambiente do Cloud Composer.
É possível usar esse ambiente local do Airflow para fins de teste e desenvolvimento, como testar novos códigos DAG, pacotes PyPI ou opções de configuração do Airflow.
Antes de começar
A ferramenta CLI de desenvolvimento local do Composer cria ambientes locais do Airflow em um diretório em que você executa o comando
composer-dev create
. Para acessar o ambiente local do Airflow mais tarde, execute os comandos da ferramenta no caminho em que você criou inicialmente o ambiente. Todos os dados do ambiente local são armazenados em um subdiretório no caminho em que você criou o ambiente local:./composer/<local_environment_name>
.Seu computador precisa ter espaço em disco suficiente para armazenar as imagens do Cloud Composer. A ferramenta CLI de desenvolvimento local do Composer armazena um arquivo de imagem para cada versão do Cloud Composer. Por exemplo, se você tiver dois ambientes locais do Airflow com versões diferentes do Cloud Composer, a ferramenta de CLI de desenvolvimento local do Composer armazenará duas imagens do Cloud Composer.
A ferramenta de CLI de desenvolvimento local do Composer usa saída colorida. É possível desativar a saída colorida com a variável
NO_COLOR=1
:NO_COLOR=1 composer-dev <other commands>
.Se você tiver apenas um ambiente local, omita o nome dele de todos os comandos
composer-dev
, excetorun-airflow-cmd
.Instale as dependências da ferramenta CLI de desenvolvimento local do Composer:
- Versões 3.7 a 3.10 do Python com
pip
- Google Cloud CLI
- Versões 3.7 a 3.10 do Python com
Instalar o Docker. O Docker precisa estar instalado e em execução no sistema local. Para verificar se o Docker está em execução, execute qualquer comando da CLI do Docker, como
docker ps
.
Configurar credenciais
Caso ainda não tenha feito isso, consiga novas credenciais de usuário para usar no Application Default Credentials:
gcloud auth application-default login
Faça login na CLI gcloud usando sua Conta do Google:
gcloud auth login
Todas as chamadas de API feitas pela ferramenta CLI de desenvolvimento local do Composer e pelos DAGs são executadas na conta que você usa na CLI gcloud. Por exemplo, se um DAG no ambiente local do Airflow ler o conteúdo de um bucket do Cloud Storage, essa conta precisará ter permissões para acessar o bucket. Isso é diferente dos ambientes do Cloud Composer, em que uma conta de serviço faz as chamadas.
Instalar a ferramenta CLI de desenvolvimento local do Composer
Clone o repositório da CLI de desenvolvimento local do Composer:
git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git
No diretório de nível superior do repositório clonado, execute:
pip install .
Dependendo da configuração de pip
, o caminho em que a ferramenta está instalada
pode não estar na variável PATH
. Se esse for o caso, pip
exibirá uma mensagem de
aviso. É possível usar as informações desta mensagem de aviso para adicionar esse diretório à variável PATH
no seu sistema operacional.
Criar um ambiente local do Airflow com uma versão específica do Cloud Composer
Para listar as versões disponíveis do Cloud Composer, execute:
composer-dev list-available-versions --include-past-releases --limit 10
Para criar um ambiente local do Airflow com parâmetros padrão, execute:
composer-dev create \
--from-image-version IMAGE_VERSION \
LOCAL_ENVIRONMENT_NAME
Outros parâmetros:
composer-dev create \
--from-image-version IMAGE_VERSION \
--project PROJECT_ID \
--port WEB_SERVER_PORT \
--dags-path LOCAL_DAGS_PATH \
LOCAL_ENVIRONMENT_NAME
Substitua:
IMAGE_VERSION
pelo nome da imagem do Cloud Composer.PROJECT_ID
pelo ID do projeto;WEB_SERVER_PORT
pela porta em que o servidor da Web do Airflow precisa detectar.LOCAL_DAGS_PATH
pelo caminho para um diretório local em que os arquivos DAG estão localizados.LOCAL_ENVIRONMENT_NAME
pelo nome deste ambiente local do Airflow.
Exemplo:
composer-dev create \
--from-image-version composer-2.8.1-airflow-2.7.3 \
example-local-environment
Criar um ambiente local do Airflow a partir de um ambiente do Cloud Composer
Somente as informações a seguir são extraídas de um ambiente do Cloud Composer:
- Versão de imagem (versões do Cloud Composer e do Airflow usadas no seu ambiente).
- Lista de pacotes PyPI personalizados instalados no ambiente.
Lista comentada de nomes das variáveis de ambiente definidas no seu ambiente.
Outras informações e parâmetros de configuração do ambiente, como arquivos DAG, histórico de execuções do DAG, variáveis do Airflow e conexões, não são copiados do ambiente do Cloud Composer.
Para criar um ambiente local do Airflow a partir de um ambiente atual do Cloud Composer:
composer-dev create LOCAL_ENVIRONMENT_NAME \
--from-source-environment ENVIRONMENT_NAME \
--location LOCATION \
--project PROJECT_ID \
--port WEB_SERVER_PORT \
--dags-path LOCAL_DAGS_PATH
Substitua:
LOCAL_ENVIRONMENT_NAME
por um nome para o ambiente local do Airflow.ENVIRONMENT_NAME
pelo nome do ambiente do Cloud Composer.LOCATION
pela região em que o ambiente do Cloud Composer está localizado.PROJECT_ID
pelo ID do projeto;WEB_SERVER_PORT
por uma porta para o servidor da Web local do Airflow.LOCAL_DAGS_PATH
por um caminho para um diretório local em que os DAGs estão localizados.
Exemplo:
composer-dev create example-local-environment \
--from-source-environment example-environment \
--location us-central1 \
--project example-project \
--port 8081 \
--dags-path example_directory/dags
Iniciar um ambiente local do Airflow
Para iniciar um ambiente local do Airflow, execute:
composer-dev start LOCAL_ENVIRONMENT_NAME
Substitua:
LOCAL_ENVIRONMENT_NAME
pelo nome de um ambiente local do Airflow.
Interromper ou reiniciar um ambiente local do Airflow
Quando você reinicia um ambiente local do Airflow, a ferramenta da CLI de desenvolvimento local do Composer reinicia o contêiner do Docker em que o ambiente é executado. Todos os componentes do Airflow são interrompidos e iniciados novamente. Como resultado, todas as execuções do DAG feitas durante uma reinicialização são marcadas como falhas .
Para reiniciar ou iniciar um ambiente local do Airflow que foi interrompido, execute:
composer-dev restart LOCAL_ENVIRONMENT_NAME
Substitua:
LOCAL_ENVIRONMENT_NAME
pelo nome de um ambiente local do Airflow.
Para interromper um ambiente local do Airflow, execute:
composer-dev stop LOCAL_ENVIRONMENT_NAME
Adicionar e atualizar DAGs
Os DAgs são armazenados no diretório especificado no parâmetro --dags-path
quando você criou o ambiente local do Airflow. Por padrão, esse diretório é ./composer/<local_environment_name>/dags
. Você pode acessar o diretório usado pelo seu ambiente com o comando describe
.
Para adicionar e atualizar DAGs, altere os arquivos neste diretório. Não é necessário reiniciar o ambiente local do Airflow.
Conferir os registros locais do ambiente do Airflow
É possível ver os registros recentes de um contêiner do Docker que executa seu ambiente local do Airflow. Dessa forma, é possível monitorar eventos relacionados a contêineres e verificar os registros do Airflow para encontrar erros, como conflitos de dependência causados pela instalação de pacotes PyPI.
Para ver os registros de um contêiner do Docker que executa seu ambiente local do Airflow, execute:
composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10
Para acompanhar o fluxo de registros, omita o argumento --max-lines
:
composer-dev logs LOCAL_ENVIRONMENT_NAME
executar um comando da CLI do Airflow
É possível executar comandos da CLI do Airflow no ambiente local do Airflow.
Para executar um comando da CLI do Airflow:
composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
SUBCOMMAND SUBCOMMAND_ARGUMENTS
Exemplo:
composer-dev run-airflow-cmd example-local-environment dags list -o table
configurar ambientes locais do Airflow
A ferramenta CLI de desenvolvimento local do Composer armazena parâmetros de configuração para um ambiente local do Airflow, como variáveis de ambiente e requisitos de pacote PyPI no diretório do ambiente local (./composer/<local_environment_name>
).
A configuração é aplicada quando um ambiente local do Airflow é iniciado. Por exemplo, se você adicionar requisitos de pacote PyPI conflitantes, a ferramenta de CLI de desenvolvimento local do Composer informará erros quando você iniciar o ambiente local.
As conexões do Airflow são armazenadas no banco de dados do ambiente local do Airflow. É possível configurá-los executando um comando da CLI do Airflow ou armazenando os parâmetros de conexão nas variáveis de ambiente. Para mais informações sobre maneiras de criar e configurar conexões, consulte Como gerenciar conexões na documentação do Airflow.
Acessar uma lista e o status dos ambientes locais do Airflow
Para listar todos os ambientes locais disponíveis do Airflow e exibir o status deles:
composer-dev list
Para descrever um ambiente específico e acessar detalhes como a versão da imagem, o caminho dos DAGs e o URL do servidor da Web de um ambiente:
composer-dev describe LOCAL_ENVIRONMENT_NAME
Substitua:
LOCAL_ENVIRONMENT_NAME
pelo nome do ambiente local do Airflow.
Listar imagens usadas por ambientes locais do Airflow
Para listar todas as imagens usadas pela ferramenta de CLI de desenvolvimento local do Composer, execute:
docker images --filter=reference='*/cloud-airflow-releaser/*/*'
Instalar plug-ins e alterar dados
Os plug-ins e os dados de um ambiente local do Airflow são recebidos do diretório do ambiente local: ./composer/<local_environment_name>/data
e ./composer/<local_environment_name>/plugins
.
Para mudar o conteúdo dos diretórios /data
e /plugins
, adicione ou remova
arquivos deles. Ele propaga automaticamente as alterações de arquivo para o ambiente local do Airflow.
A ferramenta CLI de desenvolvimento local do Composer não oferece suporte à especificação de um diretório diferente para dados e plug-ins.
Configure as variáveis de ambiente
Para configurar variáveis de ambiente, edite o arquivo variables.env
no diretório de ambiente:
./composer/<local_environment_name>/variables.env
.
O arquivo variables.env
precisa conter definições de chave-valor, uma linha para cada variável de ambiente. Para alterar as opções de configuração do Airflow, use o formato AIRFLOW__SECTION__KEY
. Para mais informações sobre as variáveis de ambiente disponíveis, consulte a referência de configuração do Airflow.
EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph
Para aplicar as mudanças, reinicie o ambiente local do Airflow.
Instalar ou remover pacotes PyPI
Para instalar ou remover pacotes PyPI, modifique o arquivo requirements.txt
no diretório do ambiente: ./composer/<local_environment_name>/requirements.txt
.
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 especificadores de versão e extras opcionais.
Para aplicar as mudanças, reinicie o ambiente local do Airflow.
Alternar para uma imagem diferente do Cloud Composer
É possível usar qualquer imagem do Cloud Composer com a ferramenta CLI de desenvolvimento local do Composer e alternar entre as imagens. Essa abordagem é diferente de fazer upgrade do ambiente do Cloud Composer, porque os parâmetros de configuração do ambiente local do Airflow são aplicados quando ele é iniciado.
Por exemplo, após o lançamento de uma nova versão do Cloud Composer, é possível mudar o ambiente para usar a nova versão e manter a configuração atual do ambiente local do Airflow. Como outro exemplo, é possível alternar entre diferentes versões do Airflow em uma versão específica do Cloud Composer.
Para alterar a imagem do ambiente usada pelo ambiente local do Airflow:
Edite o arquivo de configuração do ambiente local:
./composer/<local_environment_name>/config.json
.Mude o valor do parâmetro
composer_image_version
. Para ver os valores disponíveis, liste as versões disponíveis do Cloud Composer.Para aplicar as mudanças, reinicie o ambiente local do Airflow.
Excluir um ambiente local do Airflow
Cuidado:verifique se você salvou todos os dados necessários do ambiente, como registros e configurações.
Para excluir um ambiente local do Airflow, execute o seguinte comando:
composer-dev remove LOCAL_ENVIRONMENT_NAME
Se o ambiente estiver em execução, adicione a sinalização --force
para forçar a remoção.
Excluir imagens do Docker
Para excluir todas as imagens transferidas por download pela ferramenta de CLI de desenvolvimento local do Composer, execute:
docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)
Solução de problemas
Esta seção fornece soluções para problemas comuns.
Não foi possível iniciar um ambiente local no MacOS
Se você instalou o pacote composer-dev
em um diretório em que o Docker não pode acessá-lo, é possível que seu ambiente local não seja iniciado.
Por exemplo, se o Python estiver instalado no diretório /opt
, como quando você
o instala com a configuração padrão do Homebrew no MacOS, o
pacote composer-dev
também será instalado no diretório /opt
. Como
o Docker está em conformidade com as regras de sandbox da Apple, o diretório /opt
não
está disponível por padrão. Além disso, não é possível adicioná-lo pela UI (Configurações
> Recursos > Compartilhamento de arquivos).
Nesse caso, a ferramenta de CLI de desenvolvimento local do Composer gera uma mensagem de erro semelhante ao seguinte exemplo:
Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh
Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")
É possível usar uma das seguintes soluções:
- Instale o Python ou o pacote
composer-dev
em um diretório diferente para que o Docker possa acessar o pacote. - Edite manualmente o arquivo
~/Library/Group\ Containers/group.com.docker/settings.json
e adicione/opt
afilesharingDirectories
.