Constructs for deploying contents to S3 buckets
Project description
AWS S3 Deployment Construct Library
This is a developer preview (public beta) module. Releases might lack important features and might have future breaking changes.
This API is still under active development and subject to non-backward compatible changes or removal in any future version. Use of the API is not recommended in production environments. Experimental APIs are not subject to the Semantic Versioning model.
Status: Experimental
This library allows populating an S3 bucket with the contents of a .zip file from another S3 bucket or from local disk.
The following example defines a publicly accessible S3 bucket with web hosting enabled and populates it from a local directory on disk.
const websiteBucket = new s3.Bucket(this, 'WebsiteBucket', {
websiteIndexDocument: 'index.html',
publicReadAccess: true
});
new s3deploy.BucketDeployment(this, 'DeployWebsite', {
source: s3deploy.Source.asset('./website-dist'),
destinationBucket: websiteBucket,
destinationKeyPrefix: 'web/static' // optional prefix in destination bucket
});
This is what happens under the hood:
- When this stack is deployed (either via
cdk deploy
or via CI/CD), the contents of the localwebsite-dist
directory will be archived and uploaded to an intermediary assets bucket. - The
BucketDeployment
construct synthesizes a custom CloudFormation resource of typeCustom::CDKBucketDeployment
into the template. The source bucket/key is set to point to the assets bucket. - The custom resource downloads the .zip archive, extracts it and issues
aws s3 sync --delete
against the destination bucket (in this casewebsiteBucket
).
Supported sources
The following source types are supported for bucket deployments:
- Local .zip file:
s3deploy.Source.asset('/path/to/local/file.zip')
- Local directory:
s3deploy.Source.asset('/path/to/local/directory')
- Another bucket:
s3deploy.Source.bucket(bucket, zipObjectKey)
Retain on Delete
By default, the contents of the destination bucket will be deleted when the
BucketDeployment
resource is removed from the stack or when the destination is
changed. You can use the option retainOnDelete: true
to disable this behavior,
in which case the contents will be retained.
Notes
- This library uses an AWS CloudFormation custom resource which about 10MiB in size. The code of this resource is bundled with this library.
- AWS Lambda execution time is limited to 15min. This limits the amount of data which can be deployed into the bucket by this timeout.
- When the
BucketDeployment
is removed from the stack, the contents are retained in the destination bucket (#952). - Bucket deployment only happens during stack create/update. This means that if you wish to update the contents of the destination, you will need to change the source s3 key (or bucket), so that the resource will be updated. This is inline with best practices. If you use local disk assets, this will happen automatically whenever you modify the asset, since the S3 key is based on a hash of the asset contents.
Development
The custom resource is implemented in Python 3.6 in order to be able to leverage
the AWS CLI for "aws sync". The code is under lambda/src
and
unit tests are under lambda/test
.
This package requires Python 3.6 during build time in order to create the custom resource Lambda bundle and test it. It also relies on a few bash scripts, so might be tricky to build on Windows.
Roadmap
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aws-cdk.aws-s3-deployment-1.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8b20738413a50de6a231ee33417f8474b0e72a5e96b001affea510651d98b4d9 |
|
MD5 | b4845df0b93f2c7a0cf5b2ae56954127 |
|
BLAKE2b-256 | fc202477b3f5b982ce1b92f67339744f6a4a82ebb7a834d2b32ed3c619f6096d |
Hashes for aws_cdk.aws_s3_deployment-1.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b5a8811907c26a891552ac2f12f8bdf088f5e7e5731503ecacaf5f3a7e672bcc |
|
MD5 | deaf13c8d8de850603ccd5ba5227a7ea |
|
BLAKE2b-256 | aa20a2d1c5d5cff7f1cb4f5f9293e58e2fbd9acf1825103205db8300e0a19d1b |