Bucket

class aws_cdk.aws_s3.Bucket(scope, id, *, access_control=None, auto_delete_objects=None, block_public_access=None, bucket_key_enabled=None, bucket_name=None, cors=None, encryption=None, encryption_key=None, enforce_ssl=None, event_bridge_enabled=None, intelligent_tiering_configurations=None, inventories=None, lifecycle_rules=None, metrics=None, minimum_tls_version=None, notifications_handler_role=None, object_lock_default_retention=None, object_lock_enabled=None, object_ownership=None, public_read_access=None, removal_policy=None, server_access_logs_bucket=None, server_access_logs_prefix=None, target_object_key_format=None, transfer_acceleration=None, versioned=None, website_error_document=None, website_index_document=None, website_redirect=None, website_routing_rules=None)

Bases: BucketBase

An S3 bucket with associated policy objects.

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

Example:

from aws_cdk import RemovalPolicy


s3.Bucket(scope, "Bucket",
    block_public_access=s3.BlockPublicAccess.BLOCK_ALL,
    encryption=s3.BucketEncryption.S3_MANAGED,
    enforce_sSL=True,
    versioned=True,
    removal_policy=RemovalPolicy.RETAIN
)
Parameters:
  • scope (Construct) –

  • id (str) –

  • access_control (Optional[BucketAccessControl]) – Specifies a canned ACL that grants predefined permissions to the bucket. Default: BucketAccessControl.PRIVATE

  • auto_delete_objects (Optional[bool]) – 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. Default: false

  • block_public_access (Optional[BlockPublicAccess]) – The block public access configuration of this bucket. 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

  • bucket_key_enabled (Optional[bool]) – 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 set to BucketEncryption.KMS or BucketEncryption.KMS_MANAGED. Default: - false

  • bucket_name (Optional[str]) – Physical name of this bucket. Default: - Assigned by CloudFormation (recommended).

  • cors (Optional[Sequence[Union[CorsRule, Dict[str, Any]]]]) – The CORS configuration of this bucket. Default: - No CORS configuration.

  • encryption (Optional[BucketEncryption]) – 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. Default: - KMS if encryptionKey is specified, or UNENCRYPTED otherwise. But if UNENCRYPTED is specified, the bucket will be encrypted as S3_MANAGED automatically.

  • encryption_key (Optional[IKey]) – 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. Default: - If encryption is set to KMS and this property is undefined, a new KMS key will be created and associated with this bucket.

  • enforce_ssl (Optional[bool]) – Enforces SSL for requests. S3.5 of the AWS Foundational Security Best Practices Regarding S3. Default: false

  • event_bridge_enabled (Optional[bool]) – Whether this bucket should send notifications to Amazon EventBridge or not. Default: false

  • intelligent_tiering_configurations (Optional[Sequence[Union[IntelligentTieringConfiguration, Dict[str, Any]]]]) – Inteligent Tiering Configurations. Default: No Intelligent Tiiering Configurations.

  • inventories (Optional[Sequence[Union[Inventory, Dict[str, Any]]]]) – The inventory configuration of the bucket. Default: - No inventory configuration

  • lifecycle_rules (Optional[Sequence[Union[LifecycleRule, Dict[str, Any]]]]) – Rules that define how Amazon S3 manages objects during their lifetime. Default: - No lifecycle rules.

  • metrics (Optional[Sequence[Union[BucketMetrics, Dict[str, Any]]]]) – The metrics configuration of this bucket. Default: - No metrics configuration.

  • minimum_tls_version (Union[int, float, None]) – Enforces minimum TLS version for requests. Requires enforceSSL to be enabled. Default: No minimum TLS version is enforced.

  • notifications_handler_role (Optional[IRole]) – The role to be used by the notifications handler. Default: - a new role will be created.

  • object_lock_default_retention (Optional[ObjectLockRetention]) – 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. Default: no default retention period

  • object_lock_enabled (Optional[bool]) – 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. Default: false, unless objectLockDefaultRetention is set (then, true)

  • object_ownership (Optional[ObjectOwnership]) – The objectOwnership of the bucket. Default: - No ObjectOwnership configuration, uploading account will own the object.

  • public_read_access (Optional[bool]) – Grants public read access to all objects in the bucket. Similar to calling bucket.grantPublicAccess() Default: false

  • removal_policy (Optional[RemovalPolicy]) – Policy to apply when the bucket is removed from this stack. Default: - The bucket will be orphaned.

  • server_access_logs_bucket (Optional[IBucket]) – Destination bucket for the server access logs. Default: - If “serverAccessLogsPrefix” undefined - access logs disabled, otherwise - log to current bucket.

  • server_access_logs_prefix (Optional[str]) – 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. Default: - No log file prefix

  • target_object_key_format (Optional[TargetObjectKeyFormat]) – Optional key format for log objects. Default: - the default key format is: [DestinationPrefix][YYYY]-[MM]-[DD]-[hh]-[mm]-[ss]-[UniqueString]

  • transfer_acceleration (Optional[bool]) – Whether this bucket should have transfer acceleration turned on or not. Default: false

  • versioned (Optional[bool]) – Whether this bucket should have versioning turned on or not. Default: false (unless object lock is enabled, then true)

  • website_error_document (Optional[str]) – The name of the error document (e.g. “404.html”) for the website. websiteIndexDocument must also be set if this is set. Default: - No error document.

  • website_index_document (Optional[str]) – The name of the index document (e.g. “index.html”) for the website. Enables static website hosting for this bucket. Default: - No index document.

  • website_redirect (Union[RedirectTarget, Dict[str, Any], None]) – 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”. Default: - No redirection.

  • website_routing_rules (Optional[Sequence[Union[RoutingRule, Dict[str, Any]]]]) – Rules that define when a redirect is applied and the redirect behavior. Default: - No redirection rules.

