Skip to main content

Bucket

The Bucket construct is a higher level CDK construct that makes it easy to create an S3 Bucket and to define its notifications. It also internally connects the notifications and bucket together.

Initializer

new Bucket(scope: Construct, id: string, props: BucketProps)

Parameters

Examples

Using the minimal config

import { Bucket } from "@serverless-stack/resources";

new Bucket(this, "Bucket");

Enabling S3 Event Notifications

Using the minimal config

import { Bucket } from "@serverless-stack/resources";

new Bucket(this, "Bucket", {
notifications: ["src/notification.main"],
});

Or configuring the notification events.

import { EventType } from "@aws-cdk/aws-s3";

const bucket = new Bucket(this, "Bucket", {
notifications: [
{
function: "src/notification.main",
notificationProps: {
events: [EventType.OBJECT_CREATED],
},
},
],
});

Lazily adding notifications

Create an empty bucket and lazily add the notifications.

const bucket = new Bucket(this, "Bucket");

bucket.addNotifications(this, ["src/notification.main"]);

Configuring Function notifications

Specifying function props for all the notifications

You can extend the minimal config, to set some function props and have them apply to all the notifications.

new Bucket(this, "Bucket", {
defaultFunctionProps: {
timeout: 20,
environment: { tableName: table.tableName },
permissions: [table],
},
notifications: [
{
function: "src/notification1.main",
notificationProps: {
events: [EventType.OBJECT_CREATED],
},
},
{
function: "src/notification2.main",
notificationProps: {
events: [EventType.OBJECT_REMOVED],
},
},
],
});

Using the full config

If you wanted to configure each Lambda function separately, you can pass in the BucketNotificationProps.

new Bucket(this, "Bucket", {
notifications: [
{
function: {
srcPath: "src/",
handler: "notification.main",
environment: { tableName: table.tableName },
permissions: [table],
},
notificationProps: {
events: [EventType.OBJECT_CREATED],
},
},
],
});

Note that, you can set the defaultFunctionProps while using the function per notification. The function will just override the defaultFunctionProps. Except for the environment, the layers, and the permissions properties, that will be merged.

new Bucket(this, "Bucket", {
defaultFunctionProps: {
timeout: 20,
environment: { tableName: table.tableName },
permissions: [table],
},
notifications: [
{
function: {
handler: "src/notification1.main",
timeout: 10,
environment: { bucketName: bucket.bucketName },
permissions: [bucket],
},
notificationProps: {
events: [EventType.OBJECT_CREATED],
},
},
{
function: "src/notification2.main",
notificationProps: {
events: [EventType.OBJECT_REMOVED],
},
},
],
});

So in the above example, the notification1 function doesn't use the timeout that is set in the defaultFunctionProps. It'll instead use the one that is defined in the function definition (10 seconds). And the function will have both the tableName and the bucketName environment variables set; as well as permissions to both the table and the bucket.

Giving the notifications some permissions

Allow the notification functions to access S3.

import { EventType } from "@aws-cdk/aws-s3";

const bucket = new Bucket(this, "Bucket", {
notifications: [
{
function: "src/notification1.main",
notificationProps: {
events: [EventType.OBJECT_CREATED],
},
},
{
function: "src/notification2.main",
notificationProps: {
events: [EventType.OBJECT_REMOVED],
},
},
],
});

bucket.attachPermissions(["s3"]);

Giving a specific notification some permissions

Allow the first notification function to access S3.

import { EventType } from "@aws-cdk/aws-s3";

const bucket = new Bucket(this, "Bucket", {
notifications: [
{
function: "src/notification1.main",
notificationProps: {
events: [EventType.OBJECT_CREATED],
},
},
{
function: "src/notification2.main",
notificationProps: {
events: [EventType.OBJECT_REMOVED],
},
},
],
});

bucket.attachPermissionsToNotification(0, ["s3"]);

Configuring Queue notifications

Specifying the Queue directly

You can directly pass in an instance of the Queue construct.

import { Queue } from "@serverless-stack/resources";

const myQueue = new Queue(this, "MyQueue");

new Bucket(this, "Bucket", {
notifications: [myQueue],
});

Configuring the notification

const myQueue = new Queue(this, "MyQueue");

new Bucket(this, "Bucket", {
notifications: [
{
queue: myQueue,
notificationProps: {
events: [EventType.OBJECT_CREATED_PUT],
filters: [{ prefix: "imports/" }, { suffix: ".jpg" }],
}
}
],
});

Configuring Topic notifications

Specifying the Topic directly

You can directly pass in an instance of the Topic construct.

import { Topic } from "@serverless-stack/resources";

const myTopic = new Topic(this, "MyTopic");

new Bucket(this, "Bucket", {
notifications: [myTopic],
});

Configuring the notification

const myTopic = new Topic(this, "MyTopic");

new Bucket(this, "Bucket", {
notifications: [
{
topic: myTopic,
notificationProps: {
events: [EventType.OBJECT_CREATED_PUT],
filters: [{ prefix: "imports/" }, { suffix: ".jpg" }],
}
}
],
});

Configuring the S3 Bucket

Configure the internally created CDK Bucket instance.

new Bucket(this, "Bucket", {
s3Bucket: {
bucketName: "my-bucket",
},
});

Removing the S3 Bucket

Only empty S3 buckets can be deleted. However, you can configure the bucket to automatically delete all objects upon removal.

import * as cdk from "@aws-cdk/core";

new Bucket(this, "Bucket", {
s3Bucket: {
autoDeleteObjects: true,
removalPolicy: cdk.RemovalPolicy.DESTROY,
},
});

Configuring a notification

Configure the internally created CDK Notification.

import { EventType } from "@aws-cdk/aws-s3";

new Bucket(this, "Bucket", {
notifications: [
{
function: "src/notification.main",
notificationProps: {
events: [EventType.OBJECT_CREATED_PUT],
filters: [{ prefix: "imports/" }, { suffix: ".jpg" }],
},
},
],
});

Properties

An instance of Bucket contains the following properties.

bucketArn

Type: string

The ARN of the internally created CDK Bucket instance.

bucketName

Type: string

The name of the internally created CDK Bucket instance.

s3Bucket

Type : cdk.aws-s3.Bucket

The internally created CDK Bucket instance.

notificationFunctions

Type : Function[]

A list of the internally created Function instances for the notifications.

Methods

An instance of Bucket contains the following methods.

addNotifications

addNotifications(scope: cdk.Construct, notifications: (FunctionDefinition | BucketFunctionNotificationProps | Queue | BucketQueueNotificationProps | Topic | BucketTopicNotificationProps)[])

Parameters

  • scope cdk.Construct
  • notifications (FunctionDefinition | BucketFunctionNotificationProps | Queue | BucketQueueNotificationProps | Topic | BucketTopicNotificationProps)[]

A list of FunctionDefinition, BucketFunctionNotificationProps, Queue, BucketQueueNotificationProps, Topic, or BucketTopicNotificationProps that'll be used to create the notifications for the bucket.

attachPermissions

attachPermissions(permissions: Permissions)

Parameters

Attaches the given list of permissions to all the notificationFunctions. This allows the notifications to access other AWS resources.

Internally calls Function.attachPermissions.

attachPermissionsToNotification

attachPermissions(index: number, permissions: Permissions)

Parameters

Attaches the given list of permissions to a specific function in the list of notificationFunctions. Where index (starting at 0) is used to identify the notification. This allows that notification to access other AWS resources.

Internally calls Function.attachPermissions.

BucketProps

notifications?

Type : (FunctionDefinition | BucketFunctionNotificationProps | Queue | BucketQueueNotificationProps | Topic | BucketTopicNotificationProps)[], defaults to []

A list of FunctionDefinition, BucketFunctionNotificationProps, Queue, BucketQueueNotificationProps, Topic, or BucketTopicNotificationProps that'll be used to create the notifications for the bucket.

s3Bucket?

Type : cdk.aws-s3.Bucket | cdk.aws-s3.BucketProps, defaults to undefined

Optionally pass in a CDK cdk.aws-s3.BucketProps or a cdk.aws-s3.Bucket instance. This allows you to override the default settings this construct uses internally to create the bucket.

defaultFunctionProps?

Type : FunctionProps, defaults to {}

The default function props to be applied to all the Lambda functions in the Bucket. If the function is specified for a notification, these default values are overridden. Except for the environment, the layers, and the permissions properties, that will be merged.

BucketFunctionNotificationProps

function

Type : FunctionDefinition

A FunctionDefinition object that'll be used to create the notification function for the bucket.

notificationProps?

Type : BucketNotificationProps, defaults to events set to [OBJECT_CREATED, OBJECT_REMOVED]

Optionally pass in a BucketNotificationProps. This allows you to configure the S3 events and key filter rules that will trigger the notification.

BucketQueueNotificationProps

queue

Type : Queue

A Queue object that'll be used to create the notification queue for the bucket.

notificationProps?

Type : BucketNotificationProps, defaults to events set to [OBJECT_CREATED, OBJECT_REMOVED]

Optionally pass in a BucketNotificationProps. This allows you to configure the S3 events and key filter rules that will trigger the notification.

BucketTopicNotificationProps

topic

Type : Topic

A Topic object that'll be used to create the notification topic for the bucket.

notificationProps?

Type : BucketNotificationProps, defaults to events set to [OBJECT_CREATED, OBJECT_REMOVED]

Optionally pass in a BucketNotificationProps. This allows you to configure the S3 events and key filter rules that will trigger the notification.

BucketNotificationProps

events?

Type : cdk.aws-s3.EventType, defaults to [OBJECT_CREATED, OBJECT_REMOVED]

The S3 event types that will trigger the notification.

filters?

Type : cdk.aws-s3.NotificationKeyFilter, defaults to no filters

S3 object key filter rules to determine which objects trigger this event.