Настройка и запуск оркестратора Airflow

Описание

Оркестратор Apache Airflow - сервис для планирования, координации, запуска и мониторинга выполнения автоматизированных задач.

Оркестратор позволяет:

Просматривать список загруженных роботов;
Управлять запланированным запуском роботов;
Контролировать последовательность и зависимости между роботами;
Запускать роботов вручную из веб-интерфейса;
Запускать процессы по триггеру или через API;
Отслеживать статус выполнения каждого робота и всей цепочки задач в реальном времени;
Просматривать подробные логи выполнения для диагностики и анализа ошибок;
Управлять конфигурациями, переменными, подключениями и пулами задач;
Отправлять уведомления и оповещения.

В Puzzle RPA Airflow используется как сервер оркестрации: DAG описывает процесс запуска, а задачи DAG загружают робота на удаленную виртуальную машину, запускают его и очищают временные файлы после выполнения.

Общая схема взаимодействия

Схема показывает, как студия Puzzle RPA, оркестратор Airflow и виртуальные машины участвуют в подготовке и запуске робота.

Основной сценарий работы:

В Puzzle RPA создается робот и DAG-файл для Airflow.
Python-скрипты робота и DAG-файл загружаются на сервер оркестратора - из студии Панелью управления Airflow, через репозиторий или вручную.
Airflow получает DAG, отображает его в веб-интерфейсе и запускает по расписанию, вручную, по триггеру или через API.
При запуске Airflow передает робота на целевую виртуальную машину, выполняет его и получает статус выполнения.
Статусы, история запусков и логи доступны в веб-интерфейсе Airflow и в Панели управления Airflow студии.

Пример использования В данном примере робот Robot Puzzle RPA публикуется на сервер Airflow 3 и запускается вручную из студии. Подробнее...

Поставка оркестратора

Puzzle RPA использует собственную сборку Apache Airflow 3. Официальный образ Airflow дополнен компонентами и параметрами конфигурации.

Требования

Минимальные системные требования:

процессор - 2 vCPU с тактовой частотой от 1800 МГц;
оперативная память - 4 ГБ;
свободное место на диске - 50 ГБ.

Рекомендуемые системные требования:

процессор - 4 vCPU с тактовой частотой от 1800 МГц;
оперативная память - 8 ГБ;
свободное место на диске - 100 ГБ.

Требования к рабочим машинам роботов и к учётной записи Airflow:

на машине робота установлена студия Puzzle RPA - её интерпретатор используется для запуска Python-скрипта робота;
на машине робота есть активная пользовательская сессия, если робот работает с графическим интерфейсом;
учётная запись Airflow имеет права на просмотр DAG, запусков, переменных, подключений и пулов - от них зависит набор доступных действий в Панели управления Airflow.

Структура проекта

В поставке оркестратора используются следующие файлы и каталоги:

docker-compose.yaml - конфигурация Docker Compose
Dockerfile - кастомный образ Airflow
.env - переменные окружения (AIRFLOW_UID, ключи, имя образа)
config
- airflow.cfg - конфигурационный файл Airflow
dags - DAG-файлы для запуска роботов
scripts - Python-скрипты роботов и служебные скрипты
data - служебные данные, в том числе архивы версий опубликованных файлов
logs - журналы выполнения
plugins - дополнительные плагины Airflow
get_user_session_scripts - служебные файлы для получения ID сессии Windows
README.md - инструкция по развёртыванию

В каталоге get_user_session_scripts находятся файлы, которые при развёртывании копируются в scripts:

get_user_session_id_airflow.py - получение ID активного сеанса Windows;
get_user_session_id_airflow.exe - исполняемая версия скрипта получения ID активного сеанса Windows;
get_user_session_id_airflow_v2.py - получение ID активного сеанса Windows для RDP-подключения;
get_user_session_id_airflow_v2.exe - исполняемая версия скрипта для RDP-подключения;
PsExec64.exe - утилита для удаленного запуска команд и программ.