Methods

add_cors_rule(*, allowed_methods, allowed_origins, allowed_headers=None, exposed_headers=None, id=None, max_age=None)

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

Parameters:
  • allowed_methods (Sequence[HttpMethods]) – An HTTP method that you allow the origin to execute.

  • allowed_origins (Sequence[str]) – One or more origins you want customers to be able to access the bucket from.

  • allowed_headers (Optional[Sequence[str]]) – Headers that are specified in the Access-Control-Request-Headers header. Default: - No headers allowed.

  • exposed_headers (Optional[Sequence[str]]) – One or more headers in the response that you want customers to be able to access from their applications. Default: - No headers exposed.

  • id (Optional[str]) – A unique identifier for this rule. Default: - No id specified.

  • max_age (Union[int, float, None]) – The time in seconds that your browser is to cache the preflight response for the specified resource. Default: - No caching.

Return type:

None

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_inventory(*, destination, enabled=None, format=None, frequency=None, include_object_versions=None, inventory_id=None, objects_prefix=None, optional_fields=None)

Add an inventory configuration.

Parameters:
  • destination (Union[InventoryDestination, Dict[str, Any]]) – The destination of the inventory.

  • enabled (Optional[bool]) – Whether the inventory is enabled or disabled. Default: true

  • format (Optional[InventoryFormat]) – The format of the inventory. Default: InventoryFormat.CSV

  • frequency (Optional[InventoryFrequency]) – Frequency at which the inventory should be generated. Default: InventoryFrequency.WEEKLY

  • include_object_versions (Optional[InventoryObjectVersion]) – If the inventory should contain all the object versions or only the current one. Default: InventoryObjectVersion.ALL

  • inventory_id (Optional[str]) – The inventory configuration ID. Should be limited to 64 characters and can only contain letters, numbers, periods, dashes, and underscores. Default: - generated ID.

  • objects_prefix (Optional[str]) – The inventory will only include objects that meet the prefix filter criteria. Default: - No objects prefix

  • optional_fields (Optional[Sequence[str]]) – A list of optional fields to be included in the inventory result. Default: - No optional fields.

Return type:

None

add_lifecycle_rule(*, abort_incomplete_multipart_upload_after=None, enabled=None, expiration=None, expiration_date=None, expired_object_delete_marker=None, id=None, noncurrent_version_expiration=None, noncurrent_versions_to_retain=None, noncurrent_version_transitions=None, object_size_greater_than=None, object_size_less_than=None, prefix=None, tag_filters=None, transitions=None)

Add a lifecycle rule to the bucket.

