class Rule (construct)

Language	Type name
.NET	Amazon.CDK.AWS.Events.Rule
Go	github.com/aws/aws-cdk-go/awscdk/v2/awsevents#Rule
Java	software.amazon.awscdk.services.events.Rule
Python	aws_cdk.aws_events.Rule
TypeScript (source)	aws-cdk-lib » aws_events » Rule

Implements IConstruct, IDependable, IResource, IRule

Defines an EventBridge Rule in this stack.

Example

import * as lambda from 'aws-cdk-lib/aws-lambda';

const fn = new lambda.Function(this, 'MyFunc', {
  runtime: lambda.Runtime.NODEJS_LATEST,
  handler: 'index.handler',
  code: lambda.Code.fromInline(`exports.handler = handler.toString()`),
});

const rule = new events.Rule(this, 'rule', {
  eventPattern: {
    source: ["aws.ec2"],
  },
});

const queue = new sqs.Queue(this, 'Queue');

rule.addTarget(new targets.LambdaFunction(fn, {
  deadLetterQueue: queue, // Optional: add a dead letter queue
  maxEventAge: Duration.hours(2), // Optional: set the maxEventAge retry policy
  retryAttempts: 2, // Optional: set the max number of retry attempts
}));

Initializer

new Rule(scope: Construct, id: string, props?: RuleProps)

Parameters

• scope Construct
• id string
• props RuleProps

Construct Props

Name	Type	Description
crossStackScope?	Construct	The scope to use if the source of the rule and its target are in different Stacks (but in the same account & region).
description?	string	A description of the rule's purpose.
enabled?	boolean	Indicates whether the rule is enabled.
eventBus?	IEventBus	The event bus to associate with this rule.
eventPattern?	EventPattern	Additional restrictions for the event to route to the specified target.
ruleName?	string	A name for the rule.
schedule?	Schedule	The schedule or rate (frequency) that determines when EventBridge runs the rule.
targets?	IRuleTarget[]	Targets to invoke when this rule matches an event.

---

crossStackScope?

Type: Construct (optional, default: none (the main scope will be used, even for cross-stack Events))

The scope to use if the source of the rule and its target are in different Stacks (but in the same account & region).

This helps dealing with cycles that often arise in these situations.

---

description?

Type: string (optional, default: No description)

A description of the rule's purpose.

---

enabled?

Type: boolean (optional, default: true)

Indicates whether the rule is enabled.

---

eventBus?

Type: IEventBus (optional, default: The default event bus.)

The event bus to associate with this rule.

---

eventPattern?

Type: EventPattern (optional, default: No additional filtering based on an event pattern.)

Additional restrictions for the event to route to the specified target.

The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering.

See also: https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html

---

ruleName?

Type: string (optional, default: AWS CloudFormation generates a unique physical ID.)

A name for the rule.

---

schedule?

Type: Schedule (optional, default: None.)

The schedule or rate (frequency) that determines when EventBridge runs the rule.

You must specify this property, the eventPattern property, or both.

For more information, see Schedule Expression Syntax for Rules in the Amazon EventBridge User Guide.

See also: https://docs.aws.amazon.com/eventbridge/latest/userguide/scheduled-events.html

---

targets?

Type: IRuleTarget[] (optional, default: No targets.)

Targets to invoke when this rule matches an event.

Input will be the full matched event. If you wish to specify custom target input, use addTarget(target[, inputOptions]).

Properties

Name	Type	Description
env	ResourceEnvironment	The environment this resource belongs to.
node	Node	The tree node.
ruleArn	string	The value of the event rule Amazon Resource Name (ARN), such as arn:aws:events:us-east-2:123456789012:rule/example.
ruleName	string	The name event rule.
stack	Stack	The stack in which this resource is defined.

---

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

---

node

Type: Node

The tree node.

---

ruleArn

Type: string

The value of the event rule Amazon Resource Name (ARN), such as arn:aws:events:us-east-2:123456789012:rule/example.

---

ruleName

Type: string

The name event rule.

---

stack

Type: Stack

The stack in which this resource is defined.

Methods

Name	Description
addEventPattern(eventPattern?)	Adds an event pattern filter to this rule.
addTarget(target?)	Adds a target to the rule. The abstract class RuleTarget can be extended to define new targets.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
toString()	Returns a string representation of this construct.
protected validateRule()
static fromEventRuleArn(scope, id, eventRuleArn)	Import an existing EventBridge Rule provided an ARN.

---

addEventPattern(eventPattern?)

public addEventPattern(eventPattern?: EventPattern): void

Parameters

• eventPattern EventPattern

Adds an event pattern filter to this rule.

If a pattern was already specified, these values are merged into the existing pattern.

For example, if the rule already contains the pattern:

{ "resources": [ "r1" ], "detail": { "hello": [ 1 ] } }

And addEventPattern is called with the pattern:

{ "resources": [ "r2" ], "detail": { "foo": [ "bar" ] } }

The resulting event pattern will be:

{ "resources": [ "r1", "r2" ], "detail": { "hello": [ 1 ], "foo": [ "bar" ] } }

---

addTarget(target?)

public addTarget(target?: IRuleTarget): void

Parameters

• target IRuleTarget

Adds a target to the rule. The abstract class RuleTarget can be extended to define new targets.

No-op if target is undefined.

---

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

• policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

---

toString()

public toString(): string

Returns

• string

Returns a string representation of this construct.

---

protected validateRule()

protected validateRule(): string[]

Returns

• string[]

---

static fromEventRuleArn(scope, id, eventRuleArn)

public static fromEventRuleArn(scope: Construct, id: string, eventRuleArn: string): IRule

Parameters

• scope Construct — The parent creating construct (usually this).
• id string — The construct's name.
• eventRuleArn string — Event Rule ARN (i.e. arn:aws:events::<account-id>:rule/MyScheduledRule).

Returns

• IRule

Import an existing EventBridge Rule provided an ARN.