Execute um ambiente Airflow local com a ferramenta Composer Local Development CLI

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

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

Acerca da ferramenta CLI de desenvolvimento local do Composer

A ferramenta CLI de desenvolvimento local do Composer simplifica o desenvolvimento de DAGs do Apache Airflow para o Cloud Composer através da execução de um ambiente do Airflow localmente. Este ambiente Airflow local usa uma imagem de compilação do Airflow usada por uma versão do Cloud Composer específica.

Pode criar um ambiente do Airflow local com base num ambiente do Cloud Composer existente. Neste caso, o ambiente Airflow local recebe a lista de pacotes PyPI instalados e os nomes das variáveis de ambiente do seu ambiente Cloud Composer.

Pode usar este ambiente local do Airflow para fins de teste e desenvolvimento, como testar novo código DAG, pacotes PyPI ou opções de configuração do Airflow.

Antes de começar

  • A ferramenta Composer Local Development CLI cria ambientes Airflow locais num diretório onde executa o comando composer-dev create. Para aceder ao seu ambiente Airflow local mais tarde, execute os comandos da ferramenta no caminho onde criou inicialmente o ambiente local. Todos os dados do ambiente local são armazenados num subdiretório no caminho onde criou o ambiente local: ./composer/<local_environment_name>.

  • O computador tem de ter espaço no disco suficiente para armazenar imagens de compilação do Airflow. A ferramenta CLI de desenvolvimento local do Composer armazena um ficheiro de imagem para cada compilação do Airflow. Por exemplo, se tiver dois ambientes Airflow locais com compilações do Airflow diferentes, a ferramenta de CLI de desenvolvimento local do Composer armazena duas imagens de compilação do Airflow.

  • A ferramenta CLI de desenvolvimento local do Composer usa resultados coloridos. Pode desativar a saída colorida com a variável NO_COLOR=1: NO_COLOR=1 composer-dev <other commands>.

  • Se tiver apenas um ambiente local, pode omitir o nome do ambiente local 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 tem de estar instalado e em execução no sistema local. Para verificar se o Docker está em execução, pode executar qualquer comando da CLI do Docker, como docker ps.

Configure as credenciais

Se ainda não o fez, obtenha novas credenciais de utilizador para usar nas credenciais predefinidas da aplicação:

gcloud auth application-default login

Inicie sessão na CLI gcloud com a sua Conta Google:

gcloud auth login

Todas as chamadas API feitas pela ferramenta CLI de desenvolvimento local do Composer e pelos DAGs são executadas a partir da conta que usa na CLI gcloud. Por exemplo, se um DAG no seu ambiente local do Airflow ler o conteúdo de um contentor do Cloud Storage, esta conta tem de ter autorizações para aceder ao contentor. Isto é diferente dos ambientes do Cloud Composer, onde a conta de serviço de um ambiente faz as chamadas.

Instale a ferramenta de 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 .

Consoante a configuração do pip, o caminho no qual a ferramenta está instalada pode não estar na variável PATH. Se for esse o caso, o ícone pip apresenta uma mensagem de aviso. Pode usar as informações desta mensagem de aviso para adicionar este diretório à variável PATH no seu sistema operativo.

Crie um ambiente Airflow local com uma imagem de compilação do Airflow

Para listar as imagens de compilação do Airflow disponíveis, execute o seguinte comando:

composer-dev list-available-versions --include-past-releases --limit 10

Para criar um ambiente local do Airflow com parâmetros predefinidos, 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

Substituir:

  • IMAGE_VERSION com o nome da imagem de compilação do Airflow.
  • PROJECT_ID com o ID do projeto.
  • WEB_SERVER_PORT com a porta na qual o servidor Web do Airflow tem de escutar.
  • LOCAL_DAGS_PATH com o caminho para um diretório local onde os ficheiros DAG estão localizados.
  • LOCAL_ENVIRONMENT_NAME com o nome deste ambiente Airflow local.

Exemplo:

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

Crie um ambiente do Airflow local a partir de um ambiente do Cloud Composer

Apenas as seguintes informações são retiradas de um ambiente do Cloud Composer:

  • Compilação específica do Airflow usada 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 ficheiros DAG, histórico de execuções de DAG, variáveis do Airflow e ligações, não são copiados do seu ambiente do Cloud Composer.

Para criar um ambiente do Airflow local a partir de um ambiente do Cloud Composer existente:

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

Substituir:

  • LOCAL_ENVIRONMENT_NAME com um nome para o ambiente local do Airflow.
  • ENVIRONMENT_NAME com o nome do ambiente do Cloud Composer.
  • LOCATION com a região onde o ambiente do Cloud Composer está localizado.
  • PROJECT_ID com o ID do projeto.
  • WEB_SERVER_PORT com uma porta para o servidor 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

Inicie um ambiente local do Airflow

Para iniciar um ambiente local do Airflow, execute o seguinte comando:

composer-dev start LOCAL_ENVIRONMENT_NAME

Substituir:

  • LOCAL_ENVIRONMENT_NAME com o nome de um ambiente do Airflow local.

Pare ou reinicie um ambiente Airflow local

Quando reinicia um ambiente local do Airflow, a ferramenta Composer Local Development CLI reinicia o contentor Docker onde o ambiente é executado. Todos os componentes do Airflow são parados e iniciados novamente. Como resultado, todas as execuções de DAGs que são executadas durante um reinício são marcadas como falhadas .

Para reiniciar ou iniciar um ambiente local do Airflow parado, execute o seguinte comando:

