How do I use EventBridge rules to automate and customize notifications for EC2 instance state changes?

Short description

You can use an Amazon EventBridge rule to trigger on EC2 state change events. Then, you can use an input transformer to extract the necessary information from the JSON event. The input transformer customizes this information before sending it to its intended target for further processing. The intended target can be an Amazon Simple Notification Service (Amazon SNS) topic with an email endpoint or an AWS Lambda function.

Resolution

Create a rule pattern for EC2 state change events

1. Open the Amazon EventBridge console.
2. In the navigation pane, choose Rules.
3. Choose Create rule.
4. Enter a name and description for the rule. For example, name the rule TestRule.
5. For Event bus, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select default. When an AWS service in your account emits an event, it always goes to your account's default event bus.
6. For Rule type, choose Rule with an event pattern.
7. Choose Next.
8. For Event source, choose AWS events or EventBridge partner events.
9. For Event pattern, choose AWS services under Event source.
10. Under AWS service, select EC2.
11. Under Event type, select EC2 Instance State-change Notification.
    Note: This section allows you to choose the type of alert for any state change or a specific stage change. Alert options include: "pending," "running," "shutting-down," "terminated," "stopping," or "stopped." You can also choose to receive alerts for a specific instance ID or all instances.
12. Select Next.

The resulting event pattern might look like this:

```plaintext
{
  "source": [
    "aws.ec2"
  ],
  "detail-type": [
    "EC2 Instance State-change Notification"
  ],
  "detail": {
    "state": [
      "pending",
      "running",
      "shutting-down",
      "terminated",
      "stopping",
      "stopped"
    ],
    "instance-id": [
      "i-123456789"
    ]
  }
}
```

Configure the targets

Configure the targets, as follows:

1. For Target types, choose AWS service.
2. For Select a target, choose SNS topic from the dropdown list and the corresponding Topic of your choice.
3. Use the input transformer to customize the following event before delivering to the target.

Example: EC2 state-change event:

{
  "version": "0",
  "id": "cd23ef67-a177-452c-2143-ec05410e4226",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "123456789012",
  "time": "2023-09-06T19:41:39Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:ec2:us-east-1:123456789012:instance/i-024de5ace7c560660"
  ],
  "detail": {
    "instance-id": "i-024de5ace7c560660",
    "state": "pending"
  }
}

Configure the input transformer

Configure the input transformer with these settings:

1. Choose Additional settings.
2. For Configure target input, choose Input transformer from the dropdown list.
3. Choose Configure input transformer. This option displays two text boxes: one for the Input Path and one for the Input Template.

   • Configure Input Path to identify the specific fields that should be sent to the target. To assign the values from the EC2 state-change event, use the JSON path "$.detail.instance-id":

     {
       "timestamp": "$.time",
       "instance": "$.detail.instance-id",
       "state": "$.detail.state",
       "resource": "$.resources[0]"
     }

   • The Input Template represents the details sent to the target. Use the variables timestamp, instance, state, and resource in the Input Path to pass a string or JSON to the target. For example:

     "At time <timestamp>, EC2 instance <instance> changed state to <state>. Here is the instance ARN <ARN>."

     Based on the configuration of this input template, the target receives this response:

     "At time 2023-09-06T19:41:39Z, EC2 instance i-024de5ace7c560660 changed state to pending. Here is the instance ARN arn:aws:ec2:us-east-1:123456789012:instance/i-024de5ace7c56066

     For more information on how to customize text from an event, see Amazon EventBridge input transformation.

4. Choose Confirm. Then, choose Next.
5. Choose Create Rule.

Confirm the test events

1. Open the Amazon EC2 console.
2. From the Amazon EC2 console dashboard, choose Launch instance.
3. (Optional) Under Name and tags, for Name, enter a descriptive name for your instance.
4. Under Application and OS Images (Amazon Machine Image), choose Quick Start. Then, choose the operating system (OS) for your instance.
5. Under Key pair (login), for Key pair name, choose an existing key pair or create a new one.
6. In the Summary panel, choose Launch instance.

After the instance launches successfully, the target SNS endpoints use the customized notification that you defined with the input transformer.

Related information

Create a rule