aws-fis-experiment-prepare

AWS FIS 实验准备

生成运行 AWS FIS 实验所需的所有配置文件，然后通过 CloudFormation 部署，并在必要时反复自愈，直到堆栈成功。输出一个独立目录，其中包含已验证并部署、可直接执行的实验模板。

核心原则： 生成文件前，先验证资源与操作的兼容性。绝不交付未经测试的配置——先部署并完成自愈。

参考资料

每个实验都必须加载：

• references/output-format.md — 目录布局、slug 命名、README 模板
• references/cfn-base-template.md — CFN 骨架（Parameters、IAM Role、Dashboard、FIS Template、Outputs）
• references/slug-conventions.md — 场景/上下文 slug 缩写、资源命名、名称长度限制

按场景有条件地加载：

• 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 Power Interruption、通过 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 自动化	目标服务没有原生 FIS 操作（MSK、ElastiCache 主节点重启、ElastiCache 故障转移）	references/msk-guide.md 或 references/elasticache-redis-guide.md

如果不明确，请询问用户。

场景库文档 URL（无法通过 CLI/API 获取 JSON 模板 — 请阅读文档并提取）：

场景	文档 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 实验模板。该文档是唯一权威来源。

目标识别 — 优先使用 resourceArns，而非 resourceTags：

• 对大多数资源类型使用 resourceArns（精确 ARN）——更加精确，无需预先添加标签
• 例外 — 以下类型不支持 resourceArns，请改用 resourceTags：
  • aws:elasticache:replicationgroup
  • aws:ec2:autoscaling-group
• EKS Pod 操作使用 Kubernetes 命名空间和 Pod 标签（既不使用 resourceArns，也不使用 resourceTags）

resourceArns 和 filters 不能同时使用。 FIS 会拒绝同时指定两者的目标。对于按 AZ 范围指定目标的情况，可以使用仅包含目标 AZ 的 ARN 的 resourceArns，或者同时使用 resourceTags 和 filters。

如果场景是 AZ 电力中断： 按照 references/az-power-interruption-guide.md 处理子操作精简、标签策略、权限和每个 AZ 使用一个 Stack 的设计。

询问用户：

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-* 操作，请在步骤 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 Custom Resource（固定名称：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 之前，阅读 AWS::FIS::ExperimentTemplate CloudFormation 资源文档：

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 电源中断）
   • references/eks-pod-action-guide.md（如果是 EKS Pod 操作）
   • 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}"

通过自愈重试循环进行部署（由 Agent 驱动，最多尝试 5 次）。deploy-with-retry.sh 脚本只执行一次尝试——循环由 Agent 在外部驱动。每次尝试时：

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（部署失败，堆栈已删除）→ 分析 stderr 输出，修复 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 电源中断文档中的伪影	移除 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。
• 目标优先使用 resourceArns，而不是 resourceTags。 例外情况： aws:elasticache:replicationgroup、aws:ec2:autoscaling-group。绝不要将 resourceArns 与 filters 结合使用。
• IAM 策略必须遵循最小权限原则。 只包含实验中特定操作所需的权限。
• CFN 模板必须独立完整。 部署 CFN 模板后，无需执行其他步骤即可获得 可用的实验。
• MCP 调用必须顺序执行。 所有 aws___read_documentation 和 aws___search_documentation 调用都必须顺序执行，不得并行。遇到速率限制 错误时，最多重试 10 次。
• 确保本地文件保持同步。 部署成功后，使用真实 ARN 和堆栈输出更新 README.md。