Скрипты используются при запуске роботов на Windows-машинах, где требуется выполнить действия в пользовательской GUI-сессии.

Основные сервисы

В Docker Compose разворачиваются сервисы Airflow 3:

airflow-apiserver - веб-интерфейс и REST API, по умолчанию доступен на порту 8080. В Airflow 3 заменяет airflow-webserver из Airflow 2;
airflow-scheduler - планировщик задач;
airflow-dag-processor - разбор DAG-файлов. В Airflow 3 вынесен из планировщика в отдельный процесс;
airflow-worker - Celery worker для выполнения задач;
airflow-triggerer - обработчик триггеров;
airflow-init - служебный сервис первичной инициализации: создаёт базу данных, пользователя по умолчанию и файл config/airflow.cfg;
postgres - база данных Airflow (PostgreSQL 16);
redis - брокер сообщений Celery (Redis 7.2);
flower - опциональный сервис мониторинга Celery worker;
airflow-cli - опциональный сервис для выполнения команд airflow в контейнере.

Сервисы flower и airflow-cli запускаются только с указанием профиля:

docker compose --profile flower up -d

После запуска Flower будет доступен по адресу http://localhost:5555.

Настройка

Изменение порта веб-интерфейса

Чтобы изменить внешний порт веб-интерфейса, требуется отредактировать секцию airflow-apiserver в файле docker-compose.yaml.

Пример настройки порта 9000:

airflow-apiserver:
  <<: *airflow-common
  command: api-server
  ports:
    - "9000:8080"

После изменения требуется перезапустить API-сервер:

docker compose restart airflow-apiserver

Переменные окружения

Основные переменные хранятся в файле .env:

AIRFLOW_UID - идентификатор пользователя, от имени которого контейнеры работают с файлами на сервере;
FERNET_KEY - ключ шифрования подключений и переменных в базе данных. Изменение ключа делает ранее сохранённые пароли нечитаемыми;
AIRFLOW__API_AUTH__JWT_SECRET - секрет для подписи JWT-токенов между компонентами Airflow 3;
AIRFLOW_IMAGE_NAME - имя и тег образа оркестратора.

Аутентификация пользователей

Пользователи и роли хранятся в базе данных Airflow (FAB auth manager) и управляются в разделе Безопасность веб-интерфейса. Для подключения LDAP или OAuth требуется разместить файл webserver_config.py в каталоге config и указать путь к нему:

AIRFLOW__FAB__CONFIG_FILE: /opt/airflow/config/webserver_config.py

Настройка SMTP

Общие параметры SMTP задаются в docker-compose.yaml, например:

AIRFLOW__EMAIL__EMAIL_BACKEND: "airflow.utils.email.send_email_smtp"
AIRFLOW__EMAIL__EMAIL_CONN_ID: smtp_default
AIRFLOW__SMTP__SMTP_HOST: smtp.test.ru
AIRFLOW__SMTP__SMTP_PORT: 465
AIRFLOW__SMTP__SMTP_MAIL_FROM: mail_from@test.ru
AIRFLOW__SMTP__SMTP_STARTTLS: "False"
AIRFLOW__SMTP__SMTP_SSL: "True"

Учетные данные SMTP требуется хранить в подключении Airflow:

Открыть веб-интерфейс Airflow.
Перейти в раздел Администрирование >> Подключения.
Создать новое подключение.
Указать параметры:
- Connection Id - smtp_default или другое значение из AIRFLOW__EMAIL__EMAIL_CONN_ID;
- Connection Type - Email;
- Host - адрес SMTP-сервера;
- Port - порт SMTP-сервера;
- Login - имя пользователя;
- Password - пароль.
Сохранить подключение.

Плагин публикации файлов Puzzle

Для работы Панели управления Airflow в студии на сервере оркестратора должен быть установлен плагин публикации файлов Puzzle. Плагин добавляет к API-серверу Airflow HTTP-интерфейс, через который студия загружает DAG-файлы и скрипты роботов, получает список опубликованных файлов, историю версий и восстанавливает предыдущие версии.

