Package software.amazon.awscdk.services.events

package software.amazon.awscdk.services.events

Amazon EventBridge Construct Library

Amazon EventBridge delivers a near real-time stream of system events that describe changes in AWS resources. For example, an AWS CodePipeline emits the State Change event when the pipeline changes its state.

  • Events: An event indicates a change in your AWS environment. AWS resources can generate events when their state changes. For example, Amazon EC2 generates an event when the state of an EC2 instance changes from pending to running, and Amazon EC2 Auto Scaling generates events when it launches or terminates instances. AWS CloudTrail publishes events when you make API calls. You can generate custom application-level events and publish them to EventBridge. You can also set up scheduled events that are generated on a periodic basis. For a list of services that generate events, and sample events from each service, see EventBridge Event Examples From Each Supported Service.
  • Targets: A target processes events. Targets can include Amazon EC2 instances, AWS Lambda functions, Kinesis streams, Amazon ECS tasks, Step Functions state machines, Amazon SNS topics, Amazon SQS queues, Amazon CloudWatch LogGroups, and built-in targets. A target receives events in JSON format.
  • Rules: A rule matches incoming events and routes them to targets for processing. A single rule can route to multiple targets, all of which are processed in parallel. Rules are not processed in a particular order. This enables different parts of an organization to look for and process the events that are of interest to them. A rule can customize the JSON sent to the target, by passing only certain parts or by overwriting it with a constant.
  • EventBuses: An event bus can receive events from your own custom applications or it can receive events from applications and services created by AWS SaaS partners. See Creating an Event Bus.

Rule

The Rule construct defines an EventBridge rule which monitors an event based on an event pattern and invoke event targets when the pattern is matched against a triggered event. Event targets are objects that implement the IRuleTarget interface.

Normally, you will use one of the source.onXxx(name[, target[, options]]) -> Rule methods on the event source to define an event rule associated with the specific activity. You can targets either via props, or add targets using rule.addTarget.

For example, to define an rule that triggers a CodeBuild project build when a commit is pushed to the "master" branch of a CodeCommit repository: 

 Repository repo;
 Project project;
 
 
 Rule onCommitRule = repo.onCommit("OnCommit", OnCommitOptions.builder()
         .target(new CodeBuildProject(project))
         .branches(List.of("master"))
         .build());

You can add additional targets, with optional input transformer using eventRule.addTarget(target[, input]). For example, we can add a SNS topic target which formats a human-readable message for the commit.

For example, this adds an SNS topic as a target: 

 Rule onCommitRule;
 Topic topic;
 
 
 onCommitRule.addTarget(SnsTopic.Builder.create(topic)
         .message(RuleTargetInput.fromText(String.format("A commit was pushed to the repository %s on branch %s", ReferenceEvent.getRepositoryName(), ReferenceEvent.getReferenceName())))
         .build());

Or using an Object: 

 Rule onCommitRule;
 Topic topic;
 
 
 onCommitRule.addTarget(SnsTopic.Builder.create(topic)
         .message(RuleTargetInput.fromObject(Map.of(
                 "DataType", String.format("custom_%s", EventField.fromPath("$.detail-type")))))
         .build());

Role

You can specify an IAM Role: 

 IRole role;
 
 
 Rule.Builder.create(this, "MyRule")
         .schedule(Schedule.cron(CronOptions.builder().minute("0").hour("4").build()))
         .role(role)
         .build();

Note: If you're setting an event bus in another account as the target and that account granted permission to your account through an organization instead of directly by the account ID, you must specify a RoleArn with proper permissions in the Target structure, instead of here in this parameter.

Matchers

To define a pattern, use the Match class, which provides a number of factory methods to declare different logical predicates. For example, to match all S3 events for objects larger than 1024 bytes, stored using one of the storage classes Glacier, Glacier IR or Deep Archive and coming from any region other than the AWS GovCloud ones: 

 Rule rule = Rule.Builder.create(this, "rule")
         .eventPattern(EventPattern.builder()
                 .detail(Map.of(
                         "object", Map.of(
                                 // Matchers may appear at any level
                                 "size", Match.greaterThan(1024)),
 
                         // 'OR' condition
                         "source-storage-class", Match.anyOf(Match.prefix("GLACIER"), Match.exactString("DEEP_ARCHIVE"))))
 
                 // If you prefer, you can use a low level array of strings, as directly consumed by EventBridge
                 .source(List.of("aws.s3"))
 
                 .region(Match.anythingButPrefix("us-gov"))
                 .build())
         .build();

Matches can also be made case-insensitive, or make use of wildcard matches. For example, to match object create events for buckets whose name starts with raw-, for objects with key matching the pattern path/to/object/*.txt and the requester ends with .AMAZONAWS.COM: 

 Rule rule = Rule.Builder.create(this, "rule")
         .eventPattern(EventPattern.builder()
                 .detail(Map.of(
                         "bucket", Map.of(
                                 "name", Match.prefixEqualsIgnoreCase("raw-")),
 
                         "object", Map.of(
                                 "key", Match.wildcard("path/to/object/*.txt")),
 
                         "requester", Match.suffixEqualsIgnoreCase(".AMAZONAWS.COM")))
                 .detailType(Match.equalsIgnoreCase("object created"))
                 .build())
         .build();

The "anything but" matchers allow you to specify multiple arguments. For example: 

 Rule rule = Rule.Builder.create(this, "rule")
         .eventPattern(EventPattern.builder()
                 .region(Match.anythingBut("us-east-1", "us-east-2", "us-west-1", "us-west-2"))
 
                 .detail(Map.of(
                         "bucket", Map.of(
                                 "name", Match.anythingButPrefix("foo", "bar", "baz")),
 
                         "object", Map.of(
                                 "key", Match.anythingButSuffix(".gif", ".png", ".jpg")),
 
                         "requester", Match.anythingButWildcard("*.amazonaws.com", "123456789012")))
                 .detailType(Match.anythingButEqualsIgnoreCase("object created", "object deleted"))
                 .build())
         .build();

Scheduling

You can configure a Rule to run on a schedule (cron or rate). Rate must be specified in minutes, hours or days.

The following example runs a task every day at 4am: 

 import software.amazon.awscdk.services.events.Rule;
 import software.amazon.awscdk.services.events.Schedule;
 import software.amazon.awscdk.services.events.targets.EcsTask;
 import software.amazon.awscdk.services.ecs.Cluster;
 import software.amazon.awscdk.services.ecs.TaskDefinition;
 import software.amazon.awscdk.services.iam.Role;
 
 Cluster cluster;
 TaskDefinition taskDefinition;
 Role role;
 
 
 EcsTask ecsTaskTarget = EcsTask.Builder.create().cluster(cluster).taskDefinition(taskDefinition).role(role).build();
 
 Rule.Builder.create(this, "ScheduleRule")
         .schedule(Schedule.cron(CronOptions.builder().minute("0").hour("4").build()))
         .targets(List.of(ecsTaskTarget))
         .build();

If you want to specify Fargate platform version, set platformVersion in EcsTask's props like the following example: 

 Cluster cluster;
 TaskDefinition taskDefinition;
 Role role;
 
 
 FargatePlatformVersion platformVersion = FargatePlatformVersion.VERSION1_4;
 EcsTask ecsTaskTarget = EcsTask.Builder.create().cluster(cluster).taskDefinition(taskDefinition).role(role).platformVersion(platformVersion).build();

Event Targets

The aws-cdk-lib/aws-events-targets module includes classes that implement the IRuleTarget interface for various AWS services.

See the README of the aws-cdk-lib/aws-events-targets module for more information on supported targets.

Cross-account and cross-region targets

It's possible to have the source of the event and a target in separate AWS accounts and regions: 

 import software.amazon.awscdk.App;
 import software.amazon.awscdk.Stack;
 import software.amazon.awscdk.services.codebuild.*;
 import software.amazon.awscdk.services.codecommit.*;
 import software.amazon.awscdk.services.events.targets.*;
 
 App app = new App();
 
 String account1 = "11111111111";
 String account2 = "22222222222";
 
 Stack stack1 = Stack.Builder.create(app, "Stack1").env(Environment.builder().account(account1).region("us-west-1").build()).build();
 Repository repo = Repository.Builder.create(stack1, "Repository")
         .repositoryName("myrepository")
         .build();
 
 Stack stack2 = Stack.Builder.create(app, "Stack2").env(Environment.builder().account(account2).region("us-east-1").build()).build();
 Project project = Project.Builder.create(stack2, "Project").build();
 
 repo.onCommit("OnCommit", OnCommitOptions.builder()
         .target(new CodeBuildProject(project))
         .build());

In this situation, the CDK will wire the 2 accounts together:

  • It will generate a rule in the source stack with the event bus of the target account as the target
  • It will generate a rule in the target stack, with the provided target
  • It will generate a separate stack that gives the source account permissions to publish events to the event bus of the target account in the given region, and make sure its deployed before the source stack

For more information, see the AWS documentation on cross-account events.

Archiving

It is possible to archive all or some events sent to an event bus. It is then possible to replay these events. 

 EventBus bus = EventBus.Builder.create(this, "bus")
         .eventBusName("MyCustomEventBus")
         .description("MyCustomEventBus")
         .build();
 
 bus.archive("MyArchive", BaseArchiveProps.builder()
         .archiveName("MyCustomEventBusArchive")
         .description("MyCustomerEventBus Archive")
         .eventPattern(EventPattern.builder()
                 .account(List.of(Stack.of(this).getAccount()))
                 .build())
         .retention(Duration.days(365))
         .build());

Dead-Letter Queue for EventBus

It is possible to configure a Dead Letter Queue for an EventBus. This is useful when you want to capture events that could not be delivered to any of the targets.

To configure a Dead Letter Queue for an EventBus, you can use the deadLetterQueue property of the EventBus construct. 

 import software.amazon.awscdk.services.sqs.*;
 
 
 Queue dlq = new Queue(this, "DLQ");
 
 EventBus bus = EventBus.Builder.create(this, "Bus")
         .deadLetterQueue(dlq)
         .build();

Granting PutEvents to an existing EventBus

To import an existing EventBus into your CDK application, use EventBus.fromEventBusArn, EventBus.fromEventBusAttributes or EventBus.fromEventBusName factory method.

Then, you can use the grantPutEventsTo method to grant event:PutEvents to the eventBus. 

 Function lambdaFunction;
 
 
 IEventBus eventBus = EventBus.fromEventBusArn(this, "ImportedEventBus", "arn:aws:events:us-east-1:111111111:event-bus/my-event-bus");
 
 // now you can just call methods on the eventbus
 eventBus.grantPutEventsTo(lambdaFunction);

Use a customer managed key

To use a customer managed key for events on the event bus, use the kmsKey attribute. 

 import software.amazon.awscdk.services.kms.*;
 
 IKey kmsKey;
 
 
 EventBus.Builder.create(this, "Bus")
         .kmsKey(kmsKey)
         .build();

To use a customer managed key for an archive, use the kmsKey attribute.

Note: When you attach a customer managed key to either an EventBus or an Archive, a policy that allows EventBridge to interact with your resource will be added. 

 import software.amazon.awscdk.services.kms.*;
 import software.amazon.awscdk.services.events.Archive;
 import software.amazon.awscdk.services.events.EventBus;
 
 IKey kmsKey;
 
 
 Stack stack = new Stack();
 
 EventBus eventBus = new EventBus(stack, "Bus");
 
 Archive archive = Archive.Builder.create(stack, "Archive")
         .kmsKey(kmsKey)
         .sourceEventBus(eventBus)
         .eventPattern(EventPattern.builder()
                 .source(List.of("aws.ec2"))
                 .build())
         .build();

To enable archives or schema discovery on an event bus, customers has the choice of using either an AWS owned key or a customer managed key. For more information, see KMS key options for event bus encryption.

Configuring logging

To configure logging for an Event Bus, leverage the LogConfig property. It allows different level of logging (NONE, INFO, TRACE, ERROR) and wether to include details or not. 

 import software.amazon.awscdk.services.events.EventBus;
 import software.amazon.awscdk.services.events.IncludeDetail;
 import software.amazon.awscdk.services.events.Level;
 
 
 EventBus bus = EventBus.Builder.create(this, "Bus")
         .logConfig(LogConfig.builder()
                 .includeDetail(IncludeDetail.FULL)
                 .level(Level.TRACE)
                 .build())
         .build();

See more Specifying event bus log level