Apache Airflow — это мощная платформа с открытым исходным кодом, предназначенная для программного создания, планирования и мониторинга рабочих процессов. Он стал стандартом де-факто для оркестрации сложных ETL-процессов, обработки данных и автоматизации задач в различных областях.
Развертывание Airflow может быть непростой задачей из-за множества зависимостей и компонентов. Именно здесь на помощь приходит Docker и Docker Compose. Использование контейнеров обеспечивает изоляцию, воспроизводимость и значительно упрощает процесс установки и управления. С помощью Docker Compose мы можем определить и запустить многоконтейнерное приложение Airflow, включающее базу данных, планировщик, веб-сервер и worker-ы, всего одной командой.
В этом руководстве мы шаг за шагом рассмотрим, как правильно настроить и запустить Apache Airflow в Docker с использованием Docker Compose, чтобы вы могли быстро приступить к созданию и управлению своими DAGs.
Подготовка к развертыванию Apache Airflow в Docker
После того как мы убедились в преимуществах контейнеризации, первым шагом к развертыванию Apache Airflow является подготовка вашей среды. Это включает в себя установку необходимых инструментов и создание базовой структуры проекта.
Установка и проверка Docker и Docker Compose
Для запуска Airflow в Docker вам потребуется установленный Docker Engine и Docker Compose. Убедитесь, что они доступны в вашей системе, выполнив следующие команды в терминале:
docker --version
docker compose version
Если команды возвращают версии, значит, инструменты установлены. В противном случае, следуйте официальным инструкциям по установке Docker Desktop (для Windows/macOS) или Docker Engine и Docker Compose (для Linux).
Создание структуры проекта и файла .env
Для организации файлов конфигурации и DAGs рекомендуется создать отдельную директорию для вашего проекта Airflow. В этой директории мы также разместим файл .env, который будет содержать переменные окружения для Docker Compose.
Создайте директорию и перейдите в нее:
mkdir airflow-docker
cd airflow-docker
Затем создайте пустой файл .env, который мы заполним позже:
touch .env
Этот файл будет использоваться для централизованного управления настройками, такими как идентификатор пользователя, порты и версии Airflow.
Установка и проверка Docker и Docker Compose
Прежде чем приступить к развертыванию Apache Airflow, убедитесь, что на вашей системе установлены и корректно работают Docker и Docker Compose. Эти инструменты являются основой для контейнеризации Airflow и управления его компонентами.
Для большинства операционных систем (Windows, macOS) рекомендуется установить Docker Desktop, который включает в себя Docker Engine, Docker CLI и Docker Compose. Пользователям Linux следует следовать официальным инструкциям по установке Docker Engine и Docker Compose для своего дистрибутива.
После установки выполните следующие команды в терминале для проверки версий и подтверждения корректной работы:
docker --version
docker compose version
Вывод должен показать установленные версии Docker и Docker Compose, что подтверждает готовность вашей среды к дальнейшим шагам.
Создание структуры проекта и файла .env
После успешной установки Docker и Docker Compose следующим шагом является создание необходимой структуры каталогов для вашего проекта Apache Airflow. Это обеспечит чистоту и порядок, а также правильное монтирование томов для контейнеров.
Начните с создания корневого каталога для вашего проекта Airflow, например, airflow-project:
mkdir airflow-project
cd airflow-project
Внутри этого каталога создайте следующие подкаталоги:
-
dags: Здесь будут храниться ваши файлы DAGs (Directed Acyclic Graphs), определяющие рабочие процессы Airflow. -
logs: В этом каталоге Airflow будет сохранять логи выполнения задач, что критически важно для отладки. -
plugins: Если вы планируете использовать пользовательские плагины, операторы или хуки, они будут размещаться здесь.
mkdir dags logs plugins
Далее создайте файл .env в корневом каталоге airflow-project. Этот файл будет содержать переменные окружения, которые Docker Compose будет использовать для настройки сервисов. Это позволяет легко управлять версиями Airflow и другими параметрами без изменения основного файла docker-compose.yaml.
Пример содержимого файла .env:
AIRFLOW_VERSION=2.8.1
AIRFLOW_UID=50000
Здесь AIRFLOW_VERSION определяет версию Apache Airflow, которую вы хотите развернуть. AIRFLOW_UID устанавливает идентификатор пользователя, под которым будут выполняться процессы Airflow внутри контейнера. Это важно для корректной работы с файловыми разрешениями на хост-машине, особенно при монтировании томов для DAGs и логов.
Создание и анализ конфигурации Docker Compose
Теперь, когда базовая структура проекта готова, перейдем к центральному элементу развертывания — файлу docker-compose.yaml. Для запуска Airflow в Docker рекомендуется использовать официальный шаблон, доступный в репозитории Apache Airflow. Он служит отличной отправной точкой, предоставляя преднастроенные сервисы, необходимые для полноценной работы.
Основные сервисы, которые мы настроим в docker-compose.yaml, включают:
-
postgres: База данных для хранения метаданных Airflow. -
airflow-scheduler: Планировщик, отвечающий за мониторинг DAGs и запуск задач. -
airflow-webserver: Веб-интерфейс для управления DAGs, мониторинга задач и просмотра логов. -
airflow-worker: Исполнитель задач. Для начала мы будем использоватьLocalExecutor, который запускает задачи локально в контейнере worker’а.
Каждый сервис будет иметь свои настройки, такие как образы Docker, монтируемые тома (для сохранения данных и DAGs), переменные окружения и открытые порты. Важно убедиться, что тома для dags, logs и plugins корректно монтируются, чтобы Airflow мог получить доступ к вашим файлам.
Обзор официального docker-compose.yaml Airflow
После создания базовой структуры проекта и файла .env, ключевым шагом становится получение и анализ конфигурации docker-compose.yaml. Apache Airflow предоставляет официальный пример этого файла в своем репозитории, который является идеальной отправной точкой для развертывания. Он спроектирован для быстрого запуска полноценной среды Airflow, включающей все необходимые компоненты.
Типичный официальный docker-compose.yaml определяет несколько ключевых сервисов:
-
База данных (PostgreSQL): для хранения метаданных Airflow.
-
Планировщик (Scheduler): отслеживает DAGs и запускает задачи.
-
Веб-сервер (Webserver): предоставляет пользовательский интерфейс Airflow.
-
Worker: выполняет задачи (по умолчанию часто используется
LocalExecutorилиCeleryExecutorс дополнительными сервисами, такими как Redis).
Этот файл также включает преднастроенные тома для обеспечения персистентности данных и базовые переменные окружения, что минимизирует начальную настройку. Понимание его структуры критически важно для дальнейшей кастомизации.
Настройка сервисов: база данных, планировщик, веб-сервер и worker
Детальная настройка каждого сервиса в docker-compose.yaml критически важна для стабильной работы Airflow. Начнем с базы данных, которая обычно представлена PostgreSQL. В секции db указывается образ postgres:13 (или новее), определяются переменные окружения для пользователя, пароля и имени базы данных (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB). Важно также настроить постоянное хранение данных через volumes.
Сервис планировщика (scheduler) отвечает за мониторинг DAGs и запуск задач. Он использует тот же образ Airflow и команду airflow scheduler. Здесь задается AIRFLOW__CORE__EXECUTOR (например, LocalExecutor для простых установок) и AIRFLOW__DATABASE__SQL_ALCHEMY_CONN для подключения к базе данных. Тома для DAGs также монтируются сюда.
Веб-сервер (webserver) предоставляет пользовательский интерфейс Airflow. Он также использует образ Airflow с командой airflow webserver, маппирует порт 8080 и требует доступа к базе данных через AIRFLOW__DATABASE__SQL_ALCHEMY_CONN. Тома для DAGs идентичны планировщику.
Наконец, worker (рабочий процесс) выполняет задачи. В случае LocalExecutor, планировщик сам выступает в роли worker’а. Для распределенных систем, таких как CeleryExecutor, потребуется отдельный сервис worker с командой airflow worker, который также будет подключен к брокеру сообщений (например, Redis) и базе данных.
Инициализация и первый запуск Apache Airflow
После того как конфигурация docker-compose.yaml готова, следующим критическим шагом является подготовка среды Airflow к работе. Это включает инициализацию базы данных и создание учетной записи администратора.
Инициализация базы данных и создание администратора
Прежде чем запускать основные сервисы Airflow, необходимо инициализировать базу данных. Это создаст все необходимые таблицы и схемы для хранения метаданных Airflow (информация о DAGs, задачах, их статусах и т.д.). Используйте следующую команду:
docker compose run airflow-init airflow db migrate
Эта команда запускает временный контейнер airflow-init, который выполняет миграцию базы данных. После успешной миграции необходимо создать учетную запись администратора для доступа к веб-интерфейсу Airflow:
docker compose run airflow-init airflow users create \
--username admin \
--firstname Admin \
--lastname User \
--role Admin \
--email admin@example.com \
-p admin
Важно: В реальных проектах используйте более надежный пароль и не запускайте эту команду повторно, если пользователь уже существует.
Запуск всех компонентов и доступ к веб-интерфейсу
Теперь, когда база данных инициализирована и администратор создан, можно запустить все компоненты Airflow, определенные в docker-compose.yaml:
docker compose up -d
Флаг -d (detach) запускает контейнеры в фоновом режиме. После выполнения этой команды Docker Compose запустит планировщик, веб-сервер, worker и базу данных. Вы можете проверить статус запущенных контейнеров с помощью docker compose ps.
Веб-интерфейс Apache Airflow станет доступен по адресу http://localhost:8080. Используйте созданные учетные данные (admin/admin) для входа.
Инициализация базы данных и создание администратора
Прежде чем запускать все компоненты Airflow, необходимо инициализировать его базу данных метаданных. Этот шаг создает все необходимые таблицы и схемы, которые Airflow использует для хранения информации о DAGs, задачах, их статусах и конфигурации. Для этого выполните следующую команду, используя сервис airflow-init, который предназначен для однократных операций:
docker compose run --rm airflow-init airflow db migrate
После успешной миграции базы данных, следующим шагом является создание учетной записи администратора. Эта учетная запись позволит вам получить доступ к веб-интерфейсу Airflow и управлять DAGs. Используйте команду:
docker compose run --rm airflow-init airflow users create \
--username admin \
--firstname Peter \
--lastname Parker \
--role Admin \
--email admin@example.com \
--password admin
Убедитесь, что вы заменили admin на желаемый пароль. Сервис airflow-init выполнит эти команды и завершит работу, не оставаясь запущенным в фоне.
Запуск всех компонентов и доступ к веб-интерфейсу
После успешной инициализации базы данных и создания администратора, можно запустить все сервисы Airflow. Для этого выполните следующую команду в корневой директории вашего проекта:
docker compose up -d
Флаг -d (detached mode) позволяет запустить контейнеры в фоновом режиме, не блокируя терминал. После выполнения команды Docker Compose создаст и запустит все сервисы, определенные в docker-compose.yaml (планировщик, веб-сервер, worker, базу данных и Redis, если используется).
Чтобы убедиться, что все контейнеры запущены и работают корректно, используйте команду:
docker compose ps
Вы должны увидеть список всех сервисов со статусом running. Теперь вы можете получить доступ к веб-интерфейсу Apache Airflow, открыв в браузере адрес http://localhost:8080. Войдите, используя учетные данные администратора, созданные на предыдущем шаге (по умолчанию admin/admin).
Управление DAGs и тонкая настройка Airflow
После успешного запуска Airflow, следующим шагом является добавление ваших собственных DAGs. Все файлы DAGs, написанные на Python, следует размещать в директории, которая монтируется в контейнер Airflow (обычно это папка dags в корне вашего проекта). Airflow автоматически сканирует эту директорию и загружает новые DAGs.
Для тестирования DAGs, после их добавления, вы можете включить их через веб-интерфейс Airflow и запустить вручную. Это позволит убедиться в корректности их работы и отсутствии синтаксических ошибок.
Тонкая настройка Airflow в Docker Compose преимущественно осуществляется через переменные окружения. Вы можете определить их в файле .env или непосредственно в секции environment для каждого сервиса в docker-compose.yaml. Например, для отключения загрузки примеров DAGs используйте AIRFLOW__CORE__LOAD_EXAMPLES=False. Такой подход обеспечивает гибкость и легкость управления конфигурацией в контейнеризированной среде.
Добавление пользовательских DAGs и их тестирование
После успешного запуска всех компонентов Airflow, следующим логичным шагом является интеграция ваших собственных DAGs. В стандартной конфигурации docker-compose.yaml для Airflow, локальная директория dags из вашего проекта монтируется непосредственно в контейнеры Airflow (обычно в /opt/airflow/dags). Это обеспечивает автоматический доступ планировщика (Scheduler) к вашим файлам DAG.
Для добавления и тестирования пользовательских DAGs:
-
Поместите ваш Python-файл с определением DAG (например,
my_custom_dag.py) в локальную директориюdags. -
Убедитесь, что ваш DAG содержит базовую логику, например, с использованием
BashOperatorилиPythonOperator. -
Сохраните файл.
Airflow Scheduler автоматически обнаружит новый DAG в течение нескольких секунд. Перейдите в веб-интерфейс Airflow, найдите ваш DAG, включите его (переключите тумблер) и запустите вручную для проверки. Мониторинг логов выполнения в UI поможет убедиться в корректной работе.
Настройка переменных окружения и конфигурирование Airflow
После того как пользовательские DAGs успешно добавлены и протестированы, следующим логичным шагом является тонкая настройка поведения самого Airflow. В контексте Docker Compose, наиболее эффективным способом конфигурирования Airflow является использование переменных окружения. Они позволяют переопределять любые параметры из файла airflow.cfg без необходимости его прямого редактирования внутри контейнера.
Формат переменных окружения следующий: AIRFLOW__<РАЗДЕЛ>__<ПАРАМЕТР>. Например, для изменения исполнителя на CeleryExecutor вы можете установить AIRFLOW__CORE__EXECUTOR=CeleryExecutor. Эти переменные можно определить непосредственно в секции environment для каждого сервиса в docker-compose.yaml или централизованно в файле .env для всего проекта. Такой подход обеспечивает гибкость и упрощает управление конфигурацией в контейнеризированной среде.
Расширенные возможности и устранение неполадок
После базовой настройки и конфигурирования Airflow через переменные окружения, важно уметь диагностировать и решать возникающие проблемы, а также оптимизировать производительность.
-
Диагностика ошибок: При возникновении проблем, первым делом проверяйте логи контейнеров с помощью
docker logs <service_name>. Частые причины: проблемы с подключением к базе данных, некорректные переменные окружения или ошибки в DAG-файлах. Используйтеdocker exec -it <service_name> bashдля интерактивной отладки внутри контейнера. -
Выбор Executor-ов: Для продакшн-среды рассмотрите переход от
LocalExecutorкCeleryExecutorилиKubernetesExecutorдля горизонтального масштабирования и повышения отказоустойчивости. Это потребует дополнительных сервисов, таких как брокер сообщений (Redis или RabbitMQ) и Celery workers. -
Оптимизация производительности: Регулируйте выделение ресурсов (CPU, RAM) для каждого сервиса Airflow в
docker-compose.yamlв зависимости от нагрузки. Мониторинг ресурсов поможет выявить узкие места.
Диагностика и решение распространенных ошибок при запуске
При работе с Airflow в Docker могут возникнуть различные проблемы. Для их диагностики всегда начинайте с просмотра логов сервисов: docker-compose logs <имя_сервиса>. Это поможет быстро выявить причину сбоя.
-
Ошибки подключения к базе данных: Убедитесь, что переменная
AIRFLOW__DATABASE__SQL_ALCHEMY_CONNв вашем.envфайле илиdocker-compose.yamlсодержит корректные данные для подключения к PostgreSQL. Проверьте, что сервис базы данных полностью запущен и доступен. -
Конфликты портов: Если веб-интерфейс Airflow (обычно на порту 8080) недоступен, проверьте, не занят ли этот порт другим приложением на вашей хост-машине. Вы можете изменить маппинг портов в
docker-compose.yaml. -
Проблемы с DAGs: Убедитесь, что папка с вашими DAGs правильно смонтирована в контейнер Airflow и имеет необходимые права доступа. Проверьте синтаксис ваших DAG-файлов на наличие ошибок.
-
Недостаток ресурсов: Если контейнеры Airflow постоянно перезапускаются или работают нестабильно, возможно, им не хватает выделенных ресурсов (памяти, CPU). Рассмотрите возможность увеличения лимитов в
docker-compose.yaml.
Оптимизация производительности и выбор Executor-ов
После успешного устранения неполадок, следующим шагом является оптимизация производительности вашей Airflow-среды. Ключевым аспектом здесь является правильный выбор исполнителя (Executor).
-
LocalExecutor: Идеален для разработки и небольших инсталляций. Все задачи выполняются в одном процессе или его дочерних процессах на той же машине, что упрощает отладку.
-
CeleryExecutor: Рекомендуется для продакшн-среды и масштабирования. Он позволяет распределять задачи между несколькими worker-ами, используя брокер сообщений (например, Redis или RabbitMQ), что значительно повышает параллелизм и отказоустойчивость.
Для дальнейшей оптимизации убедитесь, что вы выделили достаточные ресурсы (CPU, RAM) для каждого сервиса Airflow в вашем docker-compose.yaml, особенно для планировщика и worker-ов. Регулярный мониторинг поможет выявить узкие места и скорректировать конфигурацию.
Заключение
Итак, мы успешно прошли путь от базовой установки Docker и Docker Compose до полноценного развертывания Apache Airflow, включая инициализацию базы данных, запуск всех ключевых сервисов и управление DAGs. Мы также рассмотрели вопросы оптимизации производительности, выбора Executor-ов и устранения распространенных проблем. Использование Docker Compose значительно упрощает процесс развертывания и обеспечивает гибкую, масштабируемую и легко воспроизводимую среду для ваших ETL-процессов и автоматизации рабочих потоков. Теперь вы готовы к созданию и управлению сложными пайплайнами данных.