Полное руководство: URL API сервера Apache Airflow – от настройки до выполнения задач

Apache Airflow зарекомендовал себя как мощный инструмент для оркестрации сложных рабочих процессов, позволяя инженерам данных и разработчикам эффективно управлять ETL-конвейерами, задачами машинного обучения и другими автоматизированными процессами. Традиционно взаимодействие с Airflow осуществлялось через его веб-интерфейс (UI) или командную строку (CLI).

Саммари статьи

ChatGPT

Google AI

Grok

Perplexity

Однако для полной автоматизации, интеграции с внешними системами и создания динамических решений требуется более гибкий и программный подход. Именно здесь на сцену выходит API Apache Airflow. Он открывает двери для бесшовного взаимодействия, позволяя запускать DAG’и, мониторить их выполнение, получать статусы задач и управлять конфигурациями программно, без необходимости ручного вмешательства.

В этом руководстве мы подробно рассмотрим, как определить и использовать URL API сервера Apache Airflow. Мы углубимся в его структуру, методы настройки и обеспечения безопасности, а также предоставим практические примеры использования для различных сценариев.

Что такое Apache Airflow API и его назначение

Apache Airflow API представляет собой мощный программный интерфейс, который позволяет внешним системам и приложениям взаимодействовать с Airflow, выходя за рамки традиционного веб-интерфейса (UI) и командной строки (CLI). Его основное назначение — обеспечить программную оркестрацию, мониторинг и управление рабочими процессами.

Роль API в оркестрации рабочих процессов

API играет ключевую роль в интеграции Airflow в более широкие экосистемы данных. Он позволяет автоматизировать такие задачи, как запуск DAG’ов, получение статусов выполнения задач, управление переменными и соединениями, а также доступ к метаданным. Это критически важно для создания полностью автоматизированных конвейеров данных, где Airflow выступает в качестве центрального оркестратора, управляемого внешними триггерами или системами.

От Experimental к Stable: обзор версий Airflow API

Исторически Airflow предлагал Experimental API (доступный по пути /api/experimental), который, как следует из названия, не гарантировал обратной совместимости и мог меняться между версиями. Это ограничивало его использование в продакшене. С выходом Airflow 2.0 был представлен Stable REST API (доступный по пути /api/v1). Этот стабильный API стал стандартом для надежного программного взаимодействия, обеспечивая предсказуемость эндпоинтов и обратную совместимость, что делает его идеальным для долгосрочных интеграций и автоматизации.

Роль API в оркестрации рабочих процессов

API Apache Airflow играет центральную роль в современной оркестрации рабочих процессов, выходя за рамки ручного взаимодействия через пользовательский интерфейс (UI) или командную строку (CLI). Он выступает в качестве программного моста, позволяющего внешним системам, скриптам и приложениям взаимодействовать с планировщиком Airflow, его DAG’ами и задачами.

Основные аспекты роли API в оркестрации:

• Автоматизация и интеграция: API позволяет автоматизировать запуск DAG’ов, мониторинг их выполнения, управление переменными, соединениями и пулами. Это критически важно для интеграции Airflow в более широкие экосистемы данных, CI/CD пайплайны, системы мониторинга или кастомные порталы.

• Динамическое управление: С помощью API можно динамически создавать, изменять или удалять DAG’и, а также управлять их состоянием и конфигурацией. Это особенно полезно для сценариев, где рабочие процессы генерируются на лету или требуют частых изменений на основе внешних событий.

• Расширяемость: API предоставляет стандартизированный способ расширения функциональности Airflow, позволяя разработчикам создавать собственные инструменты и сервисы, которые используют Airflow как бэкэнд для оркестрации.

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

От Experimental к Stable: обзор версий Airflow API

Исторически Apache Airflow предлагал Experimental API, который был доступен по пути /api/experimental. Как следует из названия, этот API не гарантировал обратной совместимости между версиями и предназначался в основном для тестирования и быстрого прототипирования. Его использование в производственных средах не рекомендовалось из-за частых изменений и отсутствия стабильных контрактов.

С развитием проекта и ростом потребностей сообщества, Airflow перешел к разработке Stable REST API, который был представлен начиная с версии Airflow 2.0. Этот API, доступный по пути /api/v1, разработан с учетом принципов стабильности, предсказуемости и обратной совместимости. Он предоставляет стандартизированные эндпоинты для большинства операций, таких как управление DAG’ами, задачами, переменными, соединениями и конфигурациями.

Основные отличия и преимущества Stable API (v1):

• Стабильность и обратная совместимость: Гарантирует, что существующие интеграции не будут нарушены при обновлении Airflow.

