Interface IBucket

Inherited Members
Namespace: Amazon.CDK.AWS.S3
Assembly: Amazon.CDK.Lib.dll
Syntax (csharp)
public interface IBucket : IResource, IBucketRef, IConstruct, IDependable, IEnvironmentAware
Syntax (vb)
Public Interface IBucket Inherits IResource, IBucketRef, IConstruct, IDependable, IEnvironmentAware

Synopsis

Properties

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

Optional KMS encryption key associated with this bucket.
IsWebsite

If this bucket has been configured for static website hosting.
Policy

The resource policy associated with this bucket.
ReplicationRoleArn

Role used to set up permissions on this bucket for replication.

Methods

AddEventNotification(EventType, IBucketNotificationDestination, params INotificationKeyFilter[])

Adds a bucket notification event destination.
AddObjectCreatedNotification(IBucketNotificationDestination, params INotificationKeyFilter[])

Subscribes a destination to receive notifications when an object is created in the bucket.
AddObjectRemovedNotification(IBucketNotificationDestination, params INotificationKeyFilter[])

Subscribes a destination to receive notifications when an object is removed from the bucket.
AddReplicationPolicy(string, bool?, string?)

Function to add required permissions to the destination bucket for cross account replication.
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.
ArnForObjects(string)

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

Enables event bridge notification, causing all events below to be sent to EventBridge:.
GrantDelete(IGrantable, object?)

Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.
GrantPublicAccess(string?, params 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).
GrantReplicationPermission(IGrantable, IGrantReplicationPermissionProps)

Allows permissions for replication operation to bucket replication role.
GrantWrite(IGrantable, object?, string[]?)

Grant write permissions to this bucket to an IAM principal.
OnCloudTrailEvent(string, IOnCloudTrailBucketEventOptions?)

Defines a CloudWatch event that triggers when something happens to this bucket.
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.
TransferAccelerationUrlForObject(string?, ITransferAccelerationUrlOptions?)

The https Transfer Acceleration URL of an S3 object.
UrlForObject(string?)

The https URL of an S3 object. For example:.
VirtualHostedUrlForObject(string?, IVirtualHostedStyleUrlOptions?)

The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.

Properties

BucketArn

The ARN of the bucket.

string BucketArn { get; }
Property Value

string

Remarks

Attribute: true

BucketDomainName

The IPv4 DNS name of the specified bucket.

string BucketDomainName { get; }
Property Value

string

Remarks

Attribute: true

BucketDualStackDomainName

The IPv6 DNS name of the specified bucket.

string BucketDualStackDomainName { get; }
Property Value

string

Remarks

Attribute: true

BucketName

The name of the bucket.

string BucketName { get; }
Property Value

string

Remarks

Attribute: true

BucketRegionalDomainName

The regional domain name of the specified bucket.

string BucketRegionalDomainName { get; }
Property Value

string

Remarks

Attribute: true

BucketWebsiteDomainName

The Domain name of the static website.

string BucketWebsiteDomainName { get; }
Property Value

string

Remarks

Attribute: true

BucketWebsiteUrl

The URL of the static website.

string BucketWebsiteUrl { get; }
Property Value

string

Remarks

Attribute: true

EncryptionKey

Optional KMS encryption key associated with this bucket.

IKey? EncryptionKey { get; }
Property Value

IKey

IsWebsite

If this bucket has been configured for static website hosting.

bool? IsWebsite { get; }
Property Value

bool?

Policy

The resource policy associated with this bucket.

BucketPolicy? Policy { get; set; }
Property Value

BucketPolicy

Remarks

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

ReplicationRoleArn

Role used to set up permissions on this bucket for replication.

string? ReplicationRoleArn { get; set; }
Property Value

string

Methods

AddEventNotification(EventType, IBucketNotificationDestination, params INotificationKeyFilter[])

Adds a bucket notification event destination.

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

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

Examples
Function myLambda;

            var bucket = new Bucket(this, "MyBucket");
            bucket.AddEventNotification(EventType.OBJECT_CREATED, new LambdaDestination(myLambda), new NotificationKeyFilter { Prefix = "home/myusername/*" });

AddObjectCreatedNotification(IBucketNotificationDestination, params INotificationKeyFilter[])

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

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(s3.EventType.OBJECT_CREATED).

AddObjectRemovedNotification(IBucketNotificationDestination, params INotificationKeyFilter[])

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

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

AddReplicationPolicy(string, bool?, string?)

Function to add required permissions to the destination bucket for cross account replication.

void AddReplicationPolicy(string roleArn, bool? accessControlTransition = null, string? account = null)
Parameters
roleArn string
accessControlTransition bool?
account string
Remarks

These permissions will be added as a resource based policy on the bucket.

See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-accesscontroltranslation.html

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.

IAddToResourcePolicyResult AddToResourcePolicy(PolicyStatement permission)
Parameters
permission PolicyStatement

the policy statement to be added to the bucket's policy.

Returns

IAddToResourcePolicyResult

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.

string ArnForObjects(string keyPattern)
Parameters
keyPattern string
Returns

string

Remarks

To represent all keys, specify "*".

