Protected
autoIndicates if a bucket resource policy should automatically created upon
the first call to addToResourcePolicy
.
Readonly
bucketReadonly
bucketReadonly
bucketReadonly
bucketReadonly
bucketReadonly
bucketReadonly
bucketProtected
Optional
disallowWhether to disallow public access
Optional
Readonly
encryptionOptional KMS encryption key associated with this bucket.
Readonly
envThe 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.
Readonly
idThe ID of the construct with the App suffix.
This should be used in place of id
when trying to reference the construct.
Optional
Readonly
isIf this bucket has been configured for static website hosting.
Readonly
nodeThe tree node.
Protected
Optional
notificationsProtected
Optional
notificationsProtected
Optional
objectProtected
Readonly
physicalReturns a string-encoded token that resolves to the physical name that should be passed to the CloudFormation resource.
This value will resolve to one of the following:
"my-awesome-bucket"
)undefined
, when a name should be generated by CloudFormationOptional
policyThe resource policy associated with this bucket.
If autoCreatePolicy
is true, a BucketPolicy
will be created upon the
first call to addToResourcePolicy(s).
Readonly
stackThe stack in which this resource is defined.
Adds a bucket notification event destination.
The event to trigger the notification
The notification destination (Lambda, SNS Topic or SQS Queue)
Rest
...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.
Subscribes a destination to receive notifications when an object is
created in the bucket. This is identical to calling
onEvent(EventType.OBJECT_CREATED)
.
The notification destination (see onEvent)
Rest
...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)
.
The notification destination (see onEvent)
Rest
...filters: NotificationKeyFilter[]Filters (see onEvent)
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.
the policy statement to be added to the bucket's policy.
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 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
).
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}/*
)
Enables event bridge notification, causing all events below to be sent to EventBridge:
Protected
generateProtected
getReturns an environment-sensitive token that should be used for the
resource's "ARN" attribute (e.g. bucket.bucketArn
).
Normally, this token will resolve to arnAttr
, but if the resource is
referenced across environments, arnComponents
will be used to synthesize
a concrete ARN with the resource's physical name. Make sure to reference
this.physicalName
in arnComponents
.
The CFN attribute which resolves to the ARN of the resource.
Commonly it will be called "Arn" (e.g. resource.attrArn
), but sometimes
it's the CFN resource's ref
.
The format of the ARN of this resource. You must
reference this.physicalName
somewhere within the ARN in order for
cross-environment references to work.
Protected
getReturns an environment-sensitive token that should be used for the
resource's "name" attribute (e.g. bucket.bucketName
).
Normally, this token will resolve to nameAttr
, but if the resource is
referenced across environments, it will be resolved to this.physicalName
,
which will be a concrete name.
The CFN attribute which resolves to the resource's name.
Commonly this is the resource's ref
.
Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.
The principal
Optional
objectsKeyPattern: anyRestrict the permission to a certain key pattern (default '*'). Parameter type is any
but string
should be passed in.
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.
Optional
keyPrefix: stringthe prefix of S3 object keys (e.g. home/*
). Default is "*".
Rest
...allowedActions: string[]the set of S3 actions to allow. Default is "s3:GetObject".
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.
The principal
Optional
objectsKeyPattern: anyRestrict the permission to a certain key pattern (default '*'). Parameter type is any
but string
should be passed in.
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.
The principal
Optional
objectsKeyPattern: stringRestrict the permission to a certain key pattern (default '*')
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.
The principal
Optional
objectsKeyPattern: anyRestrict the permission to a certain key pattern (default '*'). Parameter type is any
but string
should be passed in.
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.
The principal
Optional
objectsKeyPattern: anyRestrict the permission to a certain key pattern (default '*'). Parameter type is any
but string
should be passed in.
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.
The principal
Optional
objectsKeyPattern: anyRestrict the permission to a certain key pattern (default '*'). Parameter type is any
but string
should be passed in.
Optional
allowedActionPatterns: string[]Restrict the permissions to certain list of action patterns
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.
The id of the rule
Optional
options: OnCloudTrailBucketEventOptionsOptions for adding the 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.
The id of the rule
Optional
options: OnCloudTrailBucketEventOptionsOptions for adding the 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.
The id of the rule
Optional
options: OnCloudTrailBucketEventOptionsOptions for adding the rule
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
Optional
key: stringThe S3 key of the object. If not specified, the URL of the bucket is returned.
Optional
options: TransferAccelerationUrlOptionsOptions for generating URL.
an TransferAccelerationUrl token
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
Optional
key: stringThe S3 key of the object. If not specified, the URL of the bucket is returned.
an ObjectS3Url token
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
Optional
key: stringThe S3 key of the object. If not specified, the URL of the bucket is returned.
Optional
options: VirtualHostedStyleUrlOptionsOptions for generating URL.
an ObjectS3Url token
Static
fromStatic
fromCreates a Bucket construct that represents an external bucket.
The parent creating construct (usually this
).
The construct's name.
A BucketAttributes
object. Can be obtained from a call to
bucket.export()
or manually created.
Static
fromStatic
fromStatic
isChecks 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.
Any object
true if x
is an object created from a class which extends Construct
.
Static
isStatic
isStatic
validate
A construct to create a bucket with a "retain" policy to prevent it from being deleted. It will be orphaned instead.