Executar um ambiente local do Airflow com a ferramenta de CLI de desenvolvimento local do Composer

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Esta seção descreve como criar, configurar e executar um ambiente local do Airflow usando a ferramenta de CLI de desenvolvimento local do Composer.

Sobre a ferramenta de 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 build do Airflow usada por uma versão específica do Cloud Composer.

É possível criar um ambiente local do Airflow com base em um ambiente do Cloud Composer. Nesse caso, o ambiente local do Airflow usa a lista de pacotes PyPI instalados e os nomes das 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 de 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 seu ambiente local do Airflow mais tarde, execute os comandos da ferramenta no caminho em que você criou o ambiente local inicialmente. 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>.

  • O computador precisa ter espaço em disco suficiente para armazenar imagens de build do Airflow. A ferramenta CLI de desenvolvimento local do Composer armazena um arquivo de imagem para cada build do Airflow. Por exemplo, se você tiver dois ambientes locais do Airflow com builds diferentes, a ferramenta de CLI de desenvolvimento local do Composer vai armazenar duas imagens de build do Airflow.

  • A ferramenta 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, poderá omitir o nome dele de todos os comandos composer-dev, exceto o run-airflow-cmd.

  • Instale as dependências da ferramenta CLI de desenvolvimento local do Composer:

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

Se ainda não tiver feito isso, consiga novas credenciais de usuário para usar com o 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 usada na CLI gcloud. Por exemplo, se um DAG no seu 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 a conta de serviço de um ambiente 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 do pip, o caminho em que a ferramenta está instalada pode não estar na variável PATH. Nesse caso, o pip mostra uma mensagem de aviso. Use as informações dessa mensagem de aviso para adicionar o diretório à variável PATH no seu sistema operacional.

Criar um ambiente local do Airflow com uma imagem de build do Airflow

Para listar as imagens de build do Airflow disponíveis, 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 de build do Airflow.
  • PROJECT_ID pelo ID do projeto;
  • WEB_SERVER_PORT com a porta em que o servidor da Web do Airflow precisa detectar.
  • LOCAL_DAGS_PATH com o caminho para um diretório local onde os arquivos DAG estão localizados.
  • LOCAL_ENVIRONMENT_NAME com o nome do ambiente local do Airflow.

Exemplo:

composer-dev create \
  --from-image-version composer-3-airflow-2.10.5-build.12 \
  example-local-environment

Criar um ambiente local do Airflow com base em um ambiente do Cloud Composer

Somente as seguintes informações são extraídas de um ambiente do Cloud Composer:

  • Build específico do Airflow usado pelo seu ambiente.

  • Lista de pacotes PyPI personalizados instalados no seu ambiente.

  • Lista comentada de nomes de variáveis de ambiente definidas no seu ambiente.

Outras informações e parâmetros de configuração do ambiente, como arquivos de DAG, histórico de execução de DAG, variáveis e conexões do Airflow, não são copiados do ambiente do Cloud Composer.

Para criar um ambiente local do Airflow com base em um ambiente 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 com um nome para o ambiente local do Airflow.
  • ENVIRONMENT_NAME com o nome do ambiente do Cloud Composer.
  • LOCATION é a região em que o ambiente do Cloud Composer está localizado.
  • PROJECT_ID pelo ID do projeto;
  • WEB_SERVER_PORT com uma porta para o servidor da Web do Airflow local.
  • LOCAL_DAGS_PATH com um caminho para um diretório local onde 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 com o nome de um ambiente local do Airflow.

Parar ou reiniciar um ambiente local do Airflow

Quando você reinicia um ambiente local do Airflow, a ferramenta de linha de comando 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 reiniciados. Como resultado, todas as execuções de DAG que são executadas durante uma reinicialização são marcadas como falhas .

Para reiniciar ou iniciar um ambiente local do Airflow interrompido, execute:

composer-dev restart LOCAL_ENVIRONMENT_NAME

