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 の移行、必須の中継バージョンが伴うため、作業が複雑になります。

Apache Airflow version upgrade lifecycle, moving from Airflow 2.x through the required 2.11.x stepping-stone to Airflow 3.x

図 1: Apache Airflow のバージョンアップグレードのライフサイクル

自動化ツールを使えば、この作業を速められるように思えます。しかし一般的な自動化手法は、最新の 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 marketplace update claude-plugins-official
/plugin install aws-data-analytics@claude-plugins-official

マーケットプレイスを更新せずにインストールすると、「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 環境のリージョンに設定してください。その後、リポジトリからスキルを追加します。

npx skills add aws/agent-toolkit-for-aws/skills

別の方法として、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 スキルが、確認を挟みながら次の手順を進めます。

  1. バージョンの移行経路を計画する。 スキルは、移行元から移行先までのバージョンアップを順序付きのリストとして計算します。2.x から 3.x へ移行する場合は、必須の中継バージョンである 2.11.x と Python の移行手順を挿入します。
  2. 戦略を選択する。 実行履歴や同じ環境 URL/ARN を維持する必要があるかどうかに基づき、新しい環境を使う Blue/Green アップグレード、テスト用コピーで事前検証するインプレースアップグレード、または直接のインプレースアップグレードを選択します。
  3. DAG を検証する。 3.x へ移行する場合は、Ruff によるスキャン、非推奨警告のログスキャン、Docker による検証を実行し、互換性を損なう変更を明らかにします。
  4. デプロイして切り替える。 再開可能な計画を保存するため、複数のセッションにまたがるアップグレードを一時停止して続行できます。

安全性も組み込まれています。スキルはアクションごとの確認なしに環境を作成したり、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 on s3://<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 to s3://<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 をバージョン管理下に置き、スキルによる変更をレビューしてロールバックできるようにします。

まとめと次のステップ

MWAA エージェントスキルは、Airflow チームの作業を遅らせる運用タスクに対応する、AWS が作成した手順を AI コーディングアシスタントに提供します。対象となるタスクには、Airflow バージョンのアップグレード、失敗した実行のデバッグ、ワークフローの作成とテストがあります。目標を伝えると、アシスタントが作業を計画し、環境を変更する前に確認を求め、結果をテストします。
利用を開始するには、次の手順を実行します。
  1. Agent Toolkit for AWS からスキルをインストールし、Getting started の手順に従って AWS MCP Server に接続します。
  2. 本記事のサンプルプロンプトを開発環境で試します。
  3. その他のサンプルプロンプトについては、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 ワークフローを作成した場合は、継続的な料金の発生を避けるため、作業後にリソースを削除してください。


著者について

Kamen Sharlandjiev

Kamen Sharlandjiev

Kamen は、プリンシパル Big Data および ETL ソリューションアーキテクトです。複雑なデータ統合やオーケストレーションの課題に直面するお客様の負担を軽減することに取り組んでいます。その切り札は、少ない労力で目的を達成できるフルマネージド AWS サービスです。最新の MWAA および AWS Glue の機能やニュースについては、LinkedIn で Kamen をフォローしてください。

Harshawardhan Kulkarni

Harshawardhan Kulkarni

AWS のパートナーテクニカルアカウントマネージャーであり、Amazon MWAA のスペシャリストです。アイルランドのダブリンを拠点に、EMEA のエンタープライズのお客様と連携し、複雑なワークフローやオーケストレーションの課題解決とベストプラクティスの導入を支援しています。仕事以外では、旅行や家族との時間を楽しんでいます。

Boyko Radulov

Boyko Radulov

Amazon Web Services (AWS) のシニアクラウドサポートエンジニアであり、Amazon MWAA と AWS Glue のスペシャリストです。お客様と緊密に連携し、全体的なコストを削減しながら AWS ワークロードの構築と最適化を支援しています。仕事以外では、スポーツと旅行を楽しんでいます。

Aritra Ghosh

Aritra Ghosh

Amazon Web Services (AWS) のシニアプロダクトマネージャーで、Amazon Managed Workflows for Apache Airflow (Amazon MWAA) と Amazon SageMaker Unified Studio の製品開発をリードしています。仕事以外では、スカッシュやジムでのトレーニングを楽しんでいます。

Ashish Goel

Ashish Goel

AWS のプリンシパルエンジニアです。2019 年のサービス開始時から Amazon Managed Workflows for Apache Airflow (Amazon MWAA) を支援し、Amazon の開発チームと Apache Airflow に直接貢献するオープンソースチームを導いています。仕事以外では、テニスや自然を楽しんでいます。