debugging-mwaa-workflow

MWAA ワークフローのデバッグ

AWS MCP サーバー（任意ですが推奨）： このスキル内の AWS CLI コマンドを AWS MCP サーバー経由で実行すると、サンドボックス化された実行と監査ログが利用できます。ここに記載されているすべてのコマンドは通常の AWS CLI でも動作するため、このスキルに MCP サーバーや MCP 専用ツールは必要ありません。

Amazon MWAA ワークフローの障害を診断して根本原因を特定し、根本原因、影響、および推奨される修復策を報告します。フレーバーに応じて処理を分岐し、その後、共通の 4 段階の診断手順を実行します。

ガードレール — このスキル自身のファイルの場所（MCP とローカルインストール）

このスキルは 2 通りの方法で読み込むことができ、それぞれスキルに同梱されたファイルの参照先が異なります。リファレンスを読む前に、スキルがどの方法で読み込まれたかを確認してください。

• AWS MCP の retrieve_skill ツール経由で読み込まれた場合： スキルはローカルファイルシステムにインストールされていません。各リファレンスは file パラメーターを指定して retrieve_skill で取得し（例：file="references/failure-catalog.md"）、返された内容を読み取る必要があります。これらのパスはディスク上に存在しないため、ローカルで file_read してはいけません。
• ローカルにインストールされている場合（例：.kiro/skills/debugging-mwaa-workflow/ または ~/.claude/skills/debugging-mwaa-workflow/）：相対パスを使って、ローカルのスキルディレクトリからファイルを読み取ってください。

この違いは、スキル自身にパッケージされたファイルにのみ適用されます。ユーザーデータとセッションのアーティファクトは、常にユーザーの作業ディレクトリから読み取り、そこに書き込んでください。retrieve_skill を通じて顧客データを取得したり、書き込んだりしてはいけません。

ステップ 0：フレーバーの検出と障害範囲の特定

フレーバーの検出

1. aws mwaa get-environment で解決できる環境名がある場合、その環境は プロビジョニング型 です。
2. workflow/... ARN、または aws mwaa-serverless のコンテキストがある場合、その環境は サーバーレス型 です。実行 ID だけではフレーバーを特定できません。プロビジョニング型の DAG 実行にも実行 ID があるためです。
3. どちらの手がかりもない場合は、対象が MWAA プロビジョニング型（Python DAG） か MWAA サーバーレス型（YAML ワークフロー） かを確認してください。

複雑さに応じた振り分け

• 単純 — 明確な例外によって、名前が特定された単一のタスクまたは実行が失敗しました。そのタスクのステップ 2 に進んでください。
• 標準 — 実行が失敗しましたが、原因が不明です。ステップ 1 からステップ 4 までをすべて実行してください。
• 複雑 — 断続的な障害、または環境全体に及ぶ障害（複数の DAG、「昨日は動いていた」、何も表示されないなど）です。ステップ 3 を重点的に確認しながら、すべての手順を実行してください。

ステップ 1：障害の特定

プロビジョニング型： aws mwaa invoke-rest-api を使って、失敗した DAG 実行とタスクインスタンスを一覧表示します（パスは /dags/{id}/dagRuns および /dags/{id}/dagRuns/{run_id}/taskInstances）。invoke-rest-api がエラーになる場合（RestApiClientException）、Scheduler および DAGProcessing のロググループにフォールバックします。aws mwaa get-environment でバージョンと設定を取得します。references/provisioned-diagnostics.md を参照してください。

サーバーレス型： aws mwaa-serverless list-workflow-runs の後に get-workflow-run を実行します。RunDetail.ErrorMessage を確認してください。パーサーのメッセージがあり TaskInstances が空の場合は定義エラーです。TaskInstances が含まれていて Workflow execution failed と表示される場合は、タスク実行の失敗です。references/serverless-diagnostics.md を参照してください。

ステップ 2：エラーの詳細を取得して分類

定型文の先にある実際の例外を取得します。

プロビジョニング型： まず Task ロググループを読み取り、症状に応じて Worker、Scheduler、DAGProcessing の順に確認します。

サーバーレス型： list-task-instances、続いて get-task-instance を実行して各タスクの LogStream を取得し、その後 CloudWatch でそのストリームを読み取ります。

次に、優先順位に従って、infra、drift、code-data の順に分類します。references/failure-catalog.md を使用してください。分類結果によってステップ 3 での確認項目が決まります。

ステップ 3：コンテキストを確認する（発生理由）

references/failure-catalog.md で一致したカテゴリのコンテキスト確認を実行します。表面上の例外だけで判断しないでください。SIGKILL は OOM の問題であり、コードに変更がないのに発生する新たなインポートエラーはドリフトの問題、センサーのタイムアウトは上流の健全性の問題です。

ステップ 4：実行可能な出力を提示する

次の厳密な構成で報告します。

Root Cause: <one-line diagnosis with the evidence that proves it>
Impact: <what failed, which runs, blast radius>
Immediate Fix: <the smallest change that unblocks>
Prevention: <the change that stops recurrence>
Commands: <exact read-only commands run, plus remediation commands for the user to run>

読み取り専用の操作だけを実行してください。状態を変更する修正措置（Provisioned の場合は clear/rerun/backfill、Serverless の場合は start-workflow-run または fix-and-redeploy）は、影響を明記したうえで、ユーザーが実行するコマンドとして提示してください。自律的に実行してはいけません（本番環境の安全性のため）。

fix-and-redeploy の手順では、authoring-mwaa-workflow を使って準拠したアーティファクトを再生成してください。

注意点

• Serverless には Airflow のウェブ UI、REST API、CLI トークンがありません。Serverless では create-web-login-token、invoke-rest-api、Airflow REST の各種パスを試さないでください。
• Provisioned では、必ず aws mwaa invoke-rest-api を使ってください（create-web-login-token と curl の組み合わせは使わないでください）。invoke-rest-api は、ネットワークアクセスがなくても VPC 専用のウェブサーバーにアクセスできます。
• GetWorkflowRun.RunDetail.ErrorMessage で、定義エラー（TaskInstances が空）とタスク実行の失敗（Workflow execution failed、TaskInstances に情報あり）を区別できます。タスクログを取得する前に確認してください。
• Serverless のロググループは既定で /aws/mwaa-serverless/{workflow-id}/ ですが、カスタムグループの場合もあります。パスを決めつける前に、get-workflow の LoggingConfiguration で確認してください。
• DAG が表示されない原因はいくつかあります。インポート／解析エラー、スケジューラーのスキャン間隔（scheduler.dag_dir_list_interval、または Airflow 3.x では dag_processor.refresh_interval）がまだ経過していない、dag_id の衝突、S3 同期の遅延などです。DAG 自体の破損であることはほとんどありません。コードに問題があると結論づける前に、invoke-rest-api 経由で GET /importErrors と GET /dags/{dag_id} を確認し（DAGProcessing ログも確認してください）、failure catalog の「DAG not appearing in the UI」チェックリストを参照してください。
• ワーカーの SIGKILL は OOM シグナルです。処理を Glue／EMR／Lambda に移すことを推奨してください。ワーカーをスケールするだけでは、タスクごとのメモリ不足は解消しません。
• MWAA は環境の更新時に依存関係を再解決するため、DAG に変更がなくてもインポート時に失敗し始めることがあります。コード変更のないインポートエラーはドリフトとして扱ってください。
• Serverless の PythonOperator／BashOperator タスクは、--code パッケージに含まれるカスタムコードを実行します。パッケージの展開に失敗した場合や ModuleNotFoundError が発生した場合は、YAML 定義のエラーではなく、パッケージングの問題（プラットフォームに合わない wheel、依存関係の不足、不適切なディレクトリ構成）です。failure catalog の serverless custom-code セクションを参照してください。

トラブルシューティング

エラー	原因	修正方法
RestApiClientException（Provisioned）	実行ロールのスコープ設定ミス、またはサービスエラー	Scheduler／DAGProcessing のロググループを代わりに確認する
get-workflow-run で ResourceNotFoundException	ワークフロー ARN または実行 ID が間違っている	list-workflow-runs で再度一覧表示する
タスクのログストリームが空（Serverless）	想定したロググループが間違っている	get-workflow から LoggingConfiguration を確認する
実行が FAILED なのにタスクログがない	定義／解析エラー	RunDetail.ErrorMessage を確認し、YAML を修正する

参考資料

• references/provisioned-diagnostics.md — Provisioned のデータソースと読み取り専用コマンド
• references/serverless-diagnostics.md — Serverless API、ロググループ、失敗の分類
• references/failure-catalog.md — カテゴリ別のコンテキスト確認と修正措置

セキュリティに関する考慮事項

• デフォルトでは読み取り専用：診断では、読み取り／一覧表示／説明の呼び出しのみを使用します。 修復（クリア／再実行／バックフィル、IAM またはキーポリシーの変更）は ユーザーが実行するコマンドとして提示し、自動で実行することはありません。
• 最小権限の IAM：AccessDenied が実際の権限不足である場合は、エラーに基づいて最小限の Action／Resource を推奨します。ワイルドカードは決して使用せず、存在しないリソースの入力ミスとは区別します（その場合、IAM の権限を広げてはいけません）。
• クロスアカウント：KMS キーポリシー／ロール引き受けの変更には人間の承認が必要であり、リソースの所有者と調整して行います。
• シークレットを公開しない：診断結果に、ログや API レスポンスから取得した認証情報や接続文字列を表示しないでください。