Bucket

caution

This is the SST v1.x Constructs doc. SST v2 is now released. If you are using v2, see the v2 Constructs doc. If you are looking to upgrade to v2, check out the upgrade 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.

Examples

Using the minimal config

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

new Bucket(stack, "Bucket");

Configuring notifications

Using the minimal config

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

new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: "src/notification.main",
  },
});

Or configuring the notification events.

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

const bucket = new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: {
      function: "src/notification.main",
      events: ["object_created"],
    },
  },
});

Lazily adding notifications

Create an empty bucket and lazily add the notifications.

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

bucket.addNotifications(this, {
  myNotification: "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(stack, "Bucket", {
  defaults: {
    function: {
      timeout: 20,
      environment: { tableName: table.tableName },
      permissions: [table],
    },
  },
  notifications: {
    myNotification1: {
      function: "src/notification1.main",
      events: ["object_created"],
    },
    myNotification2: {
      function: "src/notification2.main",
      events: ["object_removed"],
    },
  },
});

Configuring an individual notification

Configure each Lambda function separately.

new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: {
      function: {
        srcPath: "src/",
        handler: "notification.main",
        environment: { tableName: table.tableName },
        permissions: [table],
      },
      events: ["object_created"],
    },
  },
});

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

new Bucket(stack, "Bucket", {
  defaults: {
    function: {
      timeout: 20,
      environment: { tableName: table.tableName },
      permissions: [table],
    },
  },
  notifications: {
    myNotification1: {
      function: {
        handler: "src/notification1.main",
        timeout: 10,
        environment: { bucketName: bucket.bucketName },
        permissions: [bucket],
      },
      events: ["object_created"],
    },
    myNotification2: {
      function: "src/notification2.main",
      events: ["object_removed"],
    },
  },
});

So in the above example, the myNotification1 function doesn't use the timeout that is set in the defaults.function. 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(stack, "Bucket", {
  notifications: {
    myNotification1: {
      function: "src/notification1.main",
      events: ["object_created"],
    },
    myNotification2: {
      function: "src/notification2.main",
      events: ["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(stack, "Bucket", {
  notifications: {
    myNotification1: {
      function: "src/notification1.main",
      events: ["object_created"],
    },
    myNotification2: {
      function: "src/notification2.main",
      events: ["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(stack, "Bucket", {
  notifications: {
    myNotification: myQueue,
  },
});

Configuring the notification

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

new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: {
      queue: myQueue,
      events: ["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(stack, "Bucket", {
  notifications: {
    myNotification: myTopic,
  },
});

Configuring the notification

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

new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: {
      topic: myTopic,
      events: ["object_created_put"],
      filters: [{ prefix: "imports/" }, { suffix: ".jpg" }],
    }
  },
});

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(stack, "Bucket", {
  cdk: {
    bucket: {
      autoDeleteObjects: true,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    },
  },
});

Advanced examples

Configuring the S3 Bucket

Configure the internally created CDK Bucket instance.

new Bucket(stack, "Bucket", {
  cdk: {
    bucket: {
      bucketName: "my-bucket",
    },
  },
});

Importing an existing bucket

Override the internally created CDK Bucket instance.

import * as s3 from "aws-cdk-lib/aws-s3";

new Bucket(stack, "Bucket", {
  cdk: {
    bucket: s3.Bucket.fromBucketArn(this, "IBucket", bucketArn),
  },
});

Constructor

new Bucket(scope, id, props)

Parameters

• scope Construct
• id string
• props BucketProps

BucketProps

cors?

Type : boolean | Array<BucketCorsRule>

The CORS configuration of this bucket.

new Bucket(stack, "Bucket", {
  cors: true,
});

new Bucket(stack, "Bucket", {
  cors: [
    {
      allowedMethods: ["GET"],
      allowedOrigins: ["https://www.example.com"],
    }
  ],
});

defaults.function?

Type : FunctionProps

The default function props to be applied to all the Lambda functions in the API. The environment, permissions and layers properties will be merged with per route definitions if they are defined.

new Bucket(stack, "Bucket", {
  defaults: {
    function: {
      timeout: 20,
    }
  },
});

name?

Type : string

The name of the bucket. Note that it's not recommended to hard code a name for the bucket, because they must be globally unique.

new Bucket(stack, "Bucket", {
  name: "my-bucket",
});

notifications?

Type : Record<string, string | Function | Queue | Topic | BucketFunctionNotificationProps | BucketQueueNotificationProps | BucketTopicNotificationProps>

Used to create notifications for various bucket events

new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: "src/notification.main",
  }
});

cdk.bucket?

Type : IBucket | BucketProps

Allows you to override default settings this construct uses internally to create the bucket.

new Bucket(stack, "Bucket", {
  cdk: {
    bucket: {
      bucketName: "my-bucket",
    },
  }
});

cdk.id?

Type : string

Allows you to override default id for this construct.

Properties

An instance of Bucket has the following properties.

bucketArn

Type : string

The ARN of the internally created Bucket instance.

bucketName

Type : string

The name of the internally created Bucket instance.

id

Type : string

notificationFunctions

Type : Array<Function>

A list of the internally created functions for the notifications.

cdk.bucket

Type : IBucket

The internally created CDK Bucket instance.

Methods

An instance of Bucket has the following methods.

addNotifications

addNotifications(scope, notifications)

Parameters

• scope Construct
• notifications Record<string, string | Function | Queue | Topic | BucketFunctionNotificationProps | BucketQueueNotificationProps | BucketTopicNotificationProps>