В поставке оркестратора плагин уже установлен в образ. Проверить, что плагин загружен, можно командой:

http://localhost:8080/puzzle/files/docs

Без плагина панель студии сообщает: «Плагин публикации файлов не установлен на сервере Airflow». Остальные возможности панели - сведения о DAG, статистика, запуск и логи - продолжают работать, так как используют штатный REST API Airflow.

API плагина

Все методы плагина размещены по префиксу /puzzle/files на том же хосте и порту, что и веб-интерфейс:

Метод и путь	Назначение
`POST /puzzle/files/dags`	Загрузить DAG-файлы (`.py` или `.zip`) с обязательным комментарием
`POST /puzzle/files/scripts`	Загрузить файлы-скрипты с обязательным комментарием
`GET /puzzle/files/dags`	Список файлов в папке DAG-ов
`GET /puzzle/files/scripts`	Список файлов в папке скриптов
`GET /puzzle/files/dags/versions`	Список версий DAG-файла (параметр `path`)
`POST /puzzle/files/dags/restore`	Восстановить версию DAG-файла (параметры `path`, `version_id`)
`GET /puzzle/files/scripts/versions`	Список версий скрипта (параметр `path`)
`POST /puzzle/files/scripts/restore`	Восстановить версию скрипта (параметры `path`, `version_id`)

Интерактивная документация доступна по адресу http://localhost:8080/puzzle/files/docs.

Особенности работы плагина:

Аутентификация - все рабочие методы требуют авторизованного пользователя Airflow: заголовок Authorization: Bearer <токен> или кука сессии веб-интерфейса. Анонимный запрос получает ответ 401;
Загрузка нескольких файлов - за один запрос можно передать несколько файлов, а необязательное поле path задаёт подпапку-приёмник (в студии это поле Подпапка). Абсолютные пути и переходы .. отклоняются;
Обязательный комментарий - комментарий сохраняется вместе с версией каждого загруженного файла и отображается в списке версий в панели студии;
Версионирование - предыдущая версия файла архивируется перед перезаписью. При восстановлении выбранная версия и текущее содержимое меняются местами, поэтому число архивных версий не растёт;
Проверка совместимости с Airflow 3 - загружаемый DAG проверяется на конструкции Airflow 2, которые Airflow 3 больше не принимает. Найденные несовместимости возвращаются как предупреждения и не блокируют загрузку.

Настройки плагина задаются переменными окружения в docker-compose.yaml:

Переменная	Назначение
`PUZZLE_SCRIPTS_FOLDER`	Папка скриптов. По умолчанию - `scripts` рядом с папкой DAG-ов
`PUZZLE_DAG_VERSIONS_FOLDER`	Каталог архива версий DAG-файлов
`PUZZLE_SCRIPT_VERSIONS_FOLDER`	Каталог архива версий скриптов
`PUZZLE_MAX_UPLOAD_BYTES`	Максимальный размер загружаемого файла. По умолчанию - 5 МиБ
`AIRFLOW_PROJ_DIR`	Путь к проекту на хост-машине. Используется только для поля Путь на хосте в ответах API

Панель управления Airflow Публикация скриптов и DAG-файлов на сервер, связь проекта с процессом, запуск и просмотр логов из студии. Подробнее...

Airflow API

Вместе с веб-интерфейсом доступен REST API Airflow. API размещается на том же хосте и порту, что и веб-интерфейс.

В Airflow 3 используется версия API v2, а авторизация выполняется по JWT-токену.

Интерактивная документация (Swagger UI) доступна по адресу:

http://localhost:8080/docs

OpenAPI-спецификация доступна по адресу:

http://localhost:8080/openapi.json

Если внешний порт веб-интерфейса был изменен, в адресе требуется указать новый порт.

Airflow API позволяет:

получать список DAG и информацию о конкретном процессе;
запускать DAG и передавать параметры запуска в поле conf;
просматривать историю запусков DAG;
получать статусы задач и отдельных экземпляров задач;
просматривать логи выполнения;
управлять объектами Airflow, например переменными, подключениями и пулами задач, если у пользователя есть соответствующие права.

Токен доступа выдаётся по логину и паролю пользователя Airflow:

curl -X POST "http://localhost:8080/auth/token" \
-H "Content-Type: application/json" \
-d '{"username": "airflow", "password": "airflow"}'

Пример запуска DAG с полученным токеном:

curl -X POST "http://localhost:8080/api/v2/dags/robot-puzzle-rpa/dagRuns" \
-H "Authorization: Bearer <токен>" \
-H "Content-Type: application/json" \
-d '{
"logical_date": null,
"conf": {
"document_id": "12345",
"run_mode": "api"
}
}'

В параметре conf можно передать данные, которые требуются роботу при запуске. В DAG эти данные обрабатываются как параметры запуска, указанные в блоке Создать процесс (Dag).

Использование веб-интерфейса

Доступ к веб-интерфейсу оркестратора Airflow выполняется по логину и паролю пользователя.

После авторизации открывается страница Главная со сводной статистикой: количество процессов с ошибками, выполняющихся и активных процессов, состояние компонентов оркестратора (метабаза данных, планировщик, триггер, обработчик DAG), занятость слотов пула и история запусков за выбранный период.

Список загруженных роботов открывается в разделе Dag-и.

Для каждого робота в списке отображаются:

идентификатор процесса и его теги;
переключатель активности процесса (активен или на паузе);
Расписание - заданное расписание запуска;
Последний запуск - дата, время и статус последнего запуска;
Следующий запуск - дата и время следующего запуска по расписанию;
история последних запусков в виде диаграммы;
кнопки запуска процесса, добавления в избранное и удаления истории запусков.

Над списком расположены фильтры и элементы управления:

поиск по идентификатору процесса;
фильтры по состоянию последнего запуска (Last run) и любого запуска (Any run);
фильтр по активности: Все, Активный, Приостановлен;
фильтр по тегам и переключатель Все / Избранное;
сортировка списка и переключение вида: карточки или таблица.

В боковой навигационной панели расположены разделы:

Главная - сводная статистика и состояние оркестратора;
Dag-и - список загруженных роботов, запусков и экземпляров задач;
Активы - наборы данных и зависимости между процессами;
Просмотр - история запусков и задач;
Администрирование - переменные, подключения, пулы задач, провайдеры и плагины;
Безопасность - пользователи, роли и права доступа;
Документы - документация Airflow и ссылка на REST API.

Клик по идентификатору процесса открывает страницу робота с вкладками Обзор, Запуски, Задачи, Календарь, Заполнение, Аудиторский журнал, Код и Детали.

На странице робота доступны:

сведения о процессе: расписание, последний и следующий запуск, владелец, теги, версия;
статистика неудачных задач и запусков;
диаграмма последних запусков с длительностью выполнения;
граф задач и их состояния;
логи выполнения каждой задачи;
кнопка Запустить для ручного запуска процесса.

Запуск робота

В оркестраторе предусмотрено несколько типов запуска:

ручной запуск - запуск из веб-интерфейса Airflow или из Панели управления Airflow студии;
запланированный запуск - запуск по расписанию, указанному в DAG;
запуск по триггеру - запуск одного процесса из другого процесса;
запуск по API - запуск с использованием API-методов.

Ручной запуск

Для ручного запуска программного робота:

Открыть веб-интерфейс оркестратора.
Перейти в раздел Dag-и.
Выбрать робота для запуска.
Выполнить клик по кнопке Запустить.
Дождаться отображения статуса запуска в истории запусков.

Тот же запуск выполняется из студии кнопкой Запустить Панели управления Airflow.

Запланированный запуск

Запланированный запуск выполняется по расписанию, заданному в DAG. Расписание настраивается в блоке Создать процесс (Dag). Информация о расписании отображается в списке процессов и на странице робота.

