class Bucket (construct)

Language	Type name
.NET	Amazon.CDK.AWS.S3.Bucket
Go	github.com/aws/aws-cdk-go/awscdk/v2/awss3#Bucket
Java	software.amazon.awscdk.services.s3.Bucket
Python	aws_cdk.aws_s3.Bucket
TypeScript (source)	aws-cdk-lib » aws_s3 » Bucket

Implements IConstruct, IDependable, IResource, IBucket

An S3 bucket with associated policy objects.

This bucket does not yet have all features that exposed by the underlying BucketResource.

Example

import { RemovalPolicy } from 'aws-cdk-lib';

new s3.Bucket(scope, 'Bucket', {
  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
  encryption: s3.BucketEncryption.S3_MANAGED,
  enforceSSL: true,
  versioned: true,
  removalPolicy: RemovalPolicy.RETAIN,
});

Initializer

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

Parameters

• scope Construct
• id string
• props BucketProps

Construct Props

Name	Type	Description
accessControl?	BucketAccessControl	Specifies a canned ACL that grants predefined permissions to the bucket.
autoDeleteObjects?	boolean	Whether all objects should be automatically deleted when the bucket is removed from the stack or when the stack is deleted.
blockPublicAccess?	BlockPublicAccess	The block public access configuration of this bucket.
bucketKeyEnabled?	boolean	Whether Amazon S3 should use its own intermediary key to generate data keys.
bucketName?	string	Physical name of this bucket.
cors?	CorsRule[]	The CORS configuration of this bucket.
encryption?	BucketEncryption	The kind of server-side encryption to apply to this bucket.
encryptionKey?	IKey	External KMS key to use for bucket encryption.
enforceSSL?	boolean	Enforces SSL for requests.
eventBridgeEnabled?	boolean	Whether this bucket should send notifications to Amazon EventBridge or not.
intelligentTieringConfigurations?	IntelligentTieringConfiguration[]	Inteligent Tiering Configurations.
inventories?	Inventory[]	The inventory configuration of the bucket.
lifecycleRules?	LifecycleRule[]	Rules that define how Amazon S3 manages objects during their lifetime.
metrics?	BucketMetrics[]	The metrics configuration of this bucket.
minimumTLSVersion?	number	Enforces minimum TLS version for requests.
notificationsHandlerRole?	IRole	The role to be used by the notifications handler.
notificationsSkipDestinationValidation?	boolean	Skips notification validation of Amazon SQS, Amazon SNS, and Lambda destinations.
objectLockDefaultRetention?	ObjectLockRetention	The default retention mode and rules for S3 Object Lock.
objectLockEnabled?	boolean	Enable object lock on the bucket.
objectOwnership?	ObjectOwnership	The objectOwnership of the bucket.
publicReadAccess?	boolean	Grants public read access to all objects in the bucket.
removalPolicy?	RemovalPolicy	Policy to apply when the bucket is removed from this stack.
serverAccessLogsBucket?	IBucket	Destination bucket for the server access logs.
serverAccessLogsPrefix?	string	Optional log file prefix to use for the bucket's access logs.
targetObjectKeyFormat?	TargetObjectKeyFormat	Optional key format for log objects.
transferAcceleration?	boolean	Whether this bucket should have transfer acceleration turned on or not.
transitionDefaultMinimumObjectSize?	TransitionDefaultMinimumObjectSize	Indicates which default minimum object size behavior is applied to the lifecycle configuration.
versioned?	boolean	Whether this bucket should have versioning turned on or not.
websiteErrorDocument?	string	The name of the error document (e.g. "404.html") for the website. websiteIndexDocument must also be set if this is set.
websiteIndexDocument?	string	The name of the index document (e.g. "index.html") for the website. Enables static website hosting for this bucket.
websiteRedirect?	RedirectTarget	Specifies the redirect behavior of all requests to a website endpoint of a bucket.
websiteRoutingRules?	RoutingRule[]	Rules that define when a redirect is applied and the redirect behavior.

---

accessControl?

Type: BucketAccessControl (optional, default: BucketAccessControl.PRIVATE)

Specifies a canned ACL that grants predefined permissions to the bucket.

