Rundeck Docs

# AWS Systems Manager (SSM) Node Executor Plugins (Enterprise)

Available in PagerDuty Process Automation products

# Description

The Node Executor and File Copier plugins use AWS's Systems Manager (opens new window) (previously named "SSM") to send commands, files and scripts to remote nodes. Specifically, they make use of System Manager's Run Command (opens new window).

From AWS's Documentation: Using Run Command, a capability of AWS Systems Manager, you can remotely and securely manage the configuration of your managed nodes. A managed node is any Amazon Elastic Compute Cloud (Amazon EC2) instance, edge device, or on-premises server or virtual machine (VM) in your hybrid environment that has been configured for Systems Manager.

This means that Rundeck does not need direct connectivity to the remote infrastructure. Rather, Rundeck sends commands to AWS Systems Manager, and Systems Manager dispatches the commands to remote nodes via the Systems Manager agents.

The File Copier plugin uses Systems Manager and S3 to copy files to remote nodes as well as run scripts on remote nodes.

# Configuration and Credential Settings

# Systems Manager Configuration

Tip

The fastest way to set up and use Systems Manager for remote commands is through the Quick Setup Host Management (opens new window) from AWS.

Before configuring these plugins, be sure that you have completed the prerequisites outlined in the Setting up AWS Systems Manager for EC2 instances (opens new window) documentation. The three key steps here are:

  1. Ensure the SSM Agent is running on remote nodes.

  2. Set up AWS IAM Roles for the target nodes and for Rundeck. If Rundeck is running on an EC2, then this can be an IAM Role that is applied to Rundeck's EC2. Otherwise, these permissions will need to be associated with an Access Key and Secret Key credential pair.

  3. Ensure that the remote nodes are added as Managed Nodes in Systems Manager. The fastest way to get started with Managed Nodes is using the Quick Setup Host Management (opens new window).

  4. You can test that you have configured Systems Manager correctly by manually using the Run Command (opens new window) feature from AWS:

    aws-ssm-test-run

    aws-ssm-test-script

# Node Executor

In order for SSM Node Executor to send commands to remote nodes, the following properties must be set on the nodes in Rundeck:

  1. instanceId - This is the EC2 instance-id from AWS. If using the AWS EC2 Node Source, then this property will be automatically applied.

  2. region - This is the AWS region where the EC2 resides. If using the AWS EC2 Resource Model plugin, then this property will be automatically applied. If you are not using the AWS EC2 Resource Model plugin, then you can add it using the Attribute Match node enhancer.

  3. AWS Access ID and Secret Key can be configured in a few ways:

    • If Rundeck is running on an EC2 and has an IAM Role applied with the correct permissions - such as the AmazonSSMAutomationRole, then the AWS credentials do not need to be added into Rundeck. Here (opens new window) is the AWS documentation on applying IAM roles to EC2.

    • As Node-attributes, these can be applied via the Mapping Params field in the EC2 Node Source plugin. The node-attributes are ssm-accessKeyId and ssm-secretKey (this is pointing to a path in Key Storage, so be sure to save your AWS Secret Key in Key Storage, not as a node-attribute). These can also be set at the project or framework levels (e.g. project.ssm-accessKeyId and project.ssm-secretKey):

      ec2-mapping-params
      Optionally Set AWS credentials in EC2 Node Source

    • The credentials can also be set via the Default Node Executor:

      default-node-executor
      Optionally Configure Credentials via Default Node Executor

  4. Optional Node Executor Settings:

    1. The log output from AWS Systems Manager's Run Command is truncated to 2500 characters. To see the full log-output for logs longer than 2500 characters, you can have SSM use a CloudWatch log bucket to retrieve the full log output.
      To set this up, add the following property in Rundeck as node-attributes: cloudwatch-log-group. This can also be set at the project and framework levels (e.g. project.cloudwatch-log-group) or in the Default Node Executor. You must also add the CloudWatchAgentServerPolicy IAM Policy to your Managed Instances (EC2's) in AWS. More detailed documentation on this can be found here (opens new window).

    2. In the event that log output takes a while to start appearing, it can be useful to delay when Rundeck attempts to retrieve the logs from SSM. Optionally add the log-retrieve-delay property as a node-attribute and set the value to be the number of seconds to wait before retrieving logs. This property can also be set at the project and framework levels (e.g. project.log-retrieve-delay) or via the Default Node Executor.

# File Copier

The SSM File Copier uses both Systems Manager's Run Command as well as S3. The plugin requires the following properties to be set:

  1. ssm-copier-accessKeyId and ssm-copier-secretKey. These can be set as Node Attributes or at the project or framework levels (e.g. project.ssm-copier-accessKeyId and project.ssm-copier-secretKey). They can also be set in the Default File Copier (for a given project). They do not need to be set if an IAM Policy has been added to the EC2 that Rundeck is running on. The permissions associated with these credentials (or IAM Role) must include policies to run commands on remote nodes using SSM and to read and write to a specified S3 bucket.

  2. ssm-copier-bucket is the S3 bucket that will be used to copy the file from Rundeck to the remote nodes. This can be set as a Node Attribute, in the Default File Copier, or at the project or framework levels (e.g. project.ssm-copier-bucket).

# See it in Action

This plugin is used in one of the prebuilt Jobs in our Automated Diagnostics Solution. Try out the Solution to see how this plugin can be used as part of incident-response workflows.

← Jobs →