feat(events): API Destinations (#13729)

Adds `Connection` and `ApiDestination` constructs in Events, and an `ApiDestination` target in Events Targets. Can be used to do arbitrary HTTP calls.

Fixes #13729 

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: msimpsonnz

packages/@aws-cdk/aws-events-targets/README.md

@@ -19,7 +19,7 @@ Currently supported are:
 * [Start a CodePipeline pipeline](#start-a-codepipeline-pipeline)
 * Run an ECS task
 * [Invoke a Lambda function](#invoke-a-lambda-function)
-* [Invoke a API Gateway REST API](#invoke-a-api-gateway-rest-api)
+* [Invoke a API Gateway REST API](#invoke-an-api-gateway-rest-api)
 * Publish a message to an SNS topic
 * Send a message to an SQS queue
 * [Start a StepFunctions state machine](#start-a-stepfunctions-state-machine)
@@ -29,6 +29,7 @@ Currently supported are:
 * [Log an event into a LogGroup](#log-an-event-into-a-loggroup)
 * Put a record to a Kinesis Data Firehose stream
 * [Put an event on an EventBridge bus](#put-an-event-on-an-eventbridge-bus)
+* [Send an event to EventBridge API Destination](#invoke-an-api-destination)
 
 See the README of the `@aws-cdk/aws-events` library for more information on
 EventBridge.
@@ -226,7 +227,7 @@ rule.addTarget(new targets.BatchJob(
 ));
 ```
 
-## Invoke a API Gateway REST API
+## Invoke an API Gateway REST API
 
 Use the `ApiGateway` target to trigger a REST API.
 
@@ -267,6 +268,31 @@ rule.addTarget(
 )
 ```
 
+## 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.
+
+```ts
+const connection = new events.Connection(this, 'Connection', {
+  authorization: events.Authorization.apiKey('x-api-key', SecretValue.secretsManager('ApiSecretName')),
+  description: 'Connection with API Key x-api-key',
+});
+
+const destination = new events.ApiDestination(this, 'Destination', {
+  connection,
+  endpoint: 'https://example.com',
+  description: 'Calling example.com with API key x-api-key',
+});
+
+const rule = new events.Rule(this, 'Rule', {
+  schedule: events.Schedule.rate(cdk.Duration.minutes(1)),
+  targets: [new targets.ApiDestination(destination)],
+});
+```
+
 ## Put an event on an EventBridge bus
 
 Use the `EventBus` target to route event to a different EventBus.

packages/@aws-cdk/aws-events-targets/lib/api-destination.ts

@@ -0,0 +1,98 @@
+import * as events from '@aws-cdk/aws-events';
+import * as iam from '@aws-cdk/aws-iam';
+import { addToDeadLetterQueueResourcePolicy, bindBaseTargetConfig, singletonEventRole, TargetBaseProps } from './util';
+
+/**
+ * Customize the EventBridge Api Destinations Target
+ */
+export interface ApiDestinationProps extends TargetBaseProps {
+  /**
+   * The event to send
+   *
+   * @default - the entire EventBridge event
+   */
+  readonly event?: events.RuleTargetInput;
+
+  /**
+   * The role to assume before invoking the target
+   *
+   * @default - a new role will be created
+   */
+  readonly eventRole?: iam.IRole;
+
+  /**
+   * Additional headers sent to the API Destination
+   *
+   * These are merged with headers specified on the Connection, with
+   * the headers on the Connection taking precedence.
+   *
+   * You can only specify secret values on the Connection.
+   *
+   * @default - none
+   */
+  readonly headerParameters?: Record<string, string>;
+
+  /**
+   * Path parameters to insert in place of path wildcards (`*`).
+   *
+   * If the API destination has a wilcard in the path, these path parts
+   * will be inserted in that place.
+   *
+   * @default - none
+   */
+  readonly pathParameterValues?: string[]
+
+  /**
+   * Additional query string parameters sent to the API Destination
+   *
+   * These are merged with headers specified on the Connection, with
+   * the headers on the Connection taking precedence.
+   *
+   * You can only specify secret values on the Connection.
+   *
+   * @default - none
+   */
+  readonly queryStringParameters?: Record<string, string>;
+}
+
+/**
+ * Use an API Destination rule target.
+ */
+export class ApiDestination implements events.IRuleTarget {
+  constructor(
+    private readonly apiDestination: events.IApiDestination,
+    private readonly props: ApiDestinationProps = {},
+  ) { }
+
+  /**
+   * Returns a RuleTarget that can be used to trigger API destinations
+   * from an EventBridge event.
+   */
+  public bind(_rule: events.IRule, _id?: string): events.RuleTargetConfig {
+    const httpParameters: events.CfnRule.HttpParametersProperty | undefined =
+      !!this.props.headerParameters ??
+      !!this.props.pathParameterValues ??
+      !!this.props.queryStringParameters
+        ? {
+          headerParameters: this.props.headerParameters,
+          pathParameterValues: this.props.pathParameterValues,
+          queryStringParameters: this.props.queryStringParameters,
+        } : undefined;
+
+    if (this.props?.deadLetterQueue) {
+      addToDeadLetterQueueResourcePolicy(_rule, this.props.deadLetterQueue);
+    }
+
+    return {
+      ...(this.props ? bindBaseTargetConfig(this.props) : {}),
+      arn: this.apiDestination.apiDestinationArn,
+      role: this.props?.eventRole ?? singletonEventRole(this.apiDestination, [new iam.PolicyStatement({
+        resources: [this.apiDestination.apiDestinationArn],
+        actions: ['events:InvokeApiDestination'],
+      })]),
+      input: this.props.event,
+      targetResource: this.apiDestination,
+      httpParameters,
+    };
+  }
+}

packages/@aws-cdk/aws-events-targets/lib/index.ts

@@ -13,4 +13,5 @@ export * from './kinesis-stream';
 export * from './log-group';
 export * from './kinesis-firehose-stream';
 export * from './api-gateway';
+export * from './api-destination';
 export * from './util';

packages/@aws-cdk/aws-events-targets/rosetta/default.ts-fixture

@@ -1,5 +1,5 @@
 // Fixture with packages imported, but nothing else
-import { Duration, RemovalPolicy, Stack } from '@aws-cdk/core';
+import { Duration, RemovalPolicy, SecretValue, Stack } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 
 import * as targets from '@aws-cdk/aws-events-targets';

packages/@aws-cdk/aws-events-targets/test/api-destination/api-destination.test.ts

@@ -0,0 +1,69 @@
+import { Template } from '@aws-cdk/assertions';
+import * as events from '@aws-cdk/aws-events';
+import * as iam from '@aws-cdk/aws-iam';
+import { Duration, SecretValue, Stack } from '@aws-cdk/core';
+import * as targets from '../../lib';
+
+
+describe('with basic auth connection', () => {
+  let stack: Stack;
+  let connection: events.Connection;
+  let destination: events.ApiDestination;
+  let rule: events.Rule;
+
+  beforeEach(() => {
+    stack = new Stack();
+    connection = new events.Connection(stack, 'Connection', {
+      authorization: events.Authorization.basic('username', SecretValue.plainText('password')),
+      description: 'ConnectionDescription',
+      connectionName: 'testConnection',
+    });
+
+    destination = new events.ApiDestination(stack, 'Destination', {
+      connection,
+      endpoint: 'https://endpoint.com',
+    });
+
+    rule = new events.Rule(stack, 'Rule', {
+      schedule: events.Schedule.rate(Duration.minutes(1)),
+    });
+  });
+
+  test('use api destination as an eventrule target', () => {
+    // WHEN
+    rule.addTarget(new targets.ApiDestination(destination));
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::Events::Rule', {
+      ScheduleExpression: 'rate(1 minute)',
+      State: 'ENABLED',
+      Targets: [
+        {
+          Arn: { 'Fn::GetAtt': ['DestinationApiDestinationA879FAE5', 'Arn'] },
+          Id: 'Target0',
+          RoleArn: { 'Fn::GetAtt': ['DestinationEventsRole7DA63556', 'Arn'] },
+        },
+      ],
+    });
+  });
+
+  test('with an explicit event role', () => {
+    // WHEN
+    const eventRole = new iam.Role(stack, 'Role', {
+      assumedBy: new iam.ServicePrincipal('events.amazonaws.com'),
+    });
+    rule.addTarget(new targets.ApiDestination(destination, { eventRole }));
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::Events::Rule', {
+      Targets: [
+        {
+          RoleArn: { 'Fn::GetAtt': ['Role1ABCC5F0', 'Arn'] },
+          Id: 'Target0',
+        },
+      ],
+    });
+  });
+});

packages/@aws-cdk/aws-events/README.md

@@ -153,6 +153,8 @@ The following targets are supported:
 * `targets.SfnStateMachine`: Trigger an AWS Step Functions state machine
 * `targets.BatchJob`: Queue an AWS Batch Job
 * `targets.AwsApi`: Make an AWS API call
+* `targets.ApiGateway`: Invoke an AWS API Gateway
+* `targets.ApiDestination`: Make an call to an external destination
 
 ### Cross-account and cross-region targets
 

packages/@aws-cdk/aws-events/lib/api-destination.ts

@@ -0,0 +1,107 @@
+import { IResource, Resource } from '@aws-cdk/core';
+import { Construct } from 'constructs';
+import { HttpMethod, IConnection } from './connection';
+import { CfnApiDestination } from './events.generated';
+
+/**
+ * The event API Destination properties
+ */
+export interface ApiDestinationProps {
+  /**
+   * The name for the API destination.
+   * @default - A unique name will be generated
+   */
+  readonly apiDestinationName?: string;
+
+  /**
+   * A description for the API destination.
+   *
+   * @default - none
+   */
+  readonly description?: string;
+
+  /**
+   * The ARN of the connection to use for the API destination
+   */
+  readonly connection: IConnection;
+
+  /**
+   * The URL to the HTTP invocation endpoint for the API destination..
+   */
+  readonly endpoint: string;
+
+  /**
+   * The method to use for the request to the HTTP invocation endpoint.
+   *
+   * @default HttpMethod.POST
+   */
+  readonly httpMethod?: HttpMethod;
+
+  /**
+   * The maximum number of requests per second to send to the HTTP invocation endpoint.
+   *
+   * @default - Not rate limited
+   */
+  readonly rateLimitPerSecond?: number;
+}
+
+/**
+ * Interface for API Destinations
+ */
+export interface IApiDestination extends IResource {
+  /**
+   * The Name of the Api Destination created.
+   * @attribute
+   */
+  readonly apiDestinationName: string;
+
+  /**
+   * The ARN of the Api Destination created.
+   * @attribute
+   */
+  readonly apiDestinationArn: string;
+}
+
+/**
+ * Define an EventBridge Api Destination
+ *
+ * @resource AWS::Events::ApiDestination
+ */
+export class ApiDestination extends Resource implements IApiDestination {
+  /**
+   * The Connection to associate with Api Destination
+   */
+  public readonly connection: IConnection;
+
+  /**
+   * The Name of the Api Destination created.
+   * @attribute
+   */
+  public readonly apiDestinationName: string;
+
+  /**
+   * The ARN of the Api Destination created.
+   * @attribute
+   */
+  public readonly apiDestinationArn: string;
+
+  constructor(scope: Construct, id: string, props: ApiDestinationProps) {
+    super(scope, id, {
+      physicalName: props.apiDestinationName,
+    });
+
+    this.connection = props.connection;
+
+    let apiDestination = new CfnApiDestination(this, 'ApiDestination', {
+      connectionArn: this.connection.connectionArn,
+      description: props.description,
+      httpMethod: props.httpMethod ?? HttpMethod.POST,
+      invocationEndpoint: props.endpoint,
+      invocationRateLimitPerSecond: props.rateLimitPerSecond,
+      name: this.physicalName,
+    });
+
+    this.apiDestinationName = this.getResourceNameAttribute(apiDestination.ref);
+    this.apiDestinationArn = apiDestination.attrArn;
+  }
+}