Amazon MWAA における Apache Airflow 2.x から Apache Airflow 3.x への移行のベストプラクティス

本記事は、2025 年 10 月 7 日に公開された Best practices for migrating from Apache Airflow 2.x to Apache Airflow 3.x on Amazon MWAA を翻訳したものです。翻訳はクラウドサポートエンジニアの山本が担当しました。

Amazon MWAA の Apache Airflow 3.x では、セキュリティと分離性を強化する API ベースのタスク実行など、アーキテクチャの改善が導入されています。その他の主要なアップデートには、ユーザーエクスペリエンスを向上させた UI の再設計、パフォーマンスを改善したスケジューラーベースのバックフィル、Python 3.12 のサポートが含まれています。Amazon MWAA における Airflow のマイナーバージョンのインプレースアップグレードとは異なり、Airflow 2 から Airflow 3 へのアップグレードには根本的な破壊的変更があるため、慎重な計画と移行アプローチによる実行が必要です。

この移行は、ビジネス継続性を確保しながら、次世代のワークフローオーケストレーション機能を導入する機会となります。しかし、これは単なるアップグレードではありません。Amazon MWAA で Airflow 3.x に移行する組織は、ワーカーからのメタデータデータベースへの直接アクセスの削除、SubDAG の廃止、デフォルトのスケジューリング動作の変更、ライブラリ依存関係の更新など、破壊的変更を理解する必要があります。この記事では、ミッションクリティカルなデータパイプラインへの影響を最小限に抑えながら、Airflow 3 の強化された機能を最大限に活用するための、ベストプラクティスとして合理的なアプローチを提供します。

移行プロセスの理解

Amazon MWAA における Airflow 2.x から 3.x への移行には、組織が移行を開始する前に理解しておくべき、いくつかの基本的な変更が含まれています。これらの変更は主要なワークフローの操作に影響を与えるため、スムーズな移行を実現するには慎重な計画が必要です。

以下の破壊的な変更に注意してください：

直接的なデータベースアクセスの削除 – Airflow 3 における破壊的変更は、ワーカーノードからのメタデータデータベースへの直接アクセスができなくなったことです。タスクとカスタムオペレーターは、直接的なデータベースアクセスではなく REST API を介して通信する必要があります。この設計変更は、以前 SQLAlchemy 接続を通じてメタデータデータベースに直接アクセスしていたコードに影響を与え、既存の DAG とカスタムオペレーターのリファクタリングが必要になります。
SubDAG の廃止 – Airflow 3 では、TaskGroups、Assets、Data Aware Scheduling を優先し、SubDAG 構造を削除します。組織は既存の SubDAG を前述のいずれかの構造にリファクタリングする必要があります。
スケジューリング動作の変更 – デフォルトのスケジューリングオプションに関する 2 つの注目すべき変更により、影響分析が必要です：
- catchup_by_default と create_cron_data_intervals のデフォルト値が False に変更されました。この変更は、これらのオプションを明示的に設定していない DAG に影響を与えます。
- Airflow 3 では、execution_date、tomorrow_ds、yesterday_ds、prev_ds、next_ds などのいくつかのコンテキスト変数が削除されます。これらの変数を、現在サポートされているコンテキスト変数に置き換える必要があります。
ライブラリと依存関係の変更 – Airflow 3.x では多数のライブラリが変更され、DAG コードのリファクタリングが必要になります。以前に含まれていた多くのプロバイダーパッケージは、requirements.txt ファイルに明示的に追加する必要が場合があります。
REST API の変更 – REST API のパスが /api/v1 から /api/v2 に変更され、外部統合に影響を与えます。Airflow REST API の使用に関する詳細については、ウェブサーバーセッショントークンを作成し、Apache Airflow REST API を呼び出すをご参照ください。
認証システム – Airflow 3.0.1 以降のバージョンでは Flask-AppBuilder の代わりに SimpleAuthManager がデフォルトになりますが、Amazon MWAA は Airflow 3.x でも引き続き Flask-AppBuilder を使用します。これは、Amazon MWAA のお客様には認証の変更が発生しないことを意味します。