composer-dev restart LOCAL_ENVIRONMENT_NAME

Substituir:

  • LOCAL_ENVIRONMENT_NAME com o nome de um ambiente do Airflow local.

Para parar um ambiente Airflow local, execute:

composer-dev stop LOCAL_ENVIRONMENT_NAME

Adicione e atualize DAGs

Os DAGs são armazenados no diretório que especificou no parâmetro --dags-path quando criou o seu ambiente local do Airflow. Por predefinição, este diretório é ./composer/<local_environment_name>/dags. Pode obter o diretório usado pelo seu ambiente com o comando describe.

Para adicionar e atualizar DAGs, altere os ficheiros neste diretório. Não precisa de reiniciar o seu ambiente Airflow local.

Veja os registos do ambiente Airflow local

Pode ver registos recentes de um contentor Docker que executa o seu ambiente Airflow local. Desta forma, pode monitorizar eventos relacionados com contentores e verificar os registos do Airflow quanto a erros, como conflitos de dependências causados pela instalação de pacotes PyPI.

Para ver os registos de um contentor Docker que executa o seu ambiente Airflow local, execute:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Para seguir a stream de registo, omita o argumento --max-lines:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Execute um comando da CLI do Airflow

Pode executar comandos da CLI do Airflow no seu ambiente do Airflow local.

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

Configure 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 do 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 adicionar requisitos de pacotes PyPI em conflito, a ferramenta CLI de desenvolvimento local do Composer comunica erros quando inicia o ambiente local.

As ligações do Airflow são armazenadas na base de dados do ambiente do Airflow local. Pode configurá-los executando um comando da CLI do Airflow ou armazenando os parâmetros de ligação em variáveis de ambiente. Para mais informações sobre formas de criar e configurar associações, consulte o artigo Gerir associações na documentação do Airflow.

Obtenha uma lista e o estado dos ambientes Airflow locais

Para listar todos os ambientes locais do Airflow disponíveis e apresentar o respetivo estado:

composer-dev list

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

composer-dev describe LOCAL_ENVIRONMENT_NAME

Substituir:

  • LOCAL_ENVIRONMENT_NAME com o nome do ambiente do Airflow local.

Liste as imagens usadas por ambientes Airflow locais

Para apresentar uma lista de todas as imagens usadas pela ferramenta Composer Local Development CLI, execute:

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

Instale plug-ins e altere dados

Os plug-ins e os dados de um ambiente do Airflow local são retirados do diretório do ambiente local: ./composer/<local_environment_name>/data e ./composer/<local_environment_name>/plugins).

Para alterar o conteúdo dos diretórios /data e /plugins, adicione ou remova ficheiros nestes diretórios. O Docker propaga automaticamente as alterações de ficheiros para o seu ambiente local do Airflow.

A ferramenta CLI de desenvolvimento local do Composer não suporta a especificação de um diretório diferente para dados e plug-ins.

Configure variáveis de ambiente

Para configurar variáveis de ambiente, edite o ficheiro variables.env no diretório do ambiente: ./composer/<local_environment_name>/variables.env.

O ficheiro variables.env tem de 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 alterações, reinicie o ambiente do Airflow local.

Instale ou remova pacotes PyPI

Para instalar ou remover pacotes PyPI, modifique o ficheiro requirements.txt no diretório do ambiente: ./composer/<local_environment_name>/requirements.txt.

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.

Para aplicar as alterações, reinicie o ambiente do Airflow local.

Mude para uma imagem de compilação do Airflow diferente

Pode usar qualquer imagem de compilação do Airflow com a ferramenta de CLI de desenvolvimento local do Composer e alternar entre as imagens. Esta abordagem é diferente da atualização do seu ambiente do Cloud Composer, porque os parâmetros de configuração do seu ambiente do Airflow local são aplicados quando este é iniciado.

Por exemplo, após o lançamento de uma nova compilação do Airflow, pode mudar o seu ambiente para a usar e manter a configuração do ambiente do Airflow local existente.

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

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

  2. Altere o valor do parâmetro composer_image_version. Para ver os valores disponíveis, pode listar as imagens disponíveis.

  3. Para aplicar as alterações, reinicie o ambiente do Airflow local.

Elimine um ambiente local do Airflow

Atenção: certifique-se de que guardou todos os dados necessários do ambiente, como registos e configuração.

Para eliminar 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 respetiva remoção.

Elimine imagens do Docker

Para eliminar todas as imagens transferidas pela ferramenta CLI de desenvolvimento local do Composer, execute o seguinte comando:

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

Resolução de problemas

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

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

Se instalou o pacote composer-dev num diretório ao qual o Docker não consegue aceder, o seu ambiente local pode não ser iniciado.

Por exemplo, se o Python estiver instalado no diretório /opt, como quando o instala com a configuração predefinida do Homebrew no MacOS, o pacote composer-dev também é instalado no diretório /opt. Uma vez que o Docker cumpre as regras de sandbox da Apple, o diretório /opt não está disponível por predefinição. Além disso, não pode adicioná-lo através da IU (Definições > Recursos > Partilha de ficheiros).

Neste caso, a ferramenta Composer Local Development CLI 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...")

Pode usar uma das seguintes soluções:

  • Instale o Python ou o pacote composer-dev num diretório diferente para que o Docker possa aceder ao pacote.
  • Edite manualmente o ficheiro ~/Library/Group\ Containers/group.com.docker/settings.json e adicione /opt a filesharingDirectories.

O que se segue?