SSM Agent for AWS FIS actions - AWS Fault Injection Simulator

SSM Agent for AWS FIS actions

AWS FIS supports custom fault types through the AWS Systems Manager SSM Agent and the AWS FIS action aws:ssm:send-command. Pre-configured Systems Manager SSM documents (SSM documents) that can be used to create common fault injection actions are available as public AWS documents that begin with the AWSFIS- prefix.

SSM Agent is Amazon software that can be installed and configured on Amazon EC2 instances, on-premises servers, or virtual machines (VMs). This makes it possible for Systems Manager to manage these resources. The agent processes requests from Systems Manager, and then runs them as specified in the request. You can include your own SSM document to inject custom faults, or reference one of the public Amazon-owned documents.

Requirements

For actions that require SSM Agent to run the action on the target, you must ensure the following:

Work with the AWS FIS SSM action type

An SSM document defines the actions that Systems Manager performs on your managed instances. Systems Manager includes a number of pre-configured documents, or you can create your own. For more information about creating your own SSM document, see Creating Systems Manager documents in the AWS Systems Manager User Guide. For more information about SSM documents in general, see AWS Systems Manager documents in the AWS Systems Manager User Guide.

AWS FIS provides pre-configured SSM documents as well. You can view the pre-configured SSM documents under Documents in the AWS Systems Manager console: https://console.aws.amazon.com/systems-manager/documents. You can also choose from a selection of pre-configured documents in the AWS FIS console. For more information, see Work with pre-configured AWS FIS SSM documents.

To use an SSM document in your AWS FIS experiments, you can use the aws:ssm:send-command action. This action fetches and runs the specified SSM document on your target instances.

When you use the aws:ssm:send-command action in your experiment template, you must specify additional parameters for the action, including the following:

  • documentArn – Required. The Amazon Resource Name (ARN) of the SSM document.

  • documentParameters – Conditional. Any parameters that are specific to the SSM document. Not all documents have required parameters. In the AWS CLI, you specify these parameters and their values as an escaped JSON string. In the AWS FIS console, you can use a JSON string without escaping.

  • documentVersion – Optional. The version of the SSM document to run.

You can view the information for an SSM document (including the parameters for the document) by using the Systems Manager console or the command line.

To view information about an SSM document using the console

  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Documents.

  3. Select the document, and choose the Details tab.

To view information about an SSM document using the command line

Use the SSM describe-document command.

Work with pre-configured AWS FIS SSM documents

You can work with pre-configured AWS FIS SSM documents.

Requirement

The pre-configured SSM documents provided by AWS FIS are supported only on Linux. On Windows, you can use the aws:ssm:send-command action to run your own SSM document.

Actions

When you create your experiment template, select one of the following actions to use the corresponding pre-configured SSM document.

AWSFIS-Run-CPU-Stress

Runs CPU stress on an instance using the stress-ng tool. Uses the AWSFIS-Run-CPU-Stress SSM document and the following document parameters:

  • DurationSeconds – Required. The duration of the CPU stress test, in seconds.

  • CPU – Optional. The number of CPU stressors to use. The default is 0, which uses all CPU stressors.

  • InstallDependencies – Optional. If set to true, Systems Manager installs the required dependencies on the target instances. The default is true.

The following is an example.

{"DurationSeconds":"60", "InstallDependencies":"True"}
AWSFIS-Run-Kill-Process

Stops the specified process in the instance, using the killall command. Uses the AWSFIS-Run-Kill-Process SSM document with the following document parameters:

  • ProcessName – Required. The name of the process to stop.

  • Signal – Optional. The signal to send along with the command. The possible values are SIGTERM (which the receiver can choose to ignore) and SIGKILL (which cannot be ignored). The default is SIGTERM.

The following is an example.

{"ProcessName":"myapplication","Signal":"SIGTERM"}
AWSFIS-Run-Memory-Stress

Runs memory stress on an instance using the stress-ng tool. Uses the AWSFIS-Run-Memory-Stress SSM document with the following document parameters:

  • DurationSeconds – Required. The duration of the memory stress test, in seconds.

  • Workers – Optional. The number of virtual memory stressors. The default is 1.

  • Percent – Required. The percentage of virtual memory to use.

  • InstallDependencies – Optional. If set to true, Systems Manager installs the required dependencies on the target instances. The default is true.

The following is an example.

{"Percent": "80", "DurationSeconds":"60", "InstallDependencies":"True"}
AWSFIS-Run-Network-Latency

Adds latency on the network interface. Uses the AWSFIS-Run-Network-Latency SSM document with the following document parameters:

  • Interface – Optional. The interface to delay. The default is eth0.

  • DelayMilliseconds – Optional. The delay to add to the interface, in milliseconds. The default is 200.

  • DurationSeconds – Required. The duration of the network latency test, in seconds.

  • InstallDependencies – Optional. If set to true, Systems Manager installs the required dependencies on the target instances. The default is true.

The following is an example.

{"DelayMilliseconds": "200", "Interface": "eth0", "DurationSeconds":"60", "InstallDependencies":"True"}