aws-cdk-lib.aws_s3_deployment.BucketDeployment

class BucketDeployment (construct)

LanguageType name
.NETAmazon.CDK.AWS.S3.Deployment.BucketDeployment
Gogithub.com/aws/aws-cdk-go/awscdk/v2/awss3deployment#BucketDeployment
Javasoftware.amazon.awscdk.services.s3.deployment.BucketDeployment
Pythonaws_cdk.aws_s3_deployment.BucketDeployment
TypeScript (source)aws-cdk-lib » aws_s3_deployment » BucketDeployment

Implements IConstruct, IDependable

BucketDeployment populates an S3 bucket with the contents of .zip files from other S3 buckets or from local disk.

Example

declare const websiteBucket: s3.Bucket;

const deployment = new s3deploy.BucketDeployment(this, 'DeployWebsite', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket: websiteBucket,
});

new ConstructThatReadsFromTheBucket(this, 'Consumer', {
  // Use 'deployment.deployedBucket' instead of 'websiteBucket' here
  bucket: deployment.deployedBucket,
});

Initializer

new BucketDeployment(scope: Construct, id: string, props: BucketDeploymentProps)

Parameters

  • scope Construct
  • id string
  • props BucketDeploymentProps

Construct Props

NameTypeDescription
destinationBucketIBucketThe S3 bucket to sync the contents of the zip file to.
sourcesISource[]The sources from which to deploy the contents of this bucket.
accessControl?BucketAccessControlSystem-defined x-amz-acl metadata to be set on all objects in the deployment.
cacheControl?CacheControl[]System-defined cache-control metadata to be set on all objects in the deployment.
contentDisposition?stringSystem-defined cache-disposition metadata to be set on all objects in the deployment.
contentEncoding?stringSystem-defined content-encoding metadata to be set on all objects in the deployment.
contentLanguage?stringSystem-defined content-language metadata to be set on all objects in the deployment.
contentType?stringSystem-defined content-type metadata to be set on all objects in the deployment.
destinationKeyPrefix?stringKey prefix in the destination bucket.
distribution?IDistributionThe CloudFront distribution using the destination bucket as an origin.
distributionPaths?string[]The file paths to invalidate in the CloudFront distribution.
ephemeralStorageSize?SizeThe size of the AWS Lambda function’s /tmp directory in MiB.
exclude?string[]If this is set, matching files or objects will be excluded from the deployment's sync command.
expires?ExpirationSystem-defined expires metadata to be set on all objects in the deployment.
extract?booleanIf this is set, the zip file will be synced to the destination S3 bucket and extracted.
include?string[]If this is set, matching files or objects will be included with the deployment's sync command.
logRetention?RetentionDaysThe number of days that the lambda function's log events are kept in CloudWatch Logs.
memoryLimit?numberThe amount of memory (in MiB) to allocate to the AWS Lambda function which replicates the files from the CDK bucket to the destination bucket.
metadata?{ [string]: string }User-defined object metadata to be set on all objects in the deployment.
prune?booleanIf this is set to false, files in the destination bucket that do not exist in the asset, will NOT be deleted during deployment (create/update).
retainOnDelete?booleanIf this is set to "false", the destination files will be deleted when the resource is deleted or the destination is updated.
role?IRoleExecution role associated with this function.
serverSideEncryption?ServerSideEncryptionSystem-defined x-amz-server-side-encryption metadata to be set on all objects in the deployment.
serverSideEncryptionAwsKmsKeyId?stringSystem-defined x-amz-server-side-encryption-aws-kms-key-id metadata to be set on all objects in the deployment.
serverSideEncryptionCustomerAlgorithm?stringSystem-defined x-amz-server-side-encryption-customer-algorithm metadata to be set on all objects in the deployment.
signContent?booleanIf set to true, uploads will precompute the value of x-amz-content-sha256 and include it in the signed S3 request headers.
storageClass?StorageClassSystem-defined x-amz-storage-class metadata to be set on all objects in the deployment.
useEfs?booleanMount an EFS file system.
vpc?IVpcThe VPC network to place the deployment lambda handler in.
vpcSubnets?SubnetSelectionWhere in the VPC to place the deployment lambda handler.
websiteRedirectLocation?stringSystem-defined x-amz-website-redirect-location metadata to be set on all objects in the deployment.

destinationBucket

Type: IBucket

The S3 bucket to sync the contents of the zip file to.


sources

Type: ISource[]

The sources from which to deploy the contents of this bucket.


accessControl?

Type: BucketAccessControl (optional, default: Not set.)

System-defined x-amz-acl metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl


cacheControl?

Type: CacheControl[] (optional, default: Not set.)

System-defined cache-control metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


contentDisposition?

Type: string (optional, default: Not set.)

System-defined cache-disposition metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


contentEncoding?

Type: string (optional, default: Not set.)

System-defined content-encoding metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


contentLanguage?

Type: string (optional, default: Not set.)

System-defined content-language metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


contentType?

Type: string (optional, default: Not set.)

System-defined content-type metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


destinationKeyPrefix?

Type: string (optional, default: "/" (unzip to root of the destination bucket))

Key prefix in the destination bucket.

Must be <=104 characters


distribution?

Type: IDistribution (optional, default: No invalidation occurs)

The CloudFront distribution using the destination bucket as an origin.

Files in the distribution's edge caches will be invalidated after files are uploaded to the destination bucket.


distributionPaths?

Type: string[] (optional, default: All files under the destination bucket key prefix will be invalidated.)

The file paths to invalidate in the CloudFront distribution.


ephemeralStorageSize?

Type: Size (optional, default: 512 MiB)

The size of the AWS Lambda function’s /tmp directory in MiB.


exclude?

Type: string[] (optional, default: No exclude filters are used)

