aws-fis-experiment-prepare

AWS FIS 実験の準備

AWS FIS 実験の実行に必要なすべての設定ファイルを生成し、スタックが 成功するまで自己修復を繰り返しながら CloudFormation でデプロイします。 検証済みでデプロイ済みの実験テンプレートを含む、自己完結型のディレクトリを 出力します。

基本原則： ファイルを生成する前に、リソースとアクションの互換性を検証します。 テストしていない設定は決して納品しません。まずデプロイし、自己修復を行います。

参考資料

すべての実験で必ず読み込む資料：

• references/output-format.md — ディレクトリ構成、スラッグの命名、README テンプレート
• references/cfn-base-template.md — CFN の骨組み（Parameters、IAM Role、 Dashboard、FIS Template、Outputs）
• references/slug-conventions.md — シナリオ／コンテキストのスラッグ略称、 リソースの命名、名前の文字数上限

シナリオに応じて読み込む資料：

• references/az-power-interruption-guide.md — AZ Power Interruption （サブアクションの絞り込み、タグ付け戦略、権限）
• references/eks-pod-action-guide.md — aws:eks:pod-* アクション全般 （RBAC Lambda、EKS Access Entry、Pod のメモリ負荷計算）
• references/elasticache-redis-guide.md — ElastiCache Redis/Valkey （ネイティブの AZ 電源遮断、SSM Automation によるプライマリノードの再起動、または SSM Automation によるレプリケーショングループのフェイルオーバー）
• references/msk-guide.md — Amazon MSK（SSM Automation によるブローカーの再起動 — ネイティブの FIS アクションはありません）

ユーティリティスクリプト（参考資料として読むのではなく、実行してください）：

• scripts/precheck-cfn-permissions.sh — 必要な CFN サービスロールを検出します
• scripts/deploy-with-retry.sh — 検証、デプロイ、失敗時の削除を行います
• scripts/rename-output-dir.sh — ディレクトリ名に FIS テンプレート ID を追加します

スクリプトの実行方法： ${SKILL_DIR} は、このスキルのディレクトリ（SKILL.md が 配置されている場所）の絶対パスを指します。スクリプトを実行する前に、スキルの ファイルシステム上の場所から解決してください。

出力言語のルール

ユーザーとの会話で使われている言語を判定し、すべての出力ファイル（README.md、JSON／YAML 内のコメント）で同じ言語を使用してください。

• 中国語の入力 → 中国語の出力
• 英語の入力 → 英語の出力
• 混在している場合 → 主に使われている言語に従う

前提条件

必要なツール：

• AWS CLI — aws fis list-actions、リソースの検出、CloudFormation
• aws___search_documentation / aws___read_documentation — FIS のドキュメント調査
• jq — scripts/deploy-with-retry.sh および scripts/precheck-cfn-permissions.sh で必要です

EKS Pod の障害注入： クラスターの認証モードは API_AND_CONFIG_MAP または API である必要があります。確認してください：

aws eks describe-cluster --name {CLUSTER} \
  --query 'cluster.accessConfig.authenticationMode'

CONFIG_MAP のみの場合、ユーザーは先にクラスターを更新する必要があります。 必須： aws:eks:pod-* アクションを使う場合は、 references/eks-pod-action-guide.md に従ってください。

ワークフロー

ステップ 1：シナリオとリージョンの特定

ユーザーの意図を、次のいずれかの分岐に分類します：

分岐	トリガー	追加の参照先
シナリオライブラリ	AZ の電源停止、AZ のアプリケーション速度低下、AZ 間／リージョン間のシナリオ	AWS ドキュメント URL を参照（下表）
カスタム FIS アクション	ユーザーがアクション ID を指定する、または単一の障害を説明する	—
カスタム FIS アクション（ElastiCache）	ElastiCache の AZ 電源停止、または Redis／Valkey のフェイルオーバー	references/elasticache-redis-guide.md
SSM Automation	対象サービスにネイティブ FIS アクションがない（MSK、ElastiCache のプライマリ再起動、ElastiCache のフェイルオーバー）	references/msk-guide.md または references/elasticache-redis-guide.md

曖昧な場合は、ユーザーに確認します。

シナリオライブラリのドキュメント URL（JSON テンプレートは CLI／API から取得できないため、ドキュメントを参照して抽出します）：

