BucketDeployment

class aws_cdk.aws_s3_deployment.BucketDeployment(scope, id, *, destination_bucket, sources, access_control=None, cache_control=None, content_disposition=None, content_encoding=None, content_language=None, content_type=None, destination_key_prefix=None, distribution=None, distribution_paths=None, ephemeral_storage_size=None, exclude=None, expires=None, extract=None, include=None, log_group=None, log_retention=None, memory_limit=None, metadata=None, prune=None, retain_on_delete=None, role=None, server_side_encryption=None, server_side_encryption_aws_kms_key_id=None, server_side_encryption_customer_algorithm=None, sign_content=None, storage_class=None, use_efs=None, vpc=None, vpc_subnets=None, website_redirect_location=None)

Bases: Construct

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

ExampleMetadata:

infused

Example:

# website_bucket: s3.Bucket


deployment = s3deploy.BucketDeployment(self, "DeployWebsite",
    sources=[s3deploy.Source.asset(path.join(__dirname, "my-website"))],
    destination_bucket=website_bucket
)

ConstructThatReadsFromTheBucket(self, "Consumer", {
    # Use 'deployment.deployedBucket' instead of 'websiteBucket' here
    "bucket": deployment.deployed_bucket
})
Parameters:

  • scope (Construct) –

  • id (str) –

  • destination_bucket (IBucket) – The S3 bucket to sync the contents of the zip file to.

  • sources (Sequence[ISource]) – The sources from which to deploy the contents of this bucket.

  • access_control (Optional[BucketAccessControl]) – System-defined x-amz-acl metadata to be set on all objects in the deployment. Default: - Not set.

  • cache_control (Optional[Sequence[CacheControl]]) – System-defined cache-control metadata to be set on all objects in the deployment. Default: - Not set.

  • content_disposition (Optional[str]) – System-defined cache-disposition metadata to be set on all objects in the deployment. Default: - Not set.

  • content_encoding (Optional[str]) – System-defined content-encoding metadata to be set on all objects in the deployment. Default: - Not set.

  • content_language (Optional[str]) – System-defined content-language metadata to be set on all objects in the deployment. Default: - Not set.

  • content_type (Optional[str]) – System-defined content-type metadata to be set on all objects in the deployment. Default: - Not set.

  • destination_key_prefix (Optional[str]) – Key prefix in the destination bucket. Must be <=104 characters Default: “/” (unzip to root of the destination bucket)

  • distribution (Optional[IDistribution]) – 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. Default: - No invalidation occurs

  • distribution_paths (Optional[Sequence[str]]) – The file paths to invalidate in the CloudFront distribution. Default: - All files under the destination bucket key prefix will be invalidated.

  • ephemeral_storage_size (Optional[Size]) – The size of the AWS Lambda function’s /tmp directory in MiB. Default: 512 MiB

  • exclude (Optional[Sequence[str]]) – 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. Default: - No exclude filters are used

  • expires (Optional[Expiration]) – System-defined expires metadata to be set on all objects in the deployment. Default: - The objects in the distribution will not expire.

  • extract (Optional[bool]) – 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. Default: true

  • include (Optional[Sequence[str]]) – 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. Default: - No include filters are used and all files are included with the sync command

  • log_group (Optional[ILogGroup]) – The Log Group used for logging of events emitted by the custom resource’s lambda function. Providing a user-controlled log group was rolled out to commercial regions on 2023-11-16. If you are deploying to another type of region, please check regional availability first. Default: - a default log group created by AWS Lambda

  • log_retention (Optional[RetentionDays]) – The number of days that the lambda function’s log events are kept in CloudWatch Logs. This is a legacy API and we strongly recommend you migrate to logGroup if you can. logGroup allows you to create a fully customizable log group and instruct the Lambda function to send logs to it. Default: logs.RetentionDays.INFINITE

  • memory_limit (Union[int, float, None]) – 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. Default: 128

  • metadata (Optional[Mapping[str, str]]) – User-defined object metadata to be set on all objects in the deployment. Default: - No user metadata is set

  • prune (Optional[bool]) – 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). Default: true

  • retain_on_delete (Optional[bool]) – 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. Default: true - when resource is deleted/updated, files are retained

  • role (Optional[IRole]) – Execution role associated with this function. Default: - A role is automatically created

  • server_side_encryption (Optional[ServerSideEncryption]) – System-defined x-amz-server-side-encryption metadata to be set on all objects in the deployment. Default: - Server side encryption is not used.

  • server_side_encryption_aws_kms_key_id (Optional[str]) – System-defined x-amz-server-side-encryption-aws-kms-key-id metadata to be set on all objects in the deployment. Default: - Not set.

  • server_side_encryption_customer_algorithm (Optional[str]) – 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 Default: - Not set.

  • sign_content (Optional[bool]) – If set to true, uploads will precompute the value of x-amz-content-sha256 and include it in the signed S3 request headers. Default: - x-amz-content-sha256 will not be computed

  • storage_class (Optional[StorageClass]) – System-defined x-amz-storage-class metadata to be set on all objects in the deployment. Default: - Default storage-class for the bucket is used.

  • use_efs (Optional[bool]) – 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. Default: - No EFS. Lambda has access only to 512MB of disk space.

  • vpc (Optional[IVpc]) – The VPC network to place the deployment lambda handler in. This is required if useEfs is set. Default: None

  • vpc_subnets (Union[SubnetSelection, Dict[str, Any], None]) – Where in the VPC to place the deployment lambda handler. Only used if ‘vpc’ is supplied. Default: - the Vpc default strategy if not specified

  • website_redirect_location (Optional[str]) – System-defined x-amz-website-redirect-location metadata to be set on all objects in the deployment. Default: - No website redirection.

Methods

add_source(source)

Add an additional source to the bucket deployment.

Parameters:

source (ISource) –

Return type:

None

Example:

# website_bucket: s3.IBucket

deployment = s3deploy.BucketDeployment(self, "Deployment",
    sources=[s3deploy.Source.asset("./website-dist")],
    destination_bucket=website_bucket
)

deployment.add_source(s3deploy.Source.asset("./another-asset"))
to_string()

Returns a string representation of this construct.

Return type:

str

Attributes

deployed_bucket

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)

handler_role

Execution role of the Lambda function behind the custom CloudFormation resource of type Custom::CDKBucketDeployment.

node

The tree node.

object_keys

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.

Static Methods

classmethod is_construct(x)

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.

Parameters:

x (Any) – Any object.

Return type:

bool

Returns:

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