About AWS Regions for AWS Health About public events for AWS Health Event processor for AWS Health Creating an EventBridge rule for AWS Health Receiving AWS Health events with AWS Chatbot Automating actions for Amazon EC2 instances

Monitoring AWS Health events with Amazon EventBridge

You can use Amazon EventBridge to detect and react to AWS Health events. Then, based on rules that you create, EventBridge invokes one or more target actions when an event matches the values that you specify in a rule. Depending on the type of event, you can capture event information, initiate additional events, send notifications, take corrective action, or perform other actions. For example, you can use AWS Health to receive email notifications if you have AWS resources in your AWS account that are scheduled for updates, such as Amazon Elastic Compute Cloud (Amazon EC2) instances.

Notes

AWS Health delivers events on a best effort basis. Events are not always guaranteed to be delivered to EventBridge.
Any EventBridge rules which you create can only receive notifications for your AWS account. You can't receive organizational events for other accounts within your AWS Organizations. For more information, see Aggregating AWS Health events across accounts with organizational view.

You can choose between multiple target types for EventBridge as part of your AWS Health workflow, including:

AWS Lambda functions
Amazon Kinesis Data Streams
Amazon Simple Queue Service (Amazon SQS) queues
Built-in targets (such as CloudWatch alarm actions)
Amazon Simple Notification Service (Amazon SNS) topics

For example, you can use a Lambda function to pass a notification to a Slack channel when an AWS Health event occurs. Or, you can use Lambda and EventBridge to send custom text or SMS notifications with Amazon SNS when an AWS Health event occurs.

For samples of automation and customized alerts that you can create in response to AWS Health events, see the AWS Health Tools in GitHub.

Topics

About AWS Regions for AWS Health
About public events for AWS Health
Event processor for AWS Health
Creating an EventBridge rule for AWS Health
Receiving AWS Health events with AWS Chatbot
Automating actions for Amazon EC2 instances

About AWS Regions for AWS Health

You must create an EventBridge rule for each Region for which you want to receive AWS Health events. If you don’t create a rule, you won’t receive events. For example, to receive events from the US West (Oregon) Region, you must create a rule for this Region.

Some AWS Health events are not Region-specific. Events that aren't specific to a Region are called global events., These include events sent for AWS Identity and Access Management (IAM). To receive global events, you must create a rule for the US East (N. Virginia) Region.

To receive global events in the AWS GovCloud (US), you must create a rule in the AWS GovCloud (US-West) Region.

About public events for AWS Health

Only AWS Health events that are specific to your account are delivered to EventBridge. This can include events such as a required update to an Amazon EC2 instance or other scheduled change events that might affect your account and resources.

Currently, you can't use EventBridge to return public events from the Service Health Dashboard. Events from the Service Health Dashboard provide public information about the Regional availability of a service. These events aren't specific to AWS accounts, so they aren't delivered to EventBridge.

Instead, you can use the AWS Health console and the DescribeEventDetails operation. You can use either option to return information about an event, and then identify if it's a public event from the Service Health Dashboard or an event specific to you AWS account.

You can use the following options to identify if an event is public or account-specific:

In the AWS Health Dashboard, choose the Affected resources tab for an event. Events with resources are specific to your account. Events without resources are public and are not specific to your account. For more information, see Getting started with your AWS Health Dashboard – Your account health.
Use the AWS Health API to return the eventScopeCode parameter. Events can have the PUBLIC, ACCOUNT_SPECIFIC, or NONE value. For more information, see the DescribeEventDetails operation in the AWS Health API Reference.

You can also use the AWS Health Service Health Dashboard notifier tool to get notified for public events. For more information, see the aws-health-tools on the GitHub website.

Event processor for AWS Health

If you use AWS Incident Detection and Response for your account, you can create the AWSServiceRoleForHealth_EventProcessor service-linked role.

This role trusts the event-processor.health.amazonaws.com service principal to assume the role. Attached to this role is the AWSHealth_EventProcessorServiceRolePolicy AWS managed policy. This policy lists the permissions that the role can perform, such as calling other AWS services for you.

This role then creates an Amazon EventBridge managed rule in your account. The rule is named AWSHealthEventProcessor-DO-NOT-DELETE. This rule is the required infrastructure for your account so that EventBridge can deliver alarm state change information from your account to AWS Health.

To learn more, see the following topics:

Creating an EventBridge rule for AWS Health

You can create an EventBridge rule to get notified for AWS Health events in your account. Before you create event rules for AWS Health, do the following:

Familiarize yourself with events, rules, and targets in EventBridge. For more information, see What is Amazon EventBridge? in the Amazon EventBridge User Guide and New EventBridge – Track and Respond to Changes to Your AWS Resources.
Create the target or targets to use in your event rules.

To create an EventBridge rule for AWS Health

Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.
To change the AWS Region, use the Region selector in the upper-right corner of the page. Choose the Region in which you want to track AWS Health events.
In the navigation pane, choose Rules.
Choose Create rule.
On the Define rule detail page, enter a name and description for your rule.
Keep the default values for Event bus and Rule type, and then choose Next.
On the Build event pattern page, for Event source, choose AWS events and EventBridge partner events.
Under Event pattern, for Event source, choose AWS services.
Under Event pattern, for AWS service, choose Health.
For Event type, choose one of the following options.
- Specific Health Abuse Events – Create a rule for AWS Health events that have the word Abuse in the event type name.
- Specific Health events – Create a rule for events for a specific AWS service, such as Amazon EC2.
You can choose Any service or Specific service(s). If you chose a specific service, choose one of the following options:
- Choose Any event type category to create a rule that applies to all event type categories.
- Choose Specific event type category(s) and then choose a value from the list, such as issue, accountNotification, or scheduledChange.
Tip
- To monitor all AWS Health events for a specific service, we recommend that you choose Any event type category and Any resource. This ensures that your rule monitors for any AWS Health events, including any new event type codes, for your specified service. For an example rule, see all Amazon EC2 events.
- You can create a rule to monitor for more than one service or event type category. To do so, you must manually update the event pattern for the rule. For more information, see Creating a rule for multiple services and categories.
If you chose a specific service and event type category, choose one of the following options for event type codes.
- Choose Any event type code to create a rule that applies to all event type codes.
- Choose Specific event type code(s) and then choose one or more values from the list. This creates a rule that applies only to specific event type codes. For example, if you choose AWS_EC2_INSTANCE_STOP_SCHEDULED and AWS_EC2_INSTANCE_RETIREMENT_SCHEDULED, your rule applies only to these events when they occur in your account.
Choose one of the following options for affected resources.
- Choose Any resource to create a rule that applies to all resources.
- Choose Specific resource(s) and enter the IDs of one or more resources. For example, you might specify an Amazon EC2 instance ID, such as i-EXAMPLEa1b2c3de4, to monitor for events that affect only this resource.
Review your rule setup so that it meets your event-monitoring requirements.
Choose Next.
On the Select target(s) page, choose the target type that you created for this rule, and then configure any additional options that are required for that type. For example, you might send the event to an Amazon SQS queue or an Amazon SNS topic.
Choose Next.
(Optional) On the Configure tags page, add any tags and then choose Next.
On the Review and create page, review your rule setup and ensure that it meets your event monitoring requirements.
Choose Create rule.

Example : Rule for all Amazon EC2 events

The following example creates a rule so that EventBridge monitors for all Amazon EC2 events, including the event type categories, event codes, and resources.

Screenshot of how to create a EventBridge rule for all Amazon EC2 events only.

Example : Rule for specific Amazon EC2 events

The following example creates a rule so that EventBridge monitors the following:

The Amazon EC2 service
The scheduledChange event type category
The event type codes for AWS_EC2_INSTANCE_TERMINATION_SCHEDULED and AWS_EC2_INSTANCE_RETIREMENT_SCHEDULED
The instance with the ID i-EXAMPLEa1b2c3de4

Create an EventBridge rule for specific Amazon EC2 events only.

Creating a rule for multiple services and categories

The examples in the previous procedure show you how to create a rule for a single service and event type category. You can also create a rule for multiple services and event type categories. This means that you don't have to create a separate rule for each service and category that you want to monitor. To do so, you must edit the event pattern and then enter your changes manually.

You can use one of the following options.

To add services and categories for an existing rule

In the EventBridge console, on the Rules page, choose the rule name.
In the upper-right corner, choose Edit.
Choose Next.
For Event pattern, choose Edit pattern, and then enter your changes into the text field.
Choose Next until you reach the Review and update page.
Choose Update rule to save your changes.

To add services and categories for a new rule

Follow the procedure in Creating an EventBridge rule for AWS Health to step 9.
Instead of choosing a single service or category from the lists, for Event pattern, choose Edit pattern.
Enter your changes into the text field. See the following example pattern as a model for creating your own event pattern.
Review your event pattern, and then follow the rest of the procedure in Creating an EventBridge rule for AWS Health to create your rule.

Use the API or AWS Command Line Interface (AWS CLI)