---

autoDeleteObjects?

Type: boolean (optional, default: false)

Whether all objects should be automatically deleted when the bucket is removed from the stack or when the stack is deleted.

Requires the removalPolicy to be set to RemovalPolicy.DESTROY.

Warning if you have deployed a bucket with autoDeleteObjects: true, switching this to false in a CDK version before 1.126.0 will lead to all objects in the bucket being deleted. Be sure to update your bucket resources by deploying with CDK version 1.126.0 or later before switching this value to false.

Setting autoDeleteObjects to true on a bucket will add s3:PutBucketPolicy to the bucket policy. This is because during bucket deletion, the custom resource provider needs to update the bucket policy by adding a deny policy for s3:PutObject to prevent race conditions with external bucket writers.

---

blockPublicAccess?

Type: BlockPublicAccess (optional, default: CloudFormation defaults will apply. New buckets and objects don't allow public access, but users can modify bucket policies or object permissions to allow public access)

The block public access configuration of this bucket.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html

---

bucketKeyEnabled?

Type: boolean (optional, default: false)

Whether Amazon S3 should use its own intermediary key to generate data keys.

Only relevant when using KMS for encryption.

• If not enabled, every object GET and PUT will cause an API call to KMS (with the attendant cost implications of that).
• If enabled, S3 will use its own time-limited key instead.

Only relevant, when Encryption is not set to BucketEncryption.UNENCRYPTED.

---

bucketName?

Type: string (optional, default: Assigned by CloudFormation (recommended).)

Physical name of this bucket.

---

cors?

Type: CorsRule[] (optional, default: No CORS configuration.)

The CORS configuration of this bucket.

See also: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-cors.html

---

encryption?

Type: BucketEncryption (optional, default: KMS if encryptionKey is specified, or UNENCRYPTED otherwise. But if UNENCRYPTED is specified, the bucket will be encrypted as S3_MANAGED automatically.)

The kind of server-side encryption to apply to this bucket.

If you choose KMS, you can specify a KMS key via encryptionKey. If encryption key is not specified, a key will automatically be created.

---

encryptionKey?

Type: IKey (optional, default: If encryption is set to KMS and this property is undefined, a new KMS key will be created and associated with this bucket.)

External KMS key to use for bucket encryption.

The encryption property must be either not specified or set to KMS or DSSE. An error will be emitted if encryption is set to UNENCRYPTED or S3_MANAGED.

---

enforceSSL?

Type: boolean (optional, default: false)

Enforces SSL for requests.

S3.5 of the AWS Foundational Security Best Practices Regarding S3.

See also: https://docs.aws.amazon.com/config/latest/developerguide/s3-bucket-ssl-requests-only.html

---

eventBridgeEnabled?

Type: boolean (optional, default: false)

Whether this bucket should send notifications to Amazon EventBridge or not.

---

intelligentTieringConfigurations?

Type: IntelligentTieringConfiguration[] (optional, default: No Intelligent Tiiering Configurations.)

Inteligent Tiering Configurations.

See also: https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering.html

---

inventories?

Type: Inventory[] (optional, default: No inventory configuration)

The inventory configuration of the bucket.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-inventory.html

---

lifecycleRules?

Type: LifecycleRule[] (optional, default: No lifecycle rules.)

Rules that define how Amazon S3 manages objects during their lifetime.

---

metrics?

Type: BucketMetrics[] (optional, default: No metrics configuration.)

The metrics configuration of this bucket.

See also: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-metricsconfiguration.html

---

minimumTLSVersion?

Type: number (optional, default: No minimum TLS version is enforced.)

Enforces minimum TLS version for requests.

Requires enforceSSL to be enabled.

See also: https://docs.aws.amazon.com/AmazonS3/latest/userguide/amazon-s3-policy-keys.html#example-object-tls-version

---

notificationsHandlerRole?

Type: IRole (optional, default: a new role will be created.)

The role to be used by the notifications handler.

---

notificationsSkipDestinationValidation?

Type: boolean (optional, default: false)

Skips notification validation of Amazon SQS, Amazon SNS, and Lambda destinations.

---

objectLockDefaultRetention?

Type: ObjectLockRetention (optional, default: no default retention period)

The default retention mode and rules for S3 Object Lock.

Default retention can be configured after a bucket is created if the bucket already has object lock enabled. Enabling object lock for existing buckets is not supported.

See also: https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-bucket-config-enable

---

objectLockEnabled?

Type: boolean (optional, default: false, unless objectLockDefaultRetention is set (then, true))

Enable object lock on the bucket.

Enabling object lock for existing buckets is not supported. Object lock must be enabled when the bucket is created.

See also: https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-bucket-config-enable

---

objectOwnership?

Type: ObjectOwnership (optional, default: No ObjectOwnership configuration. By default, Amazon S3 sets Object Ownership to Bucket owner enforced. This means ACLs are disabled and the bucket owner will own every object.)

The objectOwnership of the bucket.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/about-object-ownership.html

---

publicReadAccess?

Type: boolean (optional, default: false)

Grants public read access to all objects in the bucket.

Similar to calling bucket.grantPublicAccess()

---

removalPolicy?

Type: RemovalPolicy (optional, default: The bucket will be orphaned.)

Policy to apply when the bucket is removed from this stack.

---

serverAccessLogsBucket?

Type: IBucket (optional, default: If "serverAccessLogsPrefix" undefined - access logs disabled, otherwise - log to current bucket.)

Destination bucket for the server access logs.

---

serverAccessLogsPrefix?

Type: string (optional, default: No log file prefix)

Optional log file prefix to use for the bucket's access logs.

If defined without "serverAccessLogsBucket", enables access logs to current bucket with this prefix.

---

targetObjectKeyFormat?

Type: TargetObjectKeyFormat (optional, default: the default key format is: [DestinationPrefix][YYYY]-[MM]-[DD]-[hh]-[mm]-[ss]-[UniqueString])

Optional key format for log objects.

---

transferAcceleration?

Type: boolean (optional, default: false)

Whether this bucket should have transfer acceleration turned on or not.

---

transitionDefaultMinimumObjectSize?

Type: TransitionDefaultMinimumObjectSize (optional, default: TransitionDefaultMinimumObjectSize.VARIES_BY_STORAGE_CLASS before September 2024, otherwise TransitionDefaultMinimumObjectSize.ALL_STORAGE_CLASSES_128_K.)

Indicates which default minimum object size behavior is applied to the lifecycle configuration.

To customize the minimum object size for any transition you can add a filter that specifies a custom objectSizeGreaterThan or objectSizeLessThan for lifecycleRules property. Custom filters always take precedence over the default transition behavior.

---

versioned?

Type: boolean (optional, default: false (unless object lock is enabled, then true))

Whether this bucket should have versioning turned on or not.

---

websiteErrorDocument?

Type: string (optional, default: No error document.)

The name of the error document (e.g. "404.html") for the website. websiteIndexDocument must also be set if this is set.

---

websiteIndexDocument?

Type: string (optional, default: No index document.)

The name of the index document (e.g. "index.html") for the website. Enables static website hosting for this bucket.

---

websiteRedirect?

Type: RedirectTarget (optional, default: No redirection.)

Specifies the redirect behavior of all requests to a website endpoint of a bucket.

If you specify this property, you can't specify "websiteIndexDocument", "websiteErrorDocument" nor , "websiteRoutingRules".

---

websiteRoutingRules?

Type: RoutingRule[] (optional, default: No redirection rules.)

Rules that define when a redirect is applied and the redirect behavior.

Properties

Name	Type	Description
autoCreatePolicy	boolean	Indicates if a bucket resource policy should automatically created upon the first call to addToResourcePolicy.
bucketArn	string	The ARN of the bucket.
bucketDomainName	string	The IPv4 DNS name of the specified bucket.
bucketDualStackDomainName	string	The IPv6 DNS name of the specified bucket.
bucketName	string	The name of the bucket.
bucketRegionalDomainName	string	The regional domain name of the specified bucket.
bucketWebsiteDomainName	string	The Domain name of the static website.
bucketWebsiteUrl	string	The URL of the static website.
env	ResourceEnvironment	The environment this resource belongs to.
node	Node	The tree node.
stack	Stack	The stack in which this resource is defined.
disallowPublicAccess?	boolean	Whether to disallow public access.
encryptionKey?	IKey	Optional KMS encryption key associated with this bucket.
isWebsite?	boolean	If this bucket has been configured for static website hosting.
policy?	BucketPolicy	The resource policy associated with this bucket.

---

autoCreatePolicy

Type: boolean

Indicates if a bucket resource policy should automatically created upon the first call to addToResourcePolicy.

---

bucketArn

Type: string

The ARN of the bucket.

---

bucketDomainName

Type: string

The IPv4 DNS name of the specified bucket.

---

bucketDualStackDomainName

Type: string

The IPv6 DNS name of the specified bucket.

---

bucketName

Type: string

The name of the bucket.

---

bucketRegionalDomainName

Type: string

The regional domain name of the specified bucket.

---

bucketWebsiteDomainName

Type: string

The Domain name of the static website.

---

bucketWebsiteUrl

Type: string

The URL of the static website.

---

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

---

node

Type: Node

The tree node.

---

stack

Type: Stack

The stack in which this resource is defined.

---

disallowPublicAccess?

Type: boolean (optional)

Whether to disallow public access.

---

encryptionKey?

Type: IKey (optional)

Optional KMS encryption key associated with this bucket.

---

isWebsite?

Type: boolean (optional)

If this bucket has been configured for static website hosting.

---

policy?

Type: BucketPolicy (optional)

The resource policy associated with this bucket.

If autoCreatePolicy is true, a BucketPolicy will be created upon the first call to addToResourcePolicy(s).

Methods

Name	Description
addCorsRule(rule)	Adds a cross-origin access configuration for objects in an Amazon S3 bucket.
addEventNotification(event, dest, ...filters)	Adds a bucket notification event destination.
addInventory(inventory)	Add an inventory configuration.
addLifecycleRule(rule)	Add a lifecycle rule to the bucket.
addMetric(metric)	Adds a metrics configuration for the CloudWatch request metrics from the bucket.
addObjectCreatedNotification(dest, ...filters)	Subscribes a destination to receive notifications when an object is created in the bucket.
addObjectRemovedNotification(dest, ...filters)	Subscribes a destination to receive notifications when an object is removed from the bucket.
addToResourcePolicy(permission)	Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use bucketArn and arnForObjects(keys) to obtain ARNs for this bucket or objects.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
arnForObjects(keyPattern)	Returns an ARN that represents all objects within the bucket that match the key pattern specified.
enableEventBridgeNotification()	Enables event bridge notification, causing all events below to be sent to EventBridge:.
grantDelete(identity, objectsKeyPattern?)	Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.
grantPublicAccess(keyPrefix?, ...allowedActions)	Allows unrestricted access to objects from this bucket.
grantPut(identity, objectsKeyPattern?)	Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.
grantPutAcl(identity, objectsKeyPattern?)	Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.
grantRead(identity, objectsKeyPattern?)	Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
grantReadWrite(identity, objectsKeyPattern?)	Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
grantWrite(identity, objectsKeyPattern?, allowedActionPatterns?)	Grant write permissions to this bucket to an IAM principal.
onCloudTrailEvent(id, options?)	Define a CloudWatch event that triggers when something happens to this repository.
onCloudTrailPutObject(id, options?)	Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call.
onCloudTrailWriteObject(id, options?)	Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.
s3UrlForObject(key?)	The S3 URL of an S3 object. For example:.
toString()	Returns a string representation of this construct.
transferAccelerationUrlForObject(key?, options?)	The https Transfer Acceleration URL of an S3 object.
urlForObject(key?)	The https URL of an S3 object. Specify regional: false at the options for non-regional URLs. For example:.
virtualHostedUrlForObject(key?, options?)	The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.
static fromBucketArn(scope, id, bucketArn)
static fromBucketAttributes(scope, id, attrs)	Creates a Bucket construct that represents an external bucket.
static fromBucketName(scope, id, bucketName)
static fromCfnBucket(cfnBucket)	Create a mutable IBucket based on a low-level CfnBucket.
static validateBucketName(physicalName, allowLegacyBucketNaming?)	Thrown an exception if the given bucket name is not valid.

---

addCorsRule(rule)

public addCorsRule(rule: CorsRule): void

Parameters

• rule CorsRule — The CORS configuration rule to add.

Adds a cross-origin access configuration for objects in an Amazon S3 bucket.

---

addEventNotification(event, dest, ...filters)

public addEventNotification(event: EventType, dest: IBucketNotificationDestination, ...filters: NotificationKeyFilter[]): void

Parameters

• event EventType — The event to trigger the notification.
• dest IBucketNotificationDestination — The notification destination (Lambda, SNS Topic or SQS Queue).
• filters NotificationKeyFilter — S3 object key filter rules to determine which objects trigger this event.

Adds a bucket notification event destination.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html Example

   declare const myLambda: lambda.Function;
   const bucket = new s3.Bucket(this, 'MyBucket');
   bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.LambdaDestination(myLambda), {prefix: 'home/myusername/*'});

