upgrading-mwaa-environments

MWAA 環境のアップグレード

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

MWAA がプロビジョニングした環境を、MWAA がサポートする任意の新しい Airflow バージョンにアップグレードします。2.x 内、3.x 内、または 2.x から 3.x への移行に対応しています。ターゲットはパラメーターです。パスプランナーが（ソース、ターゲット）から順序付けられたバージョン移行のリストを計算します。最新の 2.11.x の中継バージョンと Python 系統の移行ステップは、パスで必要な場合にのみ挿入されます。履歴実行データを保持する必要があるかどうか、また同じ環境（その URL/ARN）を維持する必要があるかどうかに応じて、デプロイ方法を選択します。方法は、新しい環境へのアップグレード（new-environment）、テスト用コピーで事前に検証するリハーサル済みインプレースアップグレード（in-place-rehearsed）、または直接インプレースアップグレード（in-place-direct）です。

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

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

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

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

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

安全性とセキュリティ

これらのルールは、ユーザーの指示にかかわらず適用されます。

• 明示的な承認なしに現在の環境で破壊的な操作を行わない： ユーザーの操作ごとの確認なしに、すべての DAG を一時停止したり、環境を削除したり、現在の環境を変更したりしてはいけません。
• 計画の確認前に環境を作成しない： ユーザーがフェーズ 4 の計画を確認するまで、aws mwaa create-environment を実行してはいけません。
• バージョン移行ごとに個別の確認を得る： 移行ごとの確認なしに、Airflow バージョンを変更するための aws mwaa update-environment を実行してはいけません。ロールバックの選択肢：3.x から 2.11.x への移行はサポートされています。同一メジャーバージョン内で、引き続きサポートされるバージョンへのダウングレードはサポートされています。EOS バージョンへのダウングレードはできません。直接インプレースアップグレードでは、追加の確認チェックポイントが必要です。
• 廃止には手順ごとの承認が必要： 環境や S3 成果物を独断で削除してはいけません。破壊的な各コマンドを提示し、確認を待ってください。リハーサル済みインプレースアップグレードでは、廃止する環境はテスト用コピーです。

セキュリティ上の考慮事項

• create／update-environment と S3 成果物へのアクセスには、最小権限の IAM を適用します。*FullAccess／service:* は使用せず、特定の環境と S3 ARN に範囲を限定してください。
• シークレット： 環境間で認証情報がコピーされたり、ログに記録されたりしないよう、接続と変数にはシークレットバックエンド（Secrets Manager／Parameter Store）を優先してください。接続パスワードは REST API で往復できません（2.x では省略され、3.x ではマスクされます）。アプローチのリファレンスにあるメタデータ移行に関する注意事項を参照してください。

参考ドキュメント

• discovery-preflight.md — フェーズ 1：環境の検出、事前チェック、バージョンマトリックスの更新、ターゲットの選択、アップグレードパスの計画
• upgrade-engine.md — 手順に沿ったアップグレード：ジャンプごとのアップグレード、条件に応じた検証／スキャン／修正、再開
• airflow2-to-3-checklist.md — Ruff では検出できない 2->3 の問題に対する grep パターン（バージョンジャンプで新しいメジャーバージョンに移行する場合のみ使用）
• mwaa-version-matrix.md — ランタイムを基準としたバージョン／Python／EOS マトリックス、バージョンジャンプのルール、プロバイダー、サポート対象外の機能
• airflow2-to-3-quick-reference.md — 2->3 のインポート／コンテキスト／設定の対応表（バージョンジャンプで新しいメジャーバージョンに移行する場合のみ使用）
• strategy-blue-green-fresh.md — 新しい環境へのアップグレード（履歴なし）
• strategy-inplace-green-validated.md — リハーサル済みのインプレースアップグレード：事前にテストコピーで検証
• strategy-inplace-direct.md — 直接のインプレースアップグレード（推奨しません）

埋め込みのリファレンスより詳しい情報が必要な場合は、実行時に取得してください。

