• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html). # Monitoring Systems Manager status changes using Amazon SNS notifications 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 tools in AWS 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](https://docs.aws.amazon.com/sns/latest/dg/) 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](monitoring-sns-examples.md). **Important** Note the following important information. Amazon Simple Notification Service FIFO topics aren't supported. Amazon Q Developer in chat applications isn't supported for monitoring Systems Manager with Amazon SNS. If you wish to use Amazon Q Developer in chat applications to monitor Systems Manager, you must use it with Amazon EventBridge. For information about monitoring Systems Manager using EventBridge, see [Monitoring Systems Manager events with Amazon EventBridge](monitoring-eventbridge-events.md). For information about Amazon EventBridge and Amazon Q Developer in chat applications, see [Tutorial: Creating an EventBridge rule that sends notifications to Amazon Q Developer in chat applications](https://docs.aws.amazon.com/chatbot/latest/adminguide/create-eventbridge-rule.html) in the *Amazon Q Developer in chat applications Administrator Guide*. ## Configure Amazon SNS notifications for AWS 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 + Cancelled For information about the conditions that cause a command to enter one of these statuses, see [Understanding command statuses](monitor-commands.md). **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. Instance 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** + [Command summary Amazon SNS notifications](#monitoring-sns-configure-summary) + [Invocation-based Amazon SNS notifications](#monitoring-sns-configure-invocation) + [Task 1: Create and subscribe to an Amazon SNS topic](#monitoring-configure-sns) + [Task 2: Create an IAM policy for Amazon SNS notifications](#monitoring-iam-policy) + [Task 3: Create an IAM role for Amazon SNS notifications](#monitoring-iam-notifications) + [Task 4: Configure user access](#monitoring-sns-passpolicy) + [Task 5: Attach the iam:PassRole policy to your maintenance window role](#monitoring-sns-passpolicy-mw) ### 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 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](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) 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](https://docs.aws.amazon.com/sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html) 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 inititating 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/](https://console.aws.amazon.com/iam/). 1. 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**.) 1. Choose the **JSON** tab. 1. Replace the default content with one of the following, depending on whether the Amazon SNS topic uses AWS KMS encryption: ------ #### [ SNS topic not encrypted ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish" ], "Resource": "arn:aws:sns:us-east-1:111122223333:sns-topic-name" } ] } ``` ------ *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **account-id** represents the 12-digit identifier for your AWS account, in the format `123456789012`. *sns-topic-name* represents the name of the Amazon SNS topic you want to use for publishing notifications. ------ #### [ SNS topic encrypted ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish" ], "Resource": "arn:aws:sns:us-east-1:111122223333:sns-topic-name" }, { "Effect": "Allow", "Action": [ "kms:GenerateDataKey", "kms:Decrypt" ], "Resource": "arn:aws:kms:us-east-1:111122223333:key/kms-key-id" } ] } ``` ------ *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **account-id** represents the 12-digit identifier for your AWS account, in the format `123456789012`. *sns-topic-name* represents the name of the Amazon SNS topic you want to use for publishing notifications. *kms-key-id* represents the ID of the symmetric encryption KMS key in AWS KMS to use for encrypting and decrypting the topic, in the format `1234abcd-12ab-34cd-56ef-12345EXAMPLE`. **Note** There is a charge for using AWS KMS encryption. For more information, see [Managing Amazon SNS encryption keys and costs](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html) in the *AWS Key Management Service Developer Guide*. ------ 1. Choose **Next: Tags**. 1. (Optional) Add one or more tag-key value pairs to organize, track, or control access for this policy. 1. Choose **Next: Review**. 1. On the **Review policy** page, for **Name**, enter a name for the inline policy. For example: **my-sns-publish-permissions**. 1. (Optional) For **Description**, enter a description for the policy. 1. 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** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane of the IAM console, choose **Roles**, and then choose **Create role**. 1. Choose the **AWS service** role type, and then choose Systems Manager. 1. Choose the Systems Manager use case. Then, choose **Next**. 1. 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**. 1. (Optional) Set a [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html). 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 AWS 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) 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. 1. Choose **Next**. 1. 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 AWS account. They are not distinguished by case. For example, you cannot create roles named both **PRODROLE** and **prodrole**. Because various entities might reference the role, you cannot edit the name of the role after it has been created. 1. (Optional) For **Description**, enter a description for the new role. 1. 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. 1. (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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*. 1. Review the role and then choose **Create role**. 1. 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. 1. 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, tools in AWS 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](#monitoring-iam-notifications). For example: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::111122223333:role/sns-role-name", "Condition": { "StringEquals": { "iam:PassedToService": "ssm.amazonaws.com" } } } ] } ``` ------ To provide access, add permissions to your users, groups, or roles: + Users and groups in AWS IAM Identity Center: Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*. + 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)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) 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](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) 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)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*. **To configure user access and attach the `iam:PassRole` policy to a user account** 1. In the IAM navigation pane, choose **Users**, and then choose the user account that you want to configure. 1. 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. 1. Choose **Add inline policy**. 1. On the **Create policy** page, choose the **Visual editor** tab. 1. Choose **Choose a service**, and then choose ** IAM**. 1. For **Actions**, in the **Filter actions** text box, enter **PassRole**, and then select the check box next to **PassRole**. 1. For **Resources**, verify that **Specific** is selected, and then choose **Add ARN**. 1. 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. 1. Choose **Add**. 1. Choose **Review policy**. 1. 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](setting-up-maintenance-windows.md). If you need to create a custom service role for maintenance window tasks, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md). **To attach the`iam:PassRole` policy to your Maintenance Windows role** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles** and select the Amazon SNS IAM role created in Task 3. 1. Copy or make a note of the **Role ARN** and return to the **Roles** section of the IAM console. 1. Select the custom Maintenance Windows service role you created from the **Role name** list. 1. 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. 1. Choose **Add permissions, Create inline policy**. 1. Choose the **Visual editor** tab. 1. For **Service**, choose **IAM**. 1. For **Actions**, in the **Filter actions** text box, enter **PassRole**, and then select the check box next to **PassRole**. 1. For **Resources**, choose **Specific**, and then choose **Add ARN**. 1. In the **Specify ARN for role** box, paste the ARN of the Amazon SNS IAM role created in Task 3, and then choose **Add**. 1. Choose **Review policy**. 1. On the **Review policy** page, specify a name for the `PassRole` policy, and then choose **Create policy**.