feat(lambda): allow Topic to be dlq for Lambda (#18546)

Adds possibility of using sns.Topic as a deadLetterQueue
for a lambda function as described in `AWS::Lambda::Function`
documentation.

closes: #16246

----

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

Author: kornicameister

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

@@ -512,7 +512,8 @@ const fn = lambda.Function.fromFunctionAttributes(this, 'Function', {
 ## Lambda with DLQ
 
 A dead-letter queue can be automatically created for a Lambda function by
-setting the `deadLetterQueueEnabled: true` configuration.
+setting the `deadLetterQueueEnabled: true` configuration. In such case CDK creates
+a `sqs.Queue` as `deadLetterQueue`.
 
 ```ts
 const fn = new lambda.Function(this, 'MyFunction', {
@@ -537,6 +538,20 @@ const fn = new lambda.Function(this, 'MyFunction', {
 });
 ```
 
+You can also use a `sns.Topic` instead of an `sqs.Queue` as dead-letter queue:
+
+```ts
+import * as sns from '@aws-cdk/aws-sns';
+
+const dlt = new sns.Topic(this, 'DLQ');
+const fn = new lambda.Function(this, 'MyFunction', {
+  runtime: lambda.Runtime.NODEJS_12_X,
+  handler: 'index.handler',
+  code: lambda.Code.fromInline('// your code here'),
+  deadLetterTopic: dlt,
+});
+```
+
 See [the AWS documentation](https://docs.aws.amazon.com/lambda/latest/dg/dlq.html)
 to learn more about AWS Lambdas and DLQs.
 

packages/@aws-cdk/aws-lambda/lib/function.ts

@@ -4,6 +4,7 @@ import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
 import * as kms from '@aws-cdk/aws-kms';
 import * as logs from '@aws-cdk/aws-logs';
+import * as sns from '@aws-cdk/aws-sns';
 import * as sqs from '@aws-cdk/aws-sqs';
 import { Annotations, ArnFormat, CfnResource, Duration, Fn, Lazy, Names, Stack } from '@aws-cdk/core';
 import { Construct } from 'constructs';
@@ -188,11 +189,21 @@ export interface FunctionOptions extends EventInvokeConfigOptions {
 
   /**
    * The SQS queue to use if DLQ is enabled.
+   * If SNS topic is desired, specify `deadLetterTopic` property instead.
    *
    * @default - SQS queue with 14 day retention period if `deadLetterQueueEnabled` is `true`
    */
   readonly deadLetterQueue?: sqs.IQueue;
 
+  /**
+   * The SNS topic to use as a DLQ.
+   * Note that if `deadLetterQueueEnabled` is set to `true`, an SQS queue will be created
+   * rather than an SNS topic. Using an SNS topic as a DLQ requires this property to be set explicitly.
+   *
+   * @default - no SNS topic
+   */
+  readonly deadLetterTopic?: sns.ITopic;
+
   /**
    * Enable AWS X-Ray Tracing for Lambda Function.
    *
@@ -573,10 +584,15 @@ export class Function extends FunctionBase {
   public readonly grantPrincipal: iam.IPrincipal;
 
   /**
-   * The DLQ associated with this Lambda Function (this is an optional attribute).
+   * The DLQ (as queue) associated with this Lambda Function (this is an optional attribute).
    */
   public readonly deadLetterQueue?: sqs.IQueue;
 
+  /**
+   * The DLQ (as topic) associated with this Lambda Function (this is an optional attribute).
+   */
+  public readonly deadLetterTopic?: sns.ITopic;
+
   /**
    * The architecture of this Lambda Function (this is an optional attribute and defaults to X86_64).
    */
@@ -673,7 +689,15 @@ export class Function extends FunctionBase {
       this.addEnvironment(key, value);
     }
 
-    this.deadLetterQueue = this.buildDeadLetterQueue(props);
+    // DLQ can be either sns.ITopic or sqs.IQueue
+    const dlqTopicOrQueue = this.buildDeadLetterQueue(props);
+    if (dlqTopicOrQueue !== undefined) {
+      if (this.isQueue(dlqTopicOrQueue)) {
+        this.deadLetterQueue = dlqTopicOrQueue;
+      } else {
+        this.deadLetterTopic = dlqTopicOrQueue;
+      }
+    }
 
     let fileSystemConfigs: CfnFunction.FileSystemConfigProperty[] | undefined = undefined;
     if (props.filesystem) {
@@ -712,7 +736,7 @@ export class Function extends FunctionBase {
       environment: Lazy.uncachedAny({ produce: () => this.renderEnvironment() }),
       memorySize: props.memorySize,
       vpcConfig: this.configureVpc(props),
-      deadLetterConfig: this.buildDeadLetterConfig(this.deadLetterQueue),
+      deadLetterConfig: this.buildDeadLetterConfig(dlqTopicOrQueue),
       tracingConfig: this.buildTracingConfig(props),
       reservedConcurrentExecutions: props.reservedConcurrentExecutions,
       imageConfig: undefinedIfNoKeys({
@@ -1031,31 +1055,45 @@ Environment variables can be marked for removal when used in Lambda@Edge by sett
     };
   }
 
-  private buildDeadLetterQueue(props: FunctionProps) {
+  private isQueue(deadLetterQueue: sqs.IQueue | sns.ITopic): deadLetterQueue is sqs.IQueue {
+    return (<sqs.IQueue>deadLetterQueue).queueArn !== undefined;
+  }
+
+  private buildDeadLetterQueue(props: FunctionProps): sqs.IQueue | sns.ITopic | undefined {
+    if (!props.deadLetterQueue && !props.deadLetterQueueEnabled && !props.deadLetterTopic) {
+      return undefined;
+    }
     if (props.deadLetterQueue && props.deadLetterQueueEnabled === false) {
       throw Error('deadLetterQueue defined but deadLetterQueueEnabled explicitly set to false');
     }
-
-    if (!props.deadLetterQueue && !props.deadLetterQueueEnabled) {
-      return undefined;
+    if (props.deadLetterTopic && (props.deadLetterQueue || props.deadLetterQueueEnabled !== undefined)) {
+      throw new Error('deadLetterQueue and deadLetterTopic cannot be specified together at the same time');
     }
 
-    const deadLetterQueue = props.deadLetterQueue || new sqs.Queue(this, 'DeadLetterQueue', {
-      retentionPeriod: Duration.days(14),
-    });
-
-    this.addToRolePolicy(new iam.PolicyStatement({
-      actions: ['sqs:SendMessage'],
-      resources: [deadLetterQueue.queueArn],
-    }));
+    let deadLetterQueue: sqs.IQueue | sns.ITopic;
+    if (props.deadLetterTopic) {
+      deadLetterQueue = props.deadLetterTopic;
+      this.addToRolePolicy(new iam.PolicyStatement({
+        actions: ['sns:Publish'],
+        resources: [deadLetterQueue.topicArn],
+      }));
+    } else {
+      deadLetterQueue = props.deadLetterQueue || new sqs.Queue(this, 'DeadLetterQueue', {
+        retentionPeriod: Duration.days(14),
+      });
+      this.addToRolePolicy(new iam.PolicyStatement({
+        actions: ['sqs:SendMessage'],
+        resources: [deadLetterQueue.queueArn],
+      }));
+    }
 
     return deadLetterQueue;
   }
 
-  private buildDeadLetterConfig(deadLetterQueue?: sqs.IQueue) {
+  private buildDeadLetterConfig(deadLetterQueue?: sqs.IQueue | sns.ITopic) {
     if (deadLetterQueue) {
       return {
-        targetArn: deadLetterQueue.queueArn,
+        targetArn: this.isQueue(deadLetterQueue) ? deadLetterQueue.queueArn : deadLetterQueue.topicArn,
       };
     } else {
       return undefined;

packages/@aws-cdk/aws-lambda/package.json

@@ -110,6 +110,7 @@
     "@aws-cdk/aws-s3": "0.0.0",
     "@aws-cdk/aws-s3-assets": "0.0.0",
     "@aws-cdk/aws-signer": "0.0.0",
+    "@aws-cdk/aws-sns": "0.0.0",
     "@aws-cdk/aws-sqs": "0.0.0",
     "@aws-cdk/core": "0.0.0",
     "@aws-cdk/cx-api": "0.0.0",
@@ -132,6 +133,7 @@
     "@aws-cdk/aws-s3": "0.0.0",
     "@aws-cdk/aws-s3-assets": "0.0.0",
     "@aws-cdk/aws-signer": "0.0.0",
+    "@aws-cdk/aws-sns": "0.0.0",
     "@aws-cdk/aws-sqs": "0.0.0",
     "@aws-cdk/core": "0.0.0",
     "@aws-cdk/cx-api": "0.0.0",

packages/@aws-cdk/aws-lambda/test/function.test.ts

@@ -8,6 +8,7 @@ import * as kms from '@aws-cdk/aws-kms';
 import * as logs from '@aws-cdk/aws-logs';
 import * as s3 from '@aws-cdk/aws-s3';
 import * as signer from '@aws-cdk/aws-signer';
+import * as sns from '@aws-cdk/aws-sns';
 import * as sqs from '@aws-cdk/aws-sqs';
 import { testDeprecated } from '@aws-cdk/cdk-build-tools';
 import * as cdk from '@aws-cdk/core';
@@ -684,6 +685,84 @@ describe('function', () => {
     })).toThrow(/deadLetterQueue defined but deadLetterQueueEnabled explicitly set to false/);
   });
 
+  test('default function with SNS DLQ when client provides Topic to be used as DLQ', () => {
+    const stack = new cdk.Stack();
+
+    const dlTopic = new sns.Topic(stack, 'DeadLetterTopic');
+
+    new lambda.Function(stack, 'MyLambda', {
+      code: new lambda.InlineCode('foo'),
+      handler: 'index.handler',
+      runtime: lambda.Runtime.NODEJS_10_X,
+      deadLetterTopic: dlTopic,
+    });
+
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::IAM::Policy', {
+      PolicyDocument: {
+        Statement: Match.arrayWith([
+          {
+            Action: 'sns:Publish',
+            Effect: 'Allow',
+            Resource: {
+              Ref: 'DeadLetterTopicC237650B',
+            },
+          },
+        ]),
+      },
+    });
+    template.hasResourceProperties('AWS::Lambda::Function', {
+      DeadLetterConfig: {
+        TargetArn: {
+          Ref: 'DeadLetterTopicC237650B',
+        },
+      },
+    });
+  });
+
+  test('error when default function with SNS DLQ when client provides Topic to be used as DLQ and deadLetterQueueEnabled set to false', () => {
+    const stack = new cdk.Stack();
+
+    const dlTopic = new sns.Topic(stack, 'DeadLetterTopic');
+
+    expect(() => new lambda.Function(stack, 'MyLambda', {
+      code: new lambda.InlineCode('foo'),
+      handler: 'index.handler',
+      runtime: lambda.Runtime.NODEJS_10_X,
+      deadLetterQueueEnabled: false,
+      deadLetterTopic: dlTopic,
+    })).toThrow(/deadLetterQueue and deadLetterTopic cannot be specified together at the same time/);
+  });
+
+  test('error when default function with SNS DLQ when client provides Topic to be used as DLQ and deadLetterQueueEnabled set to true', () => {
+    const stack = new cdk.Stack();
+
+    const dlTopic = new sns.Topic(stack, 'DeadLetterTopic');
+
+    expect(() => new lambda.Function(stack, 'MyLambda', {
+      code: new lambda.InlineCode('foo'),
+      handler: 'index.handler',
+      runtime: lambda.Runtime.NODEJS_10_X,
+      deadLetterQueueEnabled: true,
+      deadLetterTopic: dlTopic,
+    })).toThrow(/deadLetterQueue and deadLetterTopic cannot be specified together at the same time/);
+  });
+
+  test('error when both topic and queue are presented as DLQ', () => {
+    const stack = new cdk.Stack();
+
+    const dlQueue = new sqs.Queue(stack, 'DLQ');
+    const dlTopic = new sns.Topic(stack, 'DeadLetterTopic');
+
+    expect(() => new lambda.Function(stack, 'MyLambda', {
+      code: new lambda.InlineCode('foo'),
+      handler: 'index.handler',
+      runtime: lambda.Runtime.NODEJS_10_X,
+      deadLetterQueue: dlQueue,
+      deadLetterTopic: dlTopic,
+    })).toThrow(/deadLetterQueue and deadLetterTopic cannot be specified together at the same time/);
+  });
+
   test('default function with Active tracing', () => {
     const stack = new cdk.Stack();
 
@@ -1561,7 +1640,7 @@ describe('function', () => {
     expect(logGroup.logGroupArn).toBeDefined();
   });
 
-  test('dlq is returned when provided by user', () => {
+  test('dlq is returned when provided by user and is Queue', () => {
     const stack = new cdk.Stack();
 
     const dlQueue = new sqs.Queue(stack, 'DeadLetterQueue', {
@@ -1576,12 +1655,37 @@ describe('function', () => {
       deadLetterQueue: dlQueue,
     });
     const deadLetterQueue = fn.deadLetterQueue;
-    expect(deadLetterQueue?.queueArn).toBeDefined();
-    expect(deadLetterQueue?.queueName).toBeDefined();
-    expect(deadLetterQueue?.queueUrl).toBeDefined();
+    const deadLetterTopic = fn.deadLetterTopic;
+
+    expect(deadLetterTopic).toBeUndefined();
+
+    expect(deadLetterQueue).toBeDefined();
+    expect(deadLetterQueue).toBeInstanceOf(sqs.Queue);
   });
 
-  test('dlq is returned when setup by cdk', () => {
+  test('dlq is returned when provided by user and is Topic', () => {
+    const stack = new cdk.Stack();
+
+    const dlTopic = new sns.Topic(stack, 'DeadLetterQueue', {
+      topicName: 'MyLambda_DLQ',
+    });
+
+    const fn = new lambda.Function(stack, 'fn', {
+      handler: 'foo',
+      runtime: lambda.Runtime.NODEJS_10_X,
+      code: lambda.Code.fromInline('foo'),
+      deadLetterTopic: dlTopic,
+    });
+    const deadLetterQueue = fn.deadLetterQueue;
+    const deadLetterTopic = fn.deadLetterTopic;
+
+    expect(deadLetterQueue).toBeUndefined();
+
+    expect(deadLetterTopic).toBeDefined();
+    expect(deadLetterTopic).toBeInstanceOf(sns.Topic);
+  });
+
+  test('dlq is returned when setup by cdk and is Queue', () => {
     const stack = new cdk.Stack();
     const fn = new lambda.Function(stack, 'fn', {
       handler: 'foo',
@@ -1590,9 +1694,12 @@ describe('function', () => {
       deadLetterQueueEnabled: true,
     });
     const deadLetterQueue = fn.deadLetterQueue;
-    expect(deadLetterQueue?.queueArn).toBeDefined();
-    expect(deadLetterQueue?.queueName).toBeDefined();
-    expect(deadLetterQueue?.queueUrl).toBeDefined();
+    const deadLetterTopic = fn.deadLetterTopic;
+
+    expect(deadLetterTopic).toBeUndefined();
+
+    expect(deadLetterQueue).toBeDefined();
+    expect(deadLetterQueue).toBeInstanceOf(sqs.Queue);
   });
 
   test('dlq is undefined when not setup', () => {
@@ -1603,7 +1710,10 @@ describe('function', () => {
       code: lambda.Code.fromInline('foo'),
     });
     const deadLetterQueue = fn.deadLetterQueue;
+    const deadLetterTopic = fn.deadLetterTopic;
+
     expect(deadLetterQueue).toBeUndefined();
+    expect(deadLetterTopic).toBeUndefined();
   });
 
   test('one and only one child LogRetention construct will be created', () => {