aws-fis-experiment-execute

AWS FIS 実験の実行

インフラストラクチャがすでにデプロイされていることを確認し、AWS FIS 実験を実行して、その進行状況を監視し、結果レポートを生成します。CloudFormation スタックがすでにデプロイされている、準備済みの実験ディレクトリから設定を読み込みます。

出力言語のルール

ユーザーとの会話の言語を判定し、すべての出力で同じ言語を使用します。

• 中国語の入力 → 中国語で出力
• 英語の入力 → 英語で出力

前提条件

必要なツール：

• AWS CLI — aws fis、aws cloudwatch、aws cloudformation、aws logs
• kubectl — 対象の EKS クラスターへのアクセスが設定されていること。
• 準備済みの実験ディレクトリ（aws-fis-experiment-prepare スキルから）
• この実験の CloudFormation スタックがすでにデプロイされていること

必須のサブスキル： app-service-log-analysis がインストールされている必要があります。アプリケーションの検出、ログ収集、分析のため、実行時に読み込まれます。このスキルがない場合でも実験は実行できますが、ログ分析はスキップされます。

ワークフロー

digraph execute_flow {
    "User input:\npath or template ID?" [shape=diamond];
    "Search CWD for\nmatching directory" [shape=box];
    "Directory found?" [shape=diamond];
    "Ask user for full path" [shape=box, style=bold];
    "Validate files" [shape=box];
    "Read README for stack name" [shape=box];
    "Check CFN stack status" [shape=diamond];
    "Extract template ID from outputs" [shape=box];
    "Display actionIds" [shape=box];
    "Pre-experiment health check" [shape=box, color=blue];
    "All resources healthy?" [shape=diamond];
    "Wait / prompt user" [shape=box];
    "Discover apps + start logs\n(app-service-log-analysis)" [shape=box];
    "User confirms experiment start" [shape=diamond, style=bold, color=red];
    "Start experiment" [shape=box];
    "Monitor experiment\n+ log insights" [shape=box];
    "Experiment complete?" [shape=diamond];
    "Wait 3 min post-baseline" [shape=box];
    "Stop logs + analyze\n(app-service-log-analysis)" [shape=box];
    "Generate results report" [shape=box];

    "User input:\npath or template ID?" -> "Validate files" [label="Full path"];
    "User input:\npath or template ID?" -> "Search CWD for\nmatching directory" [label="Template ID"];
    "Search CWD for\nmatching directory" -> "Directory found?";
    "Directory found?" -> "Validate files" [label="Yes (1 match)"];
    "Directory found?" -> "Ask user for full path" [label="No match"];
    "Ask user for full path" -> "Validate files" [label="User provides path"];
    "Validate files" -> "Read README for stack name";
    "Read README for stack name" -> "Check CFN stack status";
    "Check CFN stack status" -> "Extract template ID from outputs" [label="CREATE_COMPLETE"];
    "Check CFN stack status" -> "Generate results report" [label="Not deployed / failed, abort"];
    "Extract template ID from outputs" -> "Display actionIds";
    "Display actionIds" -> "Pre-experiment health check";
    "Pre-experiment health check" -> "All resources healthy?";
    "All resources healthy?" -> "Discover apps + start logs\n(app-service-log-analysis)" [label="Yes"];
    "All resources healthy?" -> "Wait / prompt user" [label="No"];
    "Wait / prompt user" -> "Pre-experiment health check" [label="Retry (poll 60s,\nmax 10 min non-interactive)"];
    "Wait / prompt user" -> "Discover apps + start logs\n(app-service-log-analysis)" [label="User override"];
    "Wait / prompt user" -> "Generate results report" [label="Abort"];
    "Discover apps + start logs\n(app-service-log-analysis)" -> "User confirms experiment start";
    "User confirms experiment start" -> "Start experiment" [label="Yes, I confirm"];
    "User confirms experiment start" -> "Stop logs + analyze\n(app-service-log-analysis)" [label="No, abort"];
    "Start experiment" -> "Monitor experiment\n+ log insights";
    "Monitor experiment\n+ log insights" -> "Experiment complete?";
    "Experiment complete?" -> "Monitor experiment\n+ log insights" [label="No, poll again"];
    "Experiment complete?" -> "Wait 3 min post-baseline" [label="Yes"];
    "Wait 3 min post-baseline" -> "Stop logs + analyze\n(app-service-log-analysis)";
    "Stop logs + analyze\n(app-service-log-analysis)" -> "Generate results report";
}

