Menu
Amazon EC2 Systems Manager
User Guide

Configuring Amazon SNS Notifications for Run Command

You can configure Amazon Simple Notification Service (Amazon SNS) to send notifications about the status of commands you send using Systems Manager Run Command. Amazon SNS coordinates and manages the delivery or sending of notifications to subscribing clients or endpoints. You can receive a notification whenever a command changes to a new state or changes to a specific state, such as failed or timed out. In cases where you send a command to multiple instances, you can receive a notification for each copy of the command sent to a specific instance. Each copy is called an invocation.

Amazon SNS can deliver notifications as HTTP or HTTPS POST, email (SMTP, either plain-text or in JSON format), or as a message posted to an Amazon Simple Queue Service (Amazon SQS) queue. For more information, see What Is Amazon SNS in the Amazon Simple Notification Service Developer Guide.

For example, if you configure Amazon SNS to send a notification when a command status changes to failed, SNS sends an email notification with the details of the command execution.

Note

If you prefer, you can use Amazon CloudWatch Events to configure a target to invoke an AWS Lambda function when a command changes status. For more information, see Configuring CloudWatch Events for Run Command.

To set up Amazon SNS notifications when a command changes status, you must complete the following tasks.

Configure Amazon SNS Notifications for Systems Manager

Run Command supports sending Amazon SNS notifications for commands that enter the following statuses. For information about the conditions that cause a command to enter one of these statuses, see Setting Up Events and Notifications.

  • In Progress

  • Success

  • Failed

  • Timed Out

  • Canceled

Note

Commands sent using Run Command also report Cancelling and Pending status. These statuses are not captured by SNS notifications.

If you configure Run Command for SNS notifications, SNS sends summary messages that include the following information:

Field Type Description

EventTime

String

The time the event was triggered. The time stamp is important because SNS does not guarantee message delivery order. Example: 2016-04-26T13:15:30Z

DocumentName

String

The name of the SSM document used to execute this command.

CommandId

String

The ID generated by Run Command after the command was sent.

ExpiresAfter

Date

If this time is reached and the command has not already started executing, it will not execute.

OutputS3BucketName

String

The Amazon Simple Storage Service (Amazon S3) bucket where the responses to the command execution should be stored.

OutputS3KeyPrefix

String

The Amazon S3 directory path inside the bucket where the responses to the command execution should be stored.

RequestedDateTime

String

The time and date the request was sent to this specific instance.

InstanceId

String

The instance targeted by the command.

Status

String

Command status for the command.

If you send a command to multiple instances, Amazon SNS can send messages about each copy or invocation of the command that include the following information:

Field Type Description

EventTime

String

The time the event was triggered. The time stamp is important because SNS does not guarantee message delivery order. Example: 2016-04-26T13:15:30Z

DocumentName

String

The name of the Systems Manager document used to execute this command.

RequestedDateTime

String

The time and date the request was sent to this specific instance.

CommandId

String

The ID generated by Run Command after the command was sent.

InstanceId

String

The instance targeted by the command.

Status

String

Command status for this invocation.

Configure Account Permissions

When you send a command that is configured for notifications, you specify a service role Amazon Resource Name (ARN). For example: --service-role-arn=arn:aws:iam::123456789012:myrole. This service role is used by Systems Manager to trigger SNS notifications.

To receive notifications from the Amazon SNS service, you must either attach the iam:PassRole policy to your existing AWS Identity and Access Management (IAM) user account, or create a new IAM account and attach this policy to it. If you create a new account, you must also attach the AmazonSSMFullAccess policy so the account can communicate with the Systems Manager API.

Use the following procedure to attach an IAM policy to your user account. If you need to create a new user account, see Creating an IAM User in Your AWS Account in the IAM User Guide.

To attach the iam:PassRole policy to your user account

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Users and select the user (under User name).

  3. At the top of the page, copy your User ARN to the clipboard.

  4. Under Permissions, verify that either the AmazonSSMFullAccess policy is listed or there is a comparable policy that gives you permission to the Systems Manager API.

  5. Choose Add inline policy.

  6. On the Set Permissions page, choose Policy Generator, and then choose Select.

  7. Verify that Effect is set to Allow.

  8. From AWS Services choose AWS Identity and Access Management.

  9. From Actions choose PassRole.

  10. In the Amazon Resource Name (ARN) field, paste your ARN.

  11. Choose Add Statement, and then choose Next.

  12. On the Review Policy page, choose Apply Policy.

