Skip navigation links

Package software.amazon.awscdk.services.events

Amazon EventBridge Construct Library

See: Description

Package software.amazon.awscdk.services.events Description

Amazon EventBridge Construct Library

---

cfn-resources: Stable

cdk-constructs: Stable

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.

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());

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/aws-events-targets module includes classes that implement the IRuleTarget interface for various AWS services.

The following targets are supported:

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.core.App;
 import software.amazon.awscdk.core.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:

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")
         .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());

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);
Skip navigation links