Использование утилиты Migration Helper

Обзор

Утилита Migration Helper помогает подготовить кластер с Airflow 2 к миграции на Airflow 3. Она анализирует исходный код DAG, конфигурацию Airflow и зависимости проекта, а также проверяет, можно ли импортировать DAG с целевой версией Airflow.

Migration Helper запускается для кластера, в котором установлен Airflow 2. При этом файлы кластера во время анализа не обновляются. Утилита запускается в отдельном виртуальном окружении и проверяет проект на соответствие правилам совместимости с Airflow 3.

Утилита выполняет несколько типов проверок:

  • правила Ruff для выявления проблем совместимости с Airflow 3 в коде Python;

  • проверки конфигурации Airflow;

  • проверки импорта DAG;

  • проверки совместимости зависимостей;

  • проверки миграции базы данных метаданных.

Требования

Ниже описано окружение, используемое для работы Migration Helper:

  • Python версии 3.10 или выше;

  • Git, доступный через PATH (только для параметра --modified-only; остальные проверки можно выполнять без Git);

  • рекомендуется использовать отдельное виртуальное окружение Python.

Установка

Рекомендуется устанавливать Migration Helper и его зависимости в отдельное виртуальное окружение, чтобы изолировать зависимости утилиты от системного Python.

  1. Создайте виртуальное окружение:

    $ python3 -m venv .venv
  2. Активируйте окружение. Команда для Linux-систем:

    $ source .venv/bin/activate

    Команда для Windows:

    $ .venv\Scripts\activate
  3. Установите Migration Helper. Чтобы установить только утилиту без Airflow (в этом случае проверки импорта DAG и миграции базы данных будут недоступны, а для проверки конфигурации будет использоваться статическая таблица правил), выполните следующую команду:

    $ pip install airflow-migration-helper

    Для выполнения полного набора проверок установите Migration Helper с дополнительной зависимостью airflow. Она устанавливает Airflow в окружение Migration Helper:

    $ pip install "airflow-migration-helper[airflow]"
  4. Убедитесь, что установка прошла успешно. Например, запросите справку:

    $ migration-helper -h

    Вывод команды:

    usage: migration-helper [-h] [--version] COMMAND ...
    
    Airflow 2 -> 3 migration utility.
    
    positional arguments:
      COMMAND
        analyze   Scan TARGET for Airflow 3 compatibility issues (read-only).
        fix       Scan TARGET and auto-apply fixes for Airflow 3 compatibility.
    
    options:
      -h, --help  show this help message and exit
      --version   show program's version number and exit

Использование Migration Helper

Migration Helper предоставляет две команды:

  • analyze — проверяет целевой проект в режиме только для чтения;

  • fix — выполняет проверки и применяет поддерживаемые утилитой автоматические исправления.

Для подготовки существующего проекта с DAG к миграции на Airflow 3 выполните следующие действия:

  1. Установите Migration Helper в изолированное окружение.

  2. Настройте отдельное окружение Airflow для проверки импорта DAG. Не используйте для этих проверок рабочую директорию Airflow или базу данных метаданных рабочей среды.

  3. Инициализируйте тестовую базу данных метаданных с помощью команды python -m airflow db migrate.

  4. Выполните первоначальный анализ с помощью команды analyze.

  5. Проверьте результаты, требующие ручного исправления.

  6. Примените поддерживаемые автоматические исправления, проверьте внесенные изменения и повторно выполните анализ.

  7. При необходимости проверьте базу данных метаданных окружения Airflow 2 с помощью параметра --db-migrate.

После проверки всех обнаруженных проблем протестируйте DAG в окружении с Airflow 3. Migration Helper следует использовать как часть процесса миграции, а не как замену функционального тестирования мигрированных DAG.

Подготовка изолированного окружения для проверки импорта DAG

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

Например, из директории проекта создайте отдельную директорию Airflow и настройте локальную базу данных метаданных SQLite:

$ export AIRFLOW_HOME="$PWD/.migration-helper-airflow"
$ export AIRFLOW_CONFIG="$AIRFLOW_HOME/airflow.cfg"
$ export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN="sqlite:///$AIRFLOW_HOME/metadata.db"
$ python -m airflow db migrate

Выполняйте эти команды в той же оболочке и окружении, из которых будет запускаться Migration Helper. Команда airflow db migrate инициализирует или обновляет тестовую базу данных метаданных для установленной версии Airflow. Не используйте рабочую базу данных для этого этапа настройки.

После инициализации тестового окружения запустите анализ директории с DAG:

$ migration-helper analyze ./dags/

Изолированное окружение предназначено для импорта и проверки DAG с версией Airflow, установленной вместе с Migration Helper. Если требуется проверить импорт с другой версией Airflow или другим набором провайдеров, используйте окружение, в котором установлены соответствующие версии.

Тихий режим проверок

При запуске утилиты в CI-пайплайнах можно использовать тихий режим с помощью параметра --quiet или -q:

$ migration-helper analyze ./dags/ --quiet

Параметр --quiet отключает вывод сведений о ходе проверки и результатов. Если указан параметр --report-dir, файлы отчетов по-прежнему создаются.

Отчеты

Для создания файлов отчетов используйте следующие параметры:

  • --report-dir — директория для сохранения отчетов. Например:

    $ migration-helper analyze ./dags/ --report-dir ./reports/
  • --output-format — формат отчета: json, html или all (по умолчанию). Например:

    $ migration-helper analyze ./dags/ \
      --report-dir ./reports/ \
      --output-format json

    Файлы отчетов создаются только при указании параметра --report-dir. При использовании формата all по умолчанию в указанной директории создаются оба файла: migration_report.json и migration_report.html.

Отчет в формате JSON содержит следующие поля верхнего уровня.

Поле Описание

generated_at

Дата и время создания отчета в формате UTC

target

Файл или директория, проанализированные Migration Helper

summary

Общее количество результатов проверки с разделением на ошибки и предупреждения, а также список проверок, которые не удалось выполнить (checkers_failed)

checkers

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

by_file

Результаты проверки, сгруппированные по затронутым файлам

by_type

Результаты проверки, сгруппированные по идентификатору правила

Каждый результат проверки может содержать следующие поля.

Поле Описание

file

Затронутый файл или логический объект, например airflow.cfg или requirements.txt

line

Строка исходного кода, в которой обнаружена проблема. Значение может быть null, если расположение в исходном коде недоступно

col

Столбец исходного кода, в котором обнаружена проблема. Значение может быть null

rule_id

Идентификатор правила или ошибки, например AIR301

message

Краткое описание результата проверки

severity

Уровень результата проверки: error, warning или info

fix_safety

Указывает, поддерживается ли автоматическое исправление (safe, unsafe или null). Если автоматическое исправление недоступно, в таблице результатов консоли отображается manual

fix_description

Описание рекомендуемого исправления или действия, которое необходимо выполнить вручную

source

Проверка, которая создала результат, например ruff, airflow_config, dag_check, dep_check или db_migrate

Пример отчета в формате JSON (сокращенный):

{
  "generated_at": "2026-09-29T10:53:50+00:00",
  "target": "dags",
  "summary": {
    "total": 11,
    "errors": 3,
    "warnings": 8
  },
  "by_file": {
    "/home/admin/dags/example_report.py": [
      {
        "file": "/home/admin/dags/example_report.py",
        "line": 21,
        "col": 2,
        "rule_id": "AIR311",
        "message": "`airflow.decorators.dag` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.",
        "severity": "warning",
        "fix_safety": "unsafe",
        "fix_description": "`dag` has been moved to `airflow.sdk` since Airflow 3.0 (with apache-airflow-task-sdk>=1.0.0).",
        "source": "ruff"
      },
      ...
    ]
  },
  "by_type": {
    "AIR301": [ ... ],
    "AIR311": [ ... ]
  }
}

Проверка определенной версии

Вы можете выбрать целевые версии Airflow и Python для проверки. По умолчанию при проверке зависимостей используется Airflow 3.2.1. При необходимости явно укажите целевые версии Airflow и Python:

$ migration-helper analyze ./dags/ \
  --target-airflow-version 3.2.1 \
  --target-python-version 3.10

Версия Python указывается в формате мажорной и минорной версии, например 3.10 или 3.11.

Проверка только измененных файлов

Если проект с DAG управляется с помощью Git, используйте параметр --modified-only, чтобы проверять только измененные и неотслеживаемые файлы. Список файлов определяется командой git status --porcelain --untracked-files=all:

$ migration-helper analyze <path> --modified-only

Если не удается определить состояние Git, Migration Helper проверяет все файлы.

Проверка DAG

Для подготовки к миграции начните с команды analyze. Она выполняет проверки и не редактирует анализируемые файлы.

Пример команды:

$ migration-helper analyze

Пример вывода:

Analyzing . …

File                                Line  Rule    Sev      Message                                                                                                                                          Fix
----------------------------------  ----  ------  -------  -----------------------------------------------------------------------------------------------------------------------------------------------  ------
/home/admin/dags/example_report.py  21    AIR311  warning  `airflow.decorators.dag` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.             unsafe
/home/admin/dags/example_report.py  23    AIR311  warning  `airflow.datasets.Dataset` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.           safe
/home/admin/dags/example_report.py  44    AIR311  warning  `airflow.decorators.task_group` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.      unsafe
/home/admin/dags/example_report.py  47    AIR311  warning  `airflow.decorators.task` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.            unsafe
/home/admin/dags/example_report.py  51    AIR301  error    `airflow.operators.python.get_current_context` is removed in Airflow 3.0                                                                         unsafe
/home/admin/dags/example_report.py  58    AIR311  warning  `airflow.decorators.task` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.            unsafe
/home/admin/dags/example_report.py  64    AIR301  error    `airflow.operators.python.get_current_context` is removed in Airflow 3.0                                                                         unsafe
/home/admin/dags/example_report.py  78    AIR311  warning  `airflow.decorators.task` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.            unsafe
/home/admin/dags/example_report.py  85    AIR301  error    `airflow.operators.python.get_current_context` is removed in Airflow 3.0                                                                         unsafe
/home/admin/dags/example_report.py  108   AIR311  warning  `airflow.decorators.task` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.            unsafe
/home/admin/dags/example_report.py  130   AIR311  warning  `airflow.models.baseoperator.chain` is removed in Airflow 3.0; It still works in Airflow 3.0 but is expected to be removed in a future version.  unsafe
airflow/airflow.cfg                 —     CFG001  warning  [core] min_serialized_dag_update_interval moved to [scheduler].                                                                                  safe
airflow/airflow.cfg                 —     CFG002  error    [core] executor='SequentialExecutor' removed in Airflow 3. Use 'LocalExecutor'.                                                                  manual
airflow/airflow.cfg                 —     CFG001  warning  [scheduler] job_heartbeat_sec renamed to scheduler_heartbeat_sec.                                                                                safe
airflow/airflow.cfg                 —     CFG003  warning  [logging] base_log_folder: verify path is accessible from all workers.                                                                           manual

17 issue(s): 4 error(s), 13 warning(s)

Per-checker breakdown:
  ruff            11 issue(s)
  airflow_config  6 issue(s)
  dag_check       0 issue(s)
  dep_check       0 issue(s)
  db_migrate      0 issue(s)

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

Analyzing . …
No issues found. Ready for Airflow 3.

Проверка определенного DAG

Чтобы проанализировать отдельный DAG или директорию с DAG, выполните:

$ migration-helper analyze <path>

где <path> — директория с DAG или путь к DAG, который необходимо проверить.

Проверка DAG на ошибки импорта

Проверка импорта DAG выполняет следующую команду Airflow из окружения Migration Helper:

$ airflow dags list-import-errors

Эта проверка позволяет найти DAG, которые невозможно импортировать с версией Airflow, установленной в окружении проверки.

Пример результата проверки:

bundle_name  | filepath                   | error
=============+============================+===========================================================================================================================================
example_dags | example_asset_partition.py | Traceback (most recent call last):
             |                            |   File "<attrs generated methods airflow.sdk.definitions.dag.DAG>", line 89, in __init__
             |                            |     __attr_validator_catchup(self, __attr_catchup, self.catchup)
             |                            |   File "/usr/lib/ado_3.2.1_arenadata1/airflow/lib/python3.10/site-packages/airflow/sdk/definitions/dag.py", line 606, in _validate_catchup
             |                            |     raise ValueError("start_date is required when catchup=True")
             |                            | ValueError: start_date is required when catchup=True

Ошибки импорта представляют собой диагностические сведения. Migration Helper не изменяет код DAG автоматически.

ПРИМЕЧАНИЕ

Проверка импорта DAG выполняет команду Airflow из окружения проверки. Поэтому на результат влияют установленные в этом окружении версия Airflow и провайдеры.

Проверка файлов зависимостей

Проверка зависимостей сопоставляет объявленные зависимости проекта с целевыми версиями Airflow и Python.

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

По умолчанию используются следующие целевые версии:

  • Airflow 3.2.1;

  • версия Python интерпретатора, в котором запущен Migration Helper.

По умолчанию утилита проверяет файл requirements.txt.

Чтобы использовать другой файл зависимостей, укажите его с помощью параметра --dependency-file. Поддерживаются файлы зависимостей с расширением .txt и файл pyproject.toml:

$ migration-helper analyze ./dags/ \
  --dependency-file requirements-prod.txt

Проверка разрешает объявленные зависимости с учетом файлов ограничений Airflow для выбранных целевых версий. Эти файлы включены в состав утилиты.

Чтобы использовать uv вместо pip для проверки разрешения зависимостей, укажите параметр --use-uv:

$ migration-helper analyze ./dags/ --use-uv

Проверка конфигурации Airflow

Проверка конфигурации анализирует файлы конфигурации Airflow на наличие параметров, несовместимых с целевой версией Airflow.

Для проверки используется встроенная таблица правил совместимости конфигурации Airflow.

Если Airflow установлен в окружении Migration Helper, утилита дополнительно может выполнить команду:

$ airflow config lint

Интерфейс командной строки Airflow работает с активной конфигурацией окружения Migration Helper, определяемой параметрами AIRFLOW_HOME и AIRFLOW_CONFIG.

Команда Airflow CLI не проверяет автоматически файл airflow.cfg, найденный в анализируемом проекте.

Чтобы проверить определенный файл конфигурации через Airflow CLI, укажите его путь в параметре AIRFLOW_CONFIG.

Пример:

$ AIRFLOW_CONFIG=/path/to/airflow.cfg \
  migration-helper analyze ./dags/

Пример результата:

airflow/airflow.cfg — CFG002  error    [core] executor='SequentialExecutor' removed in Airflow 3. Use 'LocalExecutor'.

Таким образом, результаты проверки конфигурации могут быть получены как при статическом анализе конфигурации, так и при проверке конфигурации Airflow в окружении утилиты.

Применение исправлений конфигурации

ПРИМЕЧАНИЕ

Исправления конфигурации необязательны для пользователей ADO. При обычном обновлении через ADCM конфигурация Airflow обновляется автоматически вместе с обновлением бандла.

Команда fix запускает механизм обновления конфигурации Airflow. Параметр --fix-config применяет рекомендуемые изменения конфигурации непосредственно к файлу. В текущей версии этот механизм автоматически включается при запуске fix, поэтому добавление параметра --fix-config не меняет поведение команды.

Airflow изменяет файл активной конфигурации, выбранный с помощью AIRFLOW_CONFIG. Если этот параметр не задан, Airflow использует файл конфигурации из AIRFLOW_HOME (обычно $AIRFLOW_HOME/airflow.cfg). Команда не изменяет автоматически файл airflow.cfg только потому, что он находится в директории проекта, выбранной для анализа.

Чтобы обновить определенный файл, укажите путь к нему в AIRFLOW_CONFIG перед запуском команды. Например:

$ AIRFLOW_CONFIG=/path/to/airflow.cfg \
  migration-helper fix ./dags/ --fix-config

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

Перед применением обновленной конфигурации проверьте полученный файл и справочную информацию по конфигурации целевой версии Airflow.

Проверка базы данных метаданных

ПРИМЕЧАНИЕ

Проверка БД метаданных необязательна для пользователей ADO. При стандартном обновлении через ADCM миграция БД метаданных выполняется автоматически в рамках обновления бандла.

Проверка базы данных метаданных является необязательной.

Запустить ее можно с помощью команды:

$ migration-helper analyze ./dags/ --db-migrate

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

$ airflow db check-migrations

Команда работает в режиме только для чтения и не применяет миграции базы данных.

Для выполнения проверки не требуется запускать процессы Airflow, однако окружение проверки должно иметь доступ к базе данных метаданных.

По умолчанию утилита использует базу данных, настроенную в ее окружении. Чтобы проверить базу данных метаданных существующего кластера Airflow 2, настройте окружение проверки с соответствующим подключением к базе данных, например:

$ export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN='postgresql://user:password@host:5432/airflow'
$ migration-helper analyze ./dags/ --db-migrate

Migration Helper не применяет миграции. После проверки результата примените миграции отдельно с помощью команды airflow db migrate. Не запускайте эту команду для рабочей базы данных, если не планируете применять к ней миграции.

Ручное исправление небезопасных результатов проверки

Отчет Migration Helper содержит коды ошибок, которые определяют тип несовместимости. Код описывает тип проверки, обнаружившей проблему, и включается в отчеты в форматах JSON и HTML.

Для проверки Ruff используются коды AIR. Migration Helper также использует коды для проверок конфигурации (CFG), импорта DAG, зависимостей и базы данных (DB).

Код Серьезность Источник Описание

AIR001

Warning

Ruff

Имя переменной, присвоенное оператору Airflow, не совпадает с task_id этого оператора

AIR002

Warning

Ruff

В DAG явно не указан аргумент schedule, из-за чего поведение планирования изменится при миграции с Airflow 2 на Airflow 3

AIR301

Error

Ruff

Функциональность Airflow удалена в Airflow 3.0

AIR302

Error

Ruff

Функциональность Airflow перенесена из основного пакета Airflow в провайдер в Airflow 3.0

AIR303

Error

Ruff

Сигнатура функции или метода Airflow несовместима с Airflow 3.0

AIR304

Error

Ruff

Изменяющееся во время выполнения значение используется в качестве аргумента DAG или задачи и может приводить к созданию новой версии DAG при повторном парсинге

AIR311

Warning

Ruff

Функциональность Airflow удалена в Airflow 3.0, но остается доступной через слой совместимости

AIR312

Warning

Ruff

Функциональность Airflow перенесена в провайдер в Airflow 3.0, но остается доступной через слой совместимости

AIR321

Error

Ruff

Функциональность Airflow перенесена в Airflow 3.1

CFG001

Warning or error

Airflow configuration

Параметр конфигурации Airflow перенесен в другой раздел или переименован в целевой версии Airflow

CFG002

Warning or error

Airflow configuration

Параметр конфигурации Airflow удален в целевой версии Airflow

CFG003

Warning

Airflow configuration

Значение параметра конфигурации Airflow по умолчанию изменено или сообщение config lint не соответствует более конкретной категории конфигурации

CFG004

Info

Airflow configuration

Изменение конфигурации применено командой airflow config update --all-recommendations --fix

CFG005

Warning

Airflow configuration

Доступно изменение конфигурации, обнаруженное командой airflow config update --all-recommendations --dry-run

DEP_RESOLUTION_FAILED

Error

Dependencies

Объявленные зависимости проекта невозможно разрешить для выбранных версий Airflow и Python

DB001

Warning

Metadata database

В базе данных метаданных Airflow имеются ожидающие миграции

