DynamoDB EventBridge Pipe Construct

A TypeScript AWS CDK construct that creates an EventBridge Pipe from a DynamoDB table stream to an EventBridge event bus. This construct automatically handles IAM permissions for reading from DynamoDB streams and publishing to EventBridge.

Prerequisites

• The DynamoDB table must have streams enabled for the pipe to work
• AWS CDK v2
• Node.js 18+ and TypeScript

Installation

npm install @lewinnovation/dynamo-eventbridge-pipe-construct

Usage

Basic Usage

import { DynamoEventbridgePipeConstruct } from '@lewinnovation/dynamo-eventbridge-pipe-construct';
import { Table, StreamViewType } from 'aws-cdk-lib/aws-dynamodb';
import { EventBus } from 'aws-cdk-lib/aws-events';

// Create a table with streams enabled
const table = new Table(this, 'MyTable', {
  partitionKey: { name: 'id', type: AttributeType.STRING },
  stream: StreamViewType.NEW_AND_OLD_IMAGES, // Required!
});

// Create an event bus
const bus = new EventBus(this, 'MyEventBus');

// Create the pipe construct
const pipe = new DynamoEventbridgePipeConstruct(this, 'MyPipe', {
  table,
  bus,
  entityName: 'User',
  sourceName: 'myapp.users'
});

Advanced Usage with Custom Names

const pipe = new DynamoEventbridgePipeConstruct(this, 'MyPipe', {
  table,
  bus,
  entityName: 'User',
  sourceName: 'myapp.users',
  pipeName: 'custom-pipe-name',     // Optional: custom pipe name
  roleName: 'custom-role-name'      // Optional: custom IAM role name
});

API Reference

DynamoEventbridgePipeConstructProps

| Property | Type | Required | Description | |----------|------|----------|-------------| | table | ITable | ✅ | DynamoDB table with streams enabled | | bus | IEventBus | ✅ | EventBridge event bus to send events to | | entityName | string | ✅ | Entity name used for the detail type in EventBridge events | | sourceName | string | ✅ | Source name for EventBridge events | | pipeName | string | ❌ | Name for the EventBridge pipe (auto-generated if not provided) | | roleName | string | ❌ | IAM role name for the pipe (auto-generated if not provided) |

Public Properties

| Property | Type | Description | |----------|------|-------------| | bus | IEventBus | The EventBridge event bus that events are sent to | | pipe | Pipe | The EventBridge pipe that connects DynamoDB stream to EventBridge |

Security and Best Practices

This construct includes cdk-nag integration for security best practices validation. The construct automatically applies appropriate suppressions for:

• IAM5: Wildcard permissions required for DynamoDB stream access and EventBridge publishing
• IAM4: Inline policies used for specific DynamoDB stream and EventBridge permissions
• Pipes-1: Pipe uses DynamoDB stream as source which requires specific permissions

Using cdk-nag with this construct

import { AwsSolutionsChecks } from 'cdk-nag';

// Apply cdk-nag checks to your stack
AwsSolutionsChecks.quiet = false; // Set to true to suppress output

// Your stack will automatically pass cdk-nag validation

Important Notes

• Role Name Uniqueness: If you provide a custom roleName, it must be globally unique within your AWS account. Consider using auto-generated names for multiple deployments.
• Stream Requirements: The DynamoDB table must have streams enabled. The construct will throw an error if streams are not configured.
• Input Validation: The construct validates that entityName and sourceName are non-empty strings.
• Security: The construct includes cdk-nag suppressions for legitimate security patterns specific to EventBridge Pipes and DynamoDB streams.

Development

Useful Commands

• npm run build compile typescript to js
• npm run watch watch for changes and compile
• npm run test perform the jest unit tests

Running Tests

npm test

License

This project is licensed under the MIT License.