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");

Adding notifications#

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"]);

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 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 | BucketNotificationProps)[])

Parameters

  • scope cdk.Construct
  • notifications (FunctionDefinition | BucketNotificationProps)[]

A list of FunctionDefinition or BucketNotificationProps 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 | BucketNotificationProps)[], defaults to []

A list of FunctionDefinition or BucketNotificationProps 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.

BucketNotificationProps#

function#

Type : FunctionDefinition

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

notificationProps?#

Type : cdk.aws-lambda-event-sources.lambdaEventSources.S3EventSourceProps, defaults to S3EventSourceProps with events set to [OBJECT_CREATED, OBJECT_REMOVED]

Optionally pass in a CDK S3EventSourceProps. This allows you to override the default settings this construct uses internally to create the notification.