---

addInventory(inventory)

public addInventory(inventory: Inventory): void

Parameters

• inventory Inventory — configuration to add.

Add an inventory configuration.

---

addLifecycleRule(rule)

public addLifecycleRule(rule: LifecycleRule): void

Parameters

• rule LifecycleRule — The rule to add.

Add a lifecycle rule to the bucket.

---

addMetric(metric)

public addMetric(metric: BucketMetrics): void

Parameters

• metric BucketMetrics — The metric configuration to add.

Adds a metrics configuration for the CloudWatch request metrics from the bucket.

---

addObjectCreatedNotification(dest, ...filters)

public addObjectCreatedNotification(dest: IBucketNotificationDestination, ...filters: NotificationKeyFilter[]): void

Parameters

• dest IBucketNotificationDestination — The notification destination (see onEvent).
• filters NotificationKeyFilter — Filters (see onEvent).

Subscribes a destination to receive notifications when an object is created in the bucket.

This is identical to calling onEvent(EventType.OBJECT_CREATED).

---

addObjectRemovedNotification(dest, ...filters)

public addObjectRemovedNotification(dest: IBucketNotificationDestination, ...filters: NotificationKeyFilter[]): void

Parameters

• dest IBucketNotificationDestination — The notification destination (see onEvent).
• filters NotificationKeyFilter — Filters (see onEvent).

