interface IBucket

Language	Type name
.NET	`Amazon.CDK.AWS.S3.IBucket`
Java	`software.amazon.awscdk.services.s3.IBucket`
Python	`aws_cdk.aws_s3.IBucket`
TypeScript (source)	`@aws-cdk/aws-s3` » `IBucket`

Implemented by Bucket

Obtainable from Bucket.fromBucketArn(), Bucket.fromBucketAttributes(), Bucket.fromBucketName()

Properties

Name	Type	Description
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	`ConstructNode`	The construct tree node for this construct.
stack	`Stack`	The stack in which this resource is defined.
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.

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: ConstructNode

The construct tree node for this construct.

stack

Type: Stack

The stack in which this resource is defined.

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
addEventNotification(event, dest, ...filters)	Adds a bucket notification event destination.
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.
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?)	Grant write permissions to this bucket to an IAM principal.
onCloudTrailEvent(id, options?)	Defines a CloudWatch event that triggers when something happens to this bucket.
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.
transferAccelerationUrlForObject(key?, options?)	The https Transfer Acceleration URL of an S3 object.
urlForObject(key?)	The https URL of an S3 object. 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:.

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.

   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/*'})

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(s3.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 "*".

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” });

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 — The principal.
objectsKeyPattern string — Restrict the permission to a certain key pattern (default '*').

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 {@link grantWrite} or {@link 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 — The principal.
objectsKeyPattern any — Restrict the permission to a certain key pattern (default '*').

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 {@link grantPutAcl} method.

grantWrite(identity, objectsKeyPattern?)

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

Parameters

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

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.

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

Defines a CloudWatch event that triggers when something happens to this bucket.

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

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