Add notification subscriptions after the bucket has been created

const bucket = new Bucket(stack, "Bucket");
bucket.addNotifications(stack, {
  myNotification: "src/notification.main"
});

attachPermissions

attachPermissions(permissions)

Parameters

• permissions Permissions

Attaches additional permissions to all bucket notifications

const bucket = new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: "src/function.handler",
  }
});

bucket.attachPermissions(["s3"]);

attachPermissionsToNotification

attachPermissionsToNotification(notificationName, permissions)

Parameters

• notificationName string
• permissions Permissions

Attaches additional permissions to a specific bucket notification

const bucket = new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: "src/function.handler",
  }
});

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

bind

bind(constructs)

Parameters

• constructs Array<SSTConstruct>

Binds the given list of resources to all bucket notifications

const bucket = new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: "src/function.handler",
  }
});

bucket.bind([STRIPE_KEY, bucket]);

bindToNotification

bindToNotification(notificationName, constructs)

Parameters

• notificationName string
• constructs Array<SSTConstruct>

Binds the given list of resources to a specific bucket notification

const bucket = new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: "src/function.handler",
  }
});

bucket.bindToNotification("myNotification", ["s3"]);

BucketFilter

prefix?

Type : string

Filter what the key starts with

suffix?

Type : string

Filter what the key ends with

BucketCorsRule

allowedHeaders?

Type : Array<string>

The collection of allowed headers.

allowedMethods

Type : Array<"GET" | "PUT" | "HEAD" | "POST" | "DELETE">

The collection of allowed HTTP methods.

allowedOrigins

Type : Array<string>

The collection of allowed origins.

// Allow all origins
allowOrigins: ["*"]

// Allow specific origins. Note that the url protocol, ie. "https://", is required.
allowOrigins: ["https://domain.com"]

exposedHeaders?

Type : Array<string>

The collection of exposed headers.

id?

Type : string

A unique identifier for this rule.

maxAge?

Type : ${number} second | ${number} seconds | ${number} minute | ${number} minutes | ${number} hour | ${number} hours | ${number} day | ${number} days

Specify how long the results of a preflight response can be cached

BucketQueueNotificationProps

Used to define a queue listener for the bucket

new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: {
      type: "queue",
      queue: new Queue(stack, "Queue")
    }
  }
}

events?

Type : Array<"object_created" | "object_created_put" | "object_created_post" | "object_created_copy" | "object_created_complete_multipart_upload" | "object_removed" | "object_removed_delete" | "object_removed_delete_marker_created" | "object_restore_post" | "object_restore_completed" | "object_restore_delete" | "reduced_redundancy_lost_object" | "replication_operation_failed_replication" | "replication_operation_missed_threshold" | "replication_operation_replicated_after_threshold" | "replication_operation_not_tracked" | "lifecycle_expiration" | "lifecycle_expiration_delete" | "lifecycle_expiration_delete_marker_created" | "lifecycle_transition" | "intelligent_tiering" | "object_tagging" | "object_tagging_put" | "object_tagging_delete" | "object_acl_put">

The S3 event types that will trigger the notification.

filters?

Type : Array<BucketFilter>

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

queue

Type : Queue

The queue to send notifications to

type

Type : "queue"

String literal to signify that the notification is a queue

BucketTopicNotificationProps

Used to define a topic listener for the bucket

new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: {
      type: "topic",
      topic: new Topic(stack, "Topic")
    }
  }],
}

events?

Type : Array<"object_created" | "object_created_put" | "object_created_post" | "object_created_copy" | "object_created_complete_multipart_upload" | "object_removed" | "object_removed_delete" | "object_removed_delete_marker_created" | "object_restore_post" | "object_restore_completed" | "object_restore_delete" | "reduced_redundancy_lost_object" | "replication_operation_failed_replication" | "replication_operation_missed_threshold" | "replication_operation_replicated_after_threshold" | "replication_operation_not_tracked" | "lifecycle_expiration" | "lifecycle_expiration_delete" | "lifecycle_expiration_delete_marker_created" | "lifecycle_transition" | "intelligent_tiering" | "object_tagging" | "object_tagging_put" | "object_tagging_delete" | "object_acl_put">

The S3 event types that will trigger the notification.

filters?

Type : Array<BucketFilter>

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

topic

Type : Topic

The topic to send notifications to

type

Type : "topic"

BucketFunctionNotificationProps

Used to define a function listener for the bucket

new Bucket(stack, "Bucket", {
  notifications: {
    myNotification: {
      function: "src/notification.main"
    }
  }
}

events?

Type : Array<"object_created" | "object_created_put" | "object_created_post" | "object_created_copy" | "object_created_complete_multipart_upload" | "object_removed" | "object_removed_delete" | "object_removed_delete_marker_created" | "object_restore_post" | "object_restore_completed" | "object_restore_delete" | "reduced_redundancy_lost_object" | "replication_operation_failed_replication" | "replication_operation_missed_threshold" | "replication_operation_replicated_after_threshold" | "replication_operation_not_tracked" | "lifecycle_expiration" | "lifecycle_expiration_delete" | "lifecycle_expiration_delete_marker_created" | "lifecycle_transition" | "intelligent_tiering" | "object_tagging" | "object_tagging_put" | "object_tagging_delete" | "object_acl_put">

The S3 event types that will trigger the notification.

filters?

Type : Array<BucketFilter>

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

function

Type : string | Function | FunctionProps

The function to send notifications to

type?

Type : "function"

String literal to signify that the notification is a function