Parameters:
  • abort_incomplete_multipart_upload_after (Optional[Duration]) – Specifies a lifecycle rule that aborts incomplete multipart uploads to an Amazon S3 bucket. The AbortIncompleteMultipartUpload property type creates a lifecycle rule that aborts incomplete multipart uploads to an Amazon S3 bucket. When Amazon S3 aborts a multipart upload, it deletes all parts associated with the multipart upload. The underlying configuration is expressed in whole numbers of days. Providing a Duration that does not represent a whole number of days will result in a runtime or deployment error. Default: - Incomplete uploads are never aborted

  • enabled (Optional[bool]) – Whether this rule is enabled. Default: true

  • expiration (Optional[Duration]) – Indicates the number of days after creation when objects are deleted from Amazon S3 and Amazon Glacier. If you specify an expiration and transition time, you must use the same time unit for both properties (either in days or by date). The expiration time must also be later than the transition time. The underlying configuration is expressed in whole numbers of days. Providing a Duration that does not represent a whole number of days will result in a runtime or deployment error. Default: - No expiration timeout

  • expiration_date (Optional[datetime]) – Indicates when objects are deleted from Amazon S3 and Amazon Glacier. The date value must be in ISO 8601 format. The time is always midnight UTC. If you specify an expiration and transition time, you must use the same time unit for both properties (either in days or by date). The expiration time must also be later than the transition time. Default: - No expiration date

  • expired_object_delete_marker (Optional[bool]) – Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. If set to true, the delete marker will be expired. Default: false

  • id (Optional[str]) – A unique identifier for this rule. The value cannot be more than 255 characters.

  • noncurrent_version_expiration (Optional[Duration]) – Time between when a new version of the object is uploaded to the bucket and when old versions of the object expire. For buckets with versioning enabled (or suspended), specifies the time, in days, between when a new version of the object is uploaded to the bucket and when old versions of the object expire. When object versions expire, Amazon S3 permanently deletes them. If you specify a transition and expiration time, the expiration time must be later than the transition time. The underlying configuration is expressed in whole numbers of days. Providing a Duration that does not represent a whole number of days will result in a runtime or deployment error. Default: - No noncurrent version expiration

  • noncurrent_versions_to_retain (Union[int, float, None]) – Indicates a maximum number of noncurrent versions to retain. If there are this many more noncurrent versions, Amazon S3 permanently deletes them. Default: - No noncurrent versions to retain

  • noncurrent_version_transitions (Optional[Sequence[Union[NoncurrentVersionTransition, Dict[str, Any]]]]) – One or more transition rules that specify when non-current objects transition to a specified storage class. Only for for buckets with versioning enabled (or suspended). If you specify a transition and expiration time, the expiration time must be later than the transition time.

  • object_size_greater_than (Union[int, float, None]) – Specifies the minimum object size in bytes for this rule to apply to. Objects must be larger than this value in bytes. Default: - No rule

  • object_size_less_than (Union[int, float, None]) – Specifies the maximum object size in bytes for this rule to apply to. Objects must be smaller than this value in bytes. Default: - No rule

  • prefix (Optional[str]) – Object key prefix that identifies one or more objects to which this rule applies. Default: - Rule applies to all objects

  • tag_filters (Optional[Mapping[str, Any]]) – The TagFilter property type specifies tags to use to identify a subset of objects for an Amazon S3 bucket. Default: - Rule applies to all objects

  • transitions (Optional[Sequence[Union[Transition, Dict[str, Any]]]]) – One or more transition rules that specify when an object transitions to a specified storage class. If you specify an expiration and transition time, you must use the same time unit for both properties (either in days or by date). The expiration time must also be later than the transition time. Default: - No transition rules

Return type:

None

add_metric(*, id, prefix=None, tag_filters=None)

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

Parameters:
  • id (str) – The ID used to identify the metrics configuration.

  • prefix (Optional[str]) – The prefix that an object must have to be included in the metrics results.

  • tag_filters (Optional[Mapping[str, Any]]) – Specifies a list of tag filters to use as a metrics configuration filter. The metrics configuration includes only objects that meet the filter’s criteria.

Return type:

None

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

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

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

Parameters:

key_pattern (str) –

Return type:

str

enable_event_bridge_notification()

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

  • 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

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 ‘*’). Parameter type is any but string should be passed in.

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

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.

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

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 ‘*’). Parameter type is any but string should be passed in.

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

Parameters:
  • identity (IGrantable) –

  • objects_key_pattern (Optional[str]) –

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 ‘*’). Parameter type is any but string should be passed in.

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

Parameters:
  • identity (IGrantable) –

  • objects_key_pattern (Optional[Any]) –

Return type:

Grant