• AWS MWAA 移行ガイド：https://docs.aws.amazon.com/mwaa/latest/migrationguide/key-considerations.html
• AWS MWAA バージョン変更（インプレースアップグレードパス）：https://docs.aws.amazon.com/mwaa/latest/userguide/upgrading-environment.html
• AWS MWAA のサポート対象バージョンと Python の対応関係：https://docs.aws.amazon.com/mwaa/latest/userguide/airflow-versions.html
• AWS MWAA 移行ブログ：https://aws.amazon.com/blogs/big-data/best-practices-for-migrating-from-apache-airflow-2-x-to-apache-airflow-3-x-on-amazon-mwaa/
• Ruff AIR ルール：https://docs.astral.sh/ruff/rules/#airflow-air

フェーズ 0：再開時の確認

呼び出しのたびに、ワークスペースのルートで .mwaa-upgrade-plan-<env-name>.md を確認します（<env-name> はソース環境名です）。複数の環境を並行してアップグレードする場合、複数の計画ファイルが共存することがあります。

• 存在する場合：計画を読み込み、ソース、ターゲット、選択したアプローチ、および位置 (working_on, current_jump, jump_status) を報告します。記録された環境、バージョンジャンプのインデックスとステータスから、エンジン（upgrade-engine.md）を再開します。upgrading の場合は、保留中の update-environment を再ポーリングまたは再発行します。validating の場合は、そのバージョンジャンプについて、条件付きの検証／スキャン／修正ループを再実行します。新規作成された環境では、開始バージョンの検証期間（バージョンジャンプ 1 の to）は current_jump: 1, jump_status: validating に対応するため、そこから再開します。位置が設定されていない場合は、次に未完了のフェーズから再開します。 必須のチェックポイントを通過する前に、計画内でそのチェックポイントのステータスを再確認し、満たされていない場合は、アプローチのリファレンス内にあるそのチェックポイントのセクションを逐語的に読み直してください。記憶した要約に基づいて作業してはいけません。具体的には、バージョンジャンプが完了していても、テスト実行のチェックポイントに合格したことにはなりません。## Test-run results セクションに SUCCESS または NEEDS-DECISION 以外の行がある場合、そのチェックポイントは NOT-PASSED であり、バージョンジャンプのステータスや has_import_errors: false にかかわらず、切り替え（新規環境へのアップグレード）、ライブアップグレード（リハーサル済みインプレースアップグレード — live_upgrade_allowed を参照）、または完了（直接インプレースアップグレード）がブロックされます。同様に、バッチの Monitored one full cycle? セルが yes でない場合、切り替えは完了していません。

再読み込みルール（再開のたびに適用）： セッション開始時と、コンテキストの圧縮後は、アクションを取る前に .mwaa-upgrade-plan-<env-name>.md 全体を読み直します。記憶した内容や要約版に基づいて作業してはいけません。このルールにより、上記の必須チェックポイントに関する記憶済み要約のルールを、計画全体に適用します。

計画の整合性確認（作業を再開する前に実施）： 計画の自己整合性に関する不変条件（全リストは plan-materialization.md を参照）を確認します。PASSED と記されたチェックポイントでは、前提となるすべてのチェックリスト項目が DONE／SKIP である必要があります。Where we are.test_run_checkpoint は Test-run results テーブルと一致している必要があります（PENDING の行があれば NOT-PASSED）。current_jump／jump_status は Upgrade Path Status と一致している必要があります。リハーサル済みインプレースアップグレードでは、live_upgrade_allowed はテスト実行のチェックポイントと一致している必要があります。違反が1つでもある場合、計画を信頼してはいけません。読み取り専用の aws mwaa get-environment、/dags、/health を使って実際の状態を確認し、計画を実態に合わせて修正し、その内容を Last updated に記録します。実態が曖昧な場合は、ユーザーに確認してください。古い PASSED チェックポイントをそのままにしておくと、破壊的な次のアクションにつながります。切り替えと現在の環境の削除（新規環境へのアップグレード）、取り消し不能なライブアップグレード（リハーサル済みインプレースアップグレード）、または時期尚早な完了（直接インプレースアップグレード）です。

• 存在しない場合：フェーズ 1 に進みます。

フェーズ 1：検出 + パスの計画 + 事前確認

references/discovery-preflight.md を取得して従ってください。環境の検出、事前の安全性チェック、バージョンマトリックスの更新、ターゲットの選択、アップグレードパスの計画を実行します（検出のみです。バージョンの切り替えはフェーズ 7 で実行します）。すべての出力を今すぐ計画に記録してください。フェーズ 4 で永続的な計画ファイルに反映されるため、フェーズ 4 より前にコンテキストが圧縮されると、記録が失われてしまいます。

