Использование утилиты Migration Helper
- Обзор
- Требования
- Установка
- Использование Migration Helper
- Проверка DAG
- Проверка файлов зависимостей
- Проверка конфигурации Airflow
- Проверка базы данных метаданных
- Ручное исправление небезопасных результатов проверки
- AIR301: Удаленная функциональность
- AIR302: Функциональность перенесена в провайдер
- AIR303: Несовместимая сигнатура функции
- AIR304: Динамическое значение DAG или задачи
- AIR311 и AIR312: Функциональность, доступная через слой совместимости
- AIR321: Функциональность перенесена в Airflow 3.1
- Ошибки конфигурации, требующие ручного изменения
- Проверка изменений
Обзор
Утилита 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.
-
Создайте виртуальное окружение:
$ python3 -m venv .venv -
Активируйте окружение. Команда для Linux-систем:
$ source .venv/bin/activateКоманда для Windows:
$ .venv\Scripts\activate -
Установите Migration Helper. Чтобы установить только утилиту без Airflow (в этом случае проверки импорта DAG и миграции базы данных будут недоступны, а для проверки конфигурации будет использоваться статическая таблица правил), выполните следующую команду:
$ pip install airflow-migration-helperДля выполнения полного набора проверок установите Migration Helper с дополнительной зависимостью
airflow. Она устанавливает Airflow в окружение Migration Helper:$ pip install "airflow-migration-helper[airflow]" -
Убедитесь, что установка прошла успешно. Например, запросите справку:
$ 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 выполните следующие действия:
-
Установите Migration Helper в изолированное окружение.
-
Настройте отдельное окружение Airflow для проверки импорта DAG. Не используйте для этих проверок рабочую директорию Airflow или базу данных метаданных рабочей среды.
-
Инициализируйте тестовую базу данных метаданных с помощью команды
python -m airflow db migrate. -
Выполните первоначальный анализ с помощью команды
analyze. -
Проверьте результаты, требующие ручного исправления.
-
Примените поддерживаемые автоматические исправления, проверьте внесенные изменения и повторно выполните анализ.
-
При необходимости проверьте базу данных метаданных окружения 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 |
Статус каждой проверки, включая |
by_file |
Результаты проверки, сгруппированные по затронутым файлам |
by_type |
Результаты проверки, сгруппированные по идентификатору правила |
Каждый результат проверки может содержать следующие поля.
| Поле | Описание |
|---|---|
file |
Затронутый файл или логический объект, например airflow.cfg или requirements.txt |
line |
Строка исходного кода, в которой обнаружена проблема. Значение может быть |
col |
Столбец исходного кода, в котором обнаружена проблема. Значение может быть |
rule_id |
Идентификатор правила или ошибки, например |
message |
Краткое описание результата проверки |
severity |
Уровень результата проверки: |
fix_safety |
Указывает, поддерживается ли автоматическое исправление ( |
fix_description |
Описание рекомендуемого исправления или действия, которое необходимо выполнить вручную |
source |
Проверка, которая создала результат, например |
Пример отчета в формате 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, не совпадает с |
AIR002 |
Warning |
Ruff |
В DAG явно не указан аргумент |
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 по умолчанию изменено или сообщение |
CFG004 |
Info |
Airflow configuration |
Изменение конфигурации применено командой |
CFG005 |
Warning |
Airflow configuration |
Доступно изменение конфигурации, обнаруженное командой |
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.