[Документация Yandex Cloud](../../../../index.md) > [Yandex DataLens](../../../index.md) > [Yandex DataLens Platform](../../index.md) > Пайплайны > Управление пайплайнами

# Управление пайплайнами

В разделе ![image](../../../../_assets/router.svg) **Оркестратор** можно управлять выполнением [DAG](../../concepts/airflow/index.md#tasks-and-dependencies) в Apache Airflow™: запускать обработку данных вручную и по расписанию, пересчитывать данные за прошлые периоды и находить причины ошибок.

* [Перед началом работы](#before-you-begin)
* [Создание кластера Apache Airflow™](#create-cluster)


* [Доступ сервисного аккаунта](#service-account-access)
* [Добавление пайплайна](#add-pipeline)
* [Просмотр списка пайплайнов](#view-pipelines)
* [Включение и остановка пайплайна](#activate-pipeline)
* [Ручной запуск пайплайна](#run-pipeline)
* [Пересчет данных за прошлые периоды (Backfill)](#backfill)
* [Просмотр запусков и задач](#view-runs)
* [Просмотр логов и XCom](#view-logs)
* [Управление запусками](#manage-runs)
* [Просмотр кода и параметров пайплайна](#view-code)
* [Ошибки загрузки DAG-файлов](#dag-import-errors)
* [Проверка состояния кластера](#cluster-health)

## Перед началом работы {#before-you-begin}

Подготовьте:

* [Окружение DataLens Platform](../clusters/manage-environment.md).
* Репозиторий Git с DAG-файлами и SSH-ключ для доступа к нему.
* [Коллекцию](../../../workbooks-collections/collections-operations.md#create-collections), в которой будет размещен кластер Apache Airflow™. Убедитесь, что у вас есть права на создание объектов в ней.

Для работы с существующим кластером [получите права на нужные действия](../../security/roles.md#object-roles) с кластером или коллекцией, в которой он размещен. Если отображается сообщение об отсутствии доступа, обратитесь к администратору.

<!-- TODO: Уточнить минимальную роль для запуска пайплайна и изменения его состояния. -->


Перед запуском пайплайнов [проверьте права сервисного аккаунта кластера](#service-account-access) на используемые данные и вычисления.

## Создание кластера Apache Airflow™ {#create-cluster}

Если кластер уже создан, перейдите к [добавлению пайплайна](#add-pipeline).

Чтобы создать кластер:

1. На панели слева выберите ![image](../../../../_assets/router.svg) **Оркестратор** и нажмите **Подключить Airflow**.
1. В блоке **Основные настройки** укажите параметры Git-репозитория:

   * **Адрес репозитория** — адрес для подключения по SSH.
   * **Путь до папки с файлами** — путь к папке с DAG-файлами в Git-репозитории.
   * **Ветка** — ветка, из которой нужно загружать DAG-файлы.
   * **SSH-ключ** — содержимое закрытого ключа. Соответствующий открытый ключ должен предоставлять доступ на чтение Git-репозитория.


1. В поле **Окружение** выберите подготовленное окружение или [создайте новое](../clusters/manage-environment.md#create-environment).

   Кластер Apache Airflow™ и объекты платформы, с которыми будут работать его пайплайны, должны находиться в одном облаке и в одном окружении.

1. Если для выполнения DAG нужны дополнительные зависимости Python, в блоке **Другие настройки** заполните поле **Pip-пакеты**. Укажите каждую зависимость на отдельной строке: название пакета или название с точной версией через `==`. Можно указать дополнительные компоненты пакета, например:

   ```text
   numpy
   requests[security,socks]
   ```

1. Нажмите **Создать кластер**.
1. В окне **Выберите коллекцию** выберите место для кластера и нажмите **Создать кластер**.
1. Дождитесь завершения операции. После создания кластера откроется список пайплайнов.

Версии Apache Airflow™ и Python задаются сервисом.


## Доступ сервисного аккаунта {#service-account-access}

Сервисный аккаунт создается автоматически вместе с кластером и используется всеми его пайплайнами. Если пайплайн обращается к объектам DataLens Platform, аккаунту нужны права на эти объекты. Например, для выполнения сохраненного SQL-запроса требуется доступ к скрипту, подключению, используемым данным и вычислениям в кластере Trino. Для задач Apache Spark™ нужны права на данные и вычисления в соответствующем кластере. Права пользователя на управление пайплайнами не заменяют права сервисного аккаунта.

Чтобы найти сервисный аккаунт кластера и перейти к запросу доступа:

1. На панели слева выберите ![image](../../../../_assets/router.svg) **Оркестратор**.
1. В верхней части страницы найдите карточку **Сервисный аккаунт**. В ней указан идентификатор аккаунта, от имени которого выполняются задачи пайплайнов.
1. В карточке нажмите значок ![image](../../../../_assets/console-icons/ellipsis.svg) и выберите **Запросить доступ**.

Подробнее о [настройке прав доступа к объектам](../../security/manage-access.md#set-access).

## Добавление пайплайна {#add-pipeline}

Пайплайн описывается в DAG-файле: в нем задаются задачи, зависимости между ними и расписание. Apache Airflow™ загружает DAG-файлы из Git-репозитория, подключенного к кластеру.

Чтобы добавить пайплайн:

1. Подготовьте DAG-файл с описанием обработки данных.
1. Добавьте файл в папку Git-репозитория, указанную при создании кластера. Используйте выбранную для кластера ветку.
1. Отправьте изменения в Git-репозиторий и дождитесь синхронизации с кластером.
1. В DataLens Platform откройте раздел ![image](../../../../_assets/router.svg) **Оркестратор** и найдите добавленный пайплайн на вкладке **Пайплайны**.

Если пайплайн не появился, проверьте [ошибки загрузки DAG-файлов](#dag-import-errors).


## Просмотр списка пайплайнов {#view-pipelines}

Чтобы открыть список, на панели слева выберите ![image](../../../../_assets/router.svg) **Оркестратор**. В верхней части страницы отображаются карточки:

* Кластер Apache Airflow™ — название кластера, версия Apache Airflow™ и состояние, например **Работает**.
* **Сервисный аккаунт** — идентификатор аккаунта для выполнения задач пайплайнов. В меню карточки доступно действие **Запросить доступ**.
* **Git-репозиторий** — ссылка на подключенный репозиторий и название ветки с DAG-файлами.

На странице доступны вкладки:

* **Пайплайны** — список загруженных DAG.
* **Запуски пайплайнов** — история выполнения всех пайплайнов.
* **Запуски задач** — история выполнения отдельных задач.

Чтобы найти пайплайн, на вкладке **Пайплайны** введите его название в поле **Поиск по названию**. Используйте фильтры **Активные** и **Остановленные**, чтобы отобрать пайплайны по состоянию. Для снятия фильтра по состоянию выберите **Все**. Дополнительно доступны фильтры **Последний запуск** и **Фильтр по тегу**.

Для быстрого перехода к недавно открытым или избранным пайплайнам используйте **Недавние** и **Избранные**. Чтобы добавить пайплайн в избранное, нажмите значок ![image](../../../../_assets/console-icons/star.svg) слева от его названия.

В таблице отображаются название, статус и описание пайплайна, расписание, следующий и последний запуски. В столбце **Последний запуск** можно проверить результат выполнения и перейти к запуску по ссылке с датой. Чтобы настроить столбцы таблицы, нажмите значок ![image](../../../../_assets/console-icons/gear.svg) справа от их заголовков.

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

## Включение и остановка пайплайна {#activate-pipeline}

Чтобы включить пайплайн:

1. На панели слева выберите ![image](../../../../_assets/router.svg) **Оркестратор** и перейдите на вкладку **Пайплайны**.
1. Найдите пайплайн и включите переключатель в его строке.

Apache Airflow™ будет создавать запуски в соответствии с расписанием из DAG-файла. Чтобы изменить расписание, обновите файл в хранилище DAG-файлов кластера и дождитесь синхронизации.

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

Для возобновления работы включите переключатель. При активации пайплайна могут создаваться запуски за пропущенные периоды — это зависит от параметра `catchup` в DAG-файле. Подробнее о нем в [документации Apache Airflow™](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dag-run.html#catchup).

## Ручной запуск пайплайна {#run-pipeline}

Чтобы запустить пайплайн вручную:

1. На панели слева выберите ![image](../../../../_assets/router.svg) **Оркестратор**, перейдите на вкладку **Пайплайны** и найдите нужный пайплайн.
1. Если пайплайн остановлен, [включите его](#activate-pipeline).
1. Откройте пайплайн, перейдите на вкладку **Запуски** и нажмите **Ручной запуск**.
1. В поле **Тип запуска** выберите **Ручной запуск**.
1. Укажите **Логическую дату запуска**. Она используется в контексте DAG и может отличаться от фактического времени выполнения. Это поле не задает время отложенного запуска.
1. Если пайплайн принимает параметры, укажите их в поле **Конфигурация JSON**. Состав параметров определяется кодом DAG.
1. Нажмите **Запустить**.
1. Найдите созданный запуск на вкладке **Запуски** и проверьте его статус.

Подробнее о логической дате и передаче параметров в [документации Apache Airflow™](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dag-run.html).

## Пересчет данных за прошлые периоды (Backfill) {#backfill}

Backfill создает запуски пайплайна за выбранный период по расписанию из DAG-файла. Используйте его, чтобы обработать пропущенные данные или повторить обработку за прошлые даты. Для Backfill у DAG должно быть расписание по времени.

Чтобы создать Backfill:

1. На панели слева выберите ![image](../../../../_assets/router.svg) **Оркестратор**, перейдите на вкладку **Пайплайны** и найдите нужный пайплайн.
1. Если пайплайн остановлен, [включите его](#activate-pipeline).
1. Откройте пайплайн, перейдите на вкладку **Запуски** и нажмите **Ручной запуск**.
1. В поле **Тип запуска** выберите **Backfill**.
1. В поле **Период** задайте начальную и конечную даты.
1. В поле **Какие запуски создать** выберите режим обработки:

   * **Отсутствующие** — создать только отсутствующие запуски.
   * **Отсутствующие и с ошибками** — создать отсутствующие запуски и повторить завершившиеся с ошибкой.
   * **Все** — создать отсутствующие запуски и повторить все завершенные, включая успешные.

1. В поле **Макс. активных запусков** задайте ограничение на количество одновременных запусков Backfill.
1. При необходимости включите опции:

   * **Запускать в обратном порядке** — чтобы сначала обрабатывать более поздние даты.
   * **Запускать на последней версии пакета** — чтобы использовать последнюю версию кода.

1. Нажмите **Запустить**.
1. Чтобы проверить созданный Backfill, откройте вкладку **Backfills** на странице пайплайна. Отдельные запуски также доступны на вкладке **Запуски** с фильтром **Тип запуска** → **Backfill**.

Если запуск за выбранную логическую дату уже выполняется или находится в очереди, новый запуск за эту дату не создается. Подробнее о режимах пересчета в [документации Apache Airflow™](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/backfill.html).

## Просмотр запусков и задач {#view-runs}

Чтобы проверить выполнение пайплайна:

1. На панели слева выберите ![image](../../../../_assets/router.svg) **Оркестратор**, перейдите на вкладку **Пайплайны** и найдите нужный пайплайн.
1. Откройте пайплайн и перейдите на вкладку **Запуски**.
1. Выберите период. При необходимости используйте поиск, фильтры **Статус** и **Тип запуска**.
1. Выберите строку запуска в таблице. На графе справа отобразятся задачи и их состояния для выбранного запуска. Запуск также можно выбрать в списке над графом.
1. Чтобы открыть подробности запуска, нажмите на его идентификатор в таблице слева.

На странице запуска отображаются его статус, тип, время выполнения, длительность, логическая дата и версия, а также список задач. Чтобы разобраться в ошибке отдельной задачи, откройте ее в этом списке. Подробную информацию о просмотре логов можно найти в разделе [Просмотр логов и XCom](#view-logs).

Для просмотра структуры пайплайна перейдите на вкладку **Задачи**. В таблице отображаются имена задач, правила их запуска, максимальное количество попыток и операторы. Выберите задачу в таблице, чтобы выделить ее на графе. Группы задач отображаются отдельными блоками.

Чтобы просмотреть историю сразу по всем пайплайнам, вернитесь в раздел ![image](../../../../_assets/router.svg) **Оркестратор** и откройте вкладку **Запуски пайплайнов** или **Запуски задач**.

## Просмотр логов и XCom {#view-logs}

Чтобы найти причину ошибки задачи:

1. Откройте [страницу запуска пайплайна](#view-runs).
1. В списке задач выберите нужную задачу и перейдите в нее.
1. На вкладке **Логи** выберите попытку выполнения, если их было несколько.
1. При необходимости отфильтруйте сообщения по уровню и источнику с помощью списков **Все уровни** и **Все источники**.
1. Изучите сообщения об ошибках. Чтобы изменить отображение логов, нажмите **Настройки логов**.

Чтобы сохранить логи в файл, нажмите ![image](../../../../_assets/console-icons/arrow-down-to-line.svg) **Скачать логи**.

На вкладке **XCom** можно просмотреть значения, которые задача передала через механизм обмена данными Apache Airflow™. Подробнее о нем в [документации Apache Airflow™](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/xcoms.html).

## Управление запусками {#manage-runs}

Чтобы просмотреть действия с существующими запусками, на панели слева выберите ![image](../../../../_assets/router.svg) **Оркестратор** → вкладка **Запуски пайплайнов** → ![image](../../../../_assets/console-icons/ellipsis.svg) меню в строке запуска.

### Перезапуск {#rerun}

Чтобы повторить выполнение запуска:

1. Найдите запуск и в его меню выберите **Перезапустить**.
1. В открывшемся окне подтвердите перезапуск.

Состояния задач этого запуска будут сброшены, и задачи будут запущены заново.

### Изменение статуса {#change-run-status}

Чтобы вручную изменить статус запуска:

1. Найдите запуск и в его меню выберите **Изменить статус**.
1. В блоке **Новый статус** выберите **Успешно** или **Ошибка**.
1. При необходимости заполните поле **Комментарий**.
1. Нажмите **Изменить статус**.

{% note info %}

Ручное изменение статуса само по себе не выполняет обработку данных и не исправляет причину ошибки.

{% endnote %}

### Удаление запуска {#delete-run}

{% note warning %}

Запуск и связанные с ним сведения в Apache Airflow™ удаляются без возможности восстановления.

{% endnote %}

Чтобы удалить запуск:

1. Найдите запуск и в его меню выберите **Удалить**.
1. В открывшемся окне подтвердите удаление.

## Просмотр кода и параметров пайплайна {#view-code}

Чтобы просмотреть DAG-файл, откройте пайплайн и перейдите на вкладку **Код**. Для изменения логики обработки, состава задач или расписания обновите файл в [хранилище DAG-файлов кластера](#add-pipeline) и дождитесь синхронизации.

Чтобы просмотреть параметры пайплайна и статистику его выполнения, перейдите на вкладку **Детали**.

## Ошибки загрузки DAG-файлов {#dag-import-errors}

Если в DAG-файле есть ошибка или для его загрузки не хватает зависимости, пайплайн может не появиться в списке. В разделе ![image](../../../../_assets/router.svg) **Оркестратор** отображается сообщение **Ошибки загрузки DAG-файлов**, даже если не загрузился ни один пайплайн.

Чтобы просмотреть ошибки:

1. В сообщении об ошибках нажмите **Подробнее**.
1. В открывшемся окне найдите файл с помощью поля **Поиск по файлу**.
1. Разверните запись с именем файла. Проверьте время ошибки, название пакета и трассировку стека.
1. Исправьте код или зависимости и дождитесь повторной загрузки DAG-файла.
1. Убедитесь, что ошибка исчезла, а пайплайн появился в списке.

## Проверка состояния кластера {#cluster-health}

Чтобы проверить состояние Apache Airflow™, на панели слева нажмите ![image](../../../../_assets/router.svg) **Оркестратор** и наведите указатель на статус в карточке кластера. В подсказке отображается состояние компонентов:

* **База метаданных**;
* **Планировщик**;
* **Триггер**;
* **DAG-процессор**.

Если данные не удалось загрузить и отображается кнопка **Повторить**, нажмите ее. Если ошибка сохраняется, передайте администратору сведения о недоступных компонентах и текст сообщения об ошибке.