EnableEventBridgeNotification()

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

void EnableEventBridgeNotification()
Remarks

    GrantDelete(IGrantable, object?)

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

    Grant GrantDelete(IGrantable identity, object? objectsKeyPattern = null)
    Parameters
    identity IGrantable

    The principal.

    objectsKeyPattern object

    Restrict the permission to a certain key pattern (default '*').

    Returns

    Grant

    GrantPublicAccess(string?, params string[])

    Allows unrestricted access to objects from this bucket.

    Grant GrantPublicAccess(string? keyPrefix = null, params string[] allowedActions)
    Parameters
    keyPrefix string

    the prefix of S3 object keys (e.g. home/*). Default is "*".

    allowedActions string[]

    the set of S3 actions to allow.

    Returns

    Grant

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

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

    GrantPut(IGrantable, object?)

    Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.

    Grant GrantPut(IGrantable identity, object? objectsKeyPattern = null)
    Parameters
    identity IGrantable

    The principal.

    objectsKeyPattern object

    Restrict the permission to a certain key pattern (default '*').

    Returns

    Grant

    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.

    Grant GrantPutAcl(IGrantable identity, string? objectsKeyPattern = null)
    Parameters
    identity IGrantable

    The principal.

    objectsKeyPattern string

    Restrict the permission to a certain key pattern (default '*').

    Returns

    Grant

    Remarks

    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.

    GrantRead(IGrantable, object?)

    Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

    Grant GrantRead(IGrantable identity, object? objectsKeyPattern = null)
    Parameters
    identity IGrantable

    The principal.

    objectsKeyPattern object

    Restrict the permission to a certain key pattern (default '*').

    Returns

    Grant

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

    Grant GrantReadWrite(IGrantable identity, object? objectsKeyPattern = null)
    Parameters
    identity IGrantable

    The principal.

    objectsKeyPattern object

    Restrict the permission to a certain key pattern (default '*').

    Returns

    Grant

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

    GrantReplicationPermission(IGrantable, IGrantReplicationPermissionProps)

    Allows permissions for replication operation to bucket replication role.

    Grant GrantReplicationPermission(IGrantable identity, IGrantReplicationPermissionProps props)
    Parameters
    identity IGrantable

    The principal.

    props IGrantReplicationPermissionProps

    The properties of the replication source and destination buckets.

    Returns

    Grant

    The iam.Grant object, which represents the grant of permissions.

    Remarks

    If an encryption key is used, permission to use the key for encrypt/decrypt will also be granted.

    GrantWrite(IGrantable, object?, string[]?)

    Grant write permissions to this bucket to an IAM principal.

    Grant GrantWrite(IGrantable identity, object? objectsKeyPattern = null, string[]? allowedActionPatterns = null)
    Parameters
    identity IGrantable

    The principal.

    objectsKeyPattern object

    Restrict the permission to a certain key pattern (default '*').

    allowedActionPatterns string[]

    Restrict the permissions to certain list of action patterns.

    Returns

    Grant

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

    OnCloudTrailEvent(string, IOnCloudTrailBucketEventOptions?)

    Defines a CloudWatch event that triggers when something happens to this bucket.

    Rule OnCloudTrailEvent(string id, IOnCloudTrailBucketEventOptions? options = null)
    Parameters
    id string

    The id of the rule.

    options IOnCloudTrailBucketEventOptions

    Options for adding the rule.

    Returns

    Rule

    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.

    Rule OnCloudTrailPutObject(string id, IOnCloudTrailBucketEventOptions? options = null)
    Parameters
    id string

    The id of the rule.

    options IOnCloudTrailBucketEventOptions

    Options for adding the rule.

    Returns

    Rule

    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.

    Rule OnCloudTrailWriteObject(string id, IOnCloudTrailBucketEventOptions? options = null)
    Parameters
    id string

    The id of the rule.

    options IOnCloudTrailBucketEventOptions

    Options for adding the rule.

    Returns

    Rule

    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.

    string S3UrlForObject(string? key = null)
    Parameters
    key string

    The S3 key of the object.

    Returns

    string

    an ObjectS3Url token

    Remarks

    For example:

      TransferAccelerationUrlForObject(string?, ITransferAccelerationUrlOptions?)

      The https Transfer Acceleration URL of an S3 object.

      string TransferAccelerationUrlForObject(string? key = null, ITransferAccelerationUrlOptions? options = null)
      Parameters
      key string

      The S3 key of the object.

      options ITransferAccelerationUrlOptions

      Options for generating URL.

      Returns

      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. For example:.

        string UrlForObject(string? key = null)
        Parameters
        key string

        The S3 key of the object.

        Returns

        string

        an ObjectS3Url token

        Remarks

          VirtualHostedUrlForObject(string?, IVirtualHostedStyleUrlOptions?)

          The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.

          string VirtualHostedUrlForObject(string? key = null, IVirtualHostedStyleUrlOptions? options = null)
          Parameters
          key string

          The S3 key of the object.

          options IVirtualHostedStyleUrlOptions

          Options for generating URL.

          Returns

          string

          an ObjectS3Url token

          Remarks