What is @aws-cdk/aws-events?
@aws-cdk/aws-events is an AWS Cloud Development Kit (CDK) library that allows you to define and manage Amazon EventBridge resources using code. EventBridge is a serverless event bus that makes it easier to build event-driven applications by connecting application data from your own applications, integrated Software-as-a-Service (SaaS) applications, and AWS services.
What are @aws-cdk/aws-events's main functionalities?
Creating an Event Bus
This code sample demonstrates how to create a new EventBridge event bus using the AWS CDK. The event bus can be used to receive and route events.
const events = require('@aws-cdk/aws-events');
const cdk = require('@aws-cdk/core');
const app = new cdk.App();
const stack = new cdk.Stack(app, 'EventBusStack');
const eventBus = new events.EventBus(stack, 'MyEventBus', {
eventBusName: 'my-event-bus'
});
app.synth();
Creating a Rule
This code sample demonstrates how to create an EventBridge rule that triggers when an EC2 instance changes state to 'running'. The rule targets a Lambda function.
const events = require('@aws-cdk/aws-events');
const targets = require('@aws-cdk/aws-events-targets');
const cdk = require('@aws-cdk/core');
const app = new cdk.App();
const stack = new cdk.Stack(app, 'EventRuleStack');
const rule = new events.Rule(stack, 'MyRule', {
eventPattern: {
source: ['aws.ec2'],
detailType: ['EC2 Instance State-change Notification'],
detail: {
state: ['running']
}
}
});
rule.addTarget(new targets.LambdaFunction(myLambdaFunction));
app.synth();
Scheduling Events
This code sample demonstrates how to create a scheduled EventBridge rule that triggers every 5 minutes. The rule targets a Lambda function.
const events = require('@aws-cdk/aws-events');
const targets = require('@aws-cdk/aws-events-targets');
const cdk = require('@aws-cdk/core');
const app = new cdk.App();
const stack = new cdk.Stack(app, 'ScheduledEventStack');
const rule = new events.Rule(stack, 'MyScheduledRule', {
schedule: events.Schedule.rate(cdk.Duration.minutes(5))
});
rule.addTarget(new targets.LambdaFunction(myLambdaFunction));
app.synth();
Other packages similar to @aws-cdk/aws-events
aws-sdk
The aws-sdk package is the official AWS SDK for JavaScript, which provides a comprehensive set of tools for interacting with AWS services, including EventBridge. Unlike @aws-cdk/aws-events, which is used for defining infrastructure as code, aws-sdk is used for making API calls to AWS services.
serverless
The serverless framework is a popular open-source framework for building and deploying serverless applications. It supports AWS Lambda and EventBridge, among other services. While @aws-cdk/aws-events focuses on infrastructure as code, serverless provides a higher-level abstraction for deploying serverless applications.
pulumi
Pulumi is an infrastructure as code tool that supports multiple cloud providers, including AWS. It allows you to define and manage cloud resources using familiar programming languages. Pulumi can be used to manage EventBridge resources similarly to @aws-cdk/aws-events, but it offers a different approach and supports multiple clouds.
AWS CloudWatch Events Construct Library
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.
- 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
CloudWatch Events. 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 CloudWatch Events 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, 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.
The EventRule
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 IEventTarget
interface.
Normally, you will use one of the source.onXxx(name[, target[, options]]) -> EventRule
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:
const onCommitRule = repo.onCommit('OnCommitToMaster', project, '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(topic, {
template: 'A commit was pushed to the repository <repo> on branch <branch>',
pathsMap: {
branch: '$.detail.referenceName',
repo: '$.detail.repositoryName'
}
});
0.11.0 (2018-10-11)
IMPORTANT NOTE: This release includes a breaking change in the toolkit <=> app protocol. This means that in order to synthesize CDK apps that use this version, the globally installed CDK toolkit must also be updated:
$ npm i -g aws-cdk
$ cdk --version
0.11.0 (build ...)
Like always, you will also need to update your project's library versions:
Language | Update?
--------------------------- | ------------------------------------------------------------------------------------------------------------------
JavaScript/TypeScript (npm) | npx npm-check-updates -u
Java (maven) | mvn versions:use-latest-versions
.NET (NuGet) | nuget update
Bug Fixes
- aws-apigateway: allow + in path parts (#769) (0c50d27), closes #768
- aws-cdk: continue after exceptions in stack monitor (#791) (b0f3298), closes #787
- aws-cloudfront: check for undefined and determining of the defaultRootObject prop is set or not (#801) (32a74c6)
- aws-cloudfront: properly support loggingConfig (#809) (5512f70), closes #721
- aws-codecommit: typo in README (#780) (0e79c2d)
- aws-ec2: Add Burstable Generation 3 Instances (#812) (d36ee6d)
- aws-ec2: fix capitalization of "VPCEndpointType" to "VpcEndpointType" (#789) (7a8ee2c), closes #765
- aws-ec2: fix typo in resource identifier (#818) (f529c80)
- aws-elbv2: fix load balancer registration (#890) (8cc9abe)
- aws-s3: properly export bucketDomainName (#844) (a65060d)
- aws-sqs: Queue.import() doesn't return a value (#885) (c592b7f), closes #879
- cdk: fix TagManager to evaluate to undefined if no tags are included (#882) (477c827)
- cdk: init templates were not upgraded to typescript ^3.0.0 (#904) (2cc7475)
- cdk: jsx support conflicts with React usage (#884) (76d8031), closes #830
- cfn2ts: expect Token instead of CloudFormationToken (#896) (6eee1d2)
- docs: fix issue #718 (Aurora DB example) (#783) (016f3a8)
- docs: update supported languages in README (#819, #450) (#820) (ffac98c)
- Correct heading level of CHANGELOG.md 0.10.0 (40d9ef0)
- Emit valid YAML-1.1 (#876) (ff857ea), closes #875
- toolkit: improve error message for large templates (#900) (a41f48f), closes #34
Code Refactoring
Features
- aws-apigateway: "LambdaRestApi" and "addProxy" routes (#867) (905a95d)
- aws-cdk: add maven wrapper to java template (#811) (72aa872)
- aws-cloudformation: rename the CFN CodePipeline Actions. (#771) (007e7b4)
- aws-cloudformation: update the ReadMe of the module to reflect the new Action names. (#775) (6c0e75b), closes #771
- aws-cloudfront: Support Security Policy (#804) (b39bf11), closes #795
- aws-codedeploy: Add the auto-scaling groups property to ServerDeploymentGroup. (#739) (0b28886)
- aws-codedeploy: Deployment Configuration Construct. (#653) (e6b67ad)
- aws-codedeploy: support setting a load balancer on a Deployment Group. (#786) (e7af9f5)
- aws-codepipeline: allow specifying the runOrder property when creating Actions. (#776) (d146c8d)
- aws-codepipeline, aws-codecommit, aws-s3: change the convention for naming the source Actions to XxxSourceAction. (#753) (9c3ce7f)
- aws-dynamodb: IAM grants support (#870) (c5a4200)
- aws-dynamodb: support Global Secondary Indexes (#760) (3601440)
- aws-dynamodb: tags support (#814) (924c84e)
- aws-dynamodB: support Local Secondary Indexes (#825) (3175af3)
- aws-ec2: add support for ICMP protocol's classification Types & Codes to SecurityGroupRule (#893) (85bd3c0)
- aws-ec2: allow configuring subnets for NAT gateway (#874) (8ec761c)
- aws-ec2: support UDP port ranges in SecurityGroups (#835) (b42ef90)
- aws-elasticloadbalancingv2: support for ALB/NLB (#750) (bd9ee01)
- aws-s3: support granting public access to objects (#886) (bdee191), closes #877
- cdk: Add support for UseOnlineResharding with UpdatePolicies (#881) (1f717e1)
- cdk: configurable default SSM context provider (#889) (353412b)
- core: resource overrides (escape hatch) (#784) (5054eef), closes #606
- aws-codepipeline: Manage IAM permissions for (some) CFN CodePipeline actions (#843) (4c69118)
- toolkit: Stop creating 'empty' stacks (#779) (1dddd8a)
- aws-autoscaling, aws-ec2: Tagging support for AutoScaling/SecurityGroup (#766) (3d48eb2)
BREAKING CHANGES TO EXPERIMENTAL FEATURES
-
framework: The cdk.App
constructor doesn't accept any arguments, and app.run()
does not return a string
anymore. All AWS CDK apps in all languages would need to be modified to adhere to the new API of the cdk.App
construct.
Instead of:
const app = new App(process.argv); // ERROR
// add stacks
process.stdout.write(app.run()); // ERROR
The new usage is:
const app = new App();
// add stacks
app.run();
-
framework: The CDK is no longer shipped with built-in support for JSX. You can still use JSX but you will have to manually configure it.
-
aws-iam: PolicyDocument
, PolicyStatement
and all PolicyPrincipal
classes moved from the @aws-cdk/cdk module and into the @aws-cdk/aws-iam module.
-
aws-codepipeline-api: Artifact.subartifact
method of the CodePipeline API was renamed to Artifact.atPath
.
-
constructor signature of TagManager
has changed. initialTags
is now passed inside a props object.
-
util: @aws-cdk/util is no longer available
-
aws-elasticloadbalancingv2: Adds classes for modeling Application and Network Load Balancers. AutoScalingGroups now implement the interface that makes constructs a load balancing target. The breaking change is that Security Group rule identifiers have been changed in order to make adding rules more reliable. No code changes are necessary but existing deployments may experience unexpected changes.
-
aws-cloudformation: this renames all CloudFormation Actions for CodePipeline to bring them in line with Actions defined in other service packages.
-
aws-codepipeline, aws-codecommit, aws-s3: change the names of the source Actions from XxxSource to XxxSourceAction. This is to align them with the other Actions, like Build. Also, CodeBuild has the concept of Sources, so it makes sense to strongly differentiate between the two.