Create an IAM Role for Notifications

In the previous procedure, you added an IAM policy to your user account so that you could send commands that return notifications. In the following procedure, you will create a role so that the Systems Manager service can act on your behalf when sending notifications.

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles, and then choose Create New Role.

  3. In Step 1: Set Role Name enter a name that identifies this role as a Run Command role for notifications.

  4. In Step 2: Select Role Type choose Amazon EC2. The system skips Step 3: Establish Trust because this is a managed policy.

  5. In Step 4: Attach Policy choose AmazonSNSFullAccess.

  6. Choose Next Step and then choose Create Role. The system returns you to the Roles page.

  7. Locate the role you just created and double-click it.

  8. Choose the Trust Relationships tab, and then choose Edit Trust Relationship.

  9. Add "ssm.amazonaws.com" to the existing policy as the following code snippet illustrates:

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com", "Service": "ssm.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

    Note

    You must add a comma after the existing entry. "Service": "sns.amazonaws.com", or the JSON will not validate.

  10. Choose Update Trust Policy.

  11. Copy or make a note of the Role ARN. You will specify this ARN when you send a command that is configured to return notifications.

Configure Amazon SNS

To use Amazon SNS to send email notifications, you must first create a topic and then subscribe your email addresses to the topic.

Create an Amazon SNS Topic

An Amazon SNS topic is a logical access point, a communication channel that Run Command uses to send the notifications. You create a topic by specifying a name for your topic.

For more information, see Create a Topic in the Amazon Simple Notification Service Developer Guide.

Note

After you create the topic, copy or make a note of the Topic ARN. You will specify this ARN when you send a command that is configured to return status notifications.

Subscribe to the Amazon SNS Topic

To receive the notifications that Run Command sends to the topic, you must subscribe an endpoint to the topic. In this procedure, for Endpoint, specify the email address where you want to receive the notifications from Run Command.

For more information, see Subscribe to a Topic in the Amazon Simple Notification Service Developer Guide.

Confirm Your Amazon SNS Subscription

Amazon SNS sends a confirmation email to the email address that you specified in the previous step.

Make sure you open the email from AWS Notifications and choose the link to confirm the subscription before you continue with the next step.

You will receive an acknowledgement message from AWS. Amazon SNS is now configured to receive notifications and send the notification as an email to the email address that you specified.

Send a Command that Returns Status Notifications

This section shows you how to send a command that is configured to return status notifications using either the Amazon EC2 console or the AWS Command Line Interface (AWS CLI).

To send a command from the Amazon EC2 console that returns notifications

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Run Command.

  3. Choose Run a command.

  4. For Command document, choose a Systems Manager document.

  5. For Target instances, choose the instances where you want the command to run. If you do not see an instance in this list, it might not be configured properly for Run Command. For more information, see Systems Manager Prerequisites.

  6. Enter information in the fields required by the Systems Manager document. In the SNS Notifications section, choose Enable SNS notifications.

  7. In the Role field, type or paste the IAM role ARN you created earlier.

  8. In the SNS Topic field, type or paste the Amazon SNS ARN you created earlier.

  9. In the Notify me on field, choose the events for which you want to receive notifications.

  10. In the Notify me for field, choose to receive notifications for each copy of a command sent to multiple instances (invocations) or the command summary.

  11. Choose Run.

  12. Check your email for a message from Amazon SNS and open the email. Amazon SNS can take a few minutes to send the mail.

To send a command that is configured for notifications from the AWS CLI

  1. Open the AWS CLI.

  2. Specify parameters in the following command.

    Copy
    aws ssm send-command --instance-ids "ID-1, ID-2" --document-name "name" --parameters commands=date --service-role ServiceRole ARN --notification-config NotificationArn=SNS ARN

    For example

    Copy
    aws ssm send-command --instance-ids "i-12345678, i-34567890" --document-name "AWS-RunPowerShellScript" --parameters commands=date --service-role arn:aws-cn:iam:: 123456789012:myrole --notification-config NotificationArn=arn:aws-cn:sns:cn-north-1:123456789012:test
  3. Press Enter.

  4. Check your email for a message from Amazon SNS and open the email. Amazon SNS can take a few minutes to send the mail.

For more information about configuring Run Command from the command line, see Amazon EC2 Systems Manager API Reference and the Systems Manager AWS CLI Reference.