Migration Helper указывает, поддерживается ли автоматическое исправление для обнаруженной проблемы. Поле fix_safety в отчете может содержать следующие значения:

  • safe — существует механическое исправление, которое можно безопасно применить;

  • unsafe — существует возможное исправление, но изменение требует проверки пользователем;

  • null — автоматическое исправление недоступно, проблему необходимо исправить вручную.

Migration Helper поддерживает несколько автоматических исправлений ошибок. Перед применением исправлений рекомендуется выполнить пробный запуск и проверить предлагаемые изменения:

$ migration-helper fix ./dags/ --safe-only --dry-run

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

$ migration-helper fix ./dags/ --safe-only

Чтобы применить также небезопасные исправления, используйте параметр --unsafe:

$ migration-helper fix ./dags/ --unsafe

Если не указан ни --safe-only, ни --unsafe, команда выводит уведомление и по умолчанию применяет только безопасные исправления. Перед развертыванием DAG проверьте все изменения: механически корректное изменение кода может повлиять на предполагаемое поведение DAG.

В следующих разделах описаны распространенные проблемы, требующие проверки пользователем. Конкретное исправление зависит от API или параметра конфигурации, указанного Migration Helper. После внесения изменений повторно запустите analyze, чтобы проверить результат.

AIR301: Удаленная функциональность

AIR301 указывает, что функция, класс, атрибут, импорт или другая функциональность Airflow, используемая DAG, была удалена в Airflow 3.0.

После миграции на Airflow 3 DAG больше не может использовать эту функциональность. Затронутый API необходимо заменить эквивалентом для Airflow 3.

Например, в DAG Airflow 2 может использоваться функция days_ago:

from airflow import DAG
from airflow.utils.dates import days_ago

dag = DAG(
    dag_id="example",
    start_date=days_ago(1),
)

Замените удаленный API реализацией, совместимой с Airflow 3. Например, вместо вычисления даты начала с помощью days_ago можно указать дату явно:

from datetime import datetime

from airflow import DAG

dag = DAG(
    dag_id="example",
    start_date=datetime(2024, 1, 1),
)

Необходимое изменение зависит от удаленной функциональности. Перед изменением DAG ознакомьтесь с документацией по миграции на Airflow 3 и найдите соответствующую замену.

AIR302: Функциональность перенесена в провайдер

AIR302 указывает, что функциональность Airflow была перенесена из основного пакета Airflow в пакет провайдера.

Функциональность по-прежнему доступна, но ее необходимо импортировать из провайдера, которому она теперь принадлежит. Соответствующий провайдер также должен быть установлен в окружении Airflow.

Например, в DAG Airflow 2 можно импортировать FabAuthManager из основного пакета Airflow:

from airflow.auth.managers.fab.fab_auth_manager import FabAuthManager

auth_manager = FabAuthManager()

В Airflow 3 эта функциональность предоставляется провайдером FAB. Измените импорт на пакет провайдера и убедитесь, что провайдер включен в зависимости проекта:

from airflow.providers.fab.auth_manager.fab_auth_manager import FabAuthManager

auth_manager = FabAuthManager()

Требуемый провайдер и путь импорта зависят от переносимой функциональности. Убедитесь, что версия провайдера совместима с версией Airflow, используемой в окружении.

AIR303: Несовместимая сигнатура функции

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

Например, в Airflow 2 параметр schedule_interval можно было передать в конструктор DAG:

from airflow import DAG

dag = DAG(
    dag_id="example",
    schedule_interval="0 0 * * *",
)

В Airflow 3 используется аргумент schedule. Поэтому вызов с аргументом Airflow 2 несовместим с сигнатурой Airflow 3.

Измените вызов, используя сигнатуру Airflow 3:

from airflow import DAG

dag = DAG(
    dag_id="example",
    schedule="0 0 * * *",
)

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

AIR304: Динамическое значение DAG или задачи

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

Airflow многократно парсит файлы DAG. Поэтому такие значения, как текущее время, могут отличаться при каждом парсинге. Если такое значение используется там, где Airflow ожидает стабильное определение DAG или задачи, DAG может постоянно создавать новые версии.

Например:

from datetime import datetime

from airflow import DAG

dag = DAG(
    dag_id="example",
    start_date=datetime.now(),
)

где datetime.now() возвращает разное значение при каждом выполнении файла DAG. Вместо этого используйте стабильное значение:

from datetime import datetime

from airflow import DAG

dag = DAG(
    dag_id="example",
    start_date=datetime(2024, 1, 1),
)

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

AIR311 и AIR312: Функциональность, доступная через слой совместимости

AIR311 указывает, что функциональность Airflow удалена из прежнего источника, но остается доступной через слой совместимости. AIR312 указывает, что функциональность перенесена в провайдер, но остается доступной через слой совместимости.

Такие результаты являются предупреждениями, а не ошибками импорта. Но результат с пометкой unsafe требует проверки, поскольку утилита не может безопасно определить, как обновить код во всех возможных случаях. Рекомендуется импортировать API из поддерживаемого источника в Airflow 3 и убедиться, что необходимый пакет провайдера или пакет SDK задач установлены.

Например, декоратор dag может импортироваться из источника, сохраненного для совместимости:

from airflow.decorators import dag

@dag(schedule=None)
def example():
    ...

В Airflow 3 импортируйте его из airflow.sdk:

from airflow.sdk import dag

@dag(schedule=None)
def example():
    ...

Аналогичным образом, если оператор перенесен в провайдер, измените импорт на пакет провайдера и добавьте необходимый провайдер в зависимости проекта. Используйте путь замены, указанный в поле fix_description результата проверки. Для разных API целевые расположения могут отличаться.

AIR321: Функциональность перенесена в Airflow 3.1

AIR321 указывает, что функциональность Airflow была перенесена в другой объект в Airflow 3.1.

Затронутая функциональность может по-прежнему быть доступна, но для совместимости с Airflow 3.1 DAG должен использовать новое расположение.

Например, DAG Airflow 3.0 может использовать convert_to_utc из прежнего расположения:

from airflow.utils.timezone import convert_to_utc

execution_time = convert_to_utc(execution_time)

В Airflow 3.1 функция была перенесена в Airflow SDK. Измените импорт на новый:

from airflow.sdk.timezone import convert_to_utc

execution_time = convert_to_utc(execution_time)

Необходимое изменение зависит от функциональности, указанной проверкой. Измените импорт и использование соответствующего API в соответствии с API Airflow 3.1.

Ошибки конфигурации, требующие ручного изменения

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

Если для результата проверки конфигурации автоматическое исправление недоступно (fix_safety имеет значение null, а в таблице результатов консоли отображается manual), измените соответствующий параметр вручную в соответствии с сообщением о проблеме. В сообщении указывается старый параметр конфигурации и, если доступно, подходящая замена.

Например, если в отчете указано, что SequentialExecutor удален и рекомендуется использовать LocalExecutor, измените параметр в активном файле конфигурации:

[core]
executor = LocalExecutor

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

При запуске migration-helper fix учитывайте, что Airflow обновляет файл, указанный в AIRFLOW_CONFIG, или файл конфигурации из AIRFLOW_HOME, если AIRFLOW_CONFIG не задан. Это не обязательно файл конфигурации в анализируемом проекте. Airflow может добавлять новые параметры в виде закомментированных строк. Они не являются активными переопределениями. Удаляйте комментарий и задавайте значение только тогда, когда требуется переопределить значение по умолчанию целевой версии Airflow.

После изменения конфигурации снова запустите Migration Helper и проверьте полученный отчет. Если утилита сообщает о другой проблеме конфигурации, примените соответствующее правило миграции перед продолжением обновления Airflow.

Проверка изменений

После ручного исправления всех проблем, помеченных как unsafe или не имеющих автоматического исправления, снова запустите Migration Helper для обновленных DAG и конфигурации.

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

Если ошибка остается после изменения кода или конфигурации, убедитесь, что Migration Helper анализирует обновленные файлы, а версии Airflow и пакетов провайдеров в окружении миграции соответствуют целевому окружению Airflow.

Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней