Package software.amazon.awscdk.services.events.targets
Event Targets for Amazon EventBridge
This library contains integration classes to send Amazon EventBridge to any
number of supported AWS Services. Instances of these classes should be passed
to the rule.addTarget()
method.
Currently supported are:
- Event Targets for Amazon EventBridge
- Event retry policy and using dead-letter queues
- Invoke a Lambda function
- Log an event into a LogGroup
- Start a CodeBuild build
- Start a CodePipeline pipeline
- Start a StepFunctions state machine
- Queue a Batch job
- Invoke an API Gateway REST API
- Invoke an API Destination
- Invoke an AppSync GraphQL API
- Put an event on an EventBridge bus
- Run an ECS Task
- Run a Redshift query
See the README of the aws-cdk-lib/aws-events
library for more information on
EventBridge.
Event retry policy and using dead-letter queues
The Codebuild, CodePipeline, Lambda, Kinesis Data Streams, StepFunctions, LogGroup, SQSQueue, SNSTopic and ECSTask targets support attaching a dead letter queue and setting retry policies. See the lambda example. Use escape hatches for the other target types.
Invoke a Lambda function
Use the LambdaFunction
target to invoke a lambda function.
The code snippet below creates an event rule with a Lambda function as a target
triggered for every events from aws.ec2
source. You can optionally attach a
dead letter queue.
import software.amazon.awscdk.services.lambda.*; Function fn = Function.Builder.create(this, "MyFunc") .runtime(Runtime.NODEJS_LATEST) .handler("index.handler") .code(Code.fromInline("exports.handler = handler.toString()")) .build(); Rule rule = Rule.Builder.create(this, "rule") .eventPattern(EventPattern.builder() .source(List.of("aws.ec2")) .build()) .build(); Queue queue = new Queue(this, "Queue"); rule.addTarget(LambdaFunction.Builder.create(fn) .deadLetterQueue(queue) // Optional: add a dead letter queue .maxEventAge(Duration.hours(2)) // Optional: set the maxEventAge retry policy .retryAttempts(2) .build());
Log an event into a LogGroup
Use the LogGroup
target to log your events in a CloudWatch LogGroup.
For example, the following code snippet creates an event rule with a CloudWatch LogGroup as a target.
Every events sent from the aws.ec2
source will be sent to the CloudWatch LogGroup.
import software.amazon.awscdk.services.logs.*; LogGroup logGroup = LogGroup.Builder.create(this, "MyLogGroup") .logGroupName("MyLogGroup") .build(); Rule rule = Rule.Builder.create(this, "rule") .eventPattern(EventPattern.builder() .source(List.of("aws.ec2")) .build()) .build(); rule.addTarget(new CloudWatchLogGroup(logGroup));
A rule target input can also be specified to modify the event that is sent to the log group. Unlike other event targets, CloudWatchLogs requires a specific input template format.
import software.amazon.awscdk.services.logs.*; LogGroup logGroup; Rule rule; rule.addTarget(CloudWatchLogGroup.Builder.create(logGroup) .logEvent(LogGroupTargetInput.fromObject(LogGroupTargetInputOptions.builder() .timestamp(EventField.fromPath("$.time")) .message(EventField.fromPath("$.detail-type")) .build())) .build());
If you want to use static values to overwrite the message
make sure that you provide a string
value.
import software.amazon.awscdk.services.logs.*; LogGroup logGroup; Rule rule; rule.addTarget(CloudWatchLogGroup.Builder.create(logGroup) .logEvent(LogGroupTargetInput.fromObject(LogGroupTargetInputOptions.builder() .message(JSON.stringify(Map.of( "CustomField", "CustomValue"))) .build())) .build());
The cloudwatch log event target will create an AWS custom resource internally which will default
to set installLatestAwsSdk
to true
. This may be problematic for CN partition deployment. To
workaround this issue, set installLatestAwsSdk
to false
.
import software.amazon.awscdk.services.logs.*; LogGroup logGroup; Rule rule; rule.addTarget(CloudWatchLogGroup.Builder.create(logGroup) .installLatestAwsSdk(false) .build());
Start a CodeBuild build
Use the CodeBuildProject
target to trigger a CodeBuild project.
The code snippet below creates a CodeCommit repository that triggers a CodeBuild project on commit to the master branch. You can optionally attach a dead letter queue.
import software.amazon.awscdk.services.codebuild.*; import software.amazon.awscdk.services.codecommit.*; Repository repo = Repository.Builder.create(this, "MyRepo") .repositoryName("aws-cdk-codebuild-events") .build(); Project project = Project.Builder.create(this, "MyProject") .source(Source.codeCommit(CodeCommitSourceProps.builder().repository(repo).build())) .build(); Queue deadLetterQueue = new Queue(this, "DeadLetterQueue"); // trigger a build when a commit is pushed to the repo Rule onCommitRule = repo.onCommit("OnCommit", OnCommitOptions.builder() .target(CodeBuildProject.Builder.create(project) .deadLetterQueue(deadLetterQueue) .build()) .branches(List.of("master")) .build());
Start a CodePipeline pipeline
Use the CodePipeline
target to trigger a CodePipeline pipeline.
The code snippet below creates a CodePipeline pipeline that is triggered every hour
import software.amazon.awscdk.services.codepipeline.*; Pipeline pipeline = new Pipeline(this, "Pipeline"); Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.expression("rate(1 hour)")) .build(); rule.addTarget(new CodePipeline(pipeline));
Start a StepFunctions state machine
Use the SfnStateMachine
target to trigger a State Machine.
The code snippet below creates a Simple StateMachine that is triggered every minute with a dummy object as input. You can optionally attach a dead letter queue to the target.
import software.amazon.awscdk.services.iam.*; import software.amazon.awscdk.services.stepfunctions.*; Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.minutes(1))) .build(); Queue dlq = new Queue(this, "DeadLetterQueue"); Role role = Role.Builder.create(this, "Role") .assumedBy(new ServicePrincipal("events.amazonaws.com")) .build(); StateMachine stateMachine = StateMachine.Builder.create(this, "SM") .definition(Wait.Builder.create(this, "Hello").time(WaitTime.duration(Duration.seconds(10))).build()) .build(); rule.addTarget(SfnStateMachine.Builder.create(stateMachine) .input(RuleTargetInput.fromObject(Map.of("SomeParam", "SomeValue"))) .deadLetterQueue(dlq) .role(role) .build());
Queue a Batch job
Use the BatchJob
target to queue a Batch job.
The code snippet below creates a Simple JobQueue that is triggered every hour with a dummy object as input. You can optionally attach a dead letter queue to the target.
import software.amazon.awscdk.services.ec2.*; import software.amazon.awscdk.services.ecs.*; import software.amazon.awscdk.services.batch.*; import software.amazon.awscdk.services.ecs.ContainerImage; Vpc vpc; FargateComputeEnvironment computeEnvironment = FargateComputeEnvironment.Builder.create(this, "ComputeEnv") .vpc(vpc) .build(); JobQueue jobQueue = JobQueue.Builder.create(this, "JobQueue") .priority(1) .computeEnvironments(List.of(OrderedComputeEnvironment.builder() .computeEnvironment(computeEnvironment) .order(1) .build())) .build(); EcsJobDefinition jobDefinition = EcsJobDefinition.Builder.create(this, "MyJob") .container(EcsEc2ContainerDefinition.Builder.create(this, "Container") .image(ContainerImage.fromRegistry("test-repo")) .memory(Size.mebibytes(2048)) .cpu(256) .build()) .build(); Queue queue = new Queue(this, "Queue"); Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.hours(1))) .build(); rule.addTarget(BatchJob.Builder.create(jobQueue.getJobQueueArn(), jobQueue, jobDefinition.getJobDefinitionArn(), jobDefinition) .deadLetterQueue(queue) .event(RuleTargetInput.fromObject(Map.of("SomeParam", "SomeValue"))) .retryAttempts(2) .maxEventAge(Duration.hours(2)) .build());
Invoke an API Gateway REST API
Use the ApiGateway
target to trigger a REST API.
The code snippet below creates a Api Gateway REST API that is invoked every hour.
import software.amazon.awscdk.services.apigateway.*; import software.amazon.awscdk.services.lambda.*; Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.minutes(1))) .build(); Function fn = Function.Builder.create(this, "MyFunc") .handler("index.handler") .runtime(Runtime.NODEJS_LATEST) .code(Code.fromInline("exports.handler = e => {}")) .build(); LambdaRestApi restApi = LambdaRestApi.Builder.create(this, "MyRestAPI").handler(fn).build(); Queue dlq = new Queue(this, "DeadLetterQueue"); rule.addTarget( ApiGateway.Builder.create(restApi) .path("/*/test") .method("GET") .stage("prod") .pathParameterValues(List.of("path-value")) .headerParameters(Map.of( "Header1", "header1")) .queryStringParameters(Map.of( "QueryParam1", "query-param-1")) .deadLetterQueue(dlq) .build());
Invoke an API Destination
Use the targets.ApiDestination
target to trigger an external API. You need to
create an events.Connection
and events.ApiDestination
as well.
The code snippet below creates an external destination that is invoked every hour.
Connection connection = Connection.Builder.create(this, "Connection") .authorization(Authorization.apiKey("x-api-key", SecretValue.secretsManager("ApiSecretName"))) .description("Connection with API Key x-api-key") .build(); ApiDestination destination = ApiDestination.Builder.create(this, "Destination") .connection(connection) .endpoint("https://example.com") .description("Calling example.com with API key x-api-key") .build(); Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.minutes(1))) .targets(List.of(new ApiDestination(destination))) .build();
You can also import an existing connection and destination to create additional rules:
IConnection connection = Connection.fromEventBusArn(this, "Connection", "arn:aws:events:us-east-1:123456789012:event-bus/EventBusName", "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretName-f3gDy9"); String apiDestinationArn = "arn:aws:events:us-east-1:123456789012:api-destination/DestinationName"; ApiDestination destination = ApiDestination.fromApiDestinationAttributes(this, "Destination", ApiDestinationAttributes.builder().apiDestinationArn(apiDestinationArn).connection(connection).build()); Rule rule = Rule.Builder.create(this, "OtherRule") .schedule(Schedule.rate(Duration.minutes(10))) .targets(List.of(new ApiDestination(destination))) .build();
Invoke an AppSync GraphQL API
Use the AppSync
target to trigger an AppSync GraphQL API. You need to
create an AppSync.GraphqlApi
configured with AWS_IAM
authorization mode.
The code snippet below creates an AppSync GraphQL API target that is invoked every hour, calling the publish
mutation.
import software.amazon.awscdk.services.appsync.*; GraphqlApi api = GraphqlApi.Builder.create(this, "api") .name("api") .definition(Definition.fromFile("schema.graphql")) .authorizationConfig(AuthorizationConfig.builder() .defaultAuthorization(AuthorizationMode.builder().authorizationType(AuthorizationType.IAM).build()) .build()) .build(); Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.hours(1))) .build(); rule.addTarget(AppSync.Builder.create(api) .graphQLOperation("mutation Publish($message: String!){ publish(message: $message) { message } }") .variables(RuleTargetInput.fromObject(Map.of( "message", "hello world"))) .build());
You can pass an existing role with the proper permissions to be used for the target when the rule is triggered. The code snippet below uses an existing role and grants permissions to use the publish Mutation on the GraphQL API.
import software.amazon.awscdk.services.iam.*; import software.amazon.awscdk.services.appsync.*; IGraphqlApi api = GraphqlApi.fromGraphqlApiAttributes(this, "ImportedAPI", GraphqlApiAttributes.builder() .graphqlApiId("<api-id>") .graphqlApiArn("<api-arn>") .graphQLEndpointArn("<api-endpoint-arn>") .visibility(Visibility.GLOBAL) .modes(List.of(AuthorizationType.IAM)) .build()); Rule rule = Rule.Builder.create(this, "Rule").schedule(Schedule.rate(Duration.minutes(1))).build(); Role role = Role.Builder.create(this, "Role").assumedBy(new ServicePrincipal("events.amazonaws.com")).build(); // allow EventBridge to use the `publish` mutation api.grantMutation(role, "publish"); rule.addTarget(AppSync.Builder.create(api) .graphQLOperation("mutation Publish($message: String!){ publish(message: $message) { message } }") .variables(RuleTargetInput.fromObject(Map.of( "message", "hello world"))) .eventRole(role) .build());
Put an event on an EventBridge bus
Use the EventBus
target to route event to a different EventBus.
The code snippet below creates the scheduled event rule that route events to an imported event bus.
Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.expression("rate(1 minute)")) .build(); rule.addTarget(new EventBus(EventBus.fromEventBusArn(this, "External", "arn:aws:events:eu-west-1:999999999999:event-bus/test-bus")));
Run an ECS Task
Use the EcsTask
target to run an ECS Task.
The code snippet below creates a scheduled event rule that will run the task described in taskDefinition
every hour.
Tagging Tasks
By default, ECS tasks run from EventBridge targets will not have tags applied to
them. You can set the propagateTags
field to propagate the tags set on the task
definition to the task initialized by the event trigger.
If you want to set tags independent of those applied to the TaskDefinition, you
can use the tags
array. Both of these fields can be used together or separately
to set tags on the triggered task.
import software.amazon.awscdk.services.ecs.*; ICluster cluster; TaskDefinition taskDefinition; Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.hours(1))) .build(); rule.addTarget( EcsTask.Builder.create() .cluster(cluster) .taskDefinition(taskDefinition) .propagateTags(PropagatedTagSource.TASK_DEFINITION) .tags(List.of(Tag.builder() .key("my-tag") .value("my-tag-value") .build())) .build());
Launch type for ECS Task
By default, if isEc2Compatible
for the taskDefinition
is true, the EC2 type is used as
the launch type for the task, otherwise the FARGATE type.
If you want to override the default launch type, you can set the launchType
property.
import software.amazon.awscdk.services.ecs.*; ICluster cluster; TaskDefinition taskDefinition; Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.hours(1))) .build(); rule.addTarget(EcsTask.Builder.create() .cluster(cluster) .taskDefinition(taskDefinition) .launchType(LaunchType.FARGATE) .build());
Assign public IP addresses to tasks
You can set the assignPublicIp
flag to assign public IP addresses to tasks.
If you want to detach the public IP address from the task, you have to set the flag false
.
You can specify the flag true
only when the launch type is set to FARGATE.
import software.amazon.awscdk.services.ecs.*; import software.amazon.awscdk.services.ec2.*; ICluster cluster; TaskDefinition taskDefinition; Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.hours(1))) .build(); rule.addTarget( EcsTask.Builder.create() .cluster(cluster) .taskDefinition(taskDefinition) .assignPublicIp(true) .subnetSelection(SubnetSelection.builder().subnetType(SubnetType.PUBLIC).build()) .build());
Enable Amazon ECS Exec for ECS Task
If you use Amazon ECS Exec, you can run commands in or get a shell to a container running on an Amazon EC2 instance or on AWS Fargate.
import software.amazon.awscdk.services.ecs.*; ICluster cluster; TaskDefinition taskDefinition; Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.hours(1))) .build(); rule.addTarget(EcsTask.Builder.create() .cluster(cluster) .taskDefinition(taskDefinition) .taskCount(1) .containerOverrides(List.of(ContainerOverride.builder() .containerName("TheContainer") .command(List.of("echo", EventField.fromPath("$.detail.event"))) .build())) .enableExecuteCommand(true) .build());
Schedule a Redshift query (serverless or cluster)
Use the RedshiftQuery
target to schedule an Amazon Redshift Query.
The code snippet below creates the scheduled event rule that route events to an Amazon Redshift Query
import software.amazon.awscdk.services.redshiftserverless.*; CfnWorkgroup workgroup; Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.rate(Duration.hours(1))) .build(); Queue dlq = new Queue(this, "DeadLetterQueue"); rule.addTarget(RedshiftQuery.Builder.create(workgroup.getAttrWorkgroupWorkgroupArn()) .database("dev") .deadLetterQueue(dlq) .sql(List.of("SELECT * FROM foo", "SELECT * FROM baz")) .build());
-
ClassDescriptionUse an API Destination rule target.A fluent builder for
ApiDestination
.Customize the EventBridge Api Destinations Target.A builder forApiDestinationProps
An implementation forApiDestinationProps
Use an API Gateway REST APIs as a target for Amazon EventBridge rules.A fluent builder forApiGateway
.Customize the API Gateway Event Target.A builder forApiGatewayProps
An implementation forApiGatewayProps
Use an AppSync GraphQL API as a target for Amazon EventBridge rules.A fluent builder forAppSync
.Customize the AppSync GraphQL API target.A builder forAppSyncGraphQLApiProps
An implementation forAppSyncGraphQLApiProps
Use an AWS Lambda function that makes API calls as an event rule target.A fluent builder forAwsApi
.Rule target input for an AwsApi target.A builder forAwsApiInput
An implementation forAwsApiInput
Properties for an AwsApi target.A builder forAwsApiProps
An implementation forAwsApiProps
Use an AWS Batch Job / Queue as an event rule target.A fluent builder forBatchJob
.Customize the Batch Job Event Target.A builder forBatchJobProps
An implementation forBatchJobProps
Use an AWS CloudWatch LogGroup as an event rule target.A fluent builder forCloudWatchLogGroup
.Start a CodeBuild build when an Amazon EventBridge rule is triggered.A fluent builder forCodeBuildProject
.Customize the CodeBuild Event Target.A builder forCodeBuildProjectProps
An implementation forCodeBuildProjectProps
Allows the pipeline to be used as an EventBridge rule target.A fluent builder forCodePipeline
.Customization options when creating aCodePipeline
event target.A builder forCodePipelineTargetOptions
An implementation forCodePipelineTargetOptions
Example:A builder forContainerOverride
An implementation forContainerOverride
Start a task on an ECS cluster.A fluent builder forEcsTask
.Properties to define an ECS Event Task.A builder forEcsTaskProps
An implementation forEcsTaskProps
Notify an existing Event Bus of an event.A fluent builder forEventBus
.Configuration properties of an Event Bus event.A builder forEventBusProps
An implementation forEventBusProps
Represents a Kinesis Data Firehose delivery stream.Internal default implementation forIDeliveryStream
.A proxy class which represents a concrete javascript instance of this type.Deprecated.Use KinesisFirehoseStreamV2Deprecated.Customize the Firehose Stream Event Target.A builder forKinesisFirehoseStreamProps
An implementation forKinesisFirehoseStreamProps
Customize the Firehose Stream Event Target V2 to support L2 Kinesis Delivery Stream instead of L1 Cfn Kinesis Delivery Stream.A fluent builder forKinesisFirehoseStreamV2
.Use a Kinesis Stream as a target for AWS CloudWatch event rules.A fluent builder forKinesisStream
.Customize the Kinesis Stream Event Target.A builder forKinesisStreamProps
An implementation forKinesisStreamProps
Use an AWS Lambda function as an event rule target.A fluent builder forLambdaFunction
.Customize the Lambda Event Target.A builder forLambdaFunctionProps
An implementation forLambdaFunctionProps
Customize the CloudWatch LogGroup Event Target.A builder forLogGroupProps
An implementation forLogGroupProps
The input to send to the CloudWatch LogGroup target.Options used when creating a target input template.A builder forLogGroupTargetInputOptions
An implementation forLogGroupTargetInputOptions
Schedule an Amazon Redshift Query to be run, using the Redshift Data API.A fluent builder forRedshiftQuery
.Configuration properties of an Amazon Redshift Query event.A builder forRedshiftQueryProps
An implementation forRedshiftQueryProps
Use a StepFunctions state machine as a target for Amazon EventBridge rules.A fluent builder forSfnStateMachine
.Customize the Step Functions State Machine target.A builder forSfnStateMachineProps
An implementation forSfnStateMachineProps
Use an SNS topic as a target for Amazon EventBridge rules.A fluent builder forSnsTopic
.Customize the SNS Topic Event Target.A builder forSnsTopicProps
An implementation forSnsTopicProps
Use an SQS Queue as a target for Amazon EventBridge rules.A fluent builder forSqsQueue
.Customize the SQS Queue Event Target.A builder forSqsQueueProps
An implementation forSqsQueueProps
Metadata that you apply to a resource to help categorize and organize the resource.A builder forTag
An implementation forTag
The generic properties for an RuleTarget.A builder forTargetBaseProps
An implementation forTargetBaseProps
An environment variable to be set in the container run as a task.A builder forTaskEnvironmentVariable
An implementation forTaskEnvironmentVariable