For a new or existing rule, use the PutRule API operation or the aws events put-rule command to update the event pattern. For an example AWS CLI command, see put-rule in the AWS CLI Command Reference.

Example: Multiple services and event type categories

The following event pattern creates a rule to monitor events for the issue, accountNotification, and scheduledChange event type categories for three AWS services: Amazon EC2, Amazon EC2 Auto Scaling, and Amazon VPC.


{
  "detail": {
    "eventTypeCategory": [
      "issue",
      "accountNotification",
      "scheduledChange"
    ],
    "service": [
      "AUTOSCALING",
      "VPC",
      "EC2"
    ]
  },
  "detail-type": [
    "AWS Health Event"
  ],
  "source": [
    "aws.health"
  ]
}

Receiving AWS Health events with AWS Chatbot

You can receive AWS Health events directly in your chat clients, such as Slack and Amazon Chime. You can use this event to identify recent AWS service issues that might affect your AWS applications and infrastructure. Then, you can sign in to your AWS Health Dashboard to learn more about the update. For example, if you're monitoring for the AWS_EC2_INSTANCE_STOP_SCHEDULED event type in your AWS account, the AWS Health event can appear directly to your Slack channel.

Prerequisites

Before you get started, you must have the following:

A chat client configured with AWS Chatbot. You can configure Amazon Chime and Slack. For more information, see Getting started with AWS Chatbot in the AWS Chatbot Administrator Guide.
An Amazon SNS topic that you created and to which you're subscribed. If you already have an SNS topic, you can use an existing one. For more information, see Getting started with Amazon SNS in the Amazon Simple Notification Service Developer Guide.

To receive AWS Health events with AWS Chatbot

Follow the procedure in Creating an EventBridge rule for AWS Health through step 13.
1. When you choose the target in step 14, choose an SNS topic. You will use this same SNS topic in the AWS Chatbot console.
2. Complete the rest of the procedure to create the rule.
Navigate to the AWS Chatbot console.
Choose your chat client, such as your Slack channel name, and then choose Edit.
In the Notifications - optional section, for Topics, choose the same SNS topic that you specified in step 1.
Choose Save.

When AWS Health sends an event to EventBridge that matches your rule, the AWS Health event will appear in your chat client.
Choose the event name to see more information in your AWS Health Dashboard.

Example : AWS Health events sent to Slack

The following is an example of two AWS Health events for Amazon EC2 and Amazon Simple Storage Service (Amazon S3) in the US East (N. Virginia) Region that appear in the Slack channel.

Screenshot of how two AWS Health events appear in a Slack channel.

Automating actions for Amazon EC2 instances

You can automate actions that respond to scheduled events for your Amazon EC2 instances. When AWS Health sends an event to your AWS account, your EventBridge rule can then invoke targets, such as AWS Systems Manager Automation documents, to automate actions on your behalf.

For example, when an Amazon EC2 instance retirement event is scheduled for an Amazon Elastic Block Store (Amazon EBS)-backed EC2 instance, AWS Health will send the AWS_EC2_PERSISTENT_INSTANCE_RETIREMENT_SCHEDULED event type to your AWS Health Dashboard. When your rule detects this event type, you can automate the stop and start of the instance. This way, you don't have to perform these actions manually.

Note

To automate actions for your Amazon EC2 instances, the instances must be managed by Systems Manager.

For more information, see Automating Amazon EC2 with EventBridge in the Amazon EC2 User Guide for Linux Instances.

Prerequisites

You must create an AWS Identity and Access Management (IAM) policy, create an IAM role, and update the role's trust policy before you can create a rule.

Follow this procedure to create a customer managed policy for your role. This policy gives the role permission to perform actions on your behalf. This procedure uses the JSON policy editor in the IAM console.

To create an IAM policy

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Policies.
Choose Create policy.
Choose the JSON tab.

Copy the following JSON and then replace the default JSON in the editor.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:StartInstances",
        "ec2:StopInstances",
        "ec2:DescribeInstanceStatus"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "ssm:*"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "sns:Publish"
      ],
      "Resource": [
        "arn:aws:sns:*:*:Automation*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": "arn:aws:iam::123456789012:role/AutomationEVRole"
    }
  ]
}

In the Resource parameter, for the Amazon Resource Name (ARN), enter your AWS account ID.
You can also replace the role name or use the default. This example uses AutomationEVRole.

Choose Next: Tags.
(Optional) You can use tags as key–value pairs to add metadata to the policy.
Choose Next: Review.
On the Review policy page, enter a Name, such as AutomationEVRolePolicy and an optional Description.
Review the Summary page to see the permissions that the policy allows. If you're satisfied with your policy, choose Create policy.