• Полный набор функций: Охватывает широкий спектр операций, необходимых для программного управления Airflow.

• Лучшая документация: Подробно описан и поддерживается в официальной документации.

• Безопасность: Разработан с учетом современных практик безопасности.

Для всех новых разработок и производственных интеграций настоятельно рекомендуется использовать Stable API (/api/v1), избегая устаревшего Experimental API.

Определение и доступ к URL-адресу Airflow API

После того как мы определили важность использования Stable API (/api/v1), следующим шагом является понимание того, как найти и получить доступ к его URL-адресу. API Airflow является частью веб-сервера Airflow, поэтому его базовый URL напрямую связан с адресом, по которому доступен пользовательский интерфейс Airflow.

Базовый URL Airflow Webserver: как его найти

Базовый URL веб-сервера Airflow обычно соответствует адресу, по которому вы получаете доступ к UI. Его можно определить несколькими способами:

• Файл airflow.cfg: В секции [webserver] параметр base_url указывает полный URL. По умолчанию это часто http://localhost:8080.

• Переменные окружения: В контейнеризированных средах или при развертывании через Helm/Kubernetes, URL может быть задан через переменные окружения или конфигурации сервисов.

• Конфигурация развертывания: Для Docker Compose, Kubernetes или других оркестраторов, URL будет зависеть от настроек сервиса webserver и его портов.

По умолчанию веб-сервер Airflow работает на порту 8080. Таким образом, типичный базовый URL выглядит как http://localhost:8080 или http://your-airflow-host.com:8080.

Структура эндпоинтов и порты доступа

Все эндпоинты Stable API Airflow начинаются с префикса /api/v1, который добавляется к базовому URL веб-сервера. Например:

• Для получения списка DAG’ов: http://localhost:8080/api/v1/dags

• Для запуска конкретного DAG: http://localhost:8080/api/v1/dags/{dag_id}/dagRuns

API использует тот же порт, что и веб-сервер Airflow, обычно 8080. Если ваш веб-сервер настроен на другой порт (например, 80), то и API будет доступен по этому же порту.

Базовый URL Airflow Webserver: как его найти

Базовый URL Airflow API, как уже упоминалось, идентичен адресу веб-сервера Airflow. Его точное определение критически важно для любого программного взаимодействия.

Для большинства инсталляций, особенно локальных или с использованием Docker Compose, базовый URL часто соответствует http://localhost:8080 или http://<имя_сервиса_вебсервера>:8080 внутри Docker-сети.

Однако, для точного определения, всегда следует обращаться к конфигурации. Основным источником истины является файл airflow.cfg, где параметры web_server_host и web_server_port в секции [webserver] определяют хост и порт. Например:

[webserver]
web_server_host = 0.0.0.0
web_server_port = 8080

Эти значения могут быть переопределены переменными окружения, такими как AIRFLOW__WEBSERVER__WEB_SERVER_HOST и AIRFLOW__WEBSERVER__WEB_SERVER_PORT.

В облачных средах или при развертывании через Kubernetes, базовый URL будет соответствовать адресу Load Balancer, Ingress или NodePort, который направляет трафик на веб-сервер Airflow. Его можно найти, просмотрев конфигурацию сервисов Kubernetes (kubectl get svc) или настройки вашего облачного провайдера. Понимание этих источников позволяет точно определить базовый URL для доступа к API.

Структура эндпоинтов и порты доступа

После определения базового URL-адреса веб-сервера Airflow, который служит точкой входа для API, важно понимать структуру эндпоинтов. Airflow API разделен на две основные категории:

• Stable API (/api/v1): Это рекомендуемый и стабильный API, который следует использовать для всех новых интеграций. Он предоставляет надежный набор эндпоинтов для управления DAG’ами, задачами, переменными, соединениями и многим другим.

• Experimental API (/api/experimental): Этот API является устаревшим и не рекомендуется для использования в продакшене, так как его эндпоинты могут меняться без обратной совместимости. Он был предшественником Stable API.

Структура эндпоинтов обычно следует RESTful принципам, например:

• http://<base_url>/api/v1/dags – для получения списка всех DAG’ов.

• http://<base_url>/api/v1/dags/{dag_id}/dagRuns – для управления запусками конкретного DAG.

По умолчанию веб-сервер Airflow (и, соответственно, его API) работает на порту 8080. Этот порт можно изменить в конфигурационном файле airflow.cfg (параметр web_server_port в секции [webserver]) или через переменную окружения AIRFLOW__WEBSERVER__WEB_SERVER_PORT.