На странице робота можно просмотреть:

статистику запусков;
календарь запусков;
задачи выбранного робота и их состояния;
длительность выполнения задачи;
количество повторений шагов запуска;
логи выполнения и ошибки.

Запуск по триггеру

Запуск по триггеру используется, когда один DAG должен инициировать запуск другого DAG. В Puzzle RPA такой сценарий настраивается с помощью блока Запустить Робота в режиме Робот-триггер.

Этот способ подходит для цепочек процессов, в которых следующий робот должен запускаться только после выполнения предыдущего процесса или отдельной задачи.

Запуск по API

Запуск по API используется, когда DAG требуется запустить из внешней системы: портала, интеграционного сервиса, расписания во внешнем планировщике или другого backend-приложения.

Для запуска используется REST API Airflow. В запросе можно передать параметры запуска в поле conf, а затем использовать их в DAG и задачах робота.

Подготовка робота к запуску через Airflow

Запуск робота через сервер оркестрации состоит из нескольких шагов:

Сохранение процессов робота как Python-скриптов и их загрузка в папку scripts;
Сохранение созданного робота как Python-скрипт Генерация Python-скриптов робота и их загрузка в директорию scripts. Подробнее...
Создание процесса (DAG) блоком Создать процесс (Dag) и его загрузка в папку dags;
Сохранение созданного процесса (Dag) Сохранение процесса с блоком «Создать процесс (Dag)» и загрузка DAG-файла в директорию dags. Подробнее...
связь проекта с DAG и запуск процесса.

Управление сервисами

Основные команды для администрирования:

# Запуск всех сервисов
docker compose up -d

# Остановка всех сервисов
docker compose down

# Просмотр логов всех сервисов
docker compose logs -f

# Просмотр логов API-сервера
docker compose logs -f airflow-apiserver

# Перезапуск API-сервера
docker compose restart airflow-apiserver

# Подключение к контейнеру API-сервера
docker compose exec airflow-apiserver bash

Для проверки состояния сервисов используется команда:

docker compose ps

Мониторинг

Для проверки доступности сервисов используются health checks:

API-сервер: http://localhost:8080/api/v2/monitor/health;
Планировщик: http://localhost:8974/health;
Celery worker: через Flower на http://localhost:5555.

Логи выполнения DAG и отдельных задач доступны в веб-интерфейсе Airflow и во вкладке Логи Панели управления Airflow. При ошибке запуска требуется открыть подробную информацию о задаче и проверить журнал выполнения.

Устранение неполадок

Ошибки прав доступа

Если контейнеры не могут записывать файлы в рабочие каталоги, требуется привести AIRFLOW_UID в файле .env к идентификатору текущего пользователя и перезапустить сервисы:

sed -i "s/^AIRFLOW_UID=.*/AIRFLOW_UID=$(id -u)/" .env
docker compose down
docker compose up -d

Не работает публикация файлов из студии

Если панель студии сообщает, что плагин публикации файлов не установлен:

Проверить наличие плагина командой docker compose exec airflow-apiserver airflow plugins;
Убедиться, что API-сервер имеет право записи в каталоги dags и scripts;
Проверить, что у учётной записи Airflow достаточно прав.

Очистка данных

Для остановки сервисов и удаления данных контейнеров выполняется:

docker compose stop
docker compose down -v

Недостаточно ресурсов

Если сервисы запускаются нестабильно или контейнеры завершаются с ошибками, требуется проверить доступные ресурсы сервера:

Оперативная память - не менее 4 ГБ;
Процессор - не менее 2 vCPU;
Свободное место на диске - не менее 50 ГБ.

Робот не запускается на Windows-машине

Требуется проверить:

Доступность удаленной машины по SSH;
Корректность подключения в Airflow;
Наличие активной пользовательской сессии Windows;
Наличие скриптов получения Session ID в каталоге scripts;
Права пользователя на запуск робота и доступ к файлам проекта.