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.

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

Parameters

• scope Construct
• id string
• props BucketProps

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

new Bucket(this, "Bucket");

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],
      },
    },
  ],
});

Create an empty bucket and lazily add the notifications.

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

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

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],
      },
    },
  ],
});

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.

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

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

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],
});

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

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

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],
});

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

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

Configure the internally created CDK Bucket instance.

new Bucket(this, "Bucket", {
  s3Bucket: {
    bucketName: "my-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,
  },
});

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

An instance of Bucket contains the following properties.

Type: string

The ARN of the internally created CDK Bucket instance.

Type: string

The name of the internally created CDK Bucket instance.

Type : cdk.aws-s3.Bucket

The internally created CDK Bucket instance.

Type : Function[]

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

An instance of Bucket contains the following methods.

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(permissions: Permissions)

Parameters

• permissions Permissions

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

Internally calls Function.attachPermissions.

attachPermissions(index: number, permissions: Permissions)

Parameters

• index number

• permissions Permissions

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.

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.

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.

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.

Type : FunctionDefinition

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

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.

Type : Queue

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

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.

Type : Topic

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

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.

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

The S3 event types that will trigger the notification.

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

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