この移行では、インプレースアップグレードではなく、新しい環境を作成する必要があります。このアプローチはより多くの計画とリソースを必要としますが、移行プロセス中にフォールバックオプションとして既存の環境を維持できるという利点があり、ビジネスの継続性を確保できます。

移行前の計画と評価

移行を成功させるには、現在の環境を徹底的に計画し評価することが重要です。この段階では、依存関係、構成、潜在的な互換性の問題を特定することで、スムーズな移行の基盤を確立します。前述の互換性に影響する変更点に照らして環境とコードを評価し、移行を成功に導きましょう。

環境評価

まず、現在の Amazon MWAA 環境の完全なインベントリを作成します。すべての DAG、カスタムオペレーター、プラグイン、依存関係について、それぞれの特定のバージョンと構成を含め文書化します。Airflow 3.x を搭載した Amazon MWAA へのアップグレードに最適な互換性パスを提供するため、現在の環境がバージョン 2.10.x であることを確認してください。

DAG コード、requirements ファイル、起動スクリプト、プラグインが含まれている Amazon Simple Storage Service (Amazon S3) バケットの構造を確認します。この構造を新しい環境用の新しいバケットに複製します。環境ごとに個別のバケットを作成することで、競合を回避し、現在のパイプラインに影響を与えることなく開発を継続できます。

設定ドキュメント

すべてのカスタム Amazon MWAA 環境変数、Airflow 接続、環境設定を文書化してください。新しい環境の実行ロールには同一のポリシーが必要となるため、AWS Identity and Access Management (IAM) のリソースを確認してください。Airflow UI にアクセスする IAM ユーザーまたはロールには、新しい環境に対する CreateWebLoginToken 権限が必要です。

パイプラインの依存関係

パイプラインの依存関係を理解することは、段階的な移行を成功させるために重要です。Datasets (現在は Assets)、SubDAG、TriggerDagRun オペレーター、または外部 API との連携を通じて相互依存関係を特定してください。これらの依存関係に基づいて移行計画を立て、関連する DAG を同時に移行できるようにします。

移行ウェーブを計画する際は、DAG のスケジューリング頻度を考慮してください。実行間隔が長い DAG は、頻繁に実行される DAG と比較して、より長い移行期間を確保でき、重複実行のリスクも低くなります。

テスト戦略

互換性の問題を特定するための体系的なアプローチを定義して、テスト戦略を作成します。ruff linter を AIR30 ルールセットと共に使用して、更新が必要なコードを自動的に特定します。

ruff check --preview --select AIR30 <path_to_your_dag_code>

次に、環境の requirements.txt ファイルを確認し、パッケージのバージョンが更新された制約ファイルに準拠するように更新してください。また、以前は airflow-core パッケージに含まれていた一般的に使用されるオペレーターは、現在は別のパッケージに移動されているため、requirements ファイルに追加する必要があります。

Airflow 3.x 用の Amazon MWAA Docker イメージを使用して DAG をテストします。これらのイメージを使用することで、requirements ファイルの作成とテスト、そしてスケジューラーが DAG を正常にパースすることを確認できます。

移行戦略とベストプラクティス

体系的な移行アプローチにより、明確な検証チェックポイントを提供しながら、リスクを最小限に抑えることができます。推奨される戦略は、信頼性の高い移行と即時のロールバック機能を提供する段階的ブルー/グリーンデプロイメントモデルを採用しています。

段階的な移行のアプローチ

以下の移行フェーズは、移行計画の定義に役立ちます。

フェーズ 1: 発見、評価、計画 – このフェーズでは、環境のインベントリ、依存関係のマッピング、変更による影響の分析を完了します。収集した情報を基に、詳細な移行計画を策定します。この計画には、コードの更新、requirements ファイルの更新、テスト環境の作成、テスト、ブルー/グリーン環境の作成 (この記事の後半で説明)、および移行手順が含まれます。また、計画には、トレーニング、モニタリング戦略、ロールバック条件、ロールバック計画も含める必要があります。
フェーズ 2: パイロット移行 – パイロット移行フェーズでは、影響範囲が限定された管理環境で詳細な移行計画の検証を行います。異なるスケジュールや依存関係など、多様な特性を持つ 2 ～ 3 個の重要度の低い DAG にフォーカスします。前のフェーズで定義した移行計画を使用して、選択した DAG を移行します。このフェーズを活用して計画とモニタリングツールを検証し、実際の結果に基づいて両者を調整します。パイロット中に、完全な移行のパフォーマンスを予測するのに役立つ基準となる移行メトリクスを確立します。
フェーズ 3: 段階的な本番移行 – パイロットが成功したら、残りの DAG の段階的な完全移行を開始する準備が整います。残りの DAG を、ビジネスの重要度 (重要度の低いものから開始)、技術的な複雑さ、相互依存関係 (依存関係のある DAG をまとめて移行)、スケジュールの頻度 (実行頻度の低い DAG は移行に時間を確保できる) に基づいて論理的なウェーブにグループ化します。ウェーブを定義したら、ステークホルダーと協力してウェーブスケジュールを作成します。次のウェーブを開始する前に、ウェーブが成功したことを確認するための十分な検証期間を設けます。この時間は、移行の問題が発生した場合の影響範囲を抑え、ロールバックを実行するための十分な時間も確保します。
フェーズ 4: 移行後のレビューと廃止 – すべてのウェーブが完了したら、得られた知見、最適化の機会、その他の未解決の項目を特定するために移行後のレビューを実施します。これはシステムの安定性を承認するのにも適した時期です。最後のステップは、元の Airflow 2.x 環境の廃止です。ビジネス要件と意見に基づいて安定性が確認されたら、元の (ブルー) 環境を廃止します。

ブルー/グリーンデプロイメント戦略

安全で元に戻せる移行のために、ブルー/グリーンデプロイメント戦略を実装します。この戦略では、移行中に 2 つの Amazon MWAA 環境が稼働し、どの DAG をどの環境で実行するかを管理します。

ブルー環境 (現行の Airflow 2.x) は、移行中に本番ワークロードを維持します。移行前に DAG の変更に対する停止期間を設定することで、直前のコードの競合を回避できます。この環境は、新しい (グリーン) 環境で問題が特定された場合の即時ロールバック環境として機能します。

グリーン環境 (新しい Airflow 3.x) は、制御された段階で移行された DAG を受け取ります。ブルー環境からネットワーク、IAM ロール、セキュリティ設定をミラーリングします。この環境はブルー環境と同じオプションで構成し、同一の監視メカニズムを作成して、両環境を同時に監視できるようにします。DAG の重複実行を避けるため、DAG が単一の環境でのみ実行されるようにしてください。これには、グリーン環境で DAG をアクティブ化する前に、ブルー環境で DAG を一時停止することが含まれます。移行全体を通じて、ブルー環境をウォームスタンバイモードで維持します。各移行段階での具体的なロールバック手順を文書化し、少なくとも 1 つの重要度の低い DAG でロールバック手順をテストしてください。さらに、ロールバックのトリガー基準（特定の失敗率や SLA 違反など）を明確に定義してください。

段階的な移行プロセス

このセクションでは、移行を実施するための詳細な手順を説明します。

移行前の評価と準備

移行プロセスを開始する前に、現在の環境を徹底的に評価し、移行計画を策定してください。

現在の Amazon MWAA 環境がバージョン 2.10.x であることを確認してください
DAG、カスタムオペレーター、プラグインについて、それらの依存関係とバージョンを含む詳細なインベントリを作成してください
現在の requirements.txt ファイルを確認し、パッケージの要件を理解してください
すべての環境変数、接続、設定を文書化してください
Apache Airflow 3.x リリースノートを確認し、破壊的変更を理解してください
移行の成功基準、ロールバック条件、ロールバック計画を決定してください
パイロット移行に適した少数の DAG を特定してください
Amazon MWAA ユーザーに対する Airflow 3 のトレーニングまたは習熟計画を策定してください

互換性のチェック

互換性の問題を特定することは、移行を成功させる上で重要です。このステップにより、開発者は Airflow 3 と互換性のない特定のコードに焦点を当てることができます。 ruff linterを AIR30 ルールセットと共に使用して、更新が必要なコードを自動的に特定します。

ruff check --preview --select AIR30 <path_to_your_dag_code>

さらに、メタデータベースへの直接アクセスがコードに含まれていないか確認してください。

DAG コードの更新

互換性テストの結果に基づいて、Airflow 3.x に影響を受ける DAG コードを更新してください。ruff DAG チェックユーティリティを使用すると、一般的な変更を自動的に修正できます。以下のコマンドを使用して、更新モードでユーティリティを実行してください：

ruff check dag/ --select AIR301 --fix ––preview

一般的な変更点は以下の通りです:

メタデータベースへの直接アクセスを API 呼び出しに置き換える：

# Before (Airflow 2.x) - Direct DB access

from airflow.settings import Session
from airflow.models.taskInstance import TaskInstance
session=Session()
result=session.query(TaskInstance)

For Apache Airflow v3.x, utilize in the Amazon MWAA SDK.
Update core construct imports with the new Airflow SDK namespace:
# Before (Airflow 2.x)
from airflow.decorators import dag, task

# After (Airflow 3.x)
from airflow.sdk import dag, task

非推奨のコンテキスト変数を最新の同等のものに置き換える：

# Before (Airflow 2.x)
def my_task(execution_date, **context):
    # Using execution_date

# After (Airflow 3.x)
def my_task(logical_date, **context):
    # Using logical_date

次に、2 つのスケジューリング関連のデフォルト変更の使用状況を評価します。catchup_by_default が False になったため、欠落した DAG の実行は自動的にバックフィルされなくなりました。バックフィルが必要な場合は、DAG の定義を catchup=True に更新してください。DAG にバックフィルが必要な場合は、この移行とバックフィルの影響を考慮する必要があります。履歴のないクリーンな環境に DAG を移行するため、バックフィルを有効にすると、指定された start_date から始まるすべての実行に対して DAG 実行が作成されます。不要な実行を避けるため、start_date の更新を検討してください。

create_cron_data_intervals も False になりました。この変更により、cron 式は CronTriggerTimetable コンストラクトとして評価されます。

最後に、手動および Asset トリガーの DAG に対する非推奨のコンテキスト変数の使用状況を評価し、適切な代替コードに更新してください。

requirements の更新とテスト

パッケージバージョンの変更に加えて、airflow-core パッケージに含まれていた複数の Airflow コアオペレーターが apache-airflow-providers-standard パッケージに移行されました。これらの変更は、requirements.txt ファイルに反映する必要があります。requirements ファイルでパッケージバージョンを指定 (固定) することはベストプラクティスであり、この移行でも推奨されています。requirements ファイルを更新するには、以下の手順を実行します：

Amazon MWAA Docker イメージをダウンロードして設定します。詳細については、GitHub リポジトリを参照してください。
現在の環境の requirements.txt ファイルを新しいファイルにコピーします。
必要に応じて、新しい requirements ファイルに apache-airflow-providers-standard パッケージを追加します。
対象の Airflow バージョンに適した Airflow constraints ファイルを作業ディレクトリにダウンロードします。constraints ファイルは、Airflow バージョンと Python バージョンの組み合わせごとに用意されています。URL は以下の形式になります：https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt
バージョン指定のない requirements ファイルと constraints ファイルを使用して、バージョン指定された requirements ファイルを作成します。requirements ファイルの作成ガイダンスについては、requirements.txt ファイルの作成を参照してください。次のステップに進む前に、依存関係の競合がないことを確認してください。
Docker イメージを使用して requirements ファイルを検証します。実行中のコンテナ内で以下のコマンドを実行します：
```
./run.sh test-requirements
```
インストールエラーが発生した場合は、パッケージのバージョンを更新して対処します。

ベストプラクティスとして、Amazon MWAA へのデプロイ用にパッケージを ZIP ファイルにパッケージ化することをお勧めします。これにより、すべての Airflow ノードに同じパッケージが確実にインストールされます。依存関係のパッケージ化に関する詳細については、PyPI.org 要件ファイルフォーマットを使用した Python 依存関係のインストールを参照してください。

新しい Amazon MWAA 3.x 環境の作成

Amazon MWAA はメジャーバージョンアップグレードに移行アプローチを必要とするため、ブルー/グリーンデプロイメント用に新しい環境を作成する必要があります。この記事では例として AWS Command Line Interface (AWS CLI) を使用しますが、Infrastructure as Code (IaC) を使用することもできます。

現在の S3 バケットと同じ構造で新しい S3 バケットを作成します。
更新された requirements ファイルとプラグインパッケージを新しい S3 バケットにアップロードします。

新しい環境設定のテンプレートを生成します：

aws mwaa create-environment --generate-cli-skeleton > new-mwaa3-env.json

生成された JSON ファイルを変更します：
1. 既存の環境から設定をコピーします。
2. 環境名を更新します。
3. AirflowVersion パラメータをターゲットの 3.x バージョンに設定します。
4. S3 バケットのプロパティを新しい S3 バケット名で更新します。
5. 必要に応じて他の設定パラメータを確認し更新します。
既存の環境と同じネットワーク設定、セキュリティグループ、IAM ロールで新しい環境を設定します。これらの設定については、Amazon MWAA ユーザーガイドを参照してください。

新しい環境を作成します：

aws mwaa create-environment --cli-input-json file://new-mwaa3-env.json

メタデータの移行

新しい環境には、同じ変数、接続、ロール、プールの設定が必要です。このセクションを、これらの情報の移行ガイドとして使用してください。AWS Secrets Manager をシークレットのバックエンドとして使用している場合は、接続を移行する必要はありません。環境サイズに応じて、Airflow UI または Apache Airflow REST API を使用してこのメタデータを移行できます。

Airflow UI を使用して、新しい環境でカスタムプールの情報を更新します。
メタデータベースをシークレットバックエンドとして使用する環境の場合、すべての接続を新しい環境に移行します。
すべての変数を新しい環境に移行します。
カスタム Airflow ロールを新しい環境に移行します。

移行の実行と検証

古い環境から新しい環境への移行を計画し、実行します。

ワークフローの影響を最小限に抑えるため、アクティビティの少ない期間に移行をスケジュールしてください。
移行前および移行中で DAG の変更の停止期間を設定してください。
移行を以下のフェーズで実行してください：
1. 古い環境で DAG を一時停止します。少数の DAG の場合は Airflow UI を使用できます。大規模なグループの場合は、REST API の使用を検討してください。
2. Airflow UI で実行中のすべてのタスクが完了したことを確認します。
3. DAG トリガーと外部統合を新しい環境にリダイレクトします。
4. 更新された DAG を新しい環境の S3 バケットにコピーします。
5. 新しい環境で DAG を有効化します。少数の DAG の場合は Airflow UI を使用できます。大規模なグループの場合は、REST API の使用を検討してください。
初期運用期間中は新しい環境を注意深く監視してください：
1. 失敗したタスクやスケジューリングの問題がないか監視します。
2. 変数や接続の欠落がないか確認します。
3. 外部システムとの統合が正しく機能しているか確認します。
4. Amazon CloudWatch メトリクスをモニタリングして、環境が期待通りに動作していることを確認します。