Subscribes a destination to receive notifications when an object is removed from the bucket.

This is identical to calling onEvent(EventType.OBJECT_REMOVED).

---

addToResourcePolicy(permission)

public addToResourcePolicy(permission: PolicyStatement): AddToResourcePolicyResult

Parameters

• permission PolicyStatement — the policy statement to be added to the bucket's policy.

Returns

• AddToResourcePolicyResult

Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use bucketArn and arnForObjects(keys) to obtain ARNs for this bucket or objects.

Note that the policy statement may or may not be added to the policy. For example, when an IBucket is created from an existing bucket, it's not possible to tell whether the bucket already has a policy attached, let alone to re-use that policy to add more statements to it. So it's safest to do nothing in these cases.

---

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

• policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

---

arnForObjects(keyPattern)

public arnForObjects(keyPattern: string): string

Parameters

• keyPattern string

Returns

• string

Returns an ARN that represents all objects within the bucket that match the key pattern specified.

To represent all keys, specify "*".

If you need to specify a keyPattern with multiple components, concatenate them into a single string, e.g.:

arnForObjects(home/${team}/${user}/*)

---

enableEventBridgeNotification()

public enableEventBridgeNotification(): void

Enables event bridge notification, causing all events below to be sent to EventBridge:.

• Object Deleted (DeleteObject)
• Object Deleted (Lifecycle expiration)
• Object Restore Initiated
• Object Restore Completed
• Object Restore Expired
• Object Storage Class Changed
• Object Access Tier Changed
• Object ACL Updated
• Object Tags Added
• Object Tags Deleted

---

grantDelete(identity, objectsKeyPattern?)

public grantDelete(identity: IGrantable, objectsKeyPattern?: any): Grant

Parameters

• identity IGrantable — The principal.
• objectsKeyPattern any — Restrict the permission to a certain key pattern (default '*').

Returns

• Grant

Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.

---

grantPublicAccess(keyPrefix?, ...allowedActions)

public grantPublicAccess(keyPrefix?: string, ...allowedActions: string[]): Grant

Parameters

• keyPrefix string — the prefix of S3 object keys (e.g. home/*). Default is "*".
• allowedActions string — the set of S3 actions to allow.

Returns

• Grant

Allows unrestricted access to objects from this bucket.

IMPORTANT: This permission allows anyone to perform actions on S3 objects in this bucket, which is useful for when you configure your bucket as a website and want everyone to be able to read objects in the bucket without needing to authenticate.

Without arguments, this method will grant read ("s3:GetObject") access to all objects ("*") in the bucket.

The method returns the iam.Grant object, which can then be modified as needed. For example, you can add a condition that will restrict access only to an IPv4 range like this:

const grant = bucket.grantPublicAccess();
grant.resourceStatement!.addCondition(‘IpAddress’, { “aws:SourceIp”: “54.240.143.0/24” });

Note that if this IBucket refers to an existing bucket, possibly not managed by CloudFormation, this method will have no effect, since it's impossible to modify the policy of an existing bucket.

---

grantPut(identity, objectsKeyPattern?)

public grantPut(identity: IGrantable, objectsKeyPattern?: any): Grant

Parameters

• identity IGrantable — The principal.
• objectsKeyPattern any — Restrict the permission to a certain key pattern (default '*').

Returns

• Grant

Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.

If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.

---

grantPutAcl(identity, objectsKeyPattern?)

public grantPutAcl(identity: IGrantable, objectsKeyPattern?: string): Grant

Parameters

• identity IGrantable
• objectsKeyPattern string

Returns

• Grant

Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.

If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, calling grantWrite or grantReadWrite no longer grants permissions to modify the ACLs of the objects; in this case, if you need to modify object ACLs, call this method explicitly.

---

grantRead(identity, objectsKeyPattern?)

public grantRead(identity: IGrantable, objectsKeyPattern?: any): Grant

Parameters

• identity IGrantable — The principal.
• objectsKeyPattern any — Restrict the permission to a certain key pattern (default '*').

Returns

• Grant

Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

If encryption is used, permission to use the key to decrypt the contents of the bucket will also be granted to the same principal.

---

grantReadWrite(identity, objectsKeyPattern?)

public grantReadWrite(identity: IGrantable, objectsKeyPattern?: any): Grant

Parameters

• identity IGrantable
• objectsKeyPattern any

Returns

• Grant

Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

If an encryption key is used, permission to use the key for encrypt/decrypt will also be granted.

Before CDK version 1.85.0, this method granted the s3:PutObject* permission that included s3:PutObjectAcl, which could be used to grant read/write object access to IAM principals in other accounts. If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, and make sure the @aws-cdk/aws-s3:grantWriteWithoutAcl feature flag is set to true in the context key of your cdk.json file. If you've already updated, but still need the principal to have permissions to modify the ACLs, use the grantPutAcl method.

---

grantWrite(identity, objectsKeyPattern?, allowedActionPatterns?)

public grantWrite(identity: IGrantable, objectsKeyPattern?: any, allowedActionPatterns?: string[]): Grant

Parameters

• identity IGrantable
• objectsKeyPattern any
• allowedActionPatterns string[]

Returns

• Grant

Grant write permissions to this bucket to an IAM principal.

If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.

Before CDK version 1.85.0, this method granted the s3:PutObject* permission that included s3:PutObjectAcl, which could be used to grant read/write object access to IAM principals in other accounts. If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, and make sure the @aws-cdk/aws-s3:grantWriteWithoutAcl feature flag is set to true in the context key of your cdk.json file. If you've already updated, but still need the principal to have permissions to modify the ACLs, use the grantPutAcl method.

---

onCloudTrailEvent(id, options?)

public onCloudTrailEvent(id: string, options?: OnCloudTrailBucketEventOptions): Rule

Parameters

• id string — The id of the rule.
• options OnCloudTrailBucketEventOptions — Options for adding the rule.

Returns

• Rule

Define a CloudWatch event that triggers when something happens to this repository.

Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.

---

onCloudTrailPutObject(id, options?)

public onCloudTrailPutObject(id: string, options?: OnCloudTrailBucketEventOptions): Rule

Parameters

• id string — The id of the rule.
• options OnCloudTrailBucketEventOptions — Options for adding the rule.

Returns

• Rule

Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call.

Note that some tools like aws s3 cp will automatically use either PutObject or the multipart upload API depending on the file size, so using onCloudTrailWriteObject may be preferable.

Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.

---

onCloudTrailWriteObject(id, options?)

public onCloudTrailWriteObject(id: string, options?: OnCloudTrailBucketEventOptions): Rule

Parameters

• id string — The id of the rule.
• options OnCloudTrailBucketEventOptions — Options for adding the rule.

Returns

• Rule

Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.

This includes the events PutObject, CopyObject, and CompleteMultipartUpload.

Note that some tools like aws s3 cp will automatically use either PutObject or the multipart upload API depending on the file size, so using this method may be preferable to onCloudTrailPutObject.

Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.

---

s3UrlForObject(key?)

public s3UrlForObject(key?: string): string

Parameters

• key string — The S3 key of the object.

Returns

• string

The S3 URL of an S3 object. For example:.

• s3://onlybucket
• s3://bucket/key

---

toString()

public toString(): string

Returns

• string

Returns a string representation of this construct.

---

transferAccelerationUrlForObject(key?, options?)

public transferAccelerationUrlForObject(key?: string, options?: TransferAccelerationUrlOptions): string

Parameters

• key string — The S3 key of the object.
• options TransferAccelerationUrlOptions — Options for generating URL.

Returns

• string

The https Transfer Acceleration URL of an S3 object.

Specify dualStack: true at the options for dual-stack endpoint (connect to the bucket over IPv6). For example:

• https://bucket.s3-accelerate.amazonaws.com
• https://bucket.s3-accelerate.amazonaws.com/key

---

urlForObject(key?)

public urlForObject(key?: string): string

Parameters

• key string — The S3 key of the object.

Returns

• string

The https URL of an S3 object. Specify regional: false at the options for non-regional URLs. For example:.

• https://s3.us-west-1.amazonaws.com/onlybucket
• https://s3.us-west-1.amazonaws.com/bucket/key
• https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey

---

virtualHostedUrlForObject(key?, options?)

public virtualHostedUrlForObject(key?: string, options?: VirtualHostedStyleUrlOptions): string

Parameters

• key string — The S3 key of the object.
• options VirtualHostedStyleUrlOptions — Options for generating URL.

Returns

• string

The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.

• https://only-bucket.s3.us-west-1.amazonaws.com
• https://bucket.s3.us-west-1.amazonaws.com/key
• https://bucket.s3.amazonaws.com/key
• https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey

---

static fromBucketArn(scope, id, bucketArn)

public static fromBucketArn(scope: Construct, id: string, bucketArn: string): IBucket

Parameters

• scope Construct
• id string
• bucketArn string

Returns

• IBucket

---

static fromBucketAttributes(scope, id, attrs)

public static fromBucketAttributes(scope: Construct, id: string, attrs: BucketAttributes): IBucket

Parameters

• scope Construct — The parent creating construct (usually this).
• id string — The construct's name.
• attrs BucketAttributes — A BucketAttributes object.

Returns

• IBucket

Creates a Bucket construct that represents an external bucket.

---

static fromBucketName(scope, id, bucketName)

public static fromBucketName(scope: Construct, id: string, bucketName: string): IBucket

Parameters

• scope Construct
• id string
• bucketName string

Returns

• IBucket

---

static fromCfnBucket(cfnBucket)

public static fromCfnBucket(cfnBucket: CfnBucket): IBucket

Parameters

• cfnBucket CfnBucket

Returns

• IBucket

Create a mutable IBucket based on a low-level CfnBucket.

---

static validateBucketName(physicalName, allowLegacyBucketNaming?)

public static validateBucketName(physicalName: string, allowLegacyBucketNaming?: boolean): void

Parameters

• physicalName string — name of the bucket.
• allowLegacyBucketNaming boolean — allow legacy bucket naming style, default is false.

Thrown an exception if the given bucket name is not valid.