Skip to main content

Bucket

caution

This is the SST v0.x Constructs doc. SST v1 is now released. If you are using v1, see the v1 Constructs doc. If you are looking to upgrade to v1, check out the migration steps.

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-lib/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-lib/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-lib/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-lib";

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-lib/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.