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

Начните диагностику с состояния AirflowCluster и условий состояния в status.conditions.

Общая диагностикаОбщая диагностика

Через консоль управленияЧерез консоль управления

1. Выберите проект и пространство имен. В левом меню выберите Кластеры Airflow. Если пункт скрыт, раскройте Ещё. Откройте нужный кластер.
2. Проверьте состояние кластера в заголовке страницы.
3. Откройте вкладку Состояния. Найдите условия со значением False и прочитайте причину и сообщение об ошибке. Значения условий описаны ниже.
4. На вкладке Основное проверьте источник DAG, хранение логов, компоненты и дополнительные зависимости. В разделе Связанные ресурсы доступны ссылки на созданные базу метаданных и ресурсы хранилища.
5. При необходимости откройте вкладку YAML, чтобы проверить полную конфигурацию и status.conditions. Изменение YAML доступно при наличии прав на изменение кластера.

Если кластер готов, но DAG отсутствует или задача не выполняется, перейдите к ошибкам импорта, диагностике запуска или состояниям задач. Состояние Ready не подтверждает, что DAG-файлы успешно загружены и выполняются без ошибок.

Через CLIЧерез CLI

1. Посмотрите состояние кластера:

   kubectl get airflowcluster <имя_кластера> \
     -n <пространство_имен> \
     -o wide
   

2. Получите условия состояния и события кластера:

   kubectl describe airflowcluster <имя_кластера> \
     -n <пространство_имен>
   

3. Получите UID кластера для поиска его ресурсов:

   kubectl get airflowcluster <имя_кластера> \
     -n <пространство_имен> \
     -o jsonpath='{.metadata.uid}'
   

4. Проверьте поды Apache Airflow™, подставив полученный UID:

   kubectl get pods -n <пространство_имен> \
     -l 'tier=airflow,airflow.stackland.yandex.cloud/owner-uid=<UID_кластера>'
   

Форма создания недоступна или список версий пустФорма создания недоступна или список версий пуст

1. Проверьте выбранные проект и пространство имен, участие в проекте и права на ресурсы.
2. Если список версий не загружается, передайте администратору установки текст ошибки. Он должен проверить, что компонент включен, каталог AirflowImageCatalog airflow существует и у пользователя есть право его чтения.
3. Если ошибка возникает при создании кластера с приватным Git, сертификатами или закрытыми репозиториями пакетов, проверьте права на создание, чтение, привязку и очистку Secret и ConfigMap. Одного разрешения на создание AirflowCluster недостаточно.

Ошибка импорта DAGОшибка импорта DAG

1. Откройте веб-интерфейс Apache Airflow™ и перейдите на Home.

2. Если есть ошибки разбора файлов, откройте Dag Import Errors. Найдите файл по имени, раскройте запись и прочитайте traceback. Проверьте время ошибки, чтобы не принять старую запись за результат последнего обновления.

3. Исправьте причину:

   • SyntaxError — исправьте Python-код и обновите файл в источнике.
   • ModuleNotFoundError или ImportError — проверьте путь импорта, совместимость кода с Apache Airflow™ 3.1.8 и наличие нужного provider или библиотеки. При необходимости добавьте зависимости.
   • Ошибка чтения Variable или Connection при разборе файла — проверьте идентификатор и перенесите обращение к настройкам или внешнему сервису внутрь выполняемой задачи, если оно не требуется для построения DAG.

4. Дождитесь синхронизации и нового разбора. Убедитесь, что ошибка исчезла, а DAG появился в Dags с ожидаемым кодом.

Если Dag Import Errors отсутствует, проверьте Git или S3, путь к файлу и Git ref. Убедитесь, что файл создает объект DAG, а его имя и путь не исключены через .airflowignore. Подробнее — в описании загрузки DAG.

DAG виден, но запуск не появляетсяDAG виден, но запуск не появляется

1. Проверьте, что кластер находится в Ready, а DAG включен переключателем рядом с именем.
2. На вкладке Code проверьте актуальное значение schedule, start_date и, если задано, end_date. При schedule=None автоматических запусков не будет. Для проверки используйте ручной запуск.
3. Для расписания проверьте часовой пояс и наступление очередного времени запуска. Не ожидайте, что логическая дата всегда совпадает с фактическим временем начала выполнения.
4. На вкладке Runs проверьте активные запуски. Лимит max_active_runs может задерживать создание или начало следующих запусков.
5. Если ручной запуск также не выполняется, проверьте состояние его задач по инструкции ниже.

Задача ожидает выполненияЗадача ожидает выполнения

Откройте Dags → нужный DAG → Runs → запуск → задачу. Проверьте состояние и вкладку Details. На графе посмотрите состояния предшествующих задач.

До начала выполнения лог задачи может отсутствовать. Если ожидание не объясняется зависимостями и ограничениями, передайте администратору имя кластера, пространство имен, dag_id, идентификатор запуска, task_id, время и состояние задачи. Для пода в Pending полезны события kubectl describe pod; для ошибки загрузки образа — ее точный текст. Подробнее о состояниях — в документации Apache Airflow™.

Задача завершилась с ошибкойЗадача завершилась с ошибкой

1. Откройте логи нужной попытки и найдите исходную ошибку.
2. При ошибке подключения проверьте Connection ID и настройки подключения, права во внешнем сервисе и сетевой доступ из задачи.
3. При отсутствии переменной проверьте ее ключ в Variables. При ошибке импорта в выполняемой задаче проверьте установленные зависимости.
4. После исправления повторите задачу через Clear и проверьте новую попытку. Перед повтором убедитесь, что частично выполненная обработка допускает повторный запуск.

