AWS Systems Manager (SSM) Automation Documents

SSM Automation Documents, a core feature of AWS Systems Manager, are used to execute predefined management and remediation actions on your AWS resources.

Execution

These documents are provisioned to your accounts from the Wiv account and are designed to be executed directly by you through the AWS Console.

Integrated Steps

The workflow system currently integrates the following steps from the SSM automation documents:

Usage GuideStep 1: Integrating the Step into Your Workflow

1. In the workflow editor, use the search bar to look up "ssm".

2. Identify and select the SSM automation step that corresponds to the specific action you wish to perform.

Drag and drop the chosen step directly into your workflow canvas.

Step 2: Configuring Parameters

Each automation step necessitates specific parameters, which are grouped as follows:

 Common Parameters: These parameters apply universally across all steps.

Parameters specific to certain automation actions:

Optional Parameters

Executing the Workflow

Step 3: Run the Workflow

1. Save the workflow configuration.

2. Execute the workflow.

3. The execution will perform the following actions and checks:

   • Verify the SSM document exists in the Wiv account.

   • Share the document with the customer account (if sharing is configured).

   • Generate a unique execution link.

Step 4: Manual Execution (AWS Console)

Once the workflow step successfully completes, an execution link will be provided within the step.output. This link facilitates manual execution:

1. Click the execution link, which will open in a new browser tab.

2. You will be automatically redirected to the AWS Systems Manager Console with the necessary document pre-configured.

3. Review the pre-filled parameters.

4. Click Execute to start the automation.

5. Monitor the ongoing execution directly within the AWS Console.

Workflow Step Output Details

Each completed step provides the following output information:

• execution_link: A direct, clickable hyperlink to the AWS Console, ready for document execution.

• execution_cli: (Used in multi-account/region scenarios) The AWS CLI command required to execute the document across specified accounts and regions.

• note: Informational instructions detailing the use of the provided execution link.

Document Sharing & Access

• SSM documents originate from the Wiv account and are automatically shared with the customer's account.

• This sharing is a prerequisite for execution within the customer account.

• The sharing process automatically occurs when the corresponding workflow step runs.

Execution Process (Manual Action Required)

• Crucially, the workflow step does NOT automatically execute the SSM document.

• The step completes by sharing the document and generating an execution link.

• You must manually click the execution link and execute the document within the AWS Console.

• This manual step is required to allow for review and approval before any remediation actions are performed.

AWS Systems Manager (SSM) Integration: Workflow Step Overview

This section details the requirements and functionality for integrating with AWS Systems Manager using a dedicated workflow step. Key areas covered include necessary IAM permissions, proper error handling, and common examples of use.

IAM Permissions Setup

To ensure successful execution of SSM automation documents, the customer's AWS account must satisfy the following IAM permissions requirements:

1. Automation Execution Role: A specific IAM role must exist with the name defined in "Automation Execution Role Name" (default: AWS-SystemsManager-AutomationExecutionRole).

2. Trust Policy: This role's trust policy must explicitly allow the SSM Automation service to assume it.

3. Action Permissions: The role must possess the necessary permissions to perform the intended action (e.g., ec2:DeleteVolume, ec2:StopInstances).

Error Handling

The workflow's execution behavior upon failure is determined by the "Continue Workflow On Error" setting. If enabled, the workflow will proceed even if a step fails.

Common failure points include:

• The required SSM document is not found in the Wiv account.

• Mandatory parameters are missing.

• Document sharing between accounts fails.

• Provided resource IDs are invalid.

ExamplesExample 1: Deleting an EBS Volume

This example demonstrates how to use the "SSM Delete EBS Volume" step:

1. Add the "SSM Delete EBS Volume" step to your workflow.

2. Configure the parameters:

   • Integrations: Select your AWS connection.

   • Volume ID: Specify the target volume, e.g., vol-0123456789abcdef0.

   • Region: Enter the AWS region, e.g., us-east-1.

3. Run the workflow.

4. Use the execution link provided in the step output to review the command execution details, including parameters.

5. Finalize and execute the operation in the AWS Console.

Example 2: Stopping Multiple EC2 Instances

This example illustrates the use of the "SSM Stop EC2 Instances" step:

1. Add the "SSM Stop EC2 Instances" step to your workflow.

2. Configure the parameters:

   • Integrations: Select your AWS connection.

   • Instance IDs: List the instances as a comma-separated string, e.g., i-0123456789abcdef0, i-0987654321fedcba0.

   • Region: Enter the AWS region, e.g., us-west-2.

3. Run the workflow.

4. Use the execution link in the step output to review the details.

5. Finalize and execute the operation in the AWS Console.