Amazon Web Services ブログ
AWS エージェントスキルを使った Amazon MWAA のアップグレードとトラブルシューティング
本記事は 2026 年 11 月 16 日 に公開された「Upgrading and troubleshooting Amazon MWAA with AWS agent skills」を翻訳したものです。翻訳はクラウドサポートエンジニアの山本が担当しました。
Amazon Managed Workflows for Apache Airflow (Amazon MWAA) は、基盤となるインフラストラクチャを管理することなく、クラウド上でデータパイプラインを大規模に構築、実行できる Apache Airflow のマネージドサービスです。Amazon MWAA には組み込みのアップグレード機能があり、環境で稼働する Airflow のバージョンを簡単にアップグレードできます。一方、DAG を最新の状態に保つ作業はより困難です。Airflow の進化に合わせて DAG を更新するには、Airflow に関する深い知識が必要であり、複数のツールを頻繁に切り替えなければなりません。その結果、アップグレードでコードの破損やバグが発生し、原因の特定と修正に時間を要するという状況が繰り返されます。チームはアップグレードを先送りし、最新バージョンとの差がさらに広がります。特に 2.x から 3.x への移行には、互換性を損なう変更、Python の移行、必須の中継バージョンが伴うため、作業が複雑になります。
自動化ツールを使えば、この作業を速められるように思えます。しかし一般的な自動化手法は、最新の Airflow 構文に対応していなかったり、異なる Airflow バージョンの概念を混同したりすることがあります。そのため、まさに回避したい種類のエラーを含むコードが生成される場合があります。
AWS は現在、オープンソースの Agent Toolkit for AWS の一部として、MWAA 向けのエージェントスキルを公開しています。AWS が作成したスキルをコーディングアシスタントが使用し、MWAA のバージョンアップグレードを適切に計画、実行、デバッグできるようにします。本記事では、各 MWAA スキルの機能、インストール方法、アップグレード、トラブルシューティング、オーサリングに使えるサンプルプロンプトを紹介します。MWAA エージェントスキルの全体像、Airflow プロジェクトへのインストール方法、実際のアップグレードやトラブルシューティングでの活用方法を理解できます。
AWS エージェントスキルとは
エージェントスキルは、特定のタスクを実行する手順をコーディングアシスタントに与える指示パッケージです。MWAA スキルはオープンな Agent Skills 標準に準拠しており、Kiro、Claude Code、Cursor、Codex など、この標準をサポートするアシスタントで利用できます。アシスタントは AWS が作成したスキルを読み込み、その手順に従うため、Airflow と MWAA の最新の動作に対応できます。
スキルは AWS Command Line Interface (AWS CLI) コマンドを実行してリソースを操作します。Agent Toolkit for AWS は AWS Model Context Protocol (MCP) Server も提供しており、プラグインをインストールすると、その設定もスキルと一緒に導入されます。スキルは AWS MCP Server を使い、実行時に最新の AWS ドキュメントを取得します。また、サンドボックス環境で AWS CLI コマンドを実行し、監査ログを記録します。
MWAA スキル
aws-data-analytics プラグインには、次の 4 つの Amazon MWAA スキルが含まれています。
- authoring-mwaa-workflow: プロビジョンド環境向けの Airflow DAG と、MWAA Serverless 向けの YAML ワークフローを作成してデプロイします。
- testing-mwaa-workflow: デプロイ済みの DAG またはワークフローを開始し、完了まで監視して、修正後に再テストします。実行に失敗した場合は、デバッグスキルやオーサリングスキルも呼び出せます。
- debugging-mwaa-workflow: 実行やタスクの失敗、表示されない DAG、インポートエラー、ワーカーのメモリ不足エラー、AWS Identity and Access Management (IAM) の権限エラーについて、根本原因を特定します。
- upgrading-mwaa-environments: Blue/Green またはインプレース方式を使い、2.x から 3.x への移行を含めて、プロビジョンド環境を新しい Airflow バージョンへアップグレードします。新しいバージョンで動作するように DAG コードも更新してテストします。移行元が 2.11.x より古い場合は、まず 2.x 系の最新 2.11.x を経由するルートを計画します。プロビジョンド環境を Airflow 3 へインプレースアップグレードするには、この中継バージョンが必要です。
プロビジョンド環境では Python DAG、MWAA Serverless では YAML ファイルを使用します。4 つのスキルはすべてプロビジョンド環境に対応しています。オーサリング、テスト、デバッグの各スキルは MWAA Serverless にも対応しています。
注: これらのスキルを使用するエージェントは、推奨事項を示すだけでなく、実際に変更を加えます。タスクによっては、DAG ファイルを編集してデプロイする場合があります。まず開発環境でスキルを試し、DAG をバージョン管理下に置いて、提案された変更をそれぞれ確認してください。
前提条件
- 既存の MWAA プロビジョンド環境がある AWS アカウント。本記事では Airflow 2.11.x から開始します。後述のセットアップセクションを参照してください。
- Agent Skills 標準をサポートする AI コーディングアシスタント。Kiro や Claude Code などが該当します。
- 使用する MWAA アクションの名前空間に対し、対象リソースに限定した IAM 権限。プロビジョンド環境と Apache Airflow REST API には
airflow名前空間、MWAA Serverless のワークフローと実行にはairflow-serverless名前空間を使用します。 - 調査手順には最小権限の認証情報を使用します。書き込みアクセスは、実行が確認された変更手順にのみ付与してください。
MWAA スキルのインストール
MWAA スキルは、Agent Toolkit for AWS の aws-data-analytics プラグインに含まれています。インストール方法は使用するアシスタントによって異なり、主に次の 2 通りです。
オプション A: プラグインをインストールする (Claude Code、Codex)
claude-plugins-official マーケットプレイスから aws-data-analytics プラグインをインストールします。最初にマーケットプレイスを更新して最新バージョンのプラグインを利用できるようにしてから、インストールします。Claude Code では、次のコマンドを実行します。
マーケットプレイスを更新せずにインストールすると、「Plugin ‘aws-data-analytics’ not found in marketplace ‘claude-plugins-official’」のようなエラーが表示される場合があります。先にマーケットプレイスの更新コマンドを実行すると解決できます。Anthropic のプラグインディレクトリには古いバージョンが掲載されている場合があるため、MWAA スキルを入手するには claude-plugins-official からインストールしてください。Codex など、プラグイン方式の他のアシスタントでは、Getting started に記載された同等のプラグインインストール手順に従います。
オプション B: AWS MCP Server を設定してからスキルを追加する (Kiro)
Kiro では、AWS MCP Server を設定ファイル (~/.kiro/settings/mcp.json) に追加します。Agent Toolkit for AWS ユーザーガイドの「Getting started」にある Kiro 用の最新設定をコピーし、AWS_REGION を MWAA 環境のリージョンに設定してください。その後、リポジトリからスキルを追加します。
別の方法として、AWS CLI で aws configure agent-toolkit を実行できます。インストール済みの AI コーディングアシスタントを検出し、AWS のデフォルトスキルをインストールして、AWS MCP Server を設定します。
インストール後は、プロンプトに基づいてスキルが自動的に選択されるため、スキル名を指定する必要はありません。各アシスタントの詳しいセットアップ手順については、Agent Toolkit for AWS ユーザーガイドの Getting started と、Amazon MWAA ユーザーガイドの Using agent skills in MWAA を参照してください。
セットアップを確認するサンプルプロンプト
- What AWS Regions are available? – A list of regions means the AWS MCP Server is connected.
- What can MWAA Skills help me with? – This confirms your assistant can see the skills.
サンプル環境のセットアップ
スキルが実行する手順を示すため、2 つのチュートリアルと、利用開始に役立つサンプルプロンプトを紹介します。チュートリアル 1 では 2.x から 3.x へのアップグレードプロセスを、チュートリアル 2 では失敗した DAG のトラブルシューティング方法を説明します。
チュートリアル 1: プロビジョンド環境を Airflow 2.x から 3.x へアップグレードする
自然言語でアシスタントに指示すると、upgrading-mwaa-environments スキルが、確認を挟みながら次の手順を進めます。
- バージョンの移行経路を計画する。 スキルは、移行元から移行先までのバージョンアップを順序付きのリストとして計算します。2.x から 3.x へ移行する場合は、必須の中継バージョンである 2.11.x と Python の移行手順を挿入します。
- 戦略を選択する。 実行履歴や同じ環境 URL/ARN を維持する必要があるかどうかに基づき、新しい環境を使う Blue/Green アップグレード、テスト用コピーで事前検証するインプレースアップグレード、または直接のインプレースアップグレードを選択します。
- DAG を検証する。 3.x へ移行する場合は、Ruff によるスキャン、非推奨警告のログスキャン、Docker による検証を実行し、互換性を損なう変更を明らかにします。
- デプロイして切り替える。 再開可能な計画を保存するため、複数のセッションにまたがるアップグレードを一時停止して続行できます。
安全性も組み込まれています。スキルはアクションごとの確認なしに環境を作成したり、Airflow のバージョンを変更したり、現在の環境を変更したりしません。各バージョンアップも個別に確認されます。
使用できるサンプルプロンプト
- Upgrade
<environment_name>from Airflow 2.7.2 to the latest 3.x. We don’t need the run history. - Upgrade
<environment_name>from 2.10.3 to 2.11.x. We must keep run history and the same URL. It has a large number of DAGs. - Upgrade
<environment_name>from 2.11.0 to 3.2.1 in place. Skip the test copy, we don’t have budget. Some DAGs import airflow.datasets and one runs ‘airflow db clean’ in a BashOperator.
チュートリアル 2: 失敗した DAG をトラブルシューティングする
アップグレードによって、DAG の実行が失敗したり、DAG をインポートできなくなったり、Airflow UI に表示されなくなったりする場合があります。debugging-mwaa-workflow スキルは、MWAA でよく発生する障害を順に調査し、根本原因を特定します。その後、問題を手動で修正するか、オーサリングスキルに DAG の更新を依頼できます。
使用できるサンプルプロンプト
- DAG
<dag_name>on<environment_name>started failing this morning with ModuleNotFoundError: No module named ‘snowflake’. Nobody changed the DAG code. - My serverless workflow
arn:aws:airflow-serverless:<region>:<accountid>:workflow/<workflowname>failed on its last run. Why? - Task
<taskname>in DAG<dag_name>on<environment_name>fails with AccessDenied ons3://<s3_bucket>/inbound/. Fix the permissions.
ワークフローの作成とテスト
MWAA スキルは 2 種類の MWAA に対応しています。アップグレードスキルはプロビジョンド環境だけに対応していますが、オーサリング、テスト、デバッグの各スキルは MWAA Serverless にも対応しています。MWAA Serverless では、Python DAG の代わりに YAML でワークフローを定義します。この例では、authoring-mwaa-workflow で YAML ワークフローを作成し、testing-mwaa-workflow で完了まで実行します。実行に失敗した場合はデバッグスキルを使用します。
使用できるサンプルプロンプト
- Write a Python DAG for my MWAA environment
<environment_name>that runs an Athena query against<db>.<table>, writes results tos3://<s3bucket>/orders/, and sends an SNS alert on failure. Then deploy and test it. - Create an MWAA Serverless workflow that runs Glue job orders-clean, then a Python step that uses pyarrow to validate the Parquet output row count. Run it nightly. Deploy only, don’t run it yet.
- Smoke-test DAG
<dagname>on<environment_name>(Airflow 3.0.6). It was just uploaded and is still paused. - Run
arn:aws:airflow-serverless:<region>:<accountid>:workflow/<workflow_name>and confirm it succeeds. If it fails, fix it and retry up to 5 times.
ベストプラクティス
- まず開発環境でテストします。本番環境をインプレースアップグレードする前に、テスト用コピーでリハーサルしてください。実行履歴を維持する必要がない場合は、新しい環境を使う Blue/Green アップグレードを推奨します。
- 環境を変更する操作では、実行前に確認するようアシスタントを設定し、各バージョンアップをレビューします。
- 調査やトラブルシューティングには読み取り専用の認証情報を使用します。書き込みアクセスは確認済みの変更手順に限定し、IAM 権限は使用する airflow / airflow-serverless 名前空間に絞ります。
- スキルと一緒に AWS MCP Server をインストールします。アシスタントは実行時に最新の AWS ドキュメントを取得し、サンドボックス環境で AWS CLI コマンドを実行して監査ログを記録できます。
- DAG と requirements をバージョン管理下に置き、スキルによる変更をレビューしてロールバックできるようにします。
まとめと次のステップ
- Agent Toolkit for AWS からスキルをインストールし、Getting started の手順に従って AWS MCP Server に接続します。
- 本記事のサンプルプロンプトを開発環境で試します。
- その他のサンプルプロンプトについては、Amazon MWAA ユーザーガイドの Using agent skills with Amazon MWAA を参照してください。Airflow 3 への移行を計画している場合は、Best practices for migrating from Apache Airflow 2.x to Apache Airflow 3.x on Amazon MWAA も参照してください。
クリーンアップ
チュートリアルで新しい環境 (Blue/Green)、リハーサル用コピー、Serverless ワークフローを作成した場合は、継続的な料金の発生を避けるため、作業後にリソースを削除してください。