Настройка и обеспечение безопасности Airflow API

После определения URL-адреса и структуры эндпоинтов, следующим шагом является настройка и обеспечение безопасности Airflow API. Активация Stable API (/api/v1) по умолчанию включена в современных версиях Airflow, но для некоторых специфических настроек или устаревших версий может потребоваться явная конфигурация.

Основные параметры, влияющие на работу API, находятся в файле airflow.cfg или могут быть заданы через переменные окружения. Важно убедиться, что секция [api] настроена корректно.

Безопасность API критически важна. Airflow поддерживает различные методы аутентификации, которые настраиваются через параметр auth_backend в секции [webserver]. Распространенные варианты включают:

• airflow.providers.cncf.kubernetes.auth.backend.kubernetes_auth (для Kubernetes)

• airflow.providers.apache.ldap.auth.backend.ldap_auth (для LDAP)

• airflow.www.security.commons.auth_backend.basic_auth (базовая аутентификация)

• airflow.www.security.commons.auth_backend.db_auth (аутентификация по базе данных)

Для авторизации используются роли пользователей, которые определяют доступ к различным ресурсам и эндпоинтам API. Управление ролями и разрешениями осуществляется через веб-интерфейс Airflow.

Наконец, для интеграции с внешними фронтенд-приложениями может потребоваться настройка Cross-Origin Resource Sharing (CORS). Параметры CORS, такие как web_server_host и web_server_port, а также специфические заголовки, могут быть настроены для разрешения запросов с определенных доменов.

Конфигурация Airflow API: параметры и активация

Для эффективного использования Airflow API необходимо убедиться, что он правильно сконфигурирован и активирован. В современных версиях Apache Airflow (начиная с 2.0) Stable REST API (/api/v1) активирован по умолчанию, что значительно упрощает его развертывание и использование. Все ключевые параметры, касающиеся API, управляются через основной конфигурационный файл Airflow – airflow.cfg.

В секции [api] файла airflow.cfg вы найдете настройки, влияющие на поведение API. Хотя Stable API обычно не требует явной активации, здесь можно настроить такие параметры, как auth_backend, который определяет используемый механизм аутентификации для доступа к API. Это критически важно для обеспечения безопасности.

Важно помнить, что Airflow API работает как часть веб-сервера Airflow. Поэтому параметры, определенные в секции [webserver], такие как web_server_host и web_server_port, напрямую влияют на доступность и URL-адрес API. Убедитесь, что эти настройки соответствуют вашей сетевой инфраструктуре и позволяют внешним системам обращаться к веб-серверу Airflow. Для более старых версий Airflow, использующих Experimental API (/api/experimental), может потребоваться явная установка enable_experimental_api = True в airflow.cfg.

Методы аутентификации, авторизации и CORS

После активации и базовой настройки API критически важно обеспечить его безопасность. Airflow API поддерживает различные методы аутентификации, которые управляются через Flask AppBuilder (FAB) — фреймворк, используемый Airflow для управления пользователями и ролями. Наиболее распространенные методы включают:

• Базовая аутентификация (Basic Auth): Часто используется для скриптов и автоматизации, где учетные данные (логин/пароль) передаются в заголовке запроса. Требует наличия пользователя в Airflow с соответствующими разрешениями.

• Аутентификация на основе токенов (Token-based Authentication): Для более сложных сценариев и интеграций с внешними системами можно настроить генерацию и использование токенов (например, JWT), хотя это часто требует дополнительной кастомизации или использования прокси-сервера.

• OAuth/OpenID Connect: Airflow может быть интегрирован с внешними провайдерами идентификации через FAB, что позволяет использовать корпоративные системы SSO для доступа к API.

Авторизация в Airflow API тесно связана с ролями и разрешениями, определенными в FAB. Пользователь, прошедший аутентификацию, может выполнять только те действия, на которые его роль имеет явное разрешение (например, can_read для DAG’ов, can_edit для переменных).

CORS (Cross-Origin Resource Sharing) — это механизм безопасности браузера, который позволяет веб-страницам запрашивать ресурсы с другого домена. Для взаимодействия с Airflow API из фронтенд-приложений, размещенных на другом домене, необходимо настроить CORS. Это делается в файле airflow.cfg через параметры webserver.cors_origin или webserver.cors_allow_headers, указывая разрешенные домены и заголовки.

Практическое применение Airflow API

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

Запуск DAG’ов, мониторинг задач и получение статусов

