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

Описание

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

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

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

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

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

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

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

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

Требования

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

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

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

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

Установка и запуск

Скачать и распаковать архив с подготовленной конфигурацией Airflow и перейти в каталог с файлами Airflow.

Перейти в каталог с файлами Airflow:
Окно терминала
```
cd airflow
```
Выдать права на каталог проекта и его содержимое:
Окно терминала
```
sudo chown -R $(id -u):$(id -g) .
chmod -R 755 .
```
Создать рабочие директории:
Окно терминала
```
mkdir -p dags logs plugins scripts data config
```
Скопировать служебные скрипты для определения пользовательской сессии Windows:
Окно терминала
```
cp -r get_user_session_scripts/* scripts/
rm -rf get_user_session_scripts
```
Создать или обновить файл .env:
Окно терминала
```
echo "AIRFLOW_UID=$(id -u)" > .env
```
Собрать кастомный образ Airflow:
Окно терминала
```
docker compose build --no-cache
```
Запустить сервисы:
Окно терминала
```
docker compose up -d
```
Проверить состояние контейнеров:
Окно терминала
```
docker compose ps
```
Открыть веб-интерфейс оркестратора:
- адрес: http://localhost:8080;
- логин по умолчанию: airflow;
- пароль по умолчанию: airflow.

После запуска веб-интерфейс Airflow будет доступен по адресу сервера и порту, указанному в docker-compose.yaml, по умолчанию http://localhost:8080.

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

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

Директорияairflow
- docker-compose.yaml - конфигурация Docker Compose
- Dockerfile - кастомный образ Airflow
- airflow.cfg - конфигурационный файл Airflow
- webserver_config.py - конфигурация веб-сервера Airflow
- dags - DAG-файлы для запуска роботов
- logs - журналы выполнения
- plugins - плагины Airflow
- scripts - служебные скрипты
- data - пользовательские данные
- config - дополнительные конфигурационные файлы
- get_user_session_scripts - служебные файлы для получения ID сессии Windows

В каталоге get_user_session_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:

airflow-webserver - веб-интерфейс Airflow, по умолчанию доступен на порту 8080;
airflow-scheduler - планировщик задач;
airflow-worker - Celery worker для выполнения задач;
airflow-triggerer - обработчик триггеров;
postgres - база данных Airflow;
redis - брокер сообщений;
flower - опциональный сервис мониторинга Celery worker.

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

docker compose --profile flower up -d

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

Настройка

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

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

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

airflow-webserver:
  <<: *airflow-common
  command: webserver
  ports:
    - "9000:8080"

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

docker compose restart airflow-webserver

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

Основная переменная окружения хранится в файле .env:

AIRFLOW_UID=1000

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

Настройка SMTP

В поставке может быть настроена отправка email через 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.
Перейти в раздел Admin -> Connections.
Создать новое подключение.
Указать параметры:
- Connection Id - smtp_default или другое значение из AIRFLOW__EMAIL__EMAIL_CONN_ID;
- Connection Type - Email;
- Host - адрес SMTP-сервера;
- Port - порт SMTP-сервера;
- Login - имя пользователя;
- Password - пароль.
Сохранить подключение.

Airflow API

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

Swagger UI доступен по адресу:

http://localhost:8080/api/v1/ui/

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

http://localhost:8080/api/v1/openapi.json

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

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

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

Пример запуска DAG через API:

curl -X POST "http://localhost:8080/api/v1/dags/puzzle_robot/dagRuns" \
  --user "airflow:airflow" \
  -H "Content-Type: application/json" \
  -d '{
    "dag_run_id": "manual_api_run_001",
    "conf": {
      "document_id": "12345",
      "run_mode": "api"
    }
  }'

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

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

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

После авторизации открывается страница со списком роботов, загруженных на сервер оркестрации.

В списке роботов отображаются:

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

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

фильтр по активности: Все, Активные, Приостановленные;
фильтр по статусу запуска;
фильтр по тегам;
поиск по загруженным роботам;
переключатель Авто-обновление;
кнопка Обновить для ручного обновления статусов.

В верхней части интерфейса расположена навигационная панель:

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

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

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

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

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

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

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

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

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

В подробной информации о роботе можно просмотреть:

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

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

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

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

Запуск по API

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

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

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

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

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

Сохранение робота как Python-скрипта

Для загрузки робота на сервер оркестрации требуется сохранить процесс как Python-скрипт.

Открыть проект с роботом в Puzzle RPA.
Открыть главный процесс проекта.
Перейти в раздел Процесс.
Для генерации Python-скрипта выполнить клик на кнопку Сгенерировать.
Выбрать тип сохранения Python-скрипт.
Сохранить процесс.
Создать папку с названием проекта, например robot_upload_pdf.
Переместить сохраненные Python-скрипты в созданную папку.

Создание DAG-файла

DAG (Directed Acyclic Graph) - процесс Airflow, который объединяет задачи и задает последовательность их выполнения по расписанию.

Для создания DAG-файла:

Создать DAG с помощью блока Создать процесс (Dag).
Добавить задачи запуска роботов с помощью блока Запустить Робота и настроить зависимости между ними.
Если DAG должен выполняться на контуре Inside, добавить аргумент по умолчанию:
```
{
    "queue": "inside_queue"
}
```
Открыть настройки Puzzle RPA.
Перейти в раздел Окно выполнения.
Отключить отображение окна выполнения.
Сохранить изменения настроек.
Перейти в раздел Процесс.
Для генерации Python-скрипта выполнить клик на кнопку Сгенерировать.
Выбрать тип сохранения Python-скрипт и сохранить процесс.
Переименовать Python-файл так, чтобы его имя совпадало с названием процесса DAG.

Загрузка файлов на сервер

Для загрузки робота на сервер оркестрации требуется:

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

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

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

# Сборка кастомного образа
docker compose build

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

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

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

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

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

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

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

docker compose ps

Мониторинг

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

веб-сервер: http://localhost:8080/health;
планировщик: http://localhost:8974/health;
Celery worker: через Flower на http://localhost:5555.

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

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

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

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

echo "AIRFLOW_UID=$(id -u)" > .env
docker compose down
docker compose up -d

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

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

docker compose stop
docker compose down -v

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

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

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

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

Проверьте:

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