シナリオ	ドキュメント URL
AZ の電源停止	https://docs.aws.amazon.com/en_us/fis/latest/userguide/az-availability-scenario.html
AZ のアプリケーション速度低下	https://docs.aws.amazon.com/en_us/fis/latest/userguide/az-application-slowdown-scenario.html
AZ 間のトラフィック速度低下	https://docs.aws.amazon.com/en_us/fis/latest/userguide/cross-az-traffic-slowdown-scenario.html
リージョン間の接続	https://docs.aws.amazon.com/en_us/fis/latest/userguide/cross-region-scenario.html

リージョンの特定順序：

1. ユーザーが明示的に指定
2. コンテキストから推測（ARN、以前の会話）
3. aws configure get region
4. ユーザーに確認

TARGET_REGION として保存します。

実験のデフォルト期間：すべてのシナリオおよびサブアクションで PT10M（10 分）。ユーザーが別の期間を指定した場合を除きます。AZ の電源停止では、ARC Zonal Autoshift の時間を比例調整します（PT10M の場合、ARC は 2 分後に開始し、8 分間実行します。計算式：startAfter = duration × (5/30)）。

ステップ 2：対象リソースの検出

シナリオライブラリのシナリオの場合

重要：シナリオライブラリの実験テンプレートは FIS API から生成できません。 ファイルを生成する前に、必ず aws___read_documentation をシナリオ URL（ステップ 1 の表）とともに呼び出し、JSON 実験テンプレートを抽出してください。ドキュメントのみが信頼できる情報源です。

対象の特定 — resourceTags よりも resourceArns を優先します：

• ほとんどのリソースタイプでは、より正確で事前のタグ付けが不要な resourceArns（正確な ARN）を使用します
• 例外 — 次のタイプは resourceArns をサポートしないため、代わりに resourceTags を使用します：
  • aws:elasticache:replicationgroup
  • aws:ec2:autoscaling-group
• EKS ポッドのアクションでは、Kubernetes の名前空間とポッドラベルを使用します（resourceArns と resourceTags のどちらも使用しません）

resourceArns と filters は相互に排他的です。 両方を指定したターゲットは FIS に拒否されます。AZ を指定して対象とする場合は、対象 AZ の ARN のみを指定した resourceArns を使用するか、resourceTags と filters を組み合わせて使用します。

シナリオが AZ の電源停止の場合： サブアクションの絞り込み、タグ付け戦略、権限、AZ ごとのスタック設計については、references/az-power-interruption-guide.md に従います。

ユーザーに確認する項目：

1. 対象とする AZ（AZ レベルのシナリオの場合）
2. 含めるサービス（AZ の電源停止の場合）— ユーザーが特定のサービスに言及した場合は、そのサービスと必須のインフラストラクチャサブアクションのみを含めます
3. 対象リソースの識別子（クラスター ID、インスタンス ID など）

カスタム FIS アクションの場合

aws fis get-action --id "ACTION_ID" --region TARGET_REGION

必要な targets と parameters を抽出します。AWS CLI を使用して、ユーザーが指定した識別子を ARN に解決します。

ネイティブ FIS アクションがないサービスの場合（SSM Automation）

1. ネイティブアクションが存在しないことを確認します：

   aws fis list-actions \
     --query "actions[?starts_with(id, 'aws:{SERVICE}:')]" \
     --region TARGET_REGION
   

2. 空の場合は、サービス固有のガイドに従います：

   • Amazon MSK → references/msk-guide.md
   • ElastiCache のプライマリノードの再起動 → references/elasticache-redis-guide.md （シナリオ 2）
   • その他のサービス → まだドキュメント化されていません。停止して、ユーザーに知らせてください。

特記事項 — ElastiCache： AZ レベルの影響に対するネイティブ FIS アクション （aws:elasticache:replicationgroup-interrupt-az-power）はありますが、単一ノードの再起動やレプリケーショングループのフェイルオーバーに対するネイティブ アクションはありません。プライマリノードの再起動には、 references/elasticache-redis-guide.md → シナリオ 2 に従って SSM Automation を使用します。レプリケーショングループの フェイルオーバー（TestFailover）には、references/elasticache-redis-guide.md → シナリオ 3 に従って SSM Automation を使用します。

3. 対象サービスの CLI を使用してリソースを検出します（aws kafka list-clusters など）。

ステップ 2.5：EKS Pod アクションのセットアップゲート

実験に aws:eks:pod-* アクションが1つでも含まれる場合は、ステップ 3 の前にこのゲートを完了してください。

対象アクション：aws:eks:pod-cpu-stress、aws:eks:pod-delete、 aws:eks:pod-io-stress、aws:eks:pod-memory-stress、 aws:eks:pod-network-blackhole-port、aws:eks:pod-network-latency、 aws:eks:pod-network-packet-loss。