ステップ 1：実験ディレクトリの特定と検証

ユーザーは次のいずれかを指定します。

• (a) 実験ディレクトリのフルパス、または
• (b) FIS 実験テンプレート ID（例：EXT1a2b3c4d5e6f7）

ステップ 1a：テンプレート ID からディレクトリを特定

ユーザーがテンプレート ID を指定した場合は、CWD 内でその ID で終わるディレクトリを検索します。

find . -maxdepth 1 -type d -name "*${TEMPLATE_ID_INPUT}" 2>/dev/null

• 一致が 1 件 → そのディレクトリを使用し、ユーザーに知らせます
• 複数一致 → 一覧を表示して、ユーザーに選択を求めます
• 一致なし → フルパスをユーザーに求めます。有効なパスが得られるまで続行しないでください。

ステップ 1b：ディレクトリ名からテンプレート ID を抽出

実験ディレクトリ名はテンプレート ID で終わります（例： 2026-04-11-az-power-int-my-cluster-EXT1a2b3c4d5e6f7）。これを抽出します。

TEMPLATE_ID=$(basename "${EXPERIMENT_DIR}" | grep -oE 'EXT[a-zA-Z0-9]+$')

TEMPLATE_ID として保存します。これは以降のすべてのステップで使用します。

ステップ 1c：必須ファイルを検証

EXPERIMENT_DIR に cfn-template.yaml と README.md が含まれていることを確認します。

ステップ 2：README を読み、実験メタデータを抽出

実験ディレクトリの README.md を読み、次の情報を抽出します。

1. シナリオ名 — H1 見出しから取得します（例：# FIS Experiment: AZ Power Interruption）
2. 対象リージョン — **Region:** {REGION} から取得します
3. 対象 AZ — **Target AZ:** {AZ_ID} から取得します（該当する場合）
4. 推定所要時間 — **Estimated Duration:** {DURATION} から取得します
5. 影響を受けるリソース — 「Affected Resources」テーブルから取得します
6. CFN スタック名 — **CFN Stack:** {STACK_NAME} から取得します（クリーンアップ時の参照専用）

抽出したすべての情報を含む概要をユーザーに提示します。

ステップ 3：実験アクションを表示

TEMPLATE_ID（ステップ 1b でディレクトリ名から抽出）を使用して、AWS CLI 経由で実験テンプレートを照会し、すべてのアクション ID を表示します。

aws fis get-experiment-template \
  --id "{TEMPLATE_ID}" \
  --region {REGION} \
  --query 'experimentTemplate.actions' --output json

アクションマップからすべての actionId 値を抽出し、ユーザーに表示します。

Actions found:
  - {actionId_1}
  - {actionId_2}
  ...

ステップ 3.5（リソースのヘルスチェック）に直接進みます。

Step 3.5: 実験前のリソース健全性チェック

ログ収集または実験そのものを開始する前に、FIS 実験テンプレートで参照されるすべての対象リソースが、正常なベースライン状態にあることを確認します。すでに劣化したリソースに対して実験を開始すると、結果の原因を特定できなくなり、脆弱なインフラへの影響を拡大させる可能性があります。

対象範囲： FIS 実験テンプレートの targets マップに記載されたすべてのリソース（Step 3 のクエリから取得）。対象となるテンプレートに応じて、RDS、Aurora、MSK、ElastiCache（Redis/Memcached）、EKS クラスターおよびノードグループ、EC2、OpenSearch、DocumentDB など、あらゆるマネージドサービスが含まれます。