Substitua:

  • LOCAL_ENVIRONMENT_NAME com o 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 ao criar o ambiente local do Airflow. Por padrão, esse diretório é ./composer/<local_environment_name>/dags. É possível acessar o diretório usado pelo seu ambiente com o comando describe.

Para adicionar e atualizar DAGs, mude os arquivos neste diretório. Não é necessário reiniciar o ambiente local do Airflow.

Conferir registros do ambiente local do Airflow

É possível ver os registros recentes de um contêiner do Docker que executa seu ambiente local do Airflow. Assim, é possível monitorar eventos relacionados a contêineres e verificar os registros do Airflow em busca de erros, como conflitos de dependência causados pela instalação de pacotes PyPI.

Para conferir 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 seguir 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 seu 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 pacotes 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 CLI de desenvolvimento local do Composer vai informar erros ao iniciar o ambiente local.

As conexões do Airflow são armazenadas no banco de dados do ambiente local do Airflow. É possível configurar essas variáveis executando um comando da CLI do Airflow ou armazenando os parâmetros de conexão em variáveis de ambiente. Para mais informações sobre como criar e configurar conexões, consulte Gerenciar conexões na documentação do Airflow.

Receber uma lista e o status dos ambientes locais do Airflow

Para listar todos os ambientes locais do Airflow disponíveis e mostrar o status deles:

composer-dev list

Para descrever um ambiente específico e receber detalhes como versão da imagem, caminho dos DAGs e URL do servidor da Web de um ambiente:

composer-dev describe LOCAL_ENVIRONMENT_NAME

Substitua:

  • LOCAL_ENVIRONMENT_NAME com o nome do ambiente local do Airflow.

Listar imagens usadas por ambientes locais do Airflow

Para listar todas as imagens usadas pela ferramenta CLI de desenvolvimento local do Composer, execute:

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

Instalar plug-ins e mudar dados

Os plug-ins e dados de um ambiente local do Airflow são extraídos 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 nesses diretórios. O Docker propaga automaticamente as mudanças de arquivo para seu ambiente local do Airflow.

A ferramenta de CLI de desenvolvimento local do Composer não permite especificar 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 do 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 mudar 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 seu 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. Nele, cada requisito é especificado em letras minúsculas e consiste no nome do pacote com especificadores de versão e atributos extras opcionais.

Para aplicar as mudanças, reinicie seu ambiente local do Airflow.

Mudar para outra imagem de build do Airflow

É possível usar qualquer imagem de build do Airflow com a ferramenta de 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, depois que uma nova build do Airflow for lançada, você poderá mudar seu ambiente para usá-la e manter a configuração do ambiente local do Airflow.

Para mudar a imagem do ambiente usada pelo seu ambiente local do Airflow:

  1. Edite o arquivo de configuração do ambiente local: ./composer/<local_environment_name>/config.json.

  2. Mude o valor do parâmetro composer_image_version. Para conferir os valores disponíveis, liste as imagens disponíveis.

  3. Para aplicar as mudanças, reinicie seu ambiente local do Airflow.

Excluir um ambiente local do Airflow

Atenção:salve todos os dados necessários do ambiente, como registros e configuração.

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 flag --force para forçar a remoção.

Excluir imagens do Docker

Para excluir todas as imagens baixadas pela ferramenta de linha de comando de desenvolvimento local do Composer, execute:

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

Solução de problemas

Esta seção oferece soluções para problemas comuns.

Não é possível iniciar um ambiente local no MacOS

Se você instalou o pacote composer-dev em um diretório que o Docker não consegue acessar, talvez o 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 obedece às regras de sandbox da Apple, o diretório /opt não está disponível por padrão. Além disso, não é possível adicionar esse recurso pela UI (Configurações > Recursos > Compartilhamento de arquivos).

Nesse caso, a ferramenta CLI de desenvolvimento local do Composer gera uma mensagem de erro semelhante ao exemplo a seguir:

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...")

Use 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 a filesharingDirectories.

A seguir