Deep Dive: The SSM Integration for OS-Level Faults

Why FIS Cannot Natively Spike Your CPU

AWS FIS can reboot an RDS instance with a single API call because Amazon controls the RDS control plane — it is an AWS-managed resource. But AWS does not control what runs inside your EC2 instance's operating system. The kernel, the processes, the filesystem — those are yours. FIS has no native mechanism to reach inside and exhaust your RAM or fill your disk.

This is where AWS Systems Manager (SSM) becomes the bridge. SSM provides a secure, agent-based channel for executing commands on EC2 instances without opening SSH ports. FIS uses this channel to deliver OS-level faults.

How the SSM Integration Works

Step 1 — The Agent: Your EC2 instances must have the SSM Agent installed and running. Amazon Linux 2, Amazon Linux 2023, and most AWS-provided AMIs include it by default. For custom AMIs, you install it manually.

Step 2 — The IAM Role: The EC2 instance profile must include the AmazonSSMManagedInstanceCore policy. Without this, SSM cannot communicate with the instance, and FIS cannot deliver the fault.

Step 3 — The SSM Document: AWS provides pre-built SSM Documents (automation scripts) specifically for chaos engineering, prefixed with AWSFIS-. These documents are maintained by AWS and use standard Linux tools:

• AWSFIS-Run-CPU-Stress uses stress-ng --cpu $(nproc) --timeout {duration} to saturate all CPU cores.
• AWSFIS-Run-Memory-Stress uses stress-ng --vm 1 --vm-bytes {percent}% to exhaust RAM.
• AWSFIS-Run-Network-Latency uses Linux tc (traffic control) to add configurable milliseconds of latency to outbound packets.
• AWSFIS-Run-Kill-Process uses pkill to terminate a named process.

Step 4 — The Execution: When you start the FIS experiment, FIS calls the SSM SendCommand API, targeting the selected instances with the chosen document and parameters. SSM delivers the command through its secure agent channel. The fault runs for the specified duration, then the document's cleanup logic reverses it (e.g., removes the tc rule, stops stress-ng).

The IAM Permission Chain

FIS experiments require an IAM Role for FIS (not your user role). This role needs:
- ssm:SendCommand permission on the target instances.
- ec2:DescribeInstances to resolve tag-based targets.
- Service-specific permissions for any AWS API actions (e.g., ec2:StopInstances, rds:RebootDBInstance).

The principle of least privilege applies here: scope the FIS role's permissions to only the resources and actions your experiments actually need. A FIS role with ec2:TerminateInstances on * is a significant blast radius risk.