Monitoring AWS Health events with Amazon EventBridge - AWS Health
About AWS Regions for AWS HealthAbout public events for AWS HealthEvent processor for AWS HealthCreating an EventBridge rule for AWS HealthAWS Health Events Amazon EventBridge Schema Pagination of AWS Health events on EventBridge Aggregating AWS Health events using organizational view and delegated administrator accessReceiving AWS Health events with AWS ChatbotAutomating 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

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

You must create an EventBridge rule for each Region that you want to receive AWS Health events for. 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.

Setting up an additional rule in a backup Region adds an extra layer of resilience to your workflows, should your primary rule be affected by an ongoing event. Public events for AWS Health are sent simultaneously to both the impacted Region and to a backup Region. See About public events for AWS Health for more information. For all Regions in the standard AWS partition, you can setup a rule in US West (Oregon) as a backup to continue receiving events even if your primary Region is affected by an ongoing issue. The backup Region for the US West (Oregon) Region is US East (N. Virginia) Region.

For example, if you're monitoring events in the Europe (Frankfurt) Region and that Region is temporarily unavailable, then AWS Health will also deliver that event to the US West (Oregon) Region. Next, your back up EventBridge rule sends the event to the targets that you specified. To create a backup rule, follow the procedure below for Creating an EventBridge rule for AWS Health and use the US West (Oregon) 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 for the primary Region and US West (Oregon) Region as the backup 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

When you create an EventBridge rule to monitor events from AWS Health, the rule delivers both account-specific events and public events:

  • Account-specific events affect your account and resources, such as an event that tells you about a required update to an Amazon EC2 instance or other scheduled change events.

  • Public events appear on the AWS Health Dashboard – Service health. Public events aren't specific to AWS accounts and provide public information about the Regional availability of a service.

Important

To receive both event types, your rule must use the "source": [ "aws.health"] value. Wildcards, such as "source": [ "aws.health*"] won't match the pattern to monitor for any events.

If you're monitoring public events from an AWS Region, we recommend that you create a back up rule. Public events for AWS Health are sent simultaneously to both the impacted Region and to a backup Region. It's recommended that you de-duplicate AWS Health events using eventARN and communicationId because these remain consistent for AWS Health messages sent to the backup Region.

You can identify if an event is public or account-specific in EventBridge, by using the eventScopeCode parameter. Events can have the PUBLIC or ACCOUNT_SPECIFIC. You can also filter your rule on this parameter.

Example: Public events for Amazon Elastic Compute Cloud

The following event shows an operational issue for Amazon EC2 in the US East (N. Virginia) Region.


{
    "version": "0",
    "id": "fd9d4512-1eb0-50f6-0491-d016ae56aef0",
    "detail-type": "AWS Health Event",
    "source": "aws.health",
    "account": "123456789012",
    "time": "2023-02-15T10:07:10Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "eventArn": "arn:aws:health:us-east-1::event/EC2/AWS_EC2_OPERATIONAL_ISSUE",
        "service": "EC2",
        "eventTypeCode": "AWS_EC2_OPERATIONAL_ISSUE",
        "eventTypeCategory": "issue",
        "eventScopeCode": "PUBLIC",
        "communicationId": "01b0993207d81a09dcd552ebd1e633e36cf1f09a-1",
        "startTime": "Wed, 15 Feb 2023 22:07:07 GMT",
        "lastUpdatedTime": "Wed, 15 Feb 2023 22:07:07 GMT",
        "statusCode": "open",
        "eventRegion": "us-east-1",
        "eventDescription": [
            {
                "latestDescription": "We are investigating increased API Error rates and Latencies for Amazon Elastic Compute Cloud in the US-EAST-1 Region.",
                "language": "en_US"
            }
        ],
        "page": "1",
        "totalPages": "1",
        "affectedAccount":"123456789012",

    }
}

Event processor for AWS Health

If you use AWS Incident Detection and Response for your account, then you must install the AWSServiceRoleForHealth_EventProcessor service-linked role in your account.

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:

To create an EventBridge rule for AWS Health

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. 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.

  3. In the navigation pane, choose Rules.

  4. Choose Create rule.

  5. On the Define rule detail page, enter a name and description for your rule.

  6. Keep the default values for Event bus and Rule type, and then choose Next.

  7. On the Build event pattern page, for Event source, choose AWS events and EventBridge partner events.

  8. Under Event pattern, for Event source, choose AWS services.

  9. Under Event pattern, for AWS service, choose Health.

  10. 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.

  11. 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.

  12. 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.

  13. 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.

  14. Review your rule setup so that it meets your event-monitoring requirements.

  15. Choose Next.

  16. 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.

  17. Choose Next.

  18. (Optional) On the Configure tags page, add any tags and then choose Next.

    • Note: Tags are currently not sent by the aws.health source in EventBridge.

  19. On the Review and create page, review your rule setup and ensure that it meets your event monitoring requirements.

  20. 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

  1. In the EventBridge console, on the Rules page, choose the rule name.

  2. In the upper-right corner, choose Edit.

  3. Choose Next.

  4. For Event pattern, choose Edit pattern, and then enter your changes into the text field.

  5. Choose Next until you reach the Review and update page.

  6. Choose Update rule to save your changes.

To add services and categories for a new rule

  1. Follow the procedure in Creating an EventBridge rule for AWS Health to step 9.

  2. Instead of choosing a single service or category from the lists, for Event pattern, choose Edit pattern.

  3. Enter your changes into the text field. See the following example pattern as a model for creating your own event pattern.

  4. 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"
  ]
}

AWS Health Events Amazon EventBridge Schema

The following is the schema for AWS Health events. Changes or additions to the previous version of the schema are highlighted as "New". A sample payload is provided after the schema.

AWS Health Event Schema

AWS Health Event Schema
Parameter Description Required
version EventBridge Version, currently "0" Yes
id The uniqueEventBridge identifier for the event Yes
detail-type Describes the detail type. For AWS Health events this will be &AWS Health Event or AWS Health Abuse Event Yes
source

The event bus source. For AWS Health events this will be aws.health

 Yes
account The accountId to that the AWS Health event was sent to.
Note

For organizational view this will be different from the affectedAccount if it's received in the management or delegated administrator account.

 Yes
time Time at which the notification was sent to EventBridge. Format: yyyy-mm-ddThh:mm:ssZ. Yes
region Identifies the AWS Region that the notification was delivered to.
Note

This field doesn't indicate the impacted Region for this AWS Health event. This is provided by "detail.eventRegion".

 Yes
resources

Describes the list of affected resources within an account, if there are affected resources.

Note

This field can be empty if there are no resources referenced.

 No
detail This section contains all the details of the AWS Health event, as listed below. Yes
eventArn Unique identifier for the AWS Health event for the specific Region, includes the Region and event id.
Note

An eventArn isn't unique to a specific customer account or to a Region.

 Yes
service The AWS service affected by the AWS Health event. For example, Amazon EC2, Amazon Simple Storage Service, Amazon Redshift, or Amazon Relational Database Service. Yes
eventTypeCode The unique identifier for the event type. For example: AWS_EC2_INSTANCE_NETWORK_MAINTENANCE_SCHEDULED and AWS_EC2_INSTANCE_REBOOT_MAINTENANCE_SCHEDULED. Events that include MAINTENANCE_SCHEDULED are generally pushed out approximately two weeks before the startTime.
Note

All new planned lifecycle events have the event type AWS_{SERVICE}_PLANNED_LIFECYCLE_EVENT.

 Yes
eventTypeCategory The category code of the event. The possible values are issue, accountNotification, investigation, and scheduledChange. Yes
eventScopeCode Indicates if the AWS Health event is account-specific or public. Possible values are ACCOUNT_SPECIFIC or PUBLIC. Yes
communicationId (New)

A unique identifier for this communication for the AWS Health event.

Messages with the same communicationId are possible backup messages or pages of a single AWS Health event. This identifier can be used with the accountId to help de-duplicate messages.

Note

With the pagination feature release, communicationId includes the page number to keep the communicationId unique across pages, for example, 12345678910-1. For more information, see Pagination of AWS Health events on EventBridge.

 Yes
startTime The start time of the AWS Health event in the format: DoW, DD, MMM, YYYY, HH:MM:SS TZ.
Note

The start time can be in the future for scheduled events.

 Yes
endTime The end time of the AWS Health event in the format: DoW, DD MMM YYYY HH:MM:SS TZ.
Note

endTime may not be provided for events that are set in the future.

 No
lastUpdatedTime The last update time for the AWS Health event in the format: DoW, DD MMM YYYY HH:MM:SS TZ. Yes
statusCode

Status of the AWS Health event. Type categories have different statuses.

The possible values for Issue event categories are open, closed or upcoming.

scheduledChanges event categories have different statuses: Upcoming, Ongoing, or Completed.

AccountNotifications event categories don't have a status and are set to "-".

Yes
eventRegion The impacted Region described by this AWS Health event. Yes
eventDescription A section that describes the AWS Health event. This includes fields for language and text to describe the event. Yes
language Language used in the AWS Health event. This is typically determined by the Region that the event is published to. For the us-east-1 Region, this is typically "en_US". Yes
latestDescription Describes the AWS Health event as it is rendered from the AWS Health API and typically appears on the the AWS Health dashboard.
Note

For public events, this contains only the latest update and not the entire history of the event.

 Yes
eventMetadata Additional event metadata that can be provided for the AWS Health event. No
<metadata key 1> metadata key, value strings "keystring1": "keyvalue1"
Note

The key-value pairs for event metadata are determined by the service that sent the AWS Health event.

 No
affectedEntities An array that describes the resource value and status of affected resources within this AWS Health event. No
entityValue The resource/entity ID No
lastUpdatedtime (New) The time when this resource/entity status was last updated in the format:DoW, DD MMM YYYY HH:MM:SS TZ No
status (new) The status of the affected resource/entity. Possible values include IMPAIRED, UNIMPAIRED, PENDING, RESOLVED, UNKNOWN. No
page (New) The page this message represents. For more information, see Pagination of AWS Health events on EventBridge.
Note

Pagination occurs only on resources. Other causes for the 256KB size limit breach will cause the communication to fail.

 Yes
totalPages (New) The total number of pages for this health event. For more information, see Pagination of AWS Health events on EventBridge.
Note

You can use this to determine if you received all of the pages of a multi-page communication for an account.

 Yes
affectedAccount (New) This is the accountId of the impacted account.
Note

This may be different from the "account" field if this health event is sent to an account that is part of an AWS Organizations and this is received in the management or delegated administrator account.

 Yes

Public Health Event - Amazon EC2 operational issue 


        {
          "version": "0",
          "id": "7bf73129-1428-4cd3-a780-95db273d1602",
          "detail-type": "AWS Health Event",
          "source": "aws.health",
          "account": "123456789012",
          "time": "2023-01-27T09:01:22Z",
          "region": "af-south-1",
          "resources": [],
          "detail": {
            "eventArn": "arn:aws:health:af-south-1::event/EC2/AWS_EC2_OPERATIONAL_ISSUE/AWS_EC2_OPERATIONAL_ISSUE_7f35c8ae-af1f-54e6-a526-d0179ed6d68f",
            "service": "EC2",
            "eventTypeCode": "AWS_EC2_OPERATIONAL_ISSUE",
            "eventTypeCategory": "issue",
            "eventScopeCode": "PUBLIC",
            "communicationId": "01b0993207d81a09dcd552ebd1e633e36cf1f09a-1",
            "startTime": "Fri, 27 Jan 2023 06:02:51 GMT",
            "endTime": "Fri, 27 Jan 2023 09:01:22 GMT",
            "lastUpdatedTime": "Fri, 27 Jan 2023 09:01:22 GMT",
            "statusCode": "open",
            "eventRegion": "af-south-1",
            "eventDescription": 
            [{
              "language": "en_US",
              "latestDescription": "Current severity level: Operating normally\n\n[RESOLVED] \n\n [03:15 PM PST] We continue see recovery \n\nThe following AWS services were previously impacted but are now operating normally: APPSYNC, BACKUP, EVENTS."      
            }],
            "affectedEntities":[],
            "page": "1",
            "totalPages": "1",
            "affectedAccount": "123456789012",
          }
        }

Account-specific AWS Health Event - Elastic Load Balancing API Issue 


        {
          "version": "0",
          "id": "121345678-1234-1234-1234-123456789012",
          "detail-type": "AWS Health Event",
          "source": "aws.health",
          "account": "123456789012",
          "time": "2022-06-10T06:27:57Z",
          "region": "ap-southeast-2",
          "resources": [],
          "detail": {
            "eventArn": "arn:aws:health:ap-southeast-2::event/AWS_ELASTICLOADBALANCING_API_ISSUE_90353408594353980",
            "service": "ELASTICLOADBALANCING",
            "eventTypeCode": "AWS_ELASTICLOADBALANCING_API_ISSUE",
            "eventTypeCategory": "issue",
            "eventScopeCode": "ACCOUNT_SPECIFIC",
            "communicationId": "01b0993207d81a09dcd552ebd1e633e36cf1f09a-1",
            "startTime": "Fri, 10 Jun 2022 05:01:10 GMT",
            "endTime": "Fri, 10 Jun 2022 05:30:57 GMT",
            "statusCode": "open",
            "eventRegion": "ap-southeast-2",
            "eventDescription": [{
                "language": "en_US",
                "latestDescription": "A description of the event will be provided here"
            }],
            "page": "1",
            "totalPages": "1",            
            "affectedAccount": "123456789012",             
          }
        }

Account-specific AWS Health Event - Amazon EC2 Instance Store Drive Performance Degraded 


        {
          "version": "0",
          "id": "121345678-1234-1234-1234-123456789012",
          "detail-type": "AWS Health Event",
          "source": "aws.health",
          "account": "123456789012",
          "time": "2022-06-03T06:27:57Z",
          "region": "us-west-2",
          "resources": [
            "i-abcd1111"
          ],
          "detail": {
            "eventArn": "arn:aws:health:us-west-2::event/AWS_EC2_INSTANCE_STORE_DRIVE_PERFORMANCE_DEGRADED_90353408594353980",
            "service": "EC2",
            "eventTypeCode": "AWS_EC2_INSTANCE_STORE_DRIVE_PERFORMANCE_DEGRADED",
            "eventTypeCategory": "issue",
            "eventScopeCode": "ACCOUNT_SPECIFIC",
            "communicationId": "01b0993207d81a09dcd552ebd1e633e36cf1f09a-1",
            "startTime": "Fri, 3 Jun 2022 05:01:10 GMT",
            "endTime": "Fri, 3 Jun 2022 05:30:57 GMT",
            "statusCode": "open",
            "eventRegion": "us-west-2",
            "eventDescription": [{
                "language": "en_US",
                "latestDescription": "A description of the event will be provided here"
            }],
            "affectedEntities": [{
              "entityValue": "i-abcd1111",
            }],
            "page": "1",
            "totalPages": "1",            
            "affectedAccount": "123456789012",    
          }
        }

Pagination of AWS Health events on EventBridge

AWS Health supports pagination of AWS Health events when the list of “resources” or “affectedEntities” causes the size of the message to exceed EventBridge’s 256KB message size limit. Previously, AWS Health didn't communicate the full list of resources with events when it exceeded this limit.

AWS Health now includes all “resources” and “detail.affectedEntities” in the message. If this list of “resources” and “detail.affectedEntities” exceeds 256KB, then AWS Health splits the health event into multiple pages and publish these pages as individual messages in EventBridge. Each page retains the same eventARN and communicationId to help recombine the list of “resources” or “detail.affectedEntities” after all the pages are received.

These additional messages might cause unecessary messages, for example when the EventBridge rule is directed to a human readable interface such as email or chat. Customers with human readable notifications can add a filter for the “detail.page” field to process only the first page, which eliminates the unnecessary messages created from subsequent pages.

Several schema changes are included to support the pagination launch. Each communicationId now includes the hyphenated page number after the communicationId, even when there is only 1 page. There are also two new fields, detail.page and detail.totalPages, which describe the current page number and the total number of pages for the AWS Health event. The information contained in each paginated message is the same except for the list of “detail.affectedEntities” or “resources”. These lists can be reconstructed after all the pages are received. The pages of affected resources and entities are order-agnostic.

Aggregating AWS Health events using organizational view and delegated administrator access

AWS Health supports organizational view and delegated administrator access for AWS Health events published on Amazon EventBridge. When organizational view is turned on in AWS Health, then the management account or a delegated administrator account receives a single feed of AWS Health events from all accounts within your organization in AWS Organizations.

This feature is designed to provide a centralized view to help manage AWS Health events across your organization. Setting up organizational view and an EventBridge rule in the management account doesn't deactivate EventBridge rules for other accounts in your organization.

For more information on enabling organizational view and delegated administrator access on AWS Health, see Aggregating AWS Health Events.

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

  1. Follow the procedure in Creating an EventBridge rule for AWS Health through step 13.

    1. When you finish setting up the event pattern in step 13, add a comma to the last line of the pattern, and add the following line to remove unnecessary chat messages from paginated AWS Health events. See Pagination of AWS Health events on EventBridge.

      "detail.page": ["1"]

    2. When you choose the target in step 14, choose an SNS topic. You will use this same SNS topic in the AWS Chatbot console.

    3. Complete the rest of the procedure to create the rule.

  2. Navigate to the AWS Chatbot console.

  3. Choose your chat client, such as your Slack channel name, and then choose Edit.

  4. In the Notifications - optional section, for Topics, choose the same SNS topic that you specified in step 1.

  5. Choose Save.

    When AWS Health sends an event to EventBridge that matches your rule, the AWS Health event will appear in your chat client.

  6. 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

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Policies.

  3. Choose Create policy.

  4. Choose the JSON tab.

  5. 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"
    }
  ]
}

    1. In the Resource parameter, for the Amazon Resource Name (ARN), enter your AWS account ID.

    2. You can also replace the role name or use the default. This example uses AutomationEVRole.

  6. Choose Next: Tags.

  7. (Optional) You can use tags as key–value pairs to add metadata to the policy.

  8. Choose Next: Review.

  9. On the Review policy page, enter a Name, such as AutomationEVRolePolicy and an optional Description.

  10. 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

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

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

  3. For Select type of trusted entity, choose AWS service.

  4. Choose EC2 for the service that you want to allow to assume this role.

  5. Choose Next: Permissions.

  6. Enter the policy name that you created, such as AutomationEVRolePolicy, and then select the check box next to the policy.

  7. Choose Next: Tags.

  8. (Optional) You can use tags as key–value pairs to add metadata to the role.

  9. Choose Next: Review.

  10. For Role name, enter AutomationEVRole. This name must be the same name that appears in the ARN of the IAM policy that you created.

  11. (Optional) For Role description, enter a description for the role.

  12. 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

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles.

  3. In the list of roles in your AWS account, choose the name of the role that you created, such as AutomationEVRole.

  4. Choose the Trust relationships tab, and then choose Edit trust relationship.

  5. 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"
        }
    ]
}

  6. 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

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. In the navigation pane, under Events, choose Rules.

  3. On the Create rule page, enter a Name and Description for your rule.

  4. Under Define pattern, choose Event pattern, and then choose Pre-defined pattern by service.

  5. For Service provider, choose AWS.

  6. For Service name, choose Health.

  7. For Event type, choose Specific Health events.

  8. Choose Specific service(s) and then choose EC2.

  9. Choose Specific event type category(s) and then choose scheduledChange.

  10. 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.

  11. 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"
    ]
  }
}

  12. Add the Systems Manager Automation document target. Under Select targets, for Target, choose SSM Automation.

  13. For Document, choose AWS-RestartEC2Instance.

  14. Expand the Configure automation parameters(s) and then choose Input Transformer.

  15. For the Input Path field, enter {"Instances":"$.resources"}.

  16. For the second field, enter {"InstanceId": <Instances>}.

  17. Choose Use existing role, and then choose the IAM role that you created, such as AutomationEVRole.

    Your target should look like the following example.

    Screenshot of the "SSM Automation" example in the EventBridge console.
    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.

  18. Choose Create.

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