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.
Examples
Using the minimal config
import { Bucket } from "sst/constructs";
new Bucket(stack, "Bucket");
Configuring notifications
Using the minimal config
import { Bucket } from "sst/constructs";
new Bucket(stack, "Bucket", {
notifications: {
myNotification: "src/notification.main",
},
});
Or configuring the notification events.
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(stack, {
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.
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.
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 "sst/constructs";
const myQueue = new Queue(stack, "MyQueue");
new Bucket(stack, "Bucket", {
notifications: {
myNotification: myQueue,
},
});
Configuring the notification
const myQueue = new Queue(stack, "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 "sst/constructs";
const myTopic = new Topic(stack, "MyTopic");
new Bucket(stack, "Bucket", {
notifications: {
myNotification: myTopic,
},
});
Configuring the notification
const myTopic = new Topic(stack, "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(stack, "IBucket", bucketArn),
},
});
Constructor
new Bucket(scope, id, props)
Parameters
- scope Construct
- id string
- props BucketProps
BucketProps
blockPublicACLs?
Type : boolean
Default : false
Prevent any files from being uploaded with public access configured. Setting this to
true
prevents uploading objects with public ACLs.
Note that setting to
false
does not necessarily mean that the bucket is completely accessible to the public. Rather, it enables the granting of public permissions on a per file basis.
new Bucket(stack, "Bucket", {
blockPublicACLs: true,
});
cors?
Type : boolean | Array<BucketCorsRule>
Default : true
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?
Type :
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, Queue | Topic | string | Function | BucketFunctionNotificationProps | BucketQueueNotificationProps | BucketTopicNotificationProps>
Used to create notifications for various bucket events
new Bucket(stack, "Bucket", {
notifications: {
myNotification: "src/notification.main",
}
});
cdk?
Type :
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
Type :
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, Queue | Topic | string | Function | 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<BindingResource>
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<BindingResource>
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