手順：

1. 実験テンプレート内の各対象から resourceType（例：aws:rds:db、aws:msk:cluster、aws:elasticache:replicationgroup）と、実際のリソース識別子（resourceArns から取得するか、resourceTags から解決）を抽出します。

2. 各リソースについて、該当するサービスの適切な AWS describe API を呼び出し、基準となるステータスフィールドを読み取ります。AWS サービスに関する知識を使って、適切な API と「正常」を示す値（例：RDS の available、MSK の ACTIVE、ElastiCache の available、EKS の ACTIVE、ステータスチェックが ok の EC2 の running）を選択します。

3. 次の表をユーザーに提示します。

   Resource             Type                              Status        Healthy?
   {id_1}               {resourceType_1}                  {status_1}    {✓ or ✗}
   {id_2}               {resourceType_2}                  {status_2}    {✓ or ✗}
   ...
   

4. リソースタイプが不明な場合、または API 呼び出しに失敗した場合は、そのリソースを未チェックとしてマークし、判断上は異常として扱います。

判断ルール：

• すべてのリソースが正常 → Step 4 に進みます。
• 1 つ以上のリソースが異常／未チェック：
  • 対話型セッション（ユーザーにプロンプトを表示して応答を受け取れる場合）： ユーザーに警告し、問題のあるリソースと現在の状態を一覧表示して、明示的な入力を待ちます。受け付ける入力は、proceed（上書きして続行）、abort（ワークフローを停止）、retry（今すぐ健全性チェックを再実行）です。
  • 非対話型セッション（応答できるユーザーがいない場合）： 60 秒ごとに、最大 10 分間自動でポーリングします。各サイクルですべての対象リソースを再確認します。制限時間内にすべてのリソースが正常になった場合は、自動的に Step 4 に進みます。10 分が経過しても異常なリソースが残っている場合は、各異常リソース、現在の状態、および待機時間を記載した診断サマリーを出力して中止します。

対話型か非対話型かの判断方法： 実行時のコンテキスト（例：TTY が接続されているか、対話型プロンプトを呼び出せるか、CI／自動実行を示す環境シグナルがあるか）に基づいて判断してください。判断に迷う場合は、対話型の動作を既定とします。

Step 3.9: App-Service-Log-Analysis スキルの読み込み

必須： skill ツールを使って、今すぐ app-service-log-analysis スキルを読み込んでください。次を呼び出します：skill(name="app-service-log-analysis")。

ユーザーが対象の Pod をすでに指定しているかどうかにかかわらず、このスキルは常に必要です。以下に対応します。

• マネージドサービスのログ検出（アプリケーションの Pod とは独立）
• ログファイルの整理と命名規則
• 実験後の分析とレポートの生成

スキルがインストールされていない、または読み込めない場合は、その旨をユーザーに伝え、ログ収集をスキップしてください（スキルがなくても実験は実行できます）。

ステップ 4：EKS アプリケーションを検出し、ログ収集を開始する

このステップは実験の開始前に実行します。実験開始後にアプリケーションを検出すると、ローテーションまたは上書きされる初期のログエントリーを取り逃すおそれがあります。

app-service-log-analysis スキルから実行します。

1. そのステップ 2（サービスリストの読み取り） — 実験ディレクトリの expected-behavior.md から影響を受ける AWS サービスを抽出します
2. そのステップ 2.5（マネージドサービスログの検出と収集） — マネージドサービスの CloudWatch ロギング状態を確認し、後の分析に備えてロググループを記録します
3. その「マルチクラスター EKS 検出と kubeconfig の分離」セクション — 対象リージョン内の すべての EKS クラスターを検出し、クラスターごとに分離された kubeconfig を生成します （~/.kube/config は決して上書きしません）。各クラスターへのアクセスを確認します
4. そのステップ 3（アプリケーションの依存関係を収集 — 詳細スキャン） — サービスエンドポイントを解決し、アクセス可能なすべてのクラスターを並列で詳細スキャンして、検出された依存関係をユーザーに確認します
5. そのステップ 4（ログ収集 — リアルタイムモード） — すべてのクラスターで確認済みのアプリケーションすべてについて、バックグラウンドで kubectl logs -f を開始します

ステップ 5：実験を開始する（重要な確認）

これは最も危険なステップです。実験は実際のリソースに影響を与えます。

開始する前に、明確な警告を提示してください。

WARNING: Starting this FIS experiment will cause REAL impact:

Scenario:    {SCENARIO_NAME}
Region:      {REGION}
Target AZ:   {AZ_ID}
Duration:    {DURATION}
Stack:       {STACK_NAME} (verified: CREATE_COMPLETE)
Template ID: {TEMPLATE_ID}

Resources that WILL be affected:
  - {list each affected resource type and count from README}

Stop Conditions:
  - {list each alarm that will stop the experiment}

Applications being monitored:
  - {list each namespace/deployment from SERVICE_APP_MAP}

Managed service log collection:
  - {list each service with logging status from MANAGED_LOG_GROUPS}

Log directory: {LOG_DIR}
Post-experiment baseline: 3 minutes (automatic)

Type "Yes, start experiment" to proceed, or "No" to abort.

ユーザーが明示的に確認した場合にのみ続行してください。 ユーザーが中止した場合は、まずログ収集を停止してクリーンアップするため、ステップ 7 に進みます。

返された experiment.id を保存します。

ステップ 6：実験を監視する

実験の状態をポーリングし、進行状況を表示します。ポーリングコマンドと実験状態のリファレンスについては、references/cli-commands.md を参照してください。

ポーリング戦略：

• 最初の 5 分間は 30 秒ごとにポーリングします
• その後は 60 秒ごとにポーリングします
• 各ポーリング後に現在の状態を表示します
• 状態の変化とアクション状態の遷移ごとにタイムスタンプを記録します。これらは最終レポートのサービスごとのタイムラインに使用されます
• サービスごとのイベントを追跡します。実験の影響を受けるサービスごとに、影響を受けた時点（アクション開始時）、復旧した時点、中間状態を記録します。詳細な状況を把握するため、監視中にサービス固有の状態（例：RDS インスタンスの状態、ElastiCache レプリケーショングループの状態、EKS ノードの状態）を確認します。

各ポーリングサイクルでのログに関する分析： app-service-log-analysis のステップ 5 （リアルタイム監視表示）を実行します。最近のログを読み取り、エラーと警告の数を集計し、 アプリケーションごとの概要を表示して、復旧の兆候を検出します。このスキルはステップ 4 ですでに読み込まれている必要があります。

監視中にユーザーに次のことを伝えます：

• リアルタイムメトリクスを CloudWatch ダッシュボードで確認する
• 実験はいつでも停止できます（停止コマンドについては references/cli-commands.md を参照してください）

ステップ 7：実験後のベースライン確認、ログ収集の停止、分析

実験が完了した後（終端状態は問いません）：

実験後のベースライン確認（3 分間）

復旧の挙動を捉えるため、実験終了後も3 分間ログ収集を続けます。これはアプリケーションログとマネージドサービスログの両方に適用されます。ユーザーにカウントダウンを表示します。

Experiment completed. Collecting post-experiment baseline logs...
Remaining: {countdown} (3 minutes total)

3 分間のベースライン期間が終了したら、分析に進みます。

アプリケーションログ分析の生成

app-service-log-analysis のステップ 7〜8 を実行します。

• そのステップ 7（分析レポートの生成） — エラーパターン、ピーク発生率、復旧時間を分析し、レポートの「アプリケーションログ分析」セクションを生成します。分析の時間範囲はベースライン期間を含めるため、実験終了時刻から 3 分後まで延長します。
• そのステップ 8（クリーンアップ） — バックグラウンドの kubectl logs プロセスを終了します

アプリケーションログ分析の出力は、別ファイルとして保存せず、実験結果レポートに埋め込みます（下記のステップ 10 を参照）。

ステップ 10：結果レポートをローカルファイルに保存する

実験の完了後（どの終端状態であっても）、結果レポートを生成し、 実験ディレクトリ内のローカルの Markdown ファイルに直接書き込みます。

レポートの完全な構成、ファイル名の規則、タイムスタンプの形式については、 references/report-template.md を参照してください。

サービスごとの分析： README の「Affected Resources」テーブルから、実験の影響を受けたサービスをすべて特定します。各サービスについて、次の項目を含むサブセクションを作成します。 （1）タイムラインイベント、（2）観測された動作、（3）主な調査結果。間接的に影響を受けたサービスも含めます。

保存後、ターミナルに簡潔な概要を出力します。

• ファイルパス、実験 ID、最終ステータス
• 開始／終了時刻と所要時間（タイムゾーン付き ISO 8601）
• アクションごとのステータス（各 1 行）
• サービスごとの復旧ステータス（各 1 行）
• アプリケーションログの概要 — アプリごとのエラー合計数
• 対応が必要な問題（あれば）
• クリーンアップ手順

安全ルール

1. 実験を自動的に開始してはいけません。 必ずユーザーの明示的な確認を求めてください。
2. 実行するすべての CLI コマンドを、実行前に表示してください。
3. 実験開始前に、対象リソースの具体的な一覧を含む影響警告を表示してください。
4. 各手順で中止方法を案内してください。
5. ユーザーの確認なしにリソースを削除してはいけません。
6. インフラストラクチャをデプロイしてはいけません。 このスキルは既存のデプロイのみを確認します。
7. まずドライランを行うよう推奨してください — 開始前にすべてのファイルを確認するようユーザーに提案してください。
8. 健全でないリソースを対象に実験を開始してはいけません。 ステップ 3.5 では、すべての対象リソースが各サービスの健全なベースライン状態にあることを確認します。対話モードでは、健全でないリソースまたは未確認のリソースがある場合、ユーザーによる明示的な上書き許可が必要です。非対話モードでは、最長 10 分間、60 秒ごとにポーリングしてください。時間切れ時点でも健全でない場合は中止してください。

クリーンアップガイド

実験後にクリーンアップを提案してください。コマンドについては references/cli-commands.md を参照してください。

エラー処理

エラー	原因	解決方法
README にスタック名が見つからない	README に **CFN Stack:** フィールドがない	実験が aws-fis-experiment-prepare の最近のバージョンで準備されたか確認してください
スタックが見つからない（ValidationError）	スタックが存在しないか、削除されている	まず aws-fis-experiment-prepare を使用してスタックをデプロイしてください
スタックが CREATE_FAILED / ROLLBACK_COMPLETE の状態	スタックのデプロイに失敗した	スタックイベントで失敗の原因を確認し、修正して再デプロイしてください
出力に ExperimentTemplateId がない	スタックテンプレートに出力がない	cfn-template.yaml で出力定義を確認してください
AccessDeniedException	権限が不足している	FIS、CloudWatch、CloudFormation の IAM 権限を確認してください
ターゲットに対する ResourceNotFoundException	タグ付きリソースが見つからない	リソースタグが実験テンプレートと一致していることを確認してください
実験が initiating のまま止まっている	IAM ロールの伝播に時間がかかっている	30 秒待ってから再確認してください
kubectl: command not found	kubectl がインストールされていない	kubectl をインストールし、kubeconfig を設定してください
error: You must be logged in	kubeconfig が設定されていない	aws eks update-kubeconfig --name {cluster} を実行してください
/.pids: Permission denied	&& の連結によって LOG_DIR 変数が空になっている	&& で連結せず、export LOG_DIR=... を含む複数行のスクリプトを使用してください
EKS アプリが見つからない	影響を受けたサービスのエンドポイントを参照するポッドがない	名前空間とデプロイのペアを手動で指定するようユーザーに依頼してください