Sign In to the Console
AWS Systems Manager
User Guide

AWS Documentation » AWS Systems Manager » User Guide » Monitoring AWS Systems Manager » Configuring Amazon SNS Notifications for AWS Systems Manager

Configuring Amazon SNS Notifications for AWS Systems Manager

You can configure Amazon Simple Notification Service (Amazon SNS) to send notifications about the status of commands that you send using AWS Systems Manager Run Command or AWS Systems Manager Maintenance Windows. Amazon SNS coordinates and manages sending and delivering notifications to clients or endpoints that are subscribed to Amazon SNS topics. You can receive a notification whenever a command changes to a new state or 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 plaintext 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 examples of the structure of the JSON data included in the Amazon SNS notification provided by Run Command and Maintenance Windows, see Example Amazon SNS Notifications for AWS Systems Manager.

Configure Amazon SNS Notifications for AWS Systems Manager

Run Command and Run Command tasks that are registered to a maintenance window can send Amazon SNS notifications for command tasks that enter the following statuses. For information about the conditions that cause a command to enter one of these statuses, see Understanding Command Statuses.

  • In Progress

  • Success

  • Failed

  • Timed Out

  • Canceled

Note

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

Command Summary Amazon SNS Notifications

If you configure Run Command or a Run Command task in your maintenance window for Amazon SNS notifications, Amazon SNS sends summary messages that include the following information.

Field Type Description

eventTime

String

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

documentName

String

The name of the SSM document used to run 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 run.

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 that the request was sent to this specific instance.

instanceIds

StringList

The instances that were targeted by the command.

Note

Instance IDs are only included in the summary message if the Run Command task targeted instance IDs directly. Instance IDs are not included in the summary message if the Run Command task was issued using tag-based targeting.

status

String

Command status for the command.

Invocation-based Amazon SNS Notifications

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

Field Type Description

eventTime

String

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

documentName

String

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

requestedDateTime

String

The time and date that 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 that was targeted by the command.

status

String

Command status for this invocation.

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

Note

If you are not configuring Amazon SNS notifications for your maintenance window, then you can skip Task 5 below.

Task 1: Create and Subscribe to an Amazon SNS Topic

An Amazon SNS topic is a communication channel that Run Command and Run Command tasks that are registered to a maintenance window use to send notifications about the status of your commands. Amazon SNS supports different communication protocols, including HTTP/S, email, and other AWS services like Amazon SQS. To get started quickly, we recommend that you start with the email protocol. For information about how to create a topic, 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 specify this ARN when you send a command that is configured to return status notifications.

After you create the topic, subscribe to it by specifying an Endpoint. If you chose the Email protocol, the endpoint is the email address where you want to receive notifications. For more information about how to subscribe to a topic, see Subscribe to a Topic in the Amazon Simple Notification Service Developer Guide.

Amazon SNS sends a confirmation email from AWS Notifications to the email address that you specify. Open the email and choose the Confirm subscription link.

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.

Task 2: Create an IAM Policy for Amazon SNS Notifications

Use the following procedure to create a custom AWS Identity and Access Management (IAM) policy that provides permissions for triggering Amazon SNS notifications.

To create a custom IAM policy for Amazon SNS notifications

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

  2. In the navigation pane, choose Policies, and then choose Create policy. (If a Get Started button appears, choose it, and then choose Create Policy.)

  3. Choose the JSON tab.

  4. Replace the default content with the following:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sns:Publish"
            ],
            "Resource": "*"
        }
    ]
}

  5. Choose Review policy.

  6. On the Review policy page, for Name, enter a name for the inline policy. For example: SNSPublishPermissions.

  7. (Optional) For Description, enter a description for the policy.

  8. Choose Create policy.

Task 3: Create an IAM Role for Amazon SNS Notifications

Use the following procedure to create an IAM role for Amazon SNS notifications. This service role is used by Systems Manager to trigger Amazon SNS notifications.

To create an IAM service role for Amazon SNS notifications

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

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

  3. On the Select type of trusted entity page, under AWS Service, choose EC2.

  4. In the Select your use case section, choose EC2, and then choose Next: Permissions.

  5. On the Attach permissions policies page, select the check box to the left of the name of the custom policy you created in Task 2. For example: SNSPublishPermissions.

  6. On the Review page, type a name in the Role name box, and then type a description.

  7. Choose Create role. The system returns you to the Roles page.

  8. On the Roles page, choose the role you just created to open the Summary page.

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

  10. Add , "ssm.amazonaws.com" to the existing policy, as shown in the following code snippet: 

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

    Note

    You must add a comma after the existing entry. In the preceding example, the entry is "ec2.amazonaws.com". Otherwise, the JSON is invalid.

  11. Choose Update Trust Policy.

  12. Copy or make a note of the Role ARN. This Role ARN is used when you send a command that is configured to return Amazon SNS notifications.

  13. Leave the Summary page open.

Task 4: Attach the iam:PassRole Policy to Your Amazon SNS Role

Use the following procedure to attach the iam:PassRole policy to the Amazon SNS service role that you created in Task 3.

To attach the iam:PassRole policy to your Amazon SNS role

  1. In the Summary page for the role you created in Task 3, choose the Permissions tab.

  2. Choose Add inline policy.

  3. On the Create policy page, choose the Visual editor tab.

  4. Choose Service, and then choose IAM.

  5. Choose Select actions.

  6. In the Filter actions text box, type PassRole, and then choose the PassRole option.

  7. Choose Resources. Verify that Specific is selected, and then choose Add ARN.

  8. In the Specify ARN for role field, paste the Amazon SNS role ARN that you copied at the end of Task 2. The system automatically populates the Account and Role name with path fields.

  9. Choose Add.

  10. Choose Review policy.

  11. On the Review Policy page, type a name and then choose Create Policy.

Task 5: Attach the iam:PassRole Policy to Your Maintenance Window Role

When you register a Run Command task with a maintenance window, you specify a service role Amazon Resource Name (ARN). This service role is used by Systems Manager to run tasks registered to the maintenance window. To configure Amazon SNS notifications for a registered Run Command task, you must attach an iam:PassRole policy to the maintenance window service role specified. If you do not intend to configure the registered task for Amazon SNS notifications, then this task can be skipped.

The iam:PassRole policy allows the Maintenance Windows service role to pass the SNS role created in Task 3 to the Amazon SNS service. The following procedure shows how to attach the iam:PassRole policy to the Maintenance Windows service role.

Note

You must use a custom service role for your maintenance window to send notifications related to the Run Command tasks registered. For information, see Should I Use a Service-Linked Role or a Custom Service Role to Run Maintenance Window Tasks?.

If you need to create a custom service role, see one of the following topics:

To attach the iam:PassRole policy to your Maintenance Windows Role

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

  2. In the navigation pane, choose Roles and select the Amazon SNS role created in Task 3.

  3. Copy or make a note of the Role ARN and return to the Roles section of the IAM console.

  4. Select the custom Maintenance Windows service role you created (under Role name).

  5. Under Permissions, verify that either the AmazonSSMMaintenanceWindowRole policy is listed or there is a comparable policy that gives maintenance windows permission to the Systems Manager API.

  6. Choose Add inline policy.

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

  8. Verify that Effect is set to Allow.

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

  10. From Actions choose PassRole.

  11. In the Amazon Resource Name (ARN) field, paste the ARN of the Amazon SNS IAM role created in Task 3.

  12. Choose Add Statement, and then choose Next.

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