Airflow API позволяет программно взаимодействовать с вашими DAG’ами. Для запуска DAG можно использовать эндпоинт /api/v1/dags/{dag_id}/dagRuns, отправляя POST-запрос с необходимой конфигурацией. Мониторинг состояния выполнения DAG’ов и отдельных задач осуществляется через эндпоинты /api/v1/dagRuns и /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances соответственно, позволяя получать детальные статусы и логи.

Интеграция с Python-клиентом и cURL

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

Пример запуска DAG с помощью cURL:

curl -X POST "http://localhost:8080/api/v1/dags/my_dag_id/dagRuns" \
-H "Content-Type: application/json" \
-d '{"conf": {"key": "value"}}' \
--user "username:password"

Этот подход идеален для скриптов оболочки и быстрой отладки.

Запуск DAG’ов, мониторинг задач и получение статусов

Для программного взаимодействия с Airflow API и выполнения ключевых операций используются специализированные эндпоинты.

Запуск DAG’ов: Инициировать новый запуск DAG можно с помощью POST запроса к эндпоинту /api/v1/dags/{dag_id}/dagRuns. Тело запроса может содержать JSON-объект {"conf": {}} для передачи конфигурационных параметров в DAG.

Пример использования curl:

curl -X POST \
  "http://localhost:8080/api/v1/dags/my_example_dag/dagRuns" \
  -H "Content-Type: application/json" \
  -d '{"conf": {"message": "Hello from API"}}' \
  --user "username:password"

Мониторинг выполнения и статусов:

• Статус запусков DAG’ов: Для получения списка всех запусков конкретного DAG и их текущих статусов (например, running, success, failed) используется GET запрос к /api/v1/dags/{dag_id}/dagRuns. Можно применять параметры фильтрации, такие как state.

• Статус экземпляров задач: Детальную информацию о статусе отдельных задач в рамках конкретного запуска DAG можно получить через GET запрос к /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances. Это позволяет отслеживать прогресс и выявлять проблемные места.

Официальный Python-клиент Airflow значительно упрощает эти операции, предоставляя высокоуровневые методы, абстрагирующие прямые HTTP-запросы и обработку ответов.

Интеграция с Python-клиентом и cURL

Для программного взаимодействия с Airflow API на Python рекомендуется использовать официальную библиотеку apache-airflow-client. Она предоставляет удобные обертки для всех эндпоинтов API v1, значительно упрощая процесс интеграции. После установки (pip install apache-airflow-client) вы можете инициализировать клиент, указав базовый URL вашего веб-сервера Airflow и учетные данные для аутентификации (например, Basic Auth или токен). Это позволяет легко выполнять такие операции, как получение списка DAG’ов, их статусов или запуск нового выполнения DAG (DagRun) с передачей конфигурационных параметров.

Инструмент командной строки cURL идеально подходит для тестирования API, выполнения одноразовых запросов или включения в скрипты оболочки. Он позволяет отправлять HTTP-запросы напрямую к эндпоинтам Airflow API. При использовании cURL важно правильно указывать метод HTTP (например, POST для запуска DAG), заголовки (Content-Type: application/json) и тело запроса в формате JSON. Для аутентификации часто используется заголовок Authorization с токеном или учетными данными Basic Auth, закодированными в Base64. Например, для запуска DAG:

curl -X POST \
  http://localhost:8080/api/v1/dags/example_bash_operator/dagRuns \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YWlyZmxvdzphaXJmbG93' \
  -d '{"conf": {"message": "Hello from cURL!"}}'

Здесь YWlyZmxvdzphaXJmbG93 — это Base64-кодировка airflow:airflow (имя пользователя:пароль).

Заключение

В этом полном руководстве мы подробно рассмотрели URL API сервера Apache Airflow, от его фундаментального назначения до практического применения. Мы начали с понимания роли API в современной оркестрации рабочих процессов, отметив переход от экспериментальных к стабильным версиям, что подчеркивает зрелость и надежность инструментария.

Ключевым аспектом стало определение и доступ к базовому URL Airflow Webserver и API, а также изучение структуры эндпоинтов и портов. Особое внимание было уделено настройке и обеспечению безопасности API, включая параметры конфигурации, активацию, а также критически важные методы аутентификации, авторизации и CORS, которые гарантируют защищенное взаимодействие.

Практические примеры, такие как запуск DAG’ов, мониторинг задач и получение статусов через Python-клиент и cURL, продемонстрировали мощь и гибкость API. Освоив эти аспекты, вы сможете эффективно интегрировать Airflow в свои существующие системы, автоматизировать рутинные операции и создавать более сложные и надежные решения для управления данными и рабочими процессами.