testing-mwaa-workflow

MWAA ワークフローのテスト

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

Amazon MWAA ワークフローの実行をエンドツーエンドでテストします。実行をトリガーし、終端状態になるまでポーリングし、失敗した場合は上限付きのデバッグ → 修正 → 再テストのループを実行します。このスキルはトリガーと状態の読み取りのみを行います。すべての診断は debugging-mwaa-workflow に、すべての変更（アーティファクトの編集、再デプロイ、環境の作成／更新）は authoring-mwaa-workflow に委任します。フレーバーに応じて振り分けた後、共通の手順を実行します。

実行に関する注意 — 離散ステップでポーリングする： AWS の操作が終端状態または準備完了状態になるのを待つ場合は、必ず1 回の呼び出しにつき 1 回のステータス確認を行い、再確認するかどうかは独自のループで判断してください。操作の種類や所要時間にかかわらず、単一のコマンドやスクリプトで待機をブロックしてはいけません（完了まで while と sleep を繰り返さないでください）。

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

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

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

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

ステップ 0：フレーバー、モード、複雑さを判定する

フレーバー（debugging のロジックを再利用）

1. aws mwaa get-environment で解決可能な環境名 -> プロビジョニング済み。
2. workflow/... ARN、または aws mwaa-serverless のコンテキスト -> サーバーレス。
3. どちらのシグナルもない場合は、次のどちらかを確認します：MWAA プロビジョニング済み（Python DAG） または MWAA サーバーレス（YAML ワークフロー）。

呼び出しモード

• 単独実行 — ユーザーが既存のデプロイ済みターゲットを指定します。
• 委任実行 — authoring-mwaa-workflow がデプロイし、解決済みのターゲット（環境名 + dag_id、またはワークフロー ARN）を引き渡します。「今すぐデプロイしてテストしますか？」への承認は、最初のトリガー確認のみを満たします。

複雑さ

• シンプル — ターゲットはすでにデプロイされ、準備完了が確認済みです -> ステップ 2 に進みます。
• 標準 — デプロイ直後で、準備状況が不明です -> 全手順を実行します。
• 複雑 — アクティブな修正ループ内で再テストします。

ステップ 1：準備状況の確認（最初のトリガー実行前）

アーティファクトがデプロイ済みで、解析可能な状態であることを確認します。確認せずにトリガーを実行してはいけません。既存の実行を採用する予定の場合でも、このステップは必須です。準備状況データ（last_parsed_time、is_active、has_import_errors）は、ステップ 2 の鮮度ゲートで使用します。

• プロビジョニング済み： dag_id が存在し、has_import_errors: false であることを確認してから、/dags コレクションエンドポイントを使ってバージョンに応じた準備完了チェックを行います。ポーリング時間は、環境に設定されたスキャン間隔から決定します。get-environment -> AirflowConfigurationOptions で、scheduler.dag_dir_list_interval（AF2）または dag_processor.refresh_interval（AF3）を確認します。未設定の場合は 300 秒をデフォルトとします。15 秒間隔で、設定された間隔 + 30 秒までポーリングします（DAG 単位のエンドポイントは反映が遅れることがあります）。**AF2（REST API v1）**では、is_active: true を必須とします。**AF3（REST API v2）**には is_active フィールドが存在しないため、代わりに is_stale: false を必須とし、is_active を決して待たないでください（常に未設定／false として読み取られます）。解析済みでも準備が完了していない DAG は、トリガーの試行を不透明な RestApiClientException で拒否します。時間内に準備が整わない場合は、debugging-mwaa-workflow に引き継ぎます。
• サーバーレス： get-workflow --workflow-arn を使って、WorkflowStatus が READY であることを確認します。準備が整っていない場合は、debugging-mwaa-workflow に引き継ぎます。

この準備状況確認の時間枠は、ステップ 3 の実行タイムアウトとは別です。正確なコマンドについては、references/provisioned-testing.md および references/serverless-testing.md を参照してください。

ステップ 2：確認してからトリガーを実行（安全ゲート）

解決された対象を示し、その環境を分類します。開発／テスト環境であると確信できない限り（名前またはタグで dev/test が明確に示されている場合）、本番環境として扱います。本番環境であることを警告し、トリガー実行の前にユーザーの明示的な確認を求めてください。対象が本番環境であることが確認された場合（名前またはタグに prod、prd、production が含まれる場合、またはユーザーがそう述べた場合）、状態を変更するすべてのステップ（各トリガー、再トリガー、クリア／再実行）で、1 回だけではなく、明示的な承認を求めてください。開発／テスト環境であると確信できる対象については、最初のトリガー実行と各再トリガーの前に、ユーザーの明示的な確認を求めてください。

ユーザーがその操作を明示的に承認している場合、このゲートはすでに満たされています。委任モードでは、作成時の「今すぐデプロイしてテストしますか？」という承認が最初のトリガーを対象とします。また、特定の実行に対するトリガーの事前承認も、その確認として扱います。すでに承認されている場合は、再度確認を求めないでください。

トリガー実行の前に、スケジューラーが作成した実行がないか確認します（プロビジョニング済みテストのリファレンスを参照）。以前の実行を採用する前に、鮮度ゲートを適用します。

• 委任モード： 常に新しい実行をトリガーします。以前の実行は定義上デプロイより前のものなので、状態にかかわらず採用しないでください。
• スタンドアロンモード： run.start_date を、ステップ 1 の準備状況チェックですでに取得した /dags コレクション応答の dag.last_parsed_time と比較します（コレクションは v1 と v2 のどちらでも DAG ごとの last_parsed_time を返すため、DAG 単位の呼び出しは不要です）。start_date < last_parsed_time の場合、その実行でテストされたのは以前のバージョンのアーティファクトです。古いものとして扱い、新しい実行をトリガーします。start_date >= last_parsed_time の実行のみ採用します。

鮮度ゲートを通過した新しい実行が対象の期間にすでに存在する場合は、POST を実行する代わりにそれを採用します。ステップ 3 で監視を続けます。

再テストでは、すべての実行識別子を新しくする必要があります（プロビジョニング済み：dag_run_id と logical_date の両方。サーバーレス：新しい start-workflow-run 呼び出し）。再トリガーの前に、以前の実行がすべて終了状態であることを確認します。実行中の以前の実行が、新しい実行の開始を妨げる場合があります。

正確なトリガーコマンドと再テスト時の注意事項については、各リファレンスを参照してください。

ステップ 3：ターミナル状態までポーリングする

トリガーした実行がターミナル状態になるまでポーリングします。正確なポーリングコマンドとエラー時の代替手段については、参考資料を確認してください。

タイムアウトの処理：

• dagrun_timeout を設定してプロビジョニングした場合： 経過時間が dagrun_timeout を超えても実行がターミナル状態になっていない場合は、失敗として扱います → ステップ 4。 （dagrun_timeout は DAG レベルの Airflow パラメーターであり、MWAA Serverless には適用されません。）
• Serverless の場合： サービスがターミナル状態を返すまでポーリングします。MWAA Serverless サービスが独自の実行上限を適用し、それをターミナル状態 TIMEOUT として通知するため、呼び出し側で上限を設ける必要はありません。
• dagrun_timeout を設定せずにプロビジョニングした場合： DAG レベルにもサービスレベルにも期限がないため、ポーリングを開始する前にユーザーと最大待機時間を合意します（DAG の想定実行時間を把握しているため、希望がなければデフォルトは 1h とします）。ターミナル状態になるか、最大待機時間が経過するまでポーリングします。上限に達したらポーリングを停止して報告します。失敗と暗黙に判断したり、無期限にポーリングを続けたりしないでください。

  実行 <run-id> は、合意した <max-wait> 以内にターミナル状態になりませんでした。 まだ実行中の可能性があります。失敗とは判断していません。次のいずれかを選択してください。 (a) 待機時間を延長する、(b) ログ／Airflow UI を確認する、または (c) この テストを判定不能として扱う。

経過時間に応じてポーリング間隔を調整します：

経過時間	ポーリング間隔
<= 5 min	15s
> 5-15 min	30s
> 15-30 min	60s
> 30-60 min	2 min
> 60 min	5 min

合格となるのはターミナル状態が SUCCESS の場合のみです。出力データの検査は行いません。合格したら → ステップ 6。

ステップ 4：失敗した場合はデバッグに委任する

実行識別子を debugging-mwaa-workflow に渡します。標準の構成（根本原因／影響／即時修正／予防策／コマンド）が返されます。ここで再診断しないでください。

Step 5: 修正を分類してループする

5a. 各アクション項目を分類します。デバッグで返された各項目を、次のいずれかのカテゴリに分類します。

カテゴリ	例	対応
ARTIFACT	演算子のパラメーターの誤り、インポートの不足、YAML スキーマ／timedelta の誤り、タスクの接続ミス、Serverless のコードパッケージの修正（依存関係の不足／プラットフォームに合わない wheel／不正な zip 構成）	authoring-mwaa-workflow に委任し、準拠したアーティファクトを再生成します（Serverless の場合は --code パッケージも再ビルド／再デプロイします）。その後、再デプロイします。自動的に続行します。
ENVIRONMENT	requirements.txt の依存関係、plugins.zip、環境設定／ワーカーのサイズ	authoring のデプロイパスに委任します（環境の変更と独自の承認を担当します）。そのゲートの後、自動的に続行します。
HUMAN-GATED	新しい IAM 権限、VPC／ネットワーク設定、データアセットの不足、クォータの引き上げ	自動適用できません。正確なコマンドを提示し、ループを一時停止して、再テストする前にユーザーが解決を確認するのを待ちます。

テストによって直接変更が加えられることはありません。

5b. 再テストします。 自動修正可能なカテゴリの修正を適用して再デプロイした後、Step 1 に戻ります（再デプロイにより S3 同期／解析が新たに実行されます）→ Step 2（再確認）→ Step 3。Step 2 の再トリガー時の注意点を適用します。新しい dag_run_id と logical_date を使い、前の実行が終端状態にあること（単にリトライのバックオフ中ではないこと）を確認してから、新たにトリガーします。

5c. 1 サイクルに複数のアクション項目がある場合（並行処理）。 自動修正可能な修正（authoring による再生成＋再デプロイ）を開始すると同時に、ユーザーに HUMAN-GATED 項目を提示します。完全に直列化しないでください。次の 2 つのガードレールを守ります。（1）両方が完了するまで再テストを開始しないこと。自動修正が再デプロイされ、かつユーザーが HUMAN-GATED 項目の完了を確認するまで、再トリガーしないでください。（2）自動修正が HUMAN-GATED 項目に依存する場合（再生成したアーティファクトが、ユーザーによる作成が必要なリソース／権限を参照する場合）、並行処理ではなく順番に実施します。

5d. ループの上限と停止条件。 上限で数えるのは試行回数ではなく、進展のない試行回数です。デフォルトは 3 回です（「最大 N 回リトライ」で上書きできます）。進展とは、次のいずれかを指します。以前は失敗していたタスクが SUCCESS に到達する（パイプラインが進んだ）、またはデバッグで前回の試行とは異なる根本原因が報告される。進展があった試行ではカウンターがリセットされます。実行ごとにブロッカーを 1 つずつ解消する複数タスクのパイプラインは進行中であり、単純な試行回数の上限では修復の途中で放棄することになります。次のいずれかに該当したら停止して要約します。（1）実行が SUCCESS に到達する → Step 6 の PASS。（2）進展なしカウンターが上限に達する。（3）HUMAN-GATED 項目に到達する → ユーザーの対応を待って一時停止。同じ根本原因が 2 回連続で発生した場合、それぞれ進展なしのカウントを 1 回増やします。これはカウンターが進むという意味であり、別のルールではありません。

Step 6: 結果を報告する

Test Result: PASS | FAIL | STOPPED (<reason>)
Target: <env-name + dag_id | workflow ARN>  [PROD WARNING if applicable]
Attempts: <n>/<cap>
Run History:
  Attempt 1: <run_id> -> <state> (<duration>) [-> root cause if failed]
Fixes Applied: <artifact/env fixes auto-applied via authoring, per attempt> | none
Outstanding Action Items: <human-gated items, exact commands> | none
Next Step: <re-invoke to retest after resolving | passed, nothing needed>

PASS には終端状態が SUCCESS であることが必要です。STOPPED には、上限到達／進展なし／HUMAN-GATED による一時停止が含まれます。それぞれ明示してください。

注意事項

• 新たにデプロイされたアーティファクトは、すぐには実行できません。S3 から同期して解析する必要があります（Provisioned）。Serverless の場合は、作成／更新時に検証されます。複雑さが Simple でない限り、最初のトリガーの前に Step 1 を必ず実行してください。
• このスキルがアーティファクトを編集したり、依存関係を変更したり、環境を作成／更新したりすることはありません。これらは authoring-mwaa-workflow の担当であり、その承認ゲートに従います。テストでは、（確認済みの）トリガーと状態の読み取りのみを行います。
• PASS と判定されるのは、実行状態が SUCCESS の場合のみです。出力データの正しさは対象外です。

トラブルシューティング

症状	原因	対応
GET /dags に DAG が表示されない	S3 同期の遅延、またはインポートエラー	トリガーを実行する前に、debugging-mwaa-workflow に引き継いでください
--path が拒否される／切り詰められる	パスが 64 文字を超えている（https://docs.aws.amazon.com/cli/latest/reference/mwaa/invoke-rest-api.html）	--query-parameters を使ってコレクションパスをポーリングしてください
ポーリング時に RestApiClientException が発生する	Web サーバーに到達できない	DAGProcessing／Scheduler のロググループに切り替えてください
dagRuns POST で RestApiClientException が発生する（メッセージなし）	DAG の準備ができていない — AF2：is_active=false（有効化が未完了）；AF3：is_stale=true（v2 には is_active がありません）	準備ができるまで /dags コレクションをポーリングしてください（AF2 は is_active=true／AF3 は is_stale=false）。むやみにトリガーを再試行しないでください
手動実行が作成されたものの queued のまま始まらない（AF3）	DAG が一時停止中 — AF3 は一時停止中に手動実行を実行しません（AF2 では実行されます）	一時停止を解除し（PATCH /dags/<dag_id> {"is_paused": false}）、その後トリガーしてください。DAG が一時停止状態でデプロイされるアップグレードの直後によく発生します
Serverless の get-workflow が READY にならない	作成／更新中、または失敗	READY になるまで待ってください。FAILED の場合はデバッグに引き継いでください
同じ失敗が発生し、2 回の試行が実行中	修正が根本原因に対処していない	進展がなければ停止し、概要をまとめてください。上限まで試行を続けないでください

参考資料

• references/provisioned-testing.md — invoke-rest-api の正確なコマンド（準備状況、トリガー、ポーリング）、パスの 64 文字制限、再テストの注意事項、ログへの切り替え
• references/serverless-testing.md — mwaa-serverless の正確なコマンド（get-workflow、start-workflow-run、get-workflow-run）、終了状態

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

• 実際の実行をトリガーします（状態を変更します）。トリガーおよび再トリガーには、その都度明示的な確認が必要です。本番環境を示す名前のターゲットには、事前に警告を表示します。
• 自律的な変更は行いません。このスキルがアーティファクト、要件、環境を編集したり、IAM を変更したりすることはありません。これらは独自の承認手順を備えた作成担当に委任されます。人による承認が必要な修正では、ユーザーの操作のためにループを一時停止します。
• シークレットを露出させません。実行やログの調査によって、認証情報や接続文字列が出力に含まれないようにしてください。