0
# AWS CDK Events Targets
1

2
> **⚠️ DEPRECATED:** AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated. Users should migrate to AWS CDK v2. For migration guidance, see the [CDK v2 Migration Guide](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).
3

4
AWS CDK Events Targets provides integration classes to send Amazon EventBridge events to various AWS services. Each target class implements the EventBridge target pattern, allowing developers to easily configure event routing with support for dead letter queues, retry policies, custom input transformation, and IAM role specification.
5

6
## Package Information
7

8
- **Package Name**: @aws-cdk/aws-events-targets
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install @aws-cdk/aws-events-targets`
12
- **License**: Apache-2.0
13
- **CDK Version**: v1 (End-of-Support as of 2023-06-01)
14

15
## Core Imports
16

17
```typescript
18
import * as targets from "@aws-cdk/aws-events-targets";
19
```
20

21
For specific targets:
22

23
```typescript
24
import { 
25
  LambdaFunction, 
26
  SqsQueue, 
27
  SnsTopic, 
28
  EcsTask 
29
} from "@aws-cdk/aws-events-targets";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import * as events from "@aws-cdk/aws-events";
36
import * as lambda from "@aws-cdk/aws-lambda";
37
import * as targets from "@aws-cdk/aws-events-targets";
38

39
// Create a Lambda function
40
const fn = new lambda.Function(this, "MyFunc", {
41
  runtime: lambda.Runtime.NODEJS_14_X,
42
  handler: "index.handler",
43
  code: lambda.Code.fromInline("exports.handler = () => {}"),
44
});
45

46
// Create an EventBridge rule
47
const rule = new events.Rule(this, "MyRule", {
48
  eventPattern: {
49
    source: ["aws.ec2"],
50
  },
51
});
52

53
// Add Lambda function as target
54
rule.addTarget(new targets.LambdaFunction(fn, {
55
  retryAttempts: 2,
56
  maxEventAge: Duration.hours(2),
57
}));
58
```
59

60
## Architecture
61

62
AWS CDK Events Targets is built around several key concepts:
63

64
- **Target Classes**: Each AWS service has a corresponding target class implementing `events.IRuleTarget`
65
- **Configuration Props**: Each target accepts service-specific configuration through props interfaces
66
- **Base Props**: Common configuration options like dead letter queues and retry policies via `TargetBaseProps`
67
- **IAM Integration**: Automatic IAM permission setup for EventBridge to invoke target services
68
- **Error Handling**: Built-in support for dead letter queues and retry policies
69

70
## Capabilities
71

72
### Compute Targets
73

74
Targets for compute services including Lambda functions, ECS tasks, and Batch jobs.
75

76
```typescript { .api }
77
class LambdaFunction implements events.IRuleTarget {
78
  constructor(handler: lambda.IFunction, props?: LambdaFunctionProps);
79
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
80
}
81

82
interface LambdaFunctionProps extends TargetBaseProps {
83
  /** The event to send to the Lambda function as payload (default: entire EventBridge event) */
84
  readonly event?: events.RuleTargetInput;
85
}
86

87
class EcsTask implements events.IRuleTarget {
88
  constructor(props: EcsTaskProps);
89
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
90
}
91

92
class BatchJob implements events.IRuleTarget {
93
  constructor(
94
    jobQueueArn: string,
95
    jobQueueScope: IConstruct,
96
    jobDefinitionArn: string,
97
    jobDefinitionScope: IConstruct,
98
    props?: BatchJobProps
99
  );
100
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
101
}
102

103
interface BatchJobProps extends TargetBaseProps {
104
  /** The event to send to the batch job (default: entire EventBridge event) */
105
  readonly event?: events.RuleTargetInput;
106
  /** The size of the array, if this is an array batch job (valid values: 2-10,000) */
107
  readonly size?: number;
108
  /** The number of times to attempt to retry, if the job fails (valid values: 1-10) */
109
  readonly attempts?: number;
110
  /** The name of the submitted job (default: automatically generated) */
111
  readonly jobName?: string;
112
}
113
```
114

115
[Compute Targets](./compute-targets.md)
116

117
### Messaging Targets
118

119
Targets for messaging services including SQS queues and SNS topics.
120

121
```typescript { .api }
122
class SqsQueue implements events.IRuleTarget {
123
  constructor(queue: sqs.IQueue, props?: SqsQueueProps);
124
  readonly queue: sqs.IQueue;
125
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
126
}
127

128
interface SqsQueueProps extends TargetBaseProps {
129
  /** Message Group ID for messages sent to FIFO queues */
130
  readonly messageGroupId?: string;
131
  /** The message to send to the queue (default: entire EventBridge event) */
132
  readonly message?: events.RuleTargetInput;
133
}
134

135
class SnsTopic implements events.IRuleTarget {
136
  constructor(topic: sns.ITopic, props?: SnsTopicProps);
137
  readonly topic: sns.ITopic;
138
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
139
}
140

141
interface SnsTopicProps {
142
  /** The message to send to the topic (default: entire EventBridge event) */
143
  readonly message?: events.RuleTargetInput;
144
}
145
```
146

147
[Messaging Targets](./messaging-targets.md)
148

149
### API and HTTP Targets
150

151
Targets for API Gateway REST APIs and external HTTP endpoints via API destinations.
152

153
```typescript { .api }
154
class ApiGateway implements events.IRuleTarget {
155
  constructor(restApi: api.RestApi, props?: ApiGatewayProps);
156
  readonly restApi: api.RestApi;
157
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
158
}
159

160
interface ApiGatewayProps extends TargetBaseProps {
161
  /** The method for API resource invoked by the rule (default: '*' treated as ANY) */
162
  readonly method?: string;
163
  /** The API resource invoked by the rule (default: '/') */
164
  readonly path?: string;
165
  /** The deploy stage of API gateway invoked by the rule */
166
  readonly stage?: string;
167
  /** The headers to be set when requesting API */
168
  readonly headerParameters?: { [key: string]: string };
169
  /** The path parameter values to populate wildcards in API path */
170
  readonly pathParameterValues?: string[];
171
  /** The query parameters to be set when requesting API */
172
  readonly queryStringParameters?: { [key: string]: string };
173
  /** The post request body sent to the API (default: entire EventBridge event) */
174
  readonly postBody?: events.RuleTargetInput;
175
  /** The role to assume before invoking the target (default: new role created) */
176
  readonly eventRole?: iam.IRole;
177
}
178

179
class ApiDestination implements events.IRuleTarget {
180
  constructor(apiDestination: events.IApiDestination, props?: ApiDestinationProps);
181
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
182
}
183

184
interface ApiDestinationProps extends TargetBaseProps {
185
  /** The event to send (default: entire EventBridge event) */
186
  readonly event?: events.RuleTargetInput;
187
  /** The role to assume before invoking the target (default: new role created) */
188
  readonly eventRole?: iam.IRole;
189
  /** Additional headers sent to the API Destination */
190
  readonly headerParameters?: Record<string, string>;
191
  /** Path parameters to insert in place of path wildcards */
192
  readonly pathParameterValues?: string[];
193
  /** Additional query string parameters sent to the API Destination */
194
  readonly queryStringParameters?: Record<string, string>;
195
}
196
```
197

198
[API and HTTP Targets](./api-targets.md)
199

200
### CI/CD Targets
201

202
Targets for continuous integration and deployment services including CodeBuild and CodePipeline.
203

204
```typescript { .api }
205
class CodeBuildProject implements events.IRuleTarget {
206
  constructor(project: codebuild.IProject, props?: CodeBuildProjectProps);
207
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
208
}
209

210
interface CodeBuildProjectProps extends TargetBaseProps {
211
  /** The role to assume before invoking the target (default: new role created) */
212
  readonly eventRole?: iam.IRole;
213
  /** The event to send to CodeBuild as StartBuild API payload (default: entire EventBridge event) */
214
  readonly event?: events.RuleTargetInput;
215
}
216

217
class CodePipeline implements events.IRuleTarget {
218
  constructor(pipeline: codepipeline.IPipeline, options?: CodePipelineTargetOptions);
219
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
220
}
221

222
interface CodePipelineTargetOptions extends TargetBaseProps {
223
  /** The role to assume before invoking the pipeline (default: new role created) */
224
  readonly eventRole?: iam.IRole;
225
}
226
```
227

228
[CI/CD Targets](./cicd-targets.md)
229

230
### Analytics and Logging Targets
231

232
Targets for data streaming, analytics, and logging services including Kinesis, CloudWatch Logs, and Kinesis Data Firehose.
233

234
```typescript { .api }
235
class KinesisStream implements events.IRuleTarget {
236
  constructor(stream: kinesis.IStream, props?: KinesisStreamProps);
237
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
238
}
239

240
class CloudWatchLogGroup implements events.IRuleTarget {
241
  constructor(logGroup: logs.ILogGroup, props?: LogGroupProps);
242
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
243
}
244

245
class KinesisFirehoseStream implements events.IRuleTarget {
246
  constructor(stream: firehose.CfnDeliveryStream, props?: KinesisFirehoseStreamProps);
247
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
248
}
249
```
250

251
[Analytics and Logging Targets](./analytics-targets.md)
252

253
### Orchestration Targets
254

255
Targets for workflow orchestration including Step Functions state machines.
256

257
```typescript { .api }
258
class SfnStateMachine implements events.IRuleTarget {
259
  constructor(machine: sfn.IStateMachine, props?: SfnStateMachineProps);
260
  readonly machine: sfn.IStateMachine;
261
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
262
}
263
```
264

265
[Orchestration Targets](./orchestration-targets.md)
266

267
### System Targets
268

269
Targets for AWS system services including EventBridge buses and AWS API calls.
270

271
```typescript { .api }
272
class EventBus implements events.IRuleTarget {
273
  constructor(eventBus: events.IEventBus, props?: EventBusProps);
274
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
275
}
276

277
class AwsApi implements events.IRuleTarget {
278
  constructor(props: AwsApiProps);
279
  bind(rule: events.IRule, id?: string): events.RuleTargetConfig;
280
}
281
```
282

283
[System Targets](./system-targets.md)
284

285
## Base Configuration
286

287
### Target Base Properties
288

289
Common configuration options available for most targets.
290

291
```typescript { .api }
292
interface TargetBaseProps {
293
  /** SQS queue for failed event deliveries */
294
  readonly deadLetterQueue?: sqs.IQueue;
295
  /** Maximum age of requests sent to target */
296
  readonly maxEventAge?: Duration;
297
  /** Maximum number of retry attempts */
298
  readonly retryAttempts?: number;
299
}
300
```
301

302
### Container Configuration
303

304
Configuration for ECS task container overrides.
305

306
```typescript { .api }
307
interface ContainerOverride {
308
  /** Name of the container inside task definition */
309
  readonly containerName: string;
310
  /** Command to run inside container */
311
  readonly command?: string[];
312
  /** Environment variables to set */
313
  readonly environment?: TaskEnvironmentVariable[];
314
  /** CPU units reserved for container */
315
  readonly cpu?: number;
316
  /** Hard memory limit on container */
317
  readonly memoryLimit?: number;
318
  /** Soft memory limit on container */
319
  readonly memoryReservation?: number;
320
}
321

322
interface TaskEnvironmentVariable {
323
  /** Name for the environment variable (exactly one of name and namePath must be specified) */
324
  readonly name: string;
325
  /** Value of the environment variable (exactly one of value and valuePath must be specified) */
326
  readonly value: string;
327
}
328
```
329

330
## Utilities
331

332
### Permission Management
333

334
Utility functions for managing IAM permissions and resource policies.
335

336
```typescript { .api }
337
function addLambdaPermission(rule: events.IRule, handler: lambda.IFunction): void;
338
function addToDeadLetterQueueResourcePolicy(rule: events.IRule, queue: sqs.IQueue): void;
339
function singletonEventRole(scope: IConstruct): iam.IRole;
340
function bindBaseTargetConfig(props: TargetBaseProps): object;
341
```