IBucket¶
-
class
aws_cdk.aws_s3.
IBucket
(*args, **kwds)¶ Bases:
aws_cdk.core.IResource
,typing_extensions.Protocol
Methods
-
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 it’s contents. Use
bucketArn
andarnForObjects(keys)
to obtain ARNs for this bucket or objects.- Parameters
permission (
PolicyStatement
) –- Return type
-
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_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
- 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_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_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_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 includeds3: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 totrue
in thecontext
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_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 includeds3: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 totrue
in thecontext
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
-
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 objectsdescription (
Optional
[str
]) – A description of the rule’s purpose. Default: - No descriptionevent_pattern (
Optional
[EventPattern
]) – 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. UseaddTarget()
to add a target.
- Return type
-
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 usingonCloudTrailWriteObject
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 objectsdescription (
Optional
[str
]) – A description of the rule’s purpose. Default: - No descriptionevent_pattern (
Optional
[EventPattern
]) – 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. UseaddTarget()
to add a target.
- Return type
-
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 toonCloudTrailPutObject
.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 objectsdescription (
Optional
[str
]) – A description of the rule’s purpose. Default: - No descriptionevent_pattern (
Optional
[EventPattern
]) – 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. UseaddTarget()
to add a target.
- Return type
-
s3_url_for_object
(key=None)¶ The S3 URL of an S3 object.
For example:
- 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
Example:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826 s3:
-
url_for_object
(key=None)¶ The https URL of an S3 object.
For example:
- 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
Example:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826 https:
-
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:- 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
Example:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826 https:
Attributes
-
bucket_arn
¶ The ARN of the bucket.
- Attribute
true
- Return type
str
-
bucket_domain_name
¶ The IPv4 DNS name of the specified bucket.
- Attribute
true
- Return type
str
-
bucket_dual_stack_domain_name
¶ The IPv6 DNS name of the specified bucket.
- Attribute
true
- Return type
str
-
bucket_name
¶ The name of the bucket.
- Attribute
true
- Return type
str
-
bucket_regional_domain_name
¶ The regional domain name of the specified bucket.
- Attribute
true
- Return type
str
-
bucket_website_domain_name
¶ The Domain name of the static website.
- Attribute
true
- Return type
str
-
bucket_website_url
¶ The URL of the static website.
- Attribute
true
- Return type
str
-
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.
- Return type
-
is_website
¶ If this bucket has been configured for static website hosting.
- Return type
Optional
[bool
]
-
node
¶ The construct tree node for this construct.
- Return type
-
policy
¶ The resource policy associated with this bucket.
If
autoCreatePolicy
is true, aBucketPolicy
will be created upon the first call to addToResourcePolicy(s).- Return type
Optional
[BucketPolicy
]
-