Class BucketBase
Represents an S3 Bucket.
Inherited Members
Namespace: Amazon.CDK.AWS.S3
Assembly: Amazon.CDK.AWS.S3.dll
Syntax (csharp)
public abstract class BucketBase : Resource, IBucket, IResource, IConstruct, IDependableSyntax (vb)
Public MustInherit Class BucketBase
Inherits Resource
Implements IBucket, IResource, IConstruct, IDependableRemarks
Buckets can be either defined within this stack:
new Bucket(this, 'MyBucket', { props });
Or imported from an existing bucket:
Bucket.import(this, 'MyImportedBucket', { bucketArn: ... });
You can also export a bucket and import it into another stack:
const ref = myBucket.export(); Bucket.import(this, 'MyImportedBucket', ref);
Synopsis
Constructors
| BucketBase(ByRefValue) | Used by jsii to construct an instance of this class from a Javascript-owned object reference |
| BucketBase(DeputyBase.DeputyProps) | Used by jsii to construct an instance of this class from DeputyProps |
| BucketBase(Construct, String, IResourceProps) |
Properties
| AutoCreatePolicy | Indicates if a bucket resource policy should automatically created upon the first call to |
| BucketArn | The ARN of the bucket. |
| BucketDomainName | The IPv4 DNS name of the specified bucket. |
| BucketDualStackDomainName | The IPv6 DNS name of the specified bucket. |
| BucketName | The name of the bucket. |
| BucketRegionalDomainName | The regional domain name of the specified bucket. |
| BucketWebsiteDomainName | The Domain name of the static website. |
| BucketWebsiteUrl | The URL of the static website. |
| DisallowPublicAccess | Whether to disallow public access. |
| EncryptionKey | Optional KMS encryption key associated with this bucket. |
| IsWebsite | If this bucket has been configured for static website hosting. |
| NotificationsHandlerRole | |
| Policy | The resource policy associated with this bucket. |
Methods
| AddEventNotification(EventType, IBucketNotificationDestination, INotificationKeyFilter[]) | Adds a bucket notification event destination. |
| AddObjectCreatedNotification(IBucketNotificationDestination, INotificationKeyFilter[]) | Subscribes a destination to receive notifications when an object is created in the bucket. |
| AddObjectRemovedNotification(IBucketNotificationDestination, INotificationKeyFilter[]) | Subscribes a destination to receive notifications when an object is removed from the bucket. |
| AddToResourcePolicy(PolicyStatement) | 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 |
| ArnForObjects(String) | Returns an ARN that represents all objects within the bucket that match the key pattern specified. |
| EnableEventBridgeNotification() | |
| GrantDelete(IGrantable, Object) | Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. |
| GrantPublicAccess(String, String[]) | Allows unrestricted access to objects from this bucket. |
| GrantPut(IGrantable, Object) | Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. |
| GrantPutAcl(IGrantable, String) | Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. |
| GrantRead(IGrantable, Object) | Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). |
| GrantReadWrite(IGrantable, Object) | Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). |
| GrantWrite(IGrantable, Object) | Grant write permissions to this bucket to an IAM principal. |
| OnCloudTrailEvent(String, IOnCloudTrailBucketEventOptions) | Define a CloudWatch event that triggers when something happens to this repository. |
| OnCloudTrailPutObject(String, IOnCloudTrailBucketEventOptions) | 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(String, IOnCloudTrailBucketEventOptions) | Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. |
| S3UrlForObject(String) | The S3 URL of an S3 object. For example:. |
| TransferAccelerationUrlForObject(String, ITransferAccelerationUrlOptions) | The https Transfer Acceleration URL of an S3 object. |
| UrlForObject(String) | The https URL of an S3 object. Specify |
| Validate() | Validate the current construct. |
| VirtualHostedUrlForObject(String, IVirtualHostedStyleUrlOptions) | The virtual hosted-style URL of an S3 object. Specify |
Constructors
BucketBase(ByRefValue)
Used by jsii to construct an instance of this class from a Javascript-owned object reference
protected BucketBase(ByRefValue reference)Parameters
- reference Amazon.JSII.Runtime.Deputy.ByRefValue
The Javascript-owned object reference
BucketBase(DeputyBase.DeputyProps)
Used by jsii to construct an instance of this class from DeputyProps
protected BucketBase(DeputyBase.DeputyProps props)Parameters
- props Amazon.JSII.Runtime.Deputy.DeputyBase.DeputyProps
The deputy props
BucketBase(Construct, String, IResourceProps)
protected BucketBase(Construct scope, string id, IResourceProps props = null)Parameters
- scope Constructs.Construct
- id System.String
- props IResourceProps
Properties
AutoCreatePolicy
Indicates if a bucket resource policy should automatically created upon the first call to addToResourcePolicy.
protected abstract bool AutoCreatePolicy { get; set; }Property Value
System.Boolean
BucketArn
The ARN of the bucket.
public abstract string BucketArn { get; }Property Value
System.String
BucketDomainName
The IPv4 DNS name of the specified bucket.
public abstract string BucketDomainName { get; }Property Value
System.String
BucketDualStackDomainName
The IPv6 DNS name of the specified bucket.
public abstract string BucketDualStackDomainName { get; }Property Value
System.String
BucketName
The name of the bucket.
public abstract string BucketName { get; }Property Value
System.String
BucketRegionalDomainName
The regional domain name of the specified bucket.
public abstract string BucketRegionalDomainName { get; }Property Value
System.String
BucketWebsiteDomainName
The Domain name of the static website.
public abstract string BucketWebsiteDomainName { get; }Property Value
System.String
BucketWebsiteUrl
The URL of the static website.
public abstract string BucketWebsiteUrl { get; }Property Value
System.String
DisallowPublicAccess
Whether to disallow public access.
protected abstract Nullable<bool> DisallowPublicAccess { get; set; }Property Value
System.Nullable<System.Boolean>
EncryptionKey
Optional KMS encryption key associated with this bucket.
public abstract IKey EncryptionKey { get; }Property Value
IsWebsite
If this bucket has been configured for static website hosting.
public abstract Nullable<bool> IsWebsite { get; }Property Value
System.Nullable<System.Boolean>
NotificationsHandlerRole
Policy
The resource policy associated with this bucket.
public abstract BucketPolicy Policy { get; set; }Property Value
Remarks
If autoCreatePolicy is true, a BucketPolicy will be created upon the
first call to addToResourcePolicy(s).
Methods
AddEventNotification(EventType, IBucketNotificationDestination, INotificationKeyFilter[])
Adds a bucket notification event destination.
public virtual void AddEventNotification(EventType event, IBucketNotificationDestination dest, params INotificationKeyFilter[] filters)Parameters
- event EventType
The event to trigger the notification.
- dest IBucketNotificationDestination
The notification destination (Lambda, SNS Topic or SQS Queue).
- filters INotificationKeyFilter[]
S3 object key filter rules to determine which objects trigger this event.
Remarks
Examples
Function myLambda;
var bucket = new Bucket(this, "MyBucket");
bucket.AddEventNotification(EventType.OBJECT_CREATED, new LambdaDestination(myLambda), new NotificationKeyFilter { Prefix = "home/myusername/*" });AddObjectCreatedNotification(IBucketNotificationDestination, INotificationKeyFilter[])
Subscribes a destination to receive notifications when an object is created in the bucket.
public virtual void AddObjectCreatedNotification(IBucketNotificationDestination dest, params INotificationKeyFilter[] filters)Parameters
- dest IBucketNotificationDestination
The notification destination (see onEvent).
- filters INotificationKeyFilter[]
Filters (see onEvent).
Remarks
This is identical to calling
onEvent(EventType.OBJECT_CREATED).
AddObjectRemovedNotification(IBucketNotificationDestination, INotificationKeyFilter[])
Subscribes a destination to receive notifications when an object is removed from the bucket.
public virtual void AddObjectRemovedNotification(IBucketNotificationDestination dest, params INotificationKeyFilter[] filters)Parameters
- dest IBucketNotificationDestination
The notification destination (see onEvent).
- filters INotificationKeyFilter[]
Filters (see onEvent).
Remarks
This is identical to calling
onEvent(EventType.OBJECT_REMOVED).
AddToResourcePolicy(PolicyStatement)
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.
public virtual IAddToResourcePolicyResult AddToResourcePolicy(PolicyStatement permission)Parameters
- permission PolicyStatement
the policy statement to be added to the bucket's policy.
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.
Remarks
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.
ArnForObjects(String)
Returns an ARN that represents all objects within the bucket that match the key pattern specified.
public virtual string ArnForObjects(string keyPattern)Parameters
- keyPattern System.String
Returns
System.String
Remarks
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}/*)
EnableEventBridgeNotification()
protected virtual void EnableEventBridgeNotification()GrantDelete(IGrantable, Object)
Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.
public virtual Grant GrantDelete(IGrantable identity, object objectsKeyPattern = null)Parameters
- identity IGrantable
The principal.
- objectsKeyPattern System.Object
Restrict the permission to a certain key pattern (default '*').
Returns
GrantPublicAccess(String, String[])
Allows unrestricted access to objects from this bucket.
public virtual Grant GrantPublicAccess(string keyPrefix = null, params string[] allowedActions)Parameters
- keyPrefix System.String
the prefix of S3 object keys (e.g.
home/*). Default is "*".- allowedActions System.String[]
the set of S3 actions to allow.
Returns
Remarks
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.
GrantPut(IGrantable, Object)
Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.
public virtual Grant GrantPut(IGrantable identity, object objectsKeyPattern = null)Parameters
- identity IGrantable
The principal.
- objectsKeyPattern System.Object
Restrict the permission to a certain key pattern (default '*').
Returns
Remarks
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(IGrantable, String)
Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.
public virtual Grant GrantPutAcl(IGrantable identity, string objectsKeyPattern = null)Parameters
- identity IGrantable
- objectsKeyPattern System.String
Returns
Remarks
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(IGrantable, Object)
Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
public virtual Grant GrantRead(IGrantable identity, object objectsKeyPattern = null)Parameters
- identity IGrantable
The principal.
- objectsKeyPattern System.Object
Restrict the permission to a certain key pattern (default '*').
Returns
Remarks
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(IGrantable, Object)
Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
public virtual Grant GrantReadWrite(IGrantable identity, object objectsKeyPattern = null)Parameters
- identity IGrantable
- objectsKeyPattern System.Object
Returns
Remarks
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(IGrantable, Object)
Grant write permissions to this bucket to an IAM principal.
public virtual Grant GrantWrite(IGrantable identity, object objectsKeyPattern = null)Parameters
- identity IGrantable
- objectsKeyPattern System.Object
Returns
Remarks
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.
OnCloudTrailEvent(String, IOnCloudTrailBucketEventOptions)
Define a CloudWatch event that triggers when something happens to this repository.
public virtual Rule OnCloudTrailEvent(string id, IOnCloudTrailBucketEventOptions options = null)Parameters
- id System.String
The id of the rule.
- options IOnCloudTrailBucketEventOptions
Options for adding the rule.
Returns
Remarks
Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.
OnCloudTrailPutObject(String, IOnCloudTrailBucketEventOptions)
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.
public virtual Rule OnCloudTrailPutObject(string id, IOnCloudTrailBucketEventOptions options = null)Parameters
- id System.String
The id of the rule.
- options IOnCloudTrailBucketEventOptions
Options for adding the rule.
Returns
Remarks
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(String, IOnCloudTrailBucketEventOptions)
Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.
public virtual Rule OnCloudTrailWriteObject(string id, IOnCloudTrailBucketEventOptions options = null)Parameters
- id System.String
The id of the rule.
- options IOnCloudTrailBucketEventOptions
Options for adding the rule.
Returns
Remarks
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(String)
The S3 URL of an S3 object. For example:.
public virtual string S3UrlForObject(string key = null)Parameters
- key System.String
The S3 key of the object.
Returns
System.String
an ObjectS3Url token
Remarks
TransferAccelerationUrlForObject(String, ITransferAccelerationUrlOptions)
The https Transfer Acceleration URL of an S3 object.
public virtual string TransferAccelerationUrlForObject(string key = null, ITransferAccelerationUrlOptions options = null)Parameters
- key System.String
The S3 key of the object.
- options ITransferAccelerationUrlOptions
Options for generating URL.
Returns
System.String
an TransferAccelerationUrl token
Remarks
Specify dualStack: true at the options
for dual-stack endpoint (connect to the bucket over IPv6). For example:
UrlForObject(String)
The https URL of an S3 object. Specify regional: false at the options for non-regional URLs. For example:.
public virtual string UrlForObject(string key = null)Parameters
- key System.String
The S3 key of the object.
Returns
System.String
an ObjectS3Url token
Remarks
Validate()
Validate the current construct.
protected override string[] Validate()Returns
System.String[]
Overrides
Remarks
This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.
VirtualHostedUrlForObject(String, IVirtualHostedStyleUrlOptions)
The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.
public virtual string VirtualHostedUrlForObject(string key = null, IVirtualHostedStyleUrlOptions options = null)Parameters
- key System.String
The S3 key of the object.
- options IVirtualHostedStyleUrlOptions
Options for generating URL.
Returns
System.String
an ObjectS3Url token