This policy defines the actions that the role can take. For more information, see Creating IAM policies (console) in the IAM User Guide.

After you create the policy, you must create an IAM role, and then attach the policy to that role.

To create a role for an AWS service

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles, and then choose Create role.
For Select type of trusted entity, choose AWS service.
Choose EC2 for the service that you want to allow to assume this role.
Choose Next: Permissions.
Enter the policy name that you created, such as AutomationEVRolePolicy, and then select the check box next to the policy.
Choose Next: Tags.
(Optional) You can use tags as key–value pairs to add metadata to the role.
Choose Next: Review.
For Role name, enter AutomationEVRole. This name must be the same name that appears in the ARN of the IAM policy that you created.
(Optional) For Role description, enter a description for the role.
Review the role and then choose Create role.

For more information, see Creating a role for an AWS service in the IAM User Guide.

Finally, you can update the trust policy for the role that you created. You must complete this procedure so that you can choose this role in the EventBridge console.

To update the trust policy for the role

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles.
In the list of roles in your AWS account, choose the name of the role that you created, such as AutomationEVRole.
Choose the Trust relationships tab, and then choose Edit trust relationship.

For Policy Document, copy the following JSON, remove the default policy, and paste the copied JSON in its place.


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

Choose Update Trust Policy.

For more information, see Modifying a role trust policy (console) in the IAM User Guide.

Create a rule for EventBridge

Follow this procedure to create a rule in the EventBridge console so that you can automate the stop and start of EC2 instances that are scheduled for retirement.

To create a rule for EventBridge for Systems Manager automated actions

Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.
In the navigation pane, under Events, choose Rules.
On the Create rule page, enter a Name and Description for your rule.
Under Define pattern, choose Event pattern, and then choose Pre-defined pattern by service.
For Service provider, choose AWS.
For Service name, choose Health.
For Event type, choose Specific Health events.
Choose Specific service(s) and then choose EC2.
Choose Specific event type category(s) and then choose scheduledChange.
Choose Specific event types code(s) and then choose the event type code.

For example, for Amazon EC2 EBS-backed instances, choose AWS_EC2_PERSISTENT_INSTANCE_RETIREMENT_SCHEDULED. For Amazon EC2 instance store-backed instances, choose AWS_EC2_INSTANCE_RETIREMENT_SCHEDULED.

Choose Any resource.

Your Event pattern will look similar to the following example.


{
  "source": [
    "aws.health"
  ],
  "detail-type": [
    "AWS Health Event"
  ],
  "detail": {
    "service": [
      "EC2"
    ],
    "eventTypeCategory": [
      "scheduledChange"
    ],
    "eventTypeCode": [
      "AWS_EC2_PERSISTENT_INSTANCE_RETIREMENT_SCHEDULED"
    ]
  }
}

Add the Systems Manager Automation document target. Under Select targets, for Target, choose SSM Automation.
For Document, choose AWS-RestartEC2Instance.
Expand the Configure automation parameters(s) and then choose Input Transformer.
For the Input Path field, enter {"Instances":"$.resources"}.
For the second field, enter {"InstanceId": <Instances>}.
Choose Use existing role, and then choose the IAM role that you created, such as AutomationEVRole.

Your target should look like the following example.

Note
If you don't have an existing IAM role with the required EC2 and Systems Manager permissions and trusted relationship, your role won't appear in the list. For more information, see Prerequisites.
Choose Create.

If an event occurs in your account that matches your rule, EventBridge will send the event to your specified target.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Organizational view (CLI)

Monitoring AWS Health

Monitoring AWS Health events with Amazon EventBridge

About AWS Regions for AWS Health

About public events for AWS Health

Event processor for AWS Health

Related information

Creating an EventBridge rule for AWS Health

To create an EventBridge rule for AWS Health

Example : Rule for all Amazon EC2 events

Example : Rule for specific Amazon EC2 events

Creating a rule for multiple services and categories

To add services and categories for an existing rule

To add services and categories for a new rule

Use the API or AWS Command Line Interface (AWS CLI)

Example: Multiple services and event type categories

Receiving AWS Health events with AWS Chatbot

Prerequisites

To receive AWS Health events with AWS Chatbot

Example : AWS Health events sent to Slack

Automating actions for Amazon EC2 instances

Prerequisites

To create an IAM policy

To create a role for an AWS service

To update the trust policy for the role

Create a rule for EventBridge

To create a rule for EventBridge for Systems Manager automated actions