• 検出された環境の事実（Airflow バージョン、S3 アーティファクトのパスとオブジェクトのバージョン、KmsKey、設定オプション、DAG リスト、共有ユーティリティ）。
• 新しい環境／テストコピーの S3 レイアウト（新しい環境へのアップグレード、リハーサル済みインプレースアップグレード）。
• 事前確認の結果（S3 バージョニング、ターゲットの制約、KMS キーポリシーの再利用）。
• 選択したターゲットバージョン。
• 順序付けされたアップグレードパス — バージョン切り替えごとの from／to／python_change／crosses_major。ソースがすでに 2.11.x でない場合にのみ、最新の 2.11.x の中継バージョンと Python 移行ステップを挿入します。

フェーズ 2：アップグレード方法の選択

最も安全な方法は、1 つの質問で決まります。同じ環境（URL と ARN）を維持するかどうかは、その結果として決まるため、別途選択するものではありません。

実行履歴を維持する必要がありますか — Airflow UI に表示される、過去の DAG 実行とタスクインスタンスの記録です。

• いいえ、まっさらな状態で問題ありません → 新しい環境へのアップグレード（スラッグ new-environment）。ターゲットバージョンでまったく新しい環境を構築し、切り替えます。新しい URL が割り当てられ、実行履歴のない状態で開始します。切り替えるまで現在の環境は変更なく稼働し続けるため、ロールバックは「切り替えない」だけです。
• はい、維持してください → リハーサル済みインプレースアップグレード（スラッグ in-place-rehearsed）。既存の環境をインプレースでアップグレードします。URL はそのままで、履歴もすべて維持されます。まず、一時的なテストコピーでアップグレード全体をリハーサルし、安全に問題を検出します。ユーザーがリハーサルを明示的に拒否した場合に限り、直接インプレースアップグレード（テストコピーなし）を使用してください。

同じ環境（URL と ARN）を維持するかどうかは、入力ではなく結果です。実行履歴を維持するには、現在の環境をインプレースでアップグレードします（URL と ARN はそのままです）。一方、新しい環境へのアップグレードでは、必ず新しい環境が作成されます。このスキルでは、新しい環境（新しい URL と ARN）と実行履歴の維持を組み合わせることはできません。新しい URL と ARN が必要な場合、実行履歴は引き継がれません（新しい環境へのアップグレード）。

方法	履歴	URL/ARN	アップグレード中の現在の環境	新しい環境／テスト環境の作成時期	推奨
新しい環境へのアップグレード	破棄	新規	切り替えまで稼働	最初のバージョン切り替えのターゲット	はい
リハーサル済みインプレースアップグレード	維持（スナップショット）	同じ	テストコピーでリハーサル後、アップグレード	最初のバージョン切り替えのターゲット	はい
直接インプレースアップグレード	維持（スナップショット）	同じ	直接アップグレード	なし	いいえ

新しい環境へのアップグレードとリハーサル済みインプレースアップグレードは、どちらも推奨されます。ユーザーは必要性に応じて選択します。直接インプレースアップグレードは推奨されず、追加の確認チェックポイントが必要です。

ガードレール：ユーザーがリハーサル済みまたは直接インプレースアップグレードを選択し、環境に 50 を超える DAG がある場合、またはフェーズ 3 で複雑な DAG が検出された場合は、警告して新しい環境へのアップグレードを推奨してください。選択を妨げてはいけません。

選択した方法のスラッグ（new-environment／in-place-rehearsed／in-place-direct）を計画に記録してください。位置（working_on、current_jump、jump_status）は、初期状態では未設定です。

フェーズ 3：互換性を評価する

1. 互換性スキャン（メジャーバージョンをまたぐアップグレードの場合）： 計画内に crosses_major に該当するバージョン変更がある場合は、必須のチェックポイントとして AIR ルールを使用して Ruff を実行します。

   ruff check --preview --select AIR .
   

   検出結果はルールコードごとにまとめて報告します。Ruff の AIR ルールは、2 から 3 への API 変更（AIR301/302/303/311/312）と 3.1 の API 変更（AIR321、プレビュー）を対象とします。2.x のマイナーバージョン間で削除された API や、3.2 固有の変更は検出しません。エンジンのアップグレード前の非推奨警告スキャンが、2.x 内部のギャップを補います。crosses_major に該当するバージョン変更がない場合（同一メジャーバージョン内のアップグレード）、AIR スキャンは参考情報にとどめ、代わりにエンジンの汎用 DeprecationWarning スキャンを利用してください。

   AIR311（インポートパスの移動）のバージョンに応じた重大度： AIR311 は airflow.sdk に移動したインポート（例：airflow.datasets.Dataset → airflow.sdk.Asset）を警告します。重大度はターゲットバージョンによって異なります。

   • ターゲットが 3.0.x または 3.1.x： ソフトな非推奨です。互換性シムが存在し、古いインポートも引き続き動作します。修正を推奨しますが、必須ではありません。
   • ターゲットが 3.2.1 以降： 重大なブロッカーです。シムモジュールは完全に削除されており、解析時に ModuleNotFoundError が発生します。ターゲット環境にデプロイする前に必ず修正してください。

   ターゲットが 3.2.1 以降の場合、AIR311 は必ず「要修正」に分類してください。修正後のコード（from airflow.sdk import ...）は AF3 専用であり、メジャーバージョンをまたぐアップグレードが完了するまでデプロイできません。各アプローチのリファレンスにある 2 段階デプロイの注意事項を参照してください。

   Ruff では検出できないパターン： 手動チェックリスト（airflow2-to-3-checklist.md）には、Ruff では検出できないパターンが含まれています。特に、_TaskDecorator.output（セクション 15）と、BashOperator 内のスタンドアロン Airflow CLI（セクション 16）に注意してください。Ruff の検出結果がゼロの場合でも、必ず手動スキャンを実行してください。

2. airflow2-to-3-checklist.md のパターンを使用して手動スキャンを実行します。 メタデータ DB に関する警告を提示する（すべてのアプローチで、メジャーバージョンをまたぐ場合のみ）： メタデータ DB にアクセスする DAG は AF2 では動作しますが、AF3 では機能しなくなります。次の 2 つのカテゴリがあります。

   • ORM アクセス DAG（settings.Session()、provide_session — チェックリストのセクション 1）：REST API を使用するよう再設計する必要があります（VPC 内のウェブサーバー、またはレート制限の低い invoke-rest-api を使用）。または、廃止する必要があります。
   • CLI アクセス DAG（BashOperator 内の airflow db ... — チェックリストのセクション 16）：MWAA CLI エンドポイント（推奨、より簡単）、REST API を使用するよう再設計するか、廃止する必要があります。この方法を採用する前に、エージェントは cheat-sheet を使用してターゲットバージョンでコマンドが利用可能か確認する必要があります。 該当する各 DAG とそのカテゴリを計画（フェーズ 4）に記録します。

3. requirements.txt を、mwaa-version-matrix.md に記載されたターゲットバージョンの制約と照合します。

4. シークレットバックエンドの検出： 環境設定で secrets.backend の上書きがないか確認します。Secrets Manager または Parameter Store を使用している場合、変数と接続は外部にあるため、移行不要であることを記録します。シークレットバックエンドが設定されていない場合は、計画時にユーザーに伝えてください。 接続パスワードは REST API 経由では移行されません（2.x では省略され、3.x ではマスクされます）。そのため、パスワードを含む接続はシークレットバックエンドに移すか、ターゲット環境で別途パスワードを再入力する必要があります。また、移行中、変数の値と接続の extra は --body／CLI 引数および監査ログを経由します。この内容を計画（フェーズ 4）に記録します。

5. プラグインの一覧作成： PluginsS3Path が設定されている場合は、内容を一覧表示します。特別な対応が必要な FAB／ウェブビューのプラグインに注意を促します。

6. 各 DAG のアップグレード難易度を「シンプル」「中程度」「複雑」に分類します。

7. DAG をバッチに分けます（共有ユーティリティはバッチ 0、シンプルなものから先にします）。

フェーズ 4：アップグレード計画の作成

ワークスペースのルートに .mwaa-upgrade-plan-<env-name>.md を書き込みます（<env-name> はフェーズ 1 で特定した移行元環境名です）。以下を含めてください。

• 環境の詳細（移行元の名前、移行元のバージョン、リージョン）、ターゲットバージョン、およびアップグレードパスの全表
• 選択したアプローチ — そのスラッグ（new-environment / in-place-rehearsed / in-place-direct）
• 事前確認の結果（S3 のバージョニング、制約、アップグレードパスのステータス）
• Docker 検証のステータス（保留中）
• シークレットバックエンドの検出結果
• 必要な要件の変更
• メジャーバージョンをまたぐ場合のみ — メタデータ DB アクセスの調査結果（フェーズ 3 のステップ 2）：メタデータ DB にアクセスする各 DAG を、ORM アクセス（REST API への再設計、または削除）または CLI アクセス（MWAA CLI エンドポイント、REST API への再設計、または削除）に分類します。さらに、修正後の再スキャンチェックポイントを保留中として記載します（フェーズ 5 のステップ 2d）。バージョン変更に crosses_major が含まれない場合は省略します。
• アプローチ固有の項目：新環境へのアップグレード — 新しい環境名、新環境の S3 パス；リハーサルを伴うインプレースアップグレード — テスト用コピーの環境名、テスト用コピーの S3 パス；直接インプレースアップグレード — なし（インプレースのため、新しい環境やテスト環境はありません）
• DAG ごとのステータスを記載したバッチ表

順序付きのアップグレードパスを ## Upgrade Path テーブルとして記録します。

Jump	From → To	Python change	New major version	Status
1	<jump.from> → <jump.to>	yes/no	yes/no	pending

リハーサルを伴うインプレースアップグレード（2 つの環境 — テスト用コピー、その後に現在の環境）では、アップグレードパスのテーブルを分け、Test copy status 列と Your current environment status 列を設けます。現在の環境でのアップグレードには IRREVERSIBLE と記載します。

すべてのチェックポイントと記録セクションを計画に書き出す（必須）

計画を提示する前に、plan-materialization.md に従って、指定されているすべてのセクションを生成し、## Plan format contract（固定されたステータス用語、Last updated 行、## Where we are のキー）に準拠し、## Self-consistency invariants を満たしてください。これには、## Checklist、アプローチごとに必要なチェックポイントをそれぞれ独立した PENDING 項目として記載すること、あらかじめ用意する ## Test-run results と ## Switchover progress の各テーブル（新環境へのアップグレード）、## Where we are ブロック、解析完了とテスト実行検証済みのステータス用語（LOADED と VERIFIED の使い分け）、アプローチ固有のサブステップ分解ルールが含まれます。計画は、再開可能な永続的な信頼できる情報源です。アプローチのリファレンスに説明文として記載されているだけで、ここに独立した PENDING 項目として存在しないステップは、コンパクション後にスキップされます。これらのセクションは、計画の提示前に生成してください。解析が完了したというシグナル（has_import_errors: false）はテスト実行チェックポイントを満たすものではなく、「検証済み」または「完了」として記録してはなりません。

作業を進める前に、計画をユーザーに提示して確認を求めてください。

フェーズ 5：コードの修正

1. バッチ 0（共有ユーティリティ）： まず共有モジュールを修正します。airflow2-to-3-quick-reference.md のパターンを適用します。
2. バッチごとの処理（1..N）： a. Ruff の自動修正を実行します：ruff check --preview --select AIR --fix --unsafe-fixes <files> b. airflow2-to-3-quick-reference.md に従って、DAG ごとに残りの問題を修正します。 c. Ruff を再実行し、AIR 違反がゼロであることを確認します。 d. 修正済みファイルを再スキャンします（メジャーバージョンをまたぐ場合のみ） — 元のファイルだけでなく、チェックリストのセクション 15/16 の grep を実行します。--unsafe-fixes は xcom_pull テンプレートを <task>.output に書き換えることがありますが、AF3 では無効であるにもかかわらず、再度警告されない場合があります。この場合の実行時エラーは、ライブ解析時まで表面化しません。該当箇所を修正し、Ruff を再実行します。 e. 進捗を保存します（plan-materialization.md の ## Saving progress を参照）：次のバッチを開始する前に、各 DAG を DONE にし、Last updated を更新します。

フェーズ 6：Docker によるローカル検証（推奨。メジャーバージョンをまたぐ場合は強く推奨）

aws/amazon-mwaa-docker-images を使用して、修正済みコードをターゲットバージョンに対して検証します。このリポジトリでは、Airflow 2.9.2 以降のイメージのみを提供しています。ターゲットバージョンが 2.9.2 未満の場合は、Docker 検証をスキップし、スキップ理由を計画に記録して、代わりにフェーズ 7 でエンジンによるライブ検証を行います。

メジャーバージョンをまたぐバージョン移行： いずれかのバージョン移行が crosses_major の場合、Docker 検証を強く推奨します。Ruff の AIR ルールでは、ランタイムを破壊するパターンのいくつか（例：_TaskDecorator.output の削除、3.2.1 以降で完全に削除された shim モジュール）を検出できません。Docker によるインポート検証では、これらを本番環境へのライブデプロイ前に検出できるため、リモート環境で修正、デプロイ、失敗を繰り返すサイクルを避けられます。メジャーバージョンをまたぐアップグレードで Docker 検証をスキップする場合は、スキップ理由に加えて、未検出のランタイムエラーが発生する可能性が高いことも警告してください。

1. Docker が利用可能か確認します：docker --version。利用できない場合、ユーザーが実施を辞退した場合、またはターゲットが 2.9.2 未満の場合は、警告とともにスキップすることを計画に記録し、フェーズ 7 に進みます。
2. ターゲットバージョンのイメージをプルします（リポジトリの README から、実行時に正確なタグを確認します）。
3. requirements.txt を検証します：コンテナにマウントし、インストール検証を実行します。失敗した場合は、競合を報告して修正方法を提案し、検証に合格するかユーザーがスキップするまで繰り返します。
4. plugins.zip を検証します（存在する場合）：マウントしてインポート検証を実行します。
5. DAG のインポートを検証します：修正済みの DAG をマウントし、解析を実行します。エラーがある場合は、該当ファイルについてフェーズ 5 に戻って修正し、再検証します。
6. 進捗を保存します：Docker 検証を DONE または SKIP（理由を付記）にして、Last updated を更新します。

フェーズ 7：デプロイ

計画で選択したアプローチに応じたリファレンスに従います。各アプローチでは、新しい環境（新環境へのアップグレード）、テスト用コピーの後に現在の環境（リハーサル付きインプレースアップグレード）、または現在の環境（直接インプレースアップグレード）で、段階的なアップグレード手順（upgrade-engine.md）を実行します。

• 新環境へのアップグレード：strategy-blue-green-fresh.md に従います
• リハーサル付きインプレースアップグレード：strategy-inplace-green-validated.md に従います
• 直接インプレースアップグレード（非推奨）：strategy-inplace-direct.md に従います

フェーズ 7 を通じて、plan-materialization.md に記載されているとおりに進捗を保存します。各ステップ、サブステップ、バージョン移行、チェックポイント、バッチ、および DAG ごとのステータスの後、次のアクションに進む前に、変更内容（ステータストークン＋永続化する事実＋Last updated＋## Where we are）を計画に保存します。

DAG のテスト実行検証（すべてのアプローチで必須）： エンジンによる解析検証に合格した後、各 DAG または DAG のバッチについて スキル testing-mwaa-workflow を実行し、ターゲットバージョンで実行が成功することを確認します。失敗した場合は、根本原因の分析に スキル debugging-mwaa-workflow を実行します。REST API（POST /dags/{id}/dagRuns）を使って手動で DAG の実行を開始したり、実行状態をその場でポーリングしたりしないでください。開始、ポーリング、分類（SUCCESS と NEEDS-DECISION）、修正の反復はテストスキルが担当します。これは必須のチェックポイントです。テスト実行検証に合格するまでは、ライブアップグレード（リハーサル付きインプレースアップグレード）、切り替え（新環境へのアップグレード）、または完了（直接インプレースアップグレード）に進まないでください。解析のみの検証（インポートエラーがないこと）では、成果物が正しく実行されることは証明できません。各アプローチのリファレンスでは、次のフェーズに進む前に満たさなければならない、番号付きの明示的な必須チェックポイントとして定義されています：新環境へのアップグレードのステップ 4 のチェックポイント、リハーサル付きインプレースアップグレードのステップ 1 のチェックポイント、直接インプレースアップグレードのステップ 4。このチェックポイントでは、結果を計画の ## Test-run results セクションに記録する必要があります。アップグレードスキルはこの反復を統括しますが、テストやデバッグの処理をその場で実行することはありません。

フェーズ 8：切り替え＋廃止

新しい/テスト環境を作成するアプローチ（新環境アップグレード、リハーサル済みインプレースアップグレード）に適用されます。直接インプレースアップグレードはフェーズ 7 で完了します（新しい/テスト環境はありません）。

• 新環境アップグレード: 現在の環境から新しい環境に切り替えてから、現在の環境を廃止します。
• リハーサル済みインプレースアップグレード: テストコピーはリハーサルでした。現在の環境が稼働中のアップグレード済み環境です。切り替えはスキップし、テストコピーを廃止します。現在の環境は削除しないでください。

1. バッチ単位の切り替え（新環境アップグレードのみ、バッチごとの明示的な承認が必要）: 各バッチ（フェーズ 7 と同じバッチグループ分けに一致）について: a. 現在の環境でそのバッチの DAG を一時停止します（短い sleep を挟んで呼び出しを間隔調整します。invoke-rest-api には 10 秒のタイムアウト / 6 MB のレスポンス上限があり (ドキュメント)、環境ごとにスロットリングされるため、固定レートではなくバックオフを使用してください）:

   aws mwaa invoke-rest-api --name <current-env> --method PATCH \
     --path /dags/<dag_id> --body '{"is_paused":true}'
   sleep 0.2
   

   b. ドレイン: 現在の環境でこれらの DAG の実行中ランが完了するのを待ちます。dag_runs を state=running でポーリングします。10 分経過してもランが実行中のままで、そのアクティブなタスクがセンサーまたは遅延オペレーターである場合（task_instances で state=deferred または state=sensing を確認）、新しい環境での一時停止解除に進みます。現在の環境で一時停止された DAG は新しいランを生成しません。実行中のランは独立して完了するかタイムアウトします。新しい環境はその execution_date に対する過去の dag_runs がなく新規に開始されるため、競合することはありません。 c. 新しい環境で同じ DAG の一時停止を解除します（同じ 0.2 秒のスロットリング）:

   aws mwaa invoke-rest-api --name <new-env> --method PATCH \
     --path /dags/<dag_id> --body '{"is_paused":false}'
   sleep 0.2
   

   d. 次のバッチに進む前に、新しい環境でそのバッチを 1 回のスケジュールサイクル全体にわたって監視します。失敗した場合は、現在の環境でそのバッチを再度有効化し（ロールバック）、調査します。

   上記の DAG 単位の一時停止/一時停止解除は --path /dags/<dag_id> を使用し、--path の 64 文字制限に従います。長さを超える dag_id の場合は、upgrade-engine.md に記載されている Airflow CLI フォールバック（aws mwaa create-cli-token -> airflow dags pause|unpause）を使用してください。

   小規模な環境（DAG が 10 個未満、またはすべてシンプル分類）の場合、ユーザーが速度を優先するなら、一括切り替えを代替手段として提案してください。

2. 安定性確認期間：最後のバッチ完了後にユーザーが定める監視期間です （推奨：24 時間、または最も実行間隔の長い DAG の 1 サイクル）。 環境の健全性は、組み込みの CloudWatch メトリクスダッシュボードと、 最新の状態が保たれる 推奨アラームの作成 アクションで確認します。切り替え後に優先して 確認すべき主要な指標は、スケジューラーの稼働状況（例：スケジューラーの ハートビート）とキューのバックログ（例：キュー内タスクの最古の経過時間）です （https://docs.aws.amazon.com/mwaa/latest/userguide/monitoring-dashboard.html）。 新環境へのアップグレードでは、現在の環境は一時停止されたままで、 削除されません。リハーサル済みのインプレースアップグレードでは、現在の環境は 稼働中で監視されています。

3. 廃止（各手順で明示的な承認が必要）：

   • 新環境へのアップグレード：現在の環境を削除します — aws mwaa delete-environment --name <current-env>。S3 アーティファクトのアーカイブは任意です。
   • リハーサル済みのインプレースアップグレード：テスト用コピーを削除します — aws mwaa delete-environment --name <test-copy>。

4. 読み取り専用オプション（新環境へのアップグレード）：最終削除の前に、 過去の UI にアクセスできるよう、現在の環境を長期間一時停止したままにする選択肢を 提示します。

5. 進捗を保存します：アップグレードを完了としてマークし（ステータスは DONE）、 Where we are を phase: complete に設定し、Last updated を更新します。