Skip navigation links

@Stability(value=Stable)

Package software.amazon.awscdk.services.events

Amazon CloudWatch Events Construct Library

See: Description

Package software.amazon.awscdk.services.events Description

Amazon CloudWatch Events Construct Library

Stability: Stable

Amazon CloudWatch Events 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 it's state.

Rule

The Rule construct defines a CloudWatch events 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:

// This example is in TypeScript, examples in Java are coming soon.
 const onCommitRule = repo.onCommit('OnCommit', {
   target: new targets.CodeBuildProject(project),
   branches: ['master']
 });

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:

onCommitRule.addTarget(new targets.SnsTopic(topic, {
   message: events.RuleTargetInput.fromText(
     `A commit was pushed to the repository ${codecommit.ReferenceEvent.repositoryName} on branch ${codecommit.ReferenceEvent.referenceName}`
   )
 }));

Scheduling

You can configure a Rule to run on a schedule (cron or rate).

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

import { Rule, Schedule } from '@aws-cdk/aws-events';
 import { EcsTask } from '@aws-cdk/aws-events-targets';
 ...
 
 const ecsTaskTarget = new EcsTask({ cluster, taskDefinition });
 
 new Rule(this, 'ScheduleRule', {
  schedule: Schedule.cron({ minute: '0', hour: '4' }),
  targets: [ecsTaskTarget],
 });

More details in ScheduledEvents documentation page.

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 targets

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

import { App, Stack } from '@aws-cdk/core';
 import codebuild = require('@aws-cdk/aws-codebuild');
 import codecommit = require('@aws-cdk/aws-codecommit');
 import targets = require('@aws-cdk/aws-events-targets');
 
 const app = new App();
 
 const stack1 = new Stack(app, 'Stack1', { env: { account: account1, region: 'us-east-1' } });
 const repo = new codecommit.Repository(stack1, 'Repository', {
   // ...
 });
 
 const stack2 = new Stack(app, 'Stack2', { env: { account: account2, region: 'us-east-1' } });
 const project = new codebuild.Project(stack2, 'Project', {
   // ...
 });
 
 repo.onCommit('OnCommit', {
   target: new targets.CodeBuildProject(project),
 });

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

Note: while events can span multiple accounts, they cannot span different regions (that is a CloudWatch, not CDK, limitation).

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

Skip navigation links

Copyright © 2019. All rights reserved.