migrate-to-msk

MSK Express への移行

概要

このスキルは、セルフマネージドの Apache Kafka ワークロードを Amazon MSK Express に移行するお客様を支援します。Discovery、Assessment、任意の Simulation の 3 つのフェーズがあり、お客様のニーズに応じて一連の流れとして、 または個別に実行できます。

対象範囲

このスキルでは、セルフマネージド Apache Kafka（オンプレミス、EC2、 Docker、Kubernetes、またはその他の MSK 以外のデプロイ）から MSK Express への 移行を扱います。MSK Standard（Provisioned）から MSK Express への移行は 対象外です。

前提条件

ドキュメントの参照や情報に関する質問には AWS MCP サーバーの使用を推奨しますが、 必須ではありません。評価スクリプトは、AWS API を呼び出さない純粋なファイル処理です。

インテントに応じた案内

お客様のインテントに応じて、リクエストを案内します。

1. オープンな質問／探索的な質問（「MSK に移行するにはどうすればよいですか？」）

このスキルでできることを説明します。

このスキルでは、MSK Express への移行を 3 つのフェーズで支援します。

フェーズ 1 — Discovery： ソース Kafka クラスターのインベントリを作成します。対象はブローカー、トピック、 パーティション数、設定、認証、ワークロードメトリクスに加え、コストを左右する 2 つのターゲット側の決定事項である、 コンシューマーのラックアフィニティと AWS との個別価格契約です。IaC ファイル（Terraform、CDK、Docker Compose、Kubernetes マニフェスト）から検出することも、クラスターで実行するコマンドを提示することも、情報を手動で提供していただくこともできます。出力： migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json。

フェーズ 2 — Assessment： 5 つの互換性の柱（トポロジー、Kafka バージョン、設定、認証、クォータ）に照らしてクラスターを MSK Express と比較し、managing-amazon-msk スキルの料金ロジックを使用してターゲットの Express 仕様を作成します。 Express が拒否する設定と、通知なく変換する設定をお知らせします。出力： compatibility.<cluster_name>.json、Markdown の msk_sizing_pricing.md に記載される料金結果、 および msk-sizing-inputs.<cluster_name>.json。

フェーズ 3 — Simulation： 負荷テスト用のインフラストラクチャとともに MSK Express クラスターを起動し、Express が お客様独自のワークロードでどのように動作するかを確認します。その後、提供されているテスト（End-to-End Latency または Broker Restart Under Load）を実行し、CloudWatch ダッシュボードで結果を確認します。

データレプリケーション： Express クラスターへのデータ移行には、MSK Replicator を使用できます。セットアップと設定の ガイダンスを提供できます。

どこから始めましょうか？インフラストラクチャのコードを共有するかクラスターについて説明していただければ、Discovery から始められます。 cluster-config.json ファイルがすでにある場合は Assessment から、ターゲットの Express 設定がすでに決まっている場合は Simulation から始めることもできます。

この概要への回答に関するガードレール：

• この回答は概要と案内の質問のみです。いずれのフェーズも開始、シミュレーション、先取りして実施しないでください。
• ここでは評価結果を作成したり推定したりしないでください。判定、柱ごとの調査結果、互換性の結論、ブローカー数、インスタンスの推奨、コストの数値を示してはいけません。これらの値は、実際の cluster-config.json に対してフェーズ 2 のスクリプトを実行した後にのみ得られます。
• フェーズの仕組みを説明するために、compatibility.py、simulation_load_test_config.py、または参照ファイルの内部を開いたり、読んだり、要約したりしないでください。上記の粒度で各フェーズを説明し、実装の詳細をお客様に説明しないでください。
• お客様がフェーズを選択したら、そのフェーズのスクリプトまたはフローを実行して、実際の結果を作成してください。回答には必ずスキルを実行してください。ソースを読んだ知識だけで回答してはいけません。正確なコマンドについては、フェーズ 2 は references/assessment-compatibility.md の「Running the assessment」、フェーズ 3 は references/simulation.md を参照してください。

2. 検出インテント（IaC ファイルが提供された場合のデフォルト）

お客様がディレクトリパスや IaC ファイルを提供した場合、または「これが当社のインフラです」と伝えた場合は、検出インテントです。Phase 1（検出）のみを実行してください。評価を実行したり、移行手順を提案したり、ブロッカーや互換性について言及したりしないでください。 migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json ファイルを作成して終了してください。

3. 評価インテント

お客様が明示的に評価を依頼した場合、または migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json ファイルがすでに作成されている場合は、Phase 2（評価）のみを実行してください。

4. シミュレーションインテント

お客様が自身のワークロードで MSK Express をテストしたい場合です。クラスターのサイジング情報（インスタンスタイプ、ブローカー数、Kafka バージョン）を直接提供するか、以前の評価を参照できます。Phase 3 — シミュレーション に直接進んでください。 評価は役立ちますが、必須ではありません。シミュレーションではサイジング情報を直接確認します。

5. 情報に関する質問

お客様がクラスター固有のデータを提供せずに、Express の機能、制約、設定の違い、認証のサポート、料金、またはコンパクションの動作について尋ねた場合は、AWS ドキュメントツール（aws___search_documentation、aws___read_documentation）が利用可能であれば、それを使って MSK Express のドキュメントから回答を調べてください。MCP ツールを利用できない場合は、MSK Express ドキュメントを参照し、AWS MSK に関する知識に基づいて回答してください。

6. 移行戦略に関する質問

お客様が MSK Replicator の互換性、バージョンのアップグレードパス、MirrorMaker 2、または移行戦略について尋ねた場合です。MSK Replicator は、データレプリケーションのために AWS がネイティブでサポートするソリューションであり、MSK から MSK への移行と、MSK 以外から MSK への移行の両方に対応しています。AWS ドキュメントツール（aws___search_documentation、aws___read_documentation）が利用可能であれば、それを使って最新の要件とサポート対象の設定を取得してください。MCP ツールを利用できない場合は、MSK Replicator ドキュメントを参照し、AWS MSK に関する知識に基づいて回答してください。

---

Phase 1 — 検出

目的： 移行プロファイルを作成するため、ソースクラスターのインベントリを作成します。

入力： 次のいずれか：

• IaC ファイル（CDK、CloudFormation、Docker Compose、Kubernetes マニフェスト、Terraform）を含むディレクトリパス
• お客様がクラスター上で実行した Kafka CLI コマンドの出力
• 会話の中でお客様から提供される手動入力の情報

出力： migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json — 作業ディレクトリに保存します。

検出のルール

• 検出でほかの作業を行う前に、必ず references/discovery.md をすべて読んでください。入力方法、必須の応答テンプレート、禁止事項、および cluster-config.json のスキーマが定義されています。読了するまで応答してはならず、テンプレートに厳密に従ってください。
• 必ず migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json を作業ディレクトリに保存してください。
• お客様の明示的な確認なしに Phase 2 に進まないでください。

---

フェーズ 2 — 評価

目的： クラスターが MSK Express の要件を満たしているか評価し、Express の目標仕様（インスタンスタイプ、ブローカー数、月額コスト予測）を作成します。

入力： フェーズ 1 の migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json。

出力：

• migrate-to-msk-skill-artifacts/<cluster_name>/compatibility.<cluster_name>.json — 5 つの柱に基づく判定。
• migrate-to-msk-skill-artifacts/<cluster_name>/msk_sizing_pricing.md — ブローカー数とコストの推奨事項を含む、managing-amazon-msk Skill の料金レポート。
• migrate-to-msk-skill-artifacts/<cluster_name>/msk-sizing-inputs.<cluster_name>.json — サイジングロジックに使う 6 つの入力値の記録。

評価は独立した 2 つの作業で構成されます。どちらから先に実行してもよく、一方で問題が発生しても、もう一方は実行できます。

• 互換性 — scripts/compatibility.py は、PEP 723 のインライン依存関係を使用して uv run で実行する、純粋なファイル処理スクリプトです（AWS API のライブ呼び出しは行いません）。トポロジー、Kafka バージョン、設定、認証、クォータの 5 つの柱に照らしてソースを検証し、柱ごとに判定（INFO、ADVISORY、ACTION_REQUIRED）を出力します。全体判定には、最も重大な判定が適用されます。この 3 つの文字列はそのまま使用してください。
• サイジング — この Skill に含まれるスクリプトではありません。managing-amazon-msk Skill を読み込み、cluster-config.json から導き出したワークロード入力を指定して、その scripts/msk_sizing.py を実行します。--broker-classes express と、移行先リージョンを指定する --region を渡してください。認証情報が利用可能な場合、スクリプトは AWS Pricing API のライブデータを使って料金を算出し、利用できない場合は埋め込みの us-east-1 スナップショットを使います。

評価ルール

• 回答する前に、references/assessment-compatibility.md を読んでください。実行コマンド、柱ごとのしきい値とエビデンスコード、判定の定義、禁止事項の全リスト、および両方の成果物を扱う必須の回答テンプレートが記載されています。スクリプト実行後の要約を独自の形式で作成しないでください。
• サイジングを実行する前に、references/assessment-sizing.md を読んでください。入力値の導出方法（1 対 1 に対応しない項目も複数あり、誤ると気付かないままブローカー数を誤って算出します）、ラックアフィニティと交渉済み割引に関する target ブロックのフラグ、リージョンと料金ソースの扱い、Express のみを提示するルール、およびソースのフットプリントとの比較について記載されています。
• ACTION_REQUIRED のエビデンスがある場合は、ユーザーが把握できるように伝えてください。ただし、それを理由に後続フェーズを中断しないでください。緩和策により、Express でワークロードを引き続き受け入れられる場合があります。
• 検出作業に戻らないでください。 評価では、既存の cluster-config.json をそのまま使用します。データが一部欠けていても問題ありません。フィールドが不足している場合、スクリプトは METRICS_MISSING、AZ_COUNT_UNKNOWN などのエビデンスを含む ADVISORY を出力します。これらの結果を伝えて終了してください。不足を補うための Kafka CLI コマンド、IaC の調査、スクリプト、質問票を提案しないでください。
• ブローカー数とコストは、サイジングスクリプトの出力から読み取ったとおりにのみ報告してください。丸めたり、再導出したり、推定したりしないでください。コストと併せて、スクリプトが使用した pricing source も報告してください。値が static の場合、その料金は埋め込みスナップショットに基づくもので、現在の料金として確認されたものではありません。

---

フェーズ 3 — シミュレーション（任意）

お客様自身のワークロードで Express の動作を確認できるよう、お客様のアカウントに一時的で分離された MSK Express クラスターとクライアントフリートをデプロイします。その後、提供されているテスト（エンドツーエンドレイテンシー、負荷時のブローカー再起動）のいずれかを実行し、CloudWatch ダッシュボードを引き渡します。references/simulation.md に記載された 12 ステップの会話フローと、デプロイ、サイジング、ガードレールの詳細すべてに従ってください。このフローで使用する決定論的なアーティファクトは、scripts/simulation_load_test_config.py と、静的な assets/simulation-stack.yaml です。

---

実行モデル

スクリプトは uv run を介してお客様のローカルマシン上で実行されます。スクリプトは独自の依存関係（PEP 723）を宣言し、ファイルのみを処理します。AWS API の呼び出しやネットワークアクセスは行わず、サードパーティ製の依存関係もありません（標準ライブラリのみ）。

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

各フェーズで以下の制御を適用してください。詳細については、 MSK Security best practices と MSK IAM access control を参照してください。

1. 転送中の暗号化（必須）。 MSK Express のターゲットで、クライアントとブローカー間のトラフィックに TLS を強制します （EncryptionInTransit.ClientBroker = TLS）。

2. 保存時の暗号化（必須）。 カスタマーマネージドの KMS キー（またはコンプライアンス要件で許容される場合は AWS マネージドキー）を使用して、ターゲットクラスターをプロビジョニングします。

3. 認証 — 長期間有効な認証情報より IAM を優先します。 IAM 認証を唯一のクライアント認証方式として、MSK Express のターゲットを設定します。 これにより、CloudTrail で完全に追跡可能な、一時的なロールベースの認証情報を使用できます。

4. 認証情報の保存 — AWS Secrets Manager を使用します。 ソースクラスターへのアクセスに使用する SASL/SCRAM および TLS の認証情報を Secrets Manager に保存します。パスワードを CLI 引数として渡さないでください。

5. ネットワークの分離。 MSK クラスターはプライベートサブネットにデプロイします。特定の CIDR 範囲またはセキュリティグループ参照に限定したセキュリティグループを使用します。0.0.0.0/0 のインバウンドルールは使用しないでください。

6. CloudTrail のログ記録と CloudWatch アラーム。 CloudTrail がターゲットアカウントで有効になっており、kafka.amazonaws.com の API 呼び出しを対象としていることを確認します。次のアラームを設定します：

   • ClientAuthenticationFailure — 急増は、認証情報の問題または攻撃を示している可能性があります
   • ConnectionCloseCount — 異常な急増は、コネクションフラッディングを示している可能性があります
   • 拒否された kafka-cluster:* アクションを対象とする CloudTrail メトリクスフィルター
   • IAM の 1 ブローカーあたりの上限である 100 接続/秒に近づいた場合の接続率アラーム

7. 機密データの取り扱い。 検出と評価の出力には、ブローカーアドレス、認証に関する情報、ブローカー設定値が含まれます。これらは機密情報として扱い、マスキングせずに公開チャンネルやチケット管理システムに貼り付けないでください。

トラブルシューティング

ソースのトポロジーや範囲外の設定ケースを含む、各柱の評価結果については、 references/assessment-compatibility.md で説明しています。