grant_write(identity, objects_key_pattern=None, allowed_action_patterns=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 grantPutAcl method.

Parameters:
  • identity (IGrantable) –

  • objects_key_pattern (Optional[Any]) –

  • allowed_action_patterns (Optional[Sequence[str]]) –

Return type:

Grant

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

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.

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

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

  • cross_stack_scope (Optional[Construct]) – The scope to use if the source of the rule and its target are in different Stacks (but in the same account & region). This helps dealing with cycles that often arise in these situations. Default: - none (the main scope will be used, even for cross-stack Events)

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

Return type:

Rule

on_cloud_trail_put_object(id, *, paths=None, target=None, cross_stack_scope=None, description=None, event_pattern=None, rule_name=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

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

  • cross_stack_scope (Optional[Construct]) – The scope to use if the source of the rule and its target are in different Stacks (but in the same account & region). This helps dealing with cycles that often arise in these situations. Default: - none (the main scope will be used, even for cross-stack Events)

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

Return type:

Rule

on_cloud_trail_write_object(id, *, paths=None, target=None, cross_stack_scope=None, description=None, event_pattern=None, rule_name=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

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

  • cross_stack_scope (Optional[Construct]) – The scope to use if the source of the rule and its target are in different Stacks (but in the same account & region). This helps dealing with cycles that often arise in these situations. Default: - none (the main scope will be used, even for cross-stack Events)

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

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

to_string()

Returns a string representation of this construct.

Return type:

str

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

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.

bucket_domain_name

The IPv4 DNS name of the specified bucket.

bucket_dual_stack_domain_name

The IPv6 DNS name of the specified bucket.

bucket_name

The name of the bucket.

bucket_regional_domain_name

The regional domain name of the specified bucket.

bucket_website_domain_name

The Domain name of the static website.

bucket_website_url

The URL of the static website.

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

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.

Static Methods

classmethod from_bucket_arn(scope, id, bucket_arn)
Parameters:
  • scope (Construct) –

  • id (str) –

  • bucket_arn (str) –

Return type:

IBucket

classmethod from_bucket_attributes(scope, id, *, account=None, bucket_arn=None, bucket_domain_name=None, bucket_dual_stack_domain_name=None, bucket_name=None, bucket_regional_domain_name=None, bucket_website_new_url_format=None, bucket_website_url=None, encryption_key=None, is_website=None, notifications_handler_role=None, region=None)

Creates a Bucket construct that represents an external bucket.

Parameters:
  • scope (Construct) – The parent creating construct (usually this).

  • id (str) – The construct’s name.

  • account (Optional[str]) – The account this existing bucket belongs to. Default: - it’s assumed the bucket belongs to the same account as the scope it’s being imported into

  • bucket_arn (Optional[str]) – The ARN of the bucket. At least one of bucketArn or bucketName must be defined in order to initialize a bucket ref.

  • bucket_domain_name (Optional[str]) – The domain name of the bucket. Default: - Inferred from bucket name

  • bucket_dual_stack_domain_name (Optional[str]) – The IPv6 DNS name of the specified bucket.

  • bucket_name (Optional[str]) – The name of the bucket. If the underlying value of ARN is a string, the name will be parsed from the ARN. Otherwise, the name is optional, but some features that require the bucket name such as auto-creating a bucket policy, won’t work.

  • bucket_regional_domain_name (Optional[str]) – The regional domain name of the specified bucket.

  • bucket_website_new_url_format (Optional[bool]) – (deprecated) Force the format of the website URL of the bucket. This should be true for regions launched since 2014. Default: - inferred from available region information, false otherwise

  • bucket_website_url (Optional[str]) – The website URL of the bucket (if static web hosting is enabled). Default: - Inferred from bucket name and region

  • encryption_key (Optional[IKey]) – KMS encryption key associated with this bucket. Default: - no encryption key

  • is_website (Optional[bool]) – If this bucket has been configured for static website hosting. Default: false

  • notifications_handler_role (Optional[IRole]) – The role to be used by the notifications handler. Default: - a new role will be created.

  • region (Optional[str]) – The region this existing bucket is in. Features that require the region (e.g. bucketWebsiteUrl) won’t fully work if the region cannot be correctly inferred. Default: - it’s assumed the bucket is in the same region as the scope it’s being imported into

Return type:

IBucket

classmethod from_bucket_name(scope, id, bucket_name)
Parameters:
  • scope (Construct) –

  • id (str) –

  • bucket_name (str) –

Return type:

IBucket

classmethod from_cfn_bucket(cfn_bucket)

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

Parameters:

cfn_bucket (CfnBucket) –

Return type:

IBucket

classmethod is_construct(x)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters:

x (Any) – Any object.

Return type:

bool

Returns:

true if x is an object created from a class which extends Construct.

classmethod is_owned_resource(construct)

Returns true if the construct was created by CDK, and false otherwise.

Parameters:

construct (IConstruct) –

Return type:

bool

classmethod is_resource(construct)

Check whether the given construct is a Resource.

Parameters:

construct (IConstruct) –

Return type:

bool

classmethod validate_bucket_name(physical_name)

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

Parameters:

physical_name (str) – name of the bucket.

Return type:

None