If this is set, matching files or objects will be excluded from the deployment's sync command.

This can be used to exclude a file from being pruned in the destination bucket.

If you want to just exclude files from the deployment package (which excludes these files evaluated when invalidating the asset), you should leverage the exclude property of AssetOptions when defining your source.

See also: https://docs.aws.amazon.com/cli/latest/reference/s3/index.html#use-of-exclude-and-include-filters


expires?

Type: Expiration (optional, default: The objects in the distribution will not expire.)

System-defined expires metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


extract?

Type: boolean (optional, default: true)

If this is set, the zip file will be synced to the destination S3 bucket and extracted.

If false, the file will remain zipped in the destination bucket.


include?

Type: string[] (optional, default: No include filters are used and all files are included with the sync command)

If this is set, matching files or objects will be included with the deployment's sync command.

Since all files from the deployment package are included by default, this property is usually leveraged alongside an exclude filter.

See also: https://docs.aws.amazon.com/cli/latest/reference/s3/index.html#use-of-exclude-and-include-filters


logRetention?

Type: RetentionDays (optional, default: logs.RetentionDays.INFINITE)

The number of days that the lambda function's log events are kept in CloudWatch Logs.


memoryLimit?

Type: number (optional, default: 128)

The amount of memory (in MiB) to allocate to the AWS Lambda function which replicates the files from the CDK bucket to the destination bucket.

If you are deploying large files, you will need to increase this number accordingly.


metadata?

Type: { [string]: string } (optional, default: No user metadata is set)

User-defined object metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#UserMetadata


prune?

Type: boolean (optional, default: true)

If this is set to false, files in the destination bucket that do not exist in the asset, will NOT be deleted during deployment (create/update).

See also: https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html


retainOnDelete?

Type: boolean (optional, default: true - when resource is deleted/updated, files are retained)

If this is set to "false", the destination files will be deleted when the resource is deleted or the destination is updated.

NOTICE: Configuring this to "false" might have operational implications. Please visit to the package documentation referred below to make sure you fully understand those implications.

See also: https://github.com/aws/aws-cdk/tree/main/packages/%40aws-cdk/aws-s3-deployment#retain-on-delete


role?

Type: IRole (optional, default: A role is automatically created)

Execution role associated with this function.


serverSideEncryption?

Type: ServerSideEncryption (optional, default: Server side encryption is not used.)

System-defined x-amz-server-side-encryption metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


serverSideEncryptionAwsKmsKeyId?

Type: string (optional, default: Not set.)

System-defined x-amz-server-side-encryption-aws-kms-key-id metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


serverSideEncryptionCustomerAlgorithm?

Type: string (optional, default: Not set.)

System-defined x-amz-server-side-encryption-customer-algorithm metadata to be set on all objects in the deployment.

Warning: This is not a useful parameter until this bug is fixed: https://github.com/aws/aws-cdk/issues/6080

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/ServerSideEncryptionCustomerKeys.html#sse-c-how-to-programmatically-intro


signContent?

Type: boolean (optional, default: x-amz-content-sha256 will not be computed)

If set to true, uploads will precompute the value of x-amz-content-sha256 and include it in the signed S3 request headers.


storageClass?

Type: StorageClass (optional, default: Default storage-class for the bucket is used.)

System-defined x-amz-storage-class metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata


useEfs?

Type: boolean (optional, default: No EFS. Lambda has access only to 512MB of disk space.)

Mount an EFS file system.

Enable this if your assets are large and you encounter disk space errors. Enabling this option will require a VPC to be specified.


vpc?

Type: IVpc (optional, default: None)

The VPC network to place the deployment lambda handler in.

This is required if useEfs is set.


vpcSubnets?

Type: SubnetSelection (optional, default: the Vpc default strategy if not specified)

Where in the VPC to place the deployment lambda handler.

Only used if 'vpc' is supplied.


websiteRedirectLocation?

Type: string (optional, default: No website redirection.)

System-defined x-amz-website-redirect-location metadata to be set on all objects in the deployment.

See also: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#SysMetadata

Properties

NameTypeDescription
deployedBucketIBucketThe bucket after the deployment.
nodeNodeThe tree node.
objectKeysstring[]The object keys for the sources deployed to the S3 bucket.

deployedBucket

Type: IBucket

The bucket after the deployment.

If you want to reference the destination bucket in another construct and make sure the bucket deployment has happened before the next operation is started, pass the other construct a reference to deployment.deployedBucket.

Note that this only returns an immutable reference to the destination bucket. If sequenced access to the original destination bucket is required, you may add a dependency on the bucket deployment instead: otherResource.node.addDependency(deployment)


node

Type: Node

The tree node.


objectKeys

Type: string[]

The object keys for the sources deployed to the S3 bucket.

This returns a list of tokenized object keys for source files that are deployed to the bucket.

This can be useful when using BucketDeployment with extract set to false and you need to reference the object key that resides in the bucket for that zip source file somewhere else in your CDK application, such as in a CFN output.

For example, use Fn.select(0, myBucketDeployment.objectKeys) to reference the object key of the first source file in your bucket deployment.

Methods

NameDescription
addSource(source)Add an additional source to the bucket deployment.
toString()Returns a string representation of this construct.

addSource(source)

public addSource(source: ISource): void

Parameters

  • source ISource

Add an additional source to the bucket deployment. Example

declare const websiteBucket: s3.IBucket;
const deployment = new s3deploy.BucketDeployment(this, 'Deployment', {
  sources: [s3deploy.Source.asset('./website-dist')],
  destinationBucket: websiteBucket,
});

deployment.addSource(s3deploy.Source.asset('./another-asset'));

toString()

public toString(): string

Returns

  • string

Returns a string representation of this construct.