Apache Airflow: Diagrama de Contêiner (C4 Nível 2)

Gilmar Pupo
17 de set.
4 min de leitura

Muita gente conhece o Airflow apenas pela UI ou pelos DAGs, mas a plataforma é composta por múltiplos serviços (contêineres) que trabalham juntos para orquestrar dados em escala.

👉 No diagrama C4 abaixo (Nível 2) mostramos como os principais componentes se relacionam entre si e com sistemas externos.

Diagrama de Contêiner (Nível 2) para a arquitetura do Apache Airflow

⚙️ Componentes em destaque:

API Server / Webserver → porta de entrada para engenheiros de dados.
Scheduler → cérebro da orquestração, decide o que roda e quando.
DAG Processor → interpreta e serializa DAGs.
Celery Worker → executa as tarefas de fato (consultas, ETLs, APIs externas).
Triggerer → gerencia tarefas assíncronas, liberando os Workers.
Redis → fila de mensagens entre Scheduler e Workers.
PostgreSQL → memória persistente de DAGs, execuções, variáveis e logs.
Flower UI → monitora em tempo real a saúde dos Workers.

📌 A orquestração só é possível porque cada peça cumpre um papel claro — e entender esses contêineres ajuda muito tanto em deploy quanto em troubleshooting.

👉 Já precisou debugar performance ou falhas no Airflow? Qual desses componentes foi o “culpado” no seu caso?

Filesystem (Docker compose)

A estrutura de arquivos é a base para uma instância do Apache Airflow configurada para rodar localmente com Docker Compose:

meu-projeto-airflow/

├── 📁 config/

│ └── ⚙️ airflow.cfg # Arquivo principal de configuração.

│

├── 📁 dags/

│ ├── 📜 etl_clientes.py # Script Python com um workflow (DAG).

│ └── 📜 relatorio_diario.py # Outro workflow.

│

├── 📁 logs/

│ └── 📂 etl_clientes/ # Pasta criada para os logs do DAG "etl_clientes".

│ └── 📂 extrair_dados/ # Logs da tarefa "extrair_dados".

│ └── 📂 2025-09-17T.../ # Logs de uma execução específica.

│ └── 📄 1.log

│

├── 📁 plugins/

│ └── 🧩 meus_operadores/

│ ├── __init__.py

│ └── ⚙️ s3_to_gcs_operator.py # Exemplo de um operador customizado.

│

└── 📜 docker-compose.yaml # serviços (contêineres).

Cada diretório e arquivo tem um papel fundamental no funcionamento da plataforma:

📁 dags

Este é o diretório **mais importante** para o seu trabalho diário. É aqui que você armazena seus scripts Python que definem os workflows, conhecidos como **DAGs** (Directed Acyclic Graphs). O **Scheduler** do Airflow monitora essa pasta continuamente para detectar novos DAGs ou atualizações nos existentes e programar suas execuções.

🧩 plugins

Esta pasta é usada para **estender as funcionalidades** do Airflow. Você pode adicionar código personalizado, como operadores, hooks, macros ou até mesmo novas visualizações na interface do usuário. Qualquer script Python colocado aqui será carregado dinamicamente pelo Airflow, disponibilizando suas customizações para uso nos DAGs.

🪵 logs

Como o nome sugere, este diretório armazena os arquivos de log gerados pela execução das tarefas. Para cada execução de uma tarefa (`task instance`), o Airflow cria um arquivo de log correspondente. É o primeiro lugar que você deve procurar quando uma tarefa falha, pois contém os detalhes do erro e do que aconteceu durante a execução.

⚙️ config

Aqui ficam os arquivos de configuração do Airflow. O arquivo principal é o airflow.cfg, que contém centenas de parâmetros para customizar o comportamento da sua instância, como configurações do executor, conexões com o banco de dados de metadados, e muito mais. Alterações neste arquivo permitem ajustar o Airflow às suas necessidades específicas.

📜 docker-compose.yaml

Este arquivo é a "receita" que o Docker Compose usa para construir e orquestrar todo o ambiente Airflow. Ele define todos os serviços necessários (como o webserver, scheduler, metadatabase, triggerer, etc.), as imagens Docker a serem usadas, as redes, as portas e, crucialmente, os volumes. É nesse arquivo que você mapeia os diretórios locais (`dags`, `plugins`, `logs`) para dentro dos contêineres, permitindo que o Airflow acesse seus arquivos.

Codigo fonte do diagrama C4

```plantuml

@startuml

!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

' Título do Diagrama

title Diagrama de Contêiner (Nível 2) para Plataforma Airflow

' -------------------

' Atores e Sistemas Externos

' -------------------

Person(data_engineer, "Engenheiro de Dados", "Cria, agenda e monitora pipelines de dados (DAGs).")

System_Ext(data_sources, "Fontes de Dados Externas", "Sistemas externos como APIs, bancos de dados, data lakes (S3), etc.")

System_Ext(data_warehouse, "Data Warehouse", "Sistema de destino para os dados processados, ex: BigQuery, Snowflake.")

' -------------------

' Limite do Sistema Principal

' -------------------

System_Boundary(airflow_cluster, "Plataforma de Orquestração Airflow") {

    ' --- Contêineres Principais da Aplicação ---

    Container(api_server, "API Server / Webserver", "Python, Flask", "Fornece a UI e a API REST para interação com o sistema. É o ponto de entrada para o usuário.")

    Container(scheduler, "Scheduler", "Python", "Monitora os DAGs e dispara as tarefas quando suas dependências e agendamentos são atendidos.")

    Container(dag_processor, "DAG Processor", "Python", "Processa os arquivos de DAG, os serializa e os sincroniza com o banco de dados.")

    Container(worker, "Celery Worker", "Python, Celery", "Executa as tarefas que são enfileiradas pelo Scheduler.")

    Container(triggerer, "Triggerer", "Python, asyncio", "Gerencia operadores 'deferrable', liberando workers de tarefas de longa espera.")

    Container(flower, "Flower UI", "Python", "Interface web para monitoramento em tempo real dos workers e tarefas Celery.")

    ' --- Contêineres de Armazenamento/Mensageria ---

    ContainerDb(postgres, "Banco de Dados de Metadados", "PostgreSQL", "Armazena o estado das DAGs, tarefas, conexões, variáveis e logs.")

    ContainerDb(redis, "Message Broker", "Redis", "Fila de mensagens que distribui as tarefas do Scheduler para os Celery Workers.")

' -------------------

' Relacionamentos

' -------------------

' Interação do Usuário

Rel(data_engineer, api_server, "Gerencia e monitora DAGs", "HTTPS")

Rel(data_engineer, flower, "Inspeciona a saúde dos workers", "HTTPS")

' Fluxo interno principal

Rel(scheduler, postgres, "Consulta DAGs e escreve estados de tarefas", "SQL")

Rel(scheduler, redis, "Enfileira tarefas para execução")

Rel(dag_processor, postgres, "Sincroniza/serializa definições de DAGs", "SQL")

Rel(worker, redis, "Consome tarefas da fila")

Rel(worker, postgres, "Atualiza o estado final das tarefas", "SQL")

Rel(api_server, postgres, "Lê metadados para exibir na UI/API", "SQL")

Rel(triggerer, postgres, "Gerencia o estado de tarefas adiadas", "SQL")

Rel(flower, redis, "Monitora a fila e os workers")

' Interação com Sistemas Externos (iniciada pelo worker)

Rel(worker, data_sources, "Extrai dados", "API REST/JDBC/etc.")

Rel(worker, data_warehouse, "Carrega dados transformados", "JDBC/ODBC")

SHOW_LEGEND()

@enduml

```