A construct to create a bucket with a "retain" policy to prevent it from being deleted. It will be orphaned instead.

Hierarchy

  • Mixin<typeof Bucket, this> & Bucket<this>
    • GuS3Bucket

Constructors

Properties

autoCreatePolicy: boolean
bucketArn: string
bucketDomainName: string
bucketDualStackDomainName: string
bucketName: string
bucketRegionalDomainName: string
bucketWebsiteDomainName: string
bucketWebsiteUrl: string
disallowPublicAccess?: boolean
encryptionKey?: IKey
env: ResourceEnvironment
idWithApp: string

The ID of the construct with the App suffix. This should be used in place of id when trying to reference the construct.

isWebsite?: boolean
node: Node

The tree node.

notificationsHandlerRole?: IRole
physicalName: string

Returns 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:

  • a concrete value (e.g. "my-awesome-bucket")
  • undefined, when a name should be generated by CloudFormation
  • a concrete name generated automatically during synthesis, in cross-environment scenarios.
policy?: BucketPolicy
stack: Stack

Accessors

  • get putActions(): any
  • Returns any

  • get writeActions(): any
  • Returns any

Methods

  • _enableCrossEnvironment(): void
  • Internal

    Called when this resource is referenced across environments (account/region) to order to request that a physical name will be generated for this resource during synthesis, so the resource can be referenced through it's absolute name/arn.

    Returns void

  • addCorsRule(rule: CorsRule): void
  • Adds a cross-origin access configuration for objects in an Amazon S3 bucket

    Parameters

    • rule: CorsRule

      The CORS configuration rule to add

    Returns void

  • addEventNotification(event: EventType, dest: IBucketNotificationDestination, ...filters: NotificationKeyFilter[]): void
  • Adds a bucket notification event destination.

    See

    Example

    declare const myLambda: lambda.Function;
    const bucket = new s3.Bucket(this, 'MyBucket');
    bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.LambdaDestination(myLambda), {prefix: 'home/myusername/*'});

    Parameters

    • event: EventType

      The event to trigger the notification

    • dest: IBucketNotificationDestination

      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.

    Returns void

  • addInventory(inventory: Inventory): void
  • Add an inventory configuration.

    Parameters

    • inventory: Inventory

      configuration to add

    Returns void

  • addLifecycleRule(rule: LifecycleRule): void
  • Add a lifecycle rule to the bucket

    Parameters

    • rule: LifecycleRule

      The rule to add

    Returns void

  • addMetric(metric: BucketMetrics): void
  • Adds a metrics configuration for the CloudWatch request metrics from the bucket.

    Parameters

    • metric: BucketMetrics

      The metric configuration to add

    Returns void

  • addObjectCreatedNotification(dest: IBucketNotificationDestination, ...filters: NotificationKeyFilter[]): void
  • Subscribes a destination to receive notifications when an object is created in the bucket. This is identical to calling onEvent(EventType.OBJECT_CREATED).

    Parameters

    • dest: IBucketNotificationDestination

      The notification destination (see onEvent)

    • Rest ...filters: NotificationKeyFilter[]

      Filters (see onEvent)

    Returns void

  • addObjectRemovedNotification(dest: IBucketNotificationDestination, ...filters: NotificationKeyFilter[]): void
  • Subscribes a destination to receive notifications when an object is removed from the bucket. This is identical to calling onEvent(EventType.OBJECT_REMOVED).

    Parameters

    • dest: IBucketNotificationDestination

      The notification destination (see onEvent)

    • Rest ...filters: NotificationKeyFilter[]

      Filters (see onEvent)

    Returns void

  • addToResourcePolicy(permission: PolicyStatement): AddToResourcePolicyResult
  • 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.

    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.

    Parameters

    • permission: PolicyStatement

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

    Returns AddToResourcePolicyResult

  • applyRemovalPolicy(policy: RemovalPolicy): void
  • 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

    Returns void

  • arnForObjects(keyPattern: string): string
  • 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

    • keyPattern: string

    Returns string

  • enableEventBridgeNotification(): void
  • Returns void

  • generatePhysicalName(): string
  • Returns string

  • getResourceArnAttribute(arnAttr: string, arnComponents: ArnComponents): string
  • Returns 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.

    Parameters

    • arnAttr: string

      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.

    • arnComponents: ArnComponents

      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.

    Returns string

  • getResourceNameAttribute(nameAttr: string): string
  • Returns 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.

    Parameters

    • nameAttr: string

      The CFN attribute which resolves to the resource's name. Commonly this is the resource's ref.

    Returns string

  • grantDelete(identity: IGrantable, objectsKeyPattern?: any): Grant
  • Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.

    Parameters

    • identity: IGrantable

      The principal

    • Optional objectsKeyPattern: any

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

    Returns Grant

  • grantPublicAccess(keyPrefix?: string, ...allowedActions: string[]): Grant
  • 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

    • Optional keyPrefix: string

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

    • Rest ...allowedActions: string[]

      the set of S3 actions to allow. Default is "s3:GetObject".

    Returns Grant

  • grantPut(identity: IGrantable, objectsKeyPattern?: any): Grant
  • 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

    • Optional objectsKeyPattern: any

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

    Returns Grant

  • grantPutAcl(identity: IGrantable, objectsKeyPattern?: string): Grant
  • Parameters

    • identity: IGrantable
    • Optional objectsKeyPattern: string

    Returns Grant

  • grantRead(identity: IGrantable, objectsKeyPattern?: any): Grant
  • 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

    • Optional objectsKeyPattern: any

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

    Returns Grant

  • grantReadWrite(identity: IGrantable, objectsKeyPattern?: any): Grant
  • Parameters

    • identity: IGrantable
    • Optional objectsKeyPattern: any

    Returns Grant

  • grantWrite(identity: IGrantable, objectsKeyPattern?: any): Grant
  • Parameters

    • identity: IGrantable
    • Optional objectsKeyPattern: any

    Returns Grant

  • onCloudTrailEvent(id: string, options?: OnCloudTrailBucketEventOptions): Rule
  • 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: string

      The id of the rule

    • Optional options: OnCloudTrailBucketEventOptions

      Options for adding the rule

    Returns Rule

  • onCloudTrailPutObject(id: string, options?: OnCloudTrailBucketEventOptions): 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.

    Parameters

    • id: string

      The id of the rule

    • Optional options: OnCloudTrailBucketEventOptions

      Options for adding the rule

    Returns Rule

  • onCloudTrailWriteObject(id: string, options?: OnCloudTrailBucketEventOptions): 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.

    Parameters

    • id: string

      The id of the rule

    • Optional options: OnCloudTrailBucketEventOptions

      Options for adding the rule

    Returns Rule

  • s3UrlForObject(key?: string): string
  • The S3 URL of an S3 object. For example:

    • s3://onlybucket
    • s3://bucket/key

    Returns

    an ObjectS3Url token

    Parameters

    • Optional key: string

      The S3 key of the object. If not specified, the S3 URL of the bucket is returned.

    Returns string

  • toString(): string
  • Returns a string representation of an object.

    Returns string

  • transferAccelerationUrlForObject(key?: string, options?: TransferAccelerationUrlOptions): string
  • 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

    Returns

    an TransferAccelerationUrl token

    Parameters

    • Optional key: string

      The S3 key of the object. If not specified, the URL of the bucket is returned.

    • Optional options: TransferAccelerationUrlOptions

      Options for generating URL.

    Returns string

  • urlForObject(key?: string): string
  • 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

    Returns

    an ObjectS3Url token

    Parameters

    • Optional key: string

      The S3 key of the object. If not specified, the URL of the bucket is returned.

    Returns string

  • virtualHostedUrlForObject(key?: string, options?: VirtualHostedStyleUrlOptions): string
  • 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

    Returns

    an ObjectS3Url token

    Parameters

    • Optional key: string

      The S3 key of the object. If not specified, the URL of the bucket is returned.

    • Optional options: VirtualHostedStyleUrlOptions

      Options for generating URL.

    Returns string

  • fromBucketArn(scope: Construct, id: string, bucketArn: string): IBucket
  • Parameters

    • scope: Construct
    • id: string
    • bucketArn: string

    Returns IBucket

  • fromBucketAttributes(scope: Construct, id: string, attrs: BucketAttributes): IBucket
  • Creates a Bucket construct that represents an external bucket.

    Parameters

    • scope: Construct

      The parent creating construct (usually this).

    • id: string

      The construct's name.

    • attrs: BucketAttributes

      A BucketAttributes object. Can be obtained from a call to bucket.export() or manually created.

    Returns IBucket

  • fromBucketName(scope: Construct, id: string, bucketName: string): IBucket
  • Parameters

    • scope: Construct
    • id: string
    • bucketName: string

    Returns IBucket

  • isConstruct(x: any): x is Construct
  • 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.

    Returns

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

    Parameters

    • x: any

      Any object

    Returns x is Construct

  • isResource(construct: IConstruct): construct is CfnResource
  • Check whether the given construct is a Resource

    Parameters

    • construct: IConstruct

    Returns construct is CfnResource

  • validateBucketName(physicalName: string): void
  • Thrown an exception if the given bucket name is not valid.

    Parameters

    • physicalName: string

      name of the bucket.

    Returns void

Generated using TypeDoc