1. 公式ドキュメントを読みます：

   aws___read_documentation:
     url: https://docs.aws.amazon.com/fis/latest/userguide/eks-pod-actions.html
   

2. references/eks-pod-action-guide.md のすべての要件に従います：

   • K8s RBAC 用の Lambda ベースの CFN カスタムリソース（固定名：fis-sa、 fis-experiment-role、fis-experiment-role-binding）
   • FIS Experiment Role の EKS Access Entry（Username: fis-experiment）
   • クラスターの認証モードの確認（API_AND_CONFIG_MAP または API）
   • Pod の readOnlyRootFilesystem: false の確認
   • ネットワークアクションの制限（Fargate およびブリッジモードは使用不可）
   • Pod のメモリストレスしきい値の計算（アクションが aws:eks:pod-memory-stress の場合）— ユーザーが指定する割合は合計目標値であり、 注入値ではありません

省略しないでください。EKS Pod アクションには、他の FIS アクションとは 大きく異なる複雑なセットアップ要件があります。

ステップ 3：リソースとアクションの互換性を検証する

重要なゲートです。 ファイルを生成する前に、ユーザーの 実際のリソースが選択した FIS アクションと互換性があることを確認してください。

3a. 実際のリソースを調べる

ユーザーの指定	CLI コマンド	主なフィールド
RDS データベース	aws rds describe-db-instances --db-instance-identifier {ID}	Engine、DBClusterIdentifier
RDS/Aurora クラスター	aws rds describe-db-clusters --db-cluster-identifier {ID}	Engine、EngineMode、MultiAZ
EC2 インスタンス	aws ec2 describe-instances --instance-ids {ID}	InstanceType、Placement.AvailabilityZone
EKS クラスター	aws eks describe-cluster --name {NAME}	accessConfig.authenticationMode、version
ElastiCache	aws elasticache describe-replication-groups --replication-group-id {ID}	NodeGroupConfiguration、MultiAZ
ASG	aws autoscaling describe-auto-scaling-groups --auto-scaling-group-names {NAME}	AvailabilityZones、Instances

3b. FIS アクションの要件と照合する

aws fis get-action --id "ACTION_ID" --region TARGET_REGION \
  --query 'action.targets' --output json

よくある非互換性の落とし穴：

FIS アクション	必須の resourceType	互換性がない対象	検出方法
aws:rds:failover-db-cluster	aws:rds:cluster	スタンドアロンの RDS（Aurora 以外）	DBClusterIdentifier が null
aws:rds:reboot-db-instances	aws:rds:db	Aurora クラスター	Engine が aurora で始まる
aws:elasticache:replicationgroup-interrupt-az-power	aws:elasticache:replicationgroup	スタンドアロンの ElastiCache ノード	レプリケーショングループがない
aws:ec2:stop-instances	aws:ec2:instance	Spot インスタンス	InstanceLifecycle = spot

3c. 判定ゲート

• 互換性あり → ステップ 4 に進みます。
• 互換性なし → 不一致の内容を説明し、実際のリソースタイプに基づく代替案を提案して、続行するか中止するかをユーザーに確認します。

代替案の例：

• スタンドアロンの RDS Multi-AZ → aws:rds:reboot-db-instances に --force-failover を指定
• Aurora クラスター → aws:rds:failover-db-cluster
• スタンドアロンの ElastiCache → レプリケーショングループが必要であることを説明

3d. シナリオライブラリのシナリオの場合

含まれるサブアクションを、それぞれの対象リソースに対して検証します。サービス単位の絞り込み（ステップ 2）後も残っているサブアクションのみを検証します。

ステップ 4：モニタリング設定の決定

停止条件 — デフォルト：source: "none"（アラームなし）。 ユーザーが明示的に指定した場合にのみ、CloudWatch アラームを作成します。

ダッシュボードのメトリクス — サービスごとに網羅的に設定します。 サービスごとにウィジェットをグループ化し、各サービスにつき 3 つのウィジェット（可用性、パフォーマンス、エラー／レイテンシ）を設定します。実験によって実際に影響を受けるサービスのみを含めます。

サービス	メトリクス
EC2	StatusCheckFailed、CPUUtilization、NetworkIn/Out、NetworkPacketsIn/Out
RDS/Aurora	DatabaseConnections、ReadLatency、WriteLatency、AuroraReplicaLag、FreeableMemory
EKS	pod_number_of_running_pods、pod_number_of_container_restarts、node_cpu_utilization、node_memory_utilization
ElastiCache	ReplicationLag、EngineCPUUtilization、CurrConnections、CacheHitRate、Evictions、IsMaster
ALB	HealthyHostCount、UnHealthyHostCount、HTTPCode_ELB_5XX_Count、TargetResponseTime
NLB	ActiveFlowCount、TCP_Client_Reset_Count、TCP_Target_Reset_Count

