Monitoring Systems Manager status changes using Amazon SNS notifications
Note
Amazon Simple Notification Service FIFO topics aren't supported.
You can configure Amazon Simple Notification Service (Amazon SNS) to send notifications about the status of commands that you send using Run Command or Maintenance Windows, which are capabilities of Amazon Systems Manager. 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 nodes, you can receive a notification for each copy of the command sent to a specific node. 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 Amazon Systems Manager.
Configure Amazon SNS notifications for Amazon Systems Manager
Run Command and Maintenance Windows tasks that are registered to a maintenance window can send Amazon SNS notifications for command tasks that enter the following statuses:
-
In Progress
-
Success
-
Failed
-
Timed Out
-
Canceled
For information about the conditions that cause a command to enter one of these statuses, see Understanding command statuses.
Note
Commands sent using Run Command also report Canceling and Pending status. These statuses aren't 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 initiated. The timestamp is important because Amazon SNS doesn't 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 hasn't already started executing, it won't 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 node. |
instanceIds |
StringList |
The nodes that were targeted by the command. NoteInstance IDs are only included in the summary message if the Run Command task targeted instance IDs directly. Instance IDs aren't 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 nodes, 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 initiated. The timestamp is important because Amazon SNS doesn't guarantee message delivery order. Example: 2016-04-26T13:15:30Z |
documentName |
String |
The name of the Systems Manager document (SSM document) used to run this command. |
requestedDateTime |
String |
The time and date that the request was sent to this specific node. |
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, complete the following tasks.
Note
If you aren't configuring Amazon SNS notifications for your maintenance window, then you can skip Task 5 later in this topic.
Topics
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 Amazon Web Services services like Amazon Simple Queue Service (Amazon SQS). To get started, we recommend that you start with the email protocol. For information about how to create a topic, see Creating an Amazon SNS 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 Subscribing to an Amazon SNS topic in the Amazon Simple Notification Service Developer Guide.
Amazon SNS sends a confirmation email from Amazon Notifications to the email address that you specify. Open the email and choose the Confirm subscription link.
You will receive an acknowledgement message from Amazon. 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 Amazon Identity and Access Management (IAM) policy that provides permissions for inititating Amazon SNS notifications.
To create a custom IAM policy for Amazon SNS notifications
Open the IAM console at https://console.amazonaws.cn/iam/
. -
In the navigation pane, choose Policies, and then choose Create Policy. (If a Get Started button is shown, choose it, and then choose Create Policy.)
-
Choose the JSON tab.
-
Replace the default content with the following.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish" ], "Resource": "
arn:aws-cn:sns:
" } ] }region
:account-id
:sns-topic-name
region
represents the identifier for an Amazon Web Services Region supported by Amazon Systems Manager, such asus-east-2
for the US East (Ohio) Region. For a list of supportedregion
values, see the Region column in Systems Manager service endpoints in the Amazon Web Services General Reference.
represents the 12-digit identifier for your Amazon Web Services account, in the formataccount-id
123456789012
.sns-topic-name
represents the name of the Amazon SNS topic you want to use for publishing notifications. -
Choose Next: Tags.
-
(Optional) Add one or more tag-key value pairs to organize, track, or control access for this policy.
-
Choose Next: Review.
-
On the Review policy page, for Name, enter a name for the inline policy. For example:
my-sns-publish-permissions
. -
(Optional) For Description, enter a description for the policy.
-
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 initiate Amazon SNS notifications. In all subsequent procedures, this role is referred to as the Amazon SNS IAM role.
To create an IAM service role for Amazon SNS notifications
Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/
. -
In the navigation pane of the IAM console, choose Roles, and then choose Create role.
-
Choose the Amazon Web Services service role type, and then choose Systems Manager.
-
Choose the Systems Manager use case. Then, choose Next.
-
On the Attach permissions policies page, select the box to the left of the name of the custom policy you created in Task 2. For example:
my-sns-publish-permissions
. -
(Optional) Set a permissions boundary. This is an advanced feature that is available for service roles, but not service-linked roles.
Expand the Permissions boundary section and choose Use a permissions boundary to control the maximum role permissions. IAM includes a list of the Amazon managed and customer managed policies in your account. Select the policy to use for the permissions boundary or choose Create policy to open a new browser tab and create a new policy from scratch. For more information, see Creating IAM policies in the IAM User Guide. After you create the policy, close that tab and return to your original tab to select the policy to use for the permissions boundary.
-
Choose Next.
-
If possible, enter a role name or role name suffix to help you identify the purpose of this role. Role names must be unique within your Amazon Web Services account. They are not distinguished by case. For example, you cannot create roles named both
PRODROLE
andprodrole
. Because various entities might reference the role, you cannot edit the name of the role after it has been created. -
(Optional) For Description, enter a description for the new role.
-
Choose Edit in the Step 1: Select trusted entities or Step 2: Select permissions sections to edit the use cases and permissions for the role.
-
(Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM resources in the IAM User Guide.
-
Review the role and then choose Create role.
-
Choose the name of the role, and then copy or make a note of the Role ARN value. This Amazon Resource Name (ARN) for the role is used when you send a command that is configured to return Amazon SNS notifications.
-
Keep the Summary page open.
Task 4: Configure user access
If an IAM entity (user, role, or group) is assigned administrator permissions, then the user or role has access to Run Command and Maintenance Windows, capabilities of Amazon Systems Manager.
For entities without administrator permissions, an administrator must grant the following permissions to the IAM entity:
-
The
AmazonSSMFullAccess
managed policy, or a policy that provides comparable permissions. -
iam:PassRole
permissions for the role created in Task 3: Create an IAM role for Amazon SNS notifications. For example:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws-cn:iam::
account-id
:role/sns-role-name
" } ] }
To provide access, add permissions to your users, groups, or roles:
-
Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in Create a role for a third-party identity provider (federation) in the IAM User Guide.
-
IAM users:
-
Create a role that your user can assume. Follow the instructions in Create a role for an IAM user in the IAM User Guide.
-
(Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in Adding permissions to a user (console) in the IAM User Guide.
-
To configure user access and attach the iam:PassRole
policy
to a user account
-
In the IAM navigation pane, choose Users, and then choose the user account that you want to configure.
-
On the Permissions tab, in the policies list, verify that either the
AmazonSSMFullAccess
policy is listed or that there is a comparable policy that gives the account permissions to access Systems Manager. -
Choose Add inline policy.
-
On the Create policy page, choose the Visual editor tab.
-
Choose Choose a service, and then choose IAM.
-
For Actions, in the Filter actions text box, enter
PassRole
, and then select the check box next to PassRole. -
For Resources, verify that Specific is selected, and then choose Add ARN.
-
In the Specify ARN for role field, paste the Amazon SNS IAM role ARN that you copied at the end of Task 3. The system automatically populates the Account and Role name with path fields.
-
Choose Add.
-
Choose Review policy.
-
On the Review Policy page, enter 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, attach an iam:PassRole
policy to
the maintenance window service role specified. If you don't intend to configure
the registered task for Amazon SNS notifications, then you can skip this task.
The iam:PassRole
policy allows the Maintenance Windows service role to pass
the Amazon SNS IAM 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
Use a custom service role for your maintenance window to send notifications related to the Run Command tasks registered. For information, see Setting up Maintenance Windows.
If you need to create a custom service role for maintenance window tasks, see Setting up Maintenance Windows.
To attach the iam:PassRole
policy to your Maintenance Windows
role
-
Open the IAM console at https://console.amazonaws.cn/iam/
. -
In the navigation pane, choose Roles and select the Amazon SNS IAM role created in Task 3.
-
Copy or make a note of the Role ARN and return to the Roles section of the IAM console.
-
Select the custom Maintenance Windows service role you created from the Role name list.
-
On the Permissions tab, verify that either the
AmazonSSMMaintenanceWindowRole
policy is listed or there is a comparable policy that gives maintenance windows permission to the Systems Manager API. If it is not, choose Add permissions, Attach policies to attach it. -
Choose Add permissions, Create inline policy.
-
Choose the Visual editor tab.
-
For Service, choose IAM.
-
For Actions, in the Filter actions text box, enter
PassRole
, and then select the check box next to PassRole. -
For Resources, choose Specific, and then choose Add ARN.
-
In the Specify ARN for role box, paste the ARN of the Amazon SNS IAM role created in Task 3, and then choose Add.
-
Choose Review policy.
-
On the Review policy page, specify a name for the
PassRole
policy, and then choose Create policy.