移行後の検証

移行後、新しい環境を徹底的に検証します:

すべての DAG が定義されたスケジュールに従って正しくスケジュールされていることを確認します。
タスク履歴とログにアクセス可能で完全であることを確認します。
重要なワークフローのエンドツーエンドテストを実施し、正常に実行されることを確認します。
外部システムへの接続が適切に機能していることを検証します。
パフォーマンスの検証のために CloudWatch メトリクスを監視します。

クリーンアップと文書化

移行が完了し、新しい環境が安定したら、以下の手順を実行してください。

移行プロセス中に行った変更を文書化します。
新しい環境を反映するように、運用手順書とオペレーション手順を更新します。
ステークホルダーが定めた十分な安定期間の後、古い環境を廃止します：
```
aws mwaa delete-environment --name old-mwaa2-env
```
組織のデータ保持ポリシーに従ってバックアップデータをアーカイブします。

まとめ

Amazon MWAA における Airflow 2.x から 3.x への移行は、ワークフロー運用の信頼性を維持しながら、次世代のワークフローオーケストレーション機能を活用する機会となります。これらのベストプラクティスに従い、体系的なアプローチを維持することで、ビジネス運用へのリスクと混乱を最小限に抑えながら、この移行を成功させることができます。

移行を成功させるには、入念な準備、体系的なテスト、そしてプロセス全体を通じた明確なドキュメントの維持が必要です。この移行アプローチは初期の労力は大きくなりますが、このような重要なアップグレードに必要な安全性と制御を提供します。

著者について

Anurag Srivastava は、AWS のシニアテクニカルアカウントマネージャーとして、Amazon MWAA を専門に担当しています。お客様のスケーラブルなデータパイプラインとワークフロー自動化ソリューションの構築支援に情熱を注いでいます。

Kamen Sharlandjiev は、ビッグデータおよび ETL ソリューションアーキテクトのシニアで、Amazon MWAA と AWS Glue ETL のエキスパートです。複雑なデータ統合とオーケストレーションの課題に直面するお客様の負担を軽減することをミッションとしています。最小限の労力で成果を出せるフルマネージド型 AWS サービスが彼の秘密兵器です。Amazon MWAA と AWS Glue の最新機能やニュースについては、LinkedIn で Kamen をフォローしてください！

Ankit Sahu は、革新的なデジタル製品やサービスの構築において 18 年以上の実績があります。製品戦略、市場投入の実行、デジタルトランスフォーメーションイニシアチブにわたる幅広い経験を持ちます。現在は Amazon Web Services (AWS)のシニアプロダクトマネージャーとして、Amazon MWAA サービスを主導しています。

Jeetendra Vaidya は、AWS のシニアソリューションアーキテクトとして、AI/ML、サーバーレス、データ分析の分野で専門性を発揮しています。お客様の安全で、スケーラブルで、信頼性が高く、コスト効率の良いソリューションの設計を支援することに情熱を注いでいます。

Mike Ellis は、AWS のシニアテクニカルアカウントマネージャーで、Amazon MWAA のスペシャリストです。お客様の Amazon MWAA 支援に加えて、Airflow オープンソースプロジェクトにも貢献しています。

Venu Thangalapally は、シカゴを拠点とする AWS のシニアソリューションアーキテクトで、クラウドアーキテクチャ、データ分析、コンテナ、アプリケーションモダナイゼーションに関する深い専門知識を持っています。金融サービス業界のお客様と協力して、ビジネス目標を安全で、スケーラブルで、コンプライアンスに準拠したクラウドソリューションに転換し、測定可能な価値を提供しています。技術を活用してイノベーションと業務効率の向上を推進することに情熱を注いでいます。仕事以外では、家族との時間を大切にし、読書や散歩を楽しんでいます。

Amazon Web Services ブログ