IBucket

class aws_cdk.aws_s3.IBucket(*args, **kwds)

Bases: IResource, Protocol

Methods

add_event_notification(event, dest, *filters)

Adds a bucket notification event destination.

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. Each filter must include a prefix and/or suffix that will be matched against the s3 object key. Refer to the S3 Developer Guide for details about allowed filter rules.

See:

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

Return type:

None

Example:

# my_lambda: lambda.Function

bucket = s3.Bucket(self, "MyBucket")
bucket.add_event_notification(s3.EventType.OBJECT_CREATED, s3n.LambdaDestination(my_lambda), prefix="home/myusername/*")
add_object_created_notification(dest, *filters)

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

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

Parameters:
Return type:

None

add_object_removed_notification(dest, *filters)

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

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

Parameters:
Return type:

None

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

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.

Parameters:

permission (PolicyStatement) – the policy statement to be added to the bucket’s policy.

Return type:

AddToResourcePolicyResult

Returns:

metadata about the execution of this method. If the policy was not added, the value of statementAdded will be false. You should always check this value to make sure that the operation was actually carried out. Otherwise, synthesis and deploy will terminate silently, which may be confusing.

apply_removal_policy(policy)

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

Parameters:

policy (RemovalPolicy) –

Return type:

None

arn_for_objects(key_pattern)

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

To represent all keys, specify "*".

Parameters:

key_pattern (str) –

Return type:

str

grant_delete(identity, objects_key_pattern=None)

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

Parameters:

  • identity (IGrantable) – The principal.

  • objects_key_pattern (Optional[Any]) – Restrict the permission to a certain key pattern (default ‘*’).

Return type:

Grant

grant_public_access(key_prefix=None, *allowed_actions)

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

  • key_prefix (Optional[str]) – the prefix of S3 object keys (e.g. home/*). Default is “*”.

  • allowed_actions (str) – the set of S3 actions to allow. Default is “s3:GetObject”.

Return type:

Grant

Returns:

The iam.PolicyStatement object, which can be used to apply e.g. conditions.

grant_put(identity, objects_key_pattern=None)

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.

Parameters:

  • identity (IGrantable) – The principal.

  • objects_key_pattern (Optional[Any]) – Restrict the permission to a certain key pattern (default ‘*’).

Return type:

Grant

grant_put_acl(identity, objects_key_pattern=None)

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.

Parameters:

  • identity (IGrantable) – The principal.

  • objects_key_pattern (Optional[str]) – Restrict the permission to a certain key pattern (default ‘*’).

Return type:

Grant

grant_read(identity, objects_key_pattern=None)

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.

Parameters:

  • identity (IGrantable) – The principal.

  • objects_key_pattern (Optional[Any]) – Restrict the permission to a certain key pattern (default ‘*’).

Return type:

Grant

grant_read_write(identity, objects_key_pattern=None)

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.

Parameters:

  • identity (IGrantable) – The principal.

  • objects_key_pattern (Optional[Any]) – Restrict the permission to a certain key pattern (default ‘*’).

Return type:

Grant

grant_write(identity, objects_key_pattern=None)

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

Parameters:

  • identity (IGrantable) – The principal.

  • objects_key_pattern (Optional[Any]) – Restrict the permission to a certain key pattern (default ‘*’).

Return type:

Grant

on_cloud_trail_event(id, *, paths=None, description=None, event_pattern=None, rule_name=None, target=None)

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.

Parameters:

  • id (str) – The id of the rule.

  • paths (Optional[Sequence[str]]) – Only watch changes to these object paths. Default: - Watch changes to all objects

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Union[EventPattern, Dict[str, Any], None]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

Return type:

Rule

on_cloud_trail_put_object(id, *, paths=None, description=None, event_pattern=None, rule_name=None, target=None)

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.

Parameters:

  • id (str) – The id of the rule.

  • paths (Optional[Sequence[str]]) – Only watch changes to these object paths. Default: - Watch changes to all objects

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Union[EventPattern, Dict[str, Any], None]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

Return type:

Rule

on_cloud_trail_write_object(id, *, paths=None, description=None, event_pattern=None, rule_name=None, target=None)

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.

Parameters:

  • id (str) – The id of the rule.

  • paths (Optional[Sequence[str]]) – Only watch changes to these object paths. Default: - Watch changes to all objects

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Union[EventPattern, Dict[str, Any], None]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

Return type:

Rule

s3_url_for_object(key=None)

The S3 URL of an S3 object.

For example:

  • s3://onlybucket

  • s3://bucket/key

Parameters:

key (Optional[str]) – The S3 key of the object. If not specified, the S3 URL of the bucket is returned.

Return type:

str

Returns:

an ObjectS3Url token

transfer_acceleration_url_for_object(key=None, *, dual_stack=None)

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

Parameters:

  • key (Optional[str]) – The S3 key of the object. If not specified, the URL of the bucket is returned.

  • dual_stack (Optional[bool]) – Dual-stack support to connect to the bucket over IPv6. Default: - false

Return type:

str

Returns:

an TransferAccelerationUrl token

url_for_object(key=None)

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

Parameters:

key (Optional[str]) – The S3 key of the object. If not specified, the URL of the bucket is returned.

Return type:

str

Returns:

an ObjectS3Url token

virtual_hosted_url_for_object(key=None, *, regional=None)

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

Parameters:

  • key (Optional[str]) – The S3 key of the object. If not specified, the URL of the bucket is returned.

  • regional (Optional[bool]) – Specifies the URL includes the region. Default: - true

Return type:

str

Returns:

an ObjectS3Url token

Attributes

bucket_arn

The ARN of the bucket.

Attribute:

true

bucket_domain_name

The IPv4 DNS name of the specified bucket.

Attribute:

true

bucket_dual_stack_domain_name

The IPv6 DNS name of the specified bucket.

Attribute:

true

bucket_name

The name of the bucket.

Attribute:

true

bucket_regional_domain_name

The regional domain name of the specified bucket.

Attribute:

true

bucket_website_domain_name

The Domain name of the static website.

Attribute:

true

bucket_website_url

The URL of the static website.

Attribute:

true

encryption_key

Optional KMS encryption key associated with this bucket.

env

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.

is_website

If this bucket has been configured for static website hosting.

node

The construct tree node for this construct.

policy

The resource policy associated with this bucket.

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

stack

The stack in which this resource is defined.