Get deployment notifications

Amazon EventBridge event rules provide you with notifications about state changes for your Greengrass group deployments. EventBridge delivers a near real-time stream of system events that describes changes in Amazon resources. Amazon IoT Greengrass sends these events to EventBridge on an at least once basis. This means that Amazon IoT Greengrass might send multiple copies of a given event to ensure delivery. Additionally, your event listeners might not receive the events in the order that the events occurred.

Note

Amazon EventBridge is an event bus service that you can use to connect your applications with data from a variety of sources, such as Greengrass core devices and deployment notifications. For more information, see What is Amazon EventBridge? in the Amazon EventBridge User Guide.

Amazon IoT Greengrass emits an event when group deployments change state. You can create an EventBridge rule that runs for all state transitions or transitions to states you specify. When a deployment enters a state that initiates a rule, EventBridge invokes the target actions defined in the rule. This allows you to send notifications, capture event information, take corrective action, or initiate other events in response to a state change. For example, you can create rules for the following use cases:

Initiate post-deployment operations, such as downloading assets and notifying personnel.
Send notifications upon a successful or failed deployment.
Publish custom metrics about deployment events.

Amazon IoT Greengrass emits an event when a deployment enters the following states: Building, InProgress, Success, and Failure.

Note

Monitoring the status of a bulk deployment operation is not currently supported. However, Amazon IoT Greengrass emits state-change events for individual group deployments that are part of a bulk deployment.

Group deployment status change event

The event for a deployment state change uses the following format:


{
    "version":"0",
    "id":" cd4d811e-ab12-322b-8255-EXAMPLEb1bc8",
    "detail-type":"Greengrass Deployment Status Change",
    "source":"aws.greengrass",
    "account":"123456789012",
    "time":"2018-03-22T00:38:11Z",
    "region":"us-west-2",
    "resources":[],
    "detail":{    
        "group-id": "284dcd4e-24bc-4c8c-a770-EXAMPLEf03b8",
        "deployment-id": "4f38f1a7-3dd0-42a1-af48-EXAMPLE09681",
        "deployment-type": "NewDeployment|Redeployment|ResetDeployment|ForceResetDeployment",
        "status": "Building|InProgress|Success|Failure"
    }
}

You can create rules that apply to one or more groups. You can filter rules by one or more of the following deployment types and deployment states:

Deployment types

NewDeployment. The first deployment of a group version.
ReDeployment. A redeployment of a group version.
ResetDeployment. Deletes deployment information stored in the Amazon Web Services Cloud and on the Amazon IoT Greengrass core. For more information, see Reset deployments.
ForceResetDeployment. Deletes deployment information stored in the Amazon Web Services Cloud and reports success without waiting for the core to respond. Also deletes deployment information stored on the core if the core is connected or when it next connects.

Deployment states

Building. Amazon IoT Greengrass is validating the group configuration and building deployment artifacts.
InProgress. The deployment is in progress on the Amazon IoT Greengrass core.
Success. The deployment was successful.
Failure. The deployment failed.

It's possible that events might be duplicated or out of order. To determine the order of events, use the time property.

Note

Amazon IoT Greengrass doesn't use the resources property, so it's always empty.

Prerequisites for creating EventBridge rules

Before you create an EventBridge rule for Amazon IoT Greengrass, do the following:

Familiarize yourself with events, rules, and targets in EventBridge.
Create and configure the targets invoked by your EventBridge rules. Rules can invoke many types of targets, including:
- Amazon Simple Notification Service (Amazon SNS)
- Amazon Lambda functions
- Amazon Kinesis Video Streams
- Amazon Simple Queue Service (Amazon SQS) queues

For more information, see What is Amazon EventBridge? and Getting started with Amazon EventBridge in the Amazon EventBridge User Guide.

Configure deployment notifications (console)

Use the following steps to create an EventBridge rule that publishes an Amazon SNS topic when the deployment state changes for a group. This allows web servers, email addresses, and other topic subscribers to respond to the event. For more information, see Creating a EventBridge rule that triggers on an event from an Amazon resource in the Amazon EventBridge User Guide.

Open the Amazon EventBridge console.
In the navigation pane, choose Rules.
Choose Create rule.
Enter a name and description for the rule.

A rule can't have the same name as another rule in the same Region and on the same event bus.
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 Amazon default event bus. When an Amazon service in your account emits an event, it always goes to your account's default event bus.
For Rule type, choose Rule with an event pattern.
Choose Next.
For Event source, choose Amazon services.
For Event pattern, choose Amazon services.
For Amazon service, choose Greengrass.
For Event type, choose Greengrass Deployment Status Change.

Note
The Amazon API Call via CloudTrail event type is based on Amazon IoT Greengrass integration with Amazon CloudTrail. You can use this option to create rules initiated by read or write calls to the Amazon IoT Greengrass API. For more information, see Logging Amazon IoT Greengrass API calls with Amazon CloudTrail.
Choose the deployment states that initiate a notification.
- To receive notifications for all state change events, choose Any state.
- To receive notifications for some state change events only, choose Specific state(s), and then choose the target states.
Choose the deployment types that initiate a notification.
- To receive notifications for all deployment types, choose Any state.
- To receive notifications for some deployment types only, choose Specific state(s), and then choose the target deployment types.
Choose Next.
For Target types, choose Amazon service.
For Select a target, configure your target. This example uses an Amazon SNS topic, but you can configure other target types to send notifications.
1. For Target, choose SNS topic.
2. For Topic, choose your target topic.
3. Choose Next.
Under Tags, define tags for the rule or leave the fields empty.
Choose Next.
Review the details of the rule and choose Create rule.

Configure deployment notifications (CLI)

Create the rule.

Replace group-id with the ID of your Amazon IoT Greengrass group.


aws events put-rule \
  --name TestRule \
  --event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"group-id\": [\"group-id\"]}}"

Properties that are omitted from the pattern are ignored.

Add the topic as a rule target.
- Replace topic-arn with the ARN of your Amazon SNS topic.
```
aws events put-targets \
  --rule TestRule \
  --targets "Id"="1","Arn"="topic-arn"
```
Note
To allow Amazon EventBridge to call your target topic, you must add a resource-based policy to your topic. For more information, see Amazon SNS permissions in the Amazon EventBridge User Guide.

For more information, see Events and event patterns in EventBridge in the Amazon EventBridge User Guide.

Configure deployment notifications (Amazon CloudFormation)

Use Amazon CloudFormation templates to create EventBridge rules that send notifications about state changes for your Greengrass group deployments. For more information, see Amazon EventBridge resource type reference in the Amazon CloudFormation User Guide.