Кластер остается в ProvisioningКластер остается в Provisioning

Проверьте условия состояния, у которых поле status имеет значение False:

Точная причина указана в полях reason и message соответствующего условия. Проверяйте, что его observedGeneration совпадает с текущим metadata.generation.

Если устранить ошибку по инструкциям ниже не удалось, передайте администратору установки имя кластера, пространство имен и значения reason и message.

Ошибки GitОшибки Git

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

Для приватного HTTPS-репозитория Secret должен содержать непустые ключи username и password. Для SSH необходимы:

• ключ ssh-privatekey в Secret из authSecretRef;
• ключ known_hosts в ConfigMap из knownHostsConfigMapRef.

Имена ключей фиксированы. Также проверьте URL репозитория, наличие ветки, тега или коммита из ref и путь subPath.

Ошибки загрузки DAG-файлов смотрите в журнале контейнера git-sync:

kubectl get pods -n <пространство_имен> \
  -l 'tier=airflow,component=dag-processor,airflow.stackland.yandex.cloud/owner-uid=<UID_кластера>'
kubectl logs -n <пространство_имен> <имя_пода> -c git-sync

Ошибки S3-синхронизации DAGОшибки S3-синхронизации DAG

Если DAG-файлы из S3 не появляются в веб-интерфейсе, проверьте:

• имя бакета, эндпоинт, регион и режим forcePathStyle;
• ключи, указанные в credentialsSecretRef, и права доступа к бакету;
• CA-сертификат для эндпоинта с частным центром сертификации;
• наличие DAG-файлов под префиксом из subPath;
• сетевой доступ из пространства имен к S3.

Посмотрите журнал синхронизации:

kubectl get pods -n <пространство_имен> \
  -l 'tier=airflow,component=dag-processor,airflow.stackland.yandex.cloud/owner-uid=<UID_кластера>'
kubectl logs -n <пространство_имен> <имя_пода> -c dag-sync

Если поды остаются в Pending, посмотрите их события:

kubectl describe pod <имя_пода> -n <пространство_имен>

Учитывайте ограничения S3-источника. Если поды не запускаются из-за нехватки ресурсов или недоступности хранилища, передайте события администратору установки.

Пароль из Secret не подходитПароль из Secret не подходит

Найдите административный Secret по UID кластера. Если изменялся ключ username, восстановите исходное имя пользователя: изменение имени администратора не поддерживается.

После изменения ключа password дождитесь обработки Secret и проверьте InitialUserReady в status.conditions. При ошибке передайте значения reason и message администратору установки.

Если кластер вернулся в состояние Ready, но вход с новым паролем не работает, пароль существующего пользователя мог остаться прежним. Чтобы восстановить доступ, вручную установите в Apache Airflow™ пароль из Secret. Для этого нужны права на выполнение команд в подах (pods/exec); при отсутствии прав обратитесь к администратору установки.

1. Если кластер приостановлен, возобновите его. Найдите работающий под API server, подставив UID из инструкции Найти Secret:

   kubectl get pods -n <пространство_имен> \
     -l 'tier=airflow,component=api-server,airflow.stackland.yandex.cloud/owner-uid=<UID_кластера>'
   

2. Запустите команду смены пароля в найденном поде:

   kubectl exec -it <имя_пода> \
     -n <пространство_имен> \
     -c api-server -- \
     airflow users reset-password --username <имя_пользователя>
   

   Используйте имя пользователя из ключа username административного Secret. В интерактивном запросе введите пароль из ключа password и подтвердите его.

3. Выйдите из веб-интерфейса, затем войдите снова с паролем из Secret.

Ошибки базы данныхОшибки базы данных

База метаданных создается и настраивается автоматически. Если DatabaseReady=False долго сохраняется или Apache Airflow™ сообщает об ошибке подключения к базе, обратитесь к администратору установки. Передайте имя кластера, пространство имен и сообщение об ошибке.

Ошибки установки пакетовОшибки установки пакетов

Если DependenciesReady=False, начните с reason и message:

• SecretNotFound, InvalidSecret или InvalidCABundle — проверьте Secret из spec.dependencies.repositories: учетные данные, CA и ключ подписи APT. Требования приведены в разделе Репозитории пакетов;
• ImageBuildPending или ImageReplicationPending — зависимости еще подготавливаются к использованию. Дождитесь завершения обновления; если состояние долго не меняется, обратитесь к администратору установки;
• ImageBuildFailed — проверьте имена и версии пакетов, доступность репозиториев и совместимость зависимостей с версией Apache Airflow™ из spec.version.

Исправьте spec.dependencies или используемый Secret. Если причина неясна из message, передайте это сообщение администратору установки.

При ImagePullBackOff в событиях пода также обратитесь к администратору установки.

Не публикуется веб-интерфейсНе публикуется веб-интерфейс

Проверьте spec.publicAccess и состояние кластера. При spec.publicAccess: false используйте внутренний доступ или измените настройку.

При spec.publicAccess: true дождитесь состояния Ready и получите адрес из status.apiServerURL по инструкции Открыть веб-интерфейс. Если адрес не появляется или недоступен, передайте администратору установки имя кластера, пространство имен и сообщение об ошибке.

Удаление не завершаетсяУдаление не завершается

Удаление кластера включает удаление его данных и автоматически созданных бакетов и может занять время. Если состояние Deleting долго не меняется, передайте администратору установки результат команды kubectl describe airflowcluster <имя_кластера> -n <пространство_имен>.

Не отключайте компонент Managed Service for Apache Airflow™ до завершения удаления всех кластеров.