ステップ 5：設定ファイルの生成

出力ディレクトリを作成します：

# ─── Fill in from user's request + references/slug-conventions.md ───
SCENARIO_SLUG="..."         # e.g., pod-delete, az-power-int, rds-failover
TARGET_RESOURCE_ID="..."    # e.g., my-aurora-cluster, i-0abc123def
CONTEXT_NAME=""             # optional (e.g., redis, msk); leave empty if N/A
# ────────────────────────────────────────────────────────────────────

# Derived values (do not edit):
TARGET_SLUG=$(echo "${TARGET_RESOURCE_ID}" | tr '[:upper:]' '[:lower:]' | tr ' :/' '-' | cut -c1-20)
CONTEXT_SLUG=$(echo "${CONTEXT_NAME}" | tr '[:upper:]' '[:lower:]' | tr ' :/' '-' | cut -c1-10)
TIMESTAMP=$(TZ=Asia/Shanghai date +%Y-%m-%d-%H-%M-%S)

if [ -n "${CONTEXT_SLUG}" ]; then
    OUTPUT_DIR="./${TIMESTAMP}-${SCENARIO_SLUG}-${TARGET_SLUG}-${CONTEXT_SLUG}"
else
    OUTPUT_DIR="./${TIMESTAMP}-${SCENARIO_SLUG}-${TARGET_SLUG}"
fi
mkdir -p "${OUTPUT_DIR}"

必須： cfn-template.yaml を生成する前に、CloudFormation リソース AWS::FIS::ExperimentTemplate のドキュメントを読みます：

aws___read_documentation:
  url: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-fis-experimenttemplate.html

こちらも必須： 使用するリソースの CloudFormation の例を検索します：

aws___search_documentation:
  search_phrase: "<CFN resource types in this experiment>"
  topics: ["cloudformation"]

ファイルを生成します：

1. cfn-template.yaml — references/cfn-base-template.md をひな形として使用します。以下に従って、シナリオ固有のリソースを追加します：

   • references/az-power-interruption-guide.md（AZ Power Interruption の場合）
   • references/eks-pod-action-guide.md（EKS のポッドアクションの場合）
   • references/msk-guide.md（MSK の場合）
   • references/elasticache-redis-guide.md（ElastiCache の場合）

2. README.md — references/output-format.md のテンプレートを使用します。

ステップ 5.5：CFN 権限の事前確認

事前確認スクリプトを実行して、CFN サービスロールが必要かどうかを検出します：

CFN_ROLE_ARN=$("${SKILL_DIR}/scripts/precheck-cfn-permissions.sh")

呼び出し元に CloudFormation の権限がない場合、スクリプトはガイダンスを表示して 1 で終了します — 処理を停止し、ユーザーに知らせてください。それ以外の場合、CFN_ROLE_ARN は空（サービスロール不要）か、必要なロール ARN を含みます。

ステップ 6：CFN テンプレートをデプロイする（自己修復ループ）

デプロイパラメーターを生成します：

# See references/slug-conventions.md for the ExperimentName composition rule
RANDOM_SUFFIX=$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c6)

if [ -n "${CONTEXT_SLUG}" ]; then
    EXPERIMENT_NAME="${SCENARIO_SLUG}-${TARGET_SLUG}-${CONTEXT_SLUG}-${RANDOM_SUFFIX}"
else
    EXPERIMENT_NAME="${SCENARIO_SLUG}-${TARGET_SLUG}-${RANDOM_SUFFIX}"
fi
STACK_NAME="fis-${EXPERIMENT_NAME}"

自己修復リトライループでデプロイします（エージェントが最大 5 回試行します）。deploy-with-retry.sh スクリプトは1 回分の試行を実行します。ループはエージェントが外部で制御します。各試行では：

1. scripts/deploy-with-retry.sh を実行します：

   "${SKILL_DIR}/scripts/deploy-with-retry.sh" \
     "${OUTPUT_DIR}/cfn-template.yaml" \
     "${STACK_NAME}" \
     "${TARGET_REGION}" \
     "${CFN_ROLE_ARN}" \
     "ExperimentName=${EXPERIMENT_NAME}" \
     "RandomSuffix=${RANDOM_SUFFIX}"
   

2. 終了コード 0 → デプロイに成功しました。「デプロイ成功時」に進みます。
3. 終了コード 1（検証失敗）または 2（デプロイ失敗、スタック削除済み） → 標準エラー出力を分析し、cfn-template.yaml を修正して、試行回数を 増やし、スクリプトを再実行します。
4. 5 回失敗した場合 → 停止し、最後のエラー、試した修正内容すべて、 現在の cfn-template.yaml をユーザーに報告します。

よくある CFN エラーと修正方法：

エラーパターン	根本原因	修正方法
Property validation failure	CFN プロパティ名または値が無効です	リソースプロパティを修正します
Template format error	YAML 構文の問題です	インデント／構造を修正します
Resource type not supported	リソースがリージョンで利用できません	リージョンで利用可能か確認します
Circular dependency	リソース同士が相互に参照しています	DependsOn を使用するか、構成を変更します
RoleArn ... is invalid	IAM ロールがまだ伝播していません	IAM ロールに DependsOn を追加します
空の logConfiguration	AZ Power Interruption のドキュメントに起因するアーティファクトです	logConfiguration ブロックを削除します

デプロイ成功時

1. スタックの出力を取得します：

   aws cloudformation describe-stacks \
     --stack-name "${STACK_NAME}" \
     --query 'Stacks[0].Outputs' \
     --region "${TARGET_REGION}" --output table
   

2. 実際のスタック名、テンプレート ID、ダッシュボード URL、 クリーンアップコマンドで README.md を更新します。すべての {STACK_NAME} プレースホルダーを置き換えてください。最終出力に プレースホルダーを残さないでください。

ステップ 7：テンプレート ID を付けて出力ディレクトリの名前を変更する

名前変更スクリプトを実行します：

NEW_OUTPUT_DIR=$("${SKILL_DIR}/scripts/rename-output-dir.sh" \
    "${OUTPUT_DIR}" \
    "${STACK_NAME}" \
    "${TARGET_REGION}")
OUTPUT_DIR="${NEW_OUTPUT_DIR}"

名前を変更したディレクトリの絶対パス全体で README.md の **Directory:** フィールドを更新します。CFN のデプロイに失敗した 場合（ステップ 6 で最大リトライ回数を超えた場合）は、このステップを スキップします。

ターミナルに簡潔な概要を出力します：

• 実験の出力ディレクトリ（テンプレート ID を含む）
• CFN スタック名とデプロイ状況
• 実験テンプレート ID
• 次のステップの指示

重要なガイドライン

• シナリオライブラリのテンプレートはドキュメントを参照します。 ファイルを生成する前に、シナリオのドキュメント URL（ステップ 1 の表）に対して aws___read_documentation を呼び出してください。ドキュメントのみを信頼できる情報源としてください。
• このスキルでは FIS 実験を開始しないでください。 実験の開始は aws-fis-experiment-execute が処理するか、ユーザーが手動で行います。
• ファイルを生成する前に、リソースとアクションの互換性を検証してください（ステップ 3）。最もよくある無駄な作業の原因は、互換性のないリソースを対象にしたテンプレートをデプロイすることです。
• 必ずデプロイして検証してください。 ファイルを生成するだけで終わらせず、CFN テンプレートをデプロイし、成功するまで反復してください（ステップ 6）。ユーザーには、すぐに開始できる、正常にデプロイ済みの実験テンプレートを提供してください。
• CFN エラーを自己修復してください。 スタックイベントを読み取り、原因を特定してテンプレートを修正し、失敗したスタックを削除して再試行してください。CFN エラーの修正をユーザーに求めないでください。
• テンプレートを生成する前に FIS アクションの利用可否を確認してください（aws fis list-actions／aws fis get-action）。アクション ID を捏造しないでください。
• ターゲットには resourceTags より resourceArns を優先してください。 例外は aws:elasticache:replicationgroup と aws:ec2:autoscaling-group です。resourceArns と filters を決して併用しないでください。
• IAM ポリシーは最小権限にしてください。 実験内の特定のアクションに必要な権限のみを含めてください。
• CFN テンプレートは自己完結型にしてください。 CFN テンプレートをデプロイするだけで、他の手順を必要とせず、実験が動作するようにしてください。
• MCP 呼び出しは順次実行してください。 すべての aws___read_documentation および aws___search_documentation 呼び出しは並列ではなく順次実行してください。レート制限エラーが発生した場合は、最大 10 回まで再試行してください。
• ローカルファイルの内容を常に同期してください。 デプロイに成功したら、実際の ARN とスタック出力で README.md を更新してください。