This documentation is for the developer preview release of the AWS CDK. Do not use this version of the AWS CDK in production. Subsequent releases of the AWS CDK will likely include breaking changes.

@aws-cdk/aws-s3-deployment

AWS S3 Deployment Construct Library

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:

  1. When this stack is deployed (either via cdk deploy or via CI/CD), the contents of the local website-dist directory will be archived and uploaded to an intermediary assets bucket.
  2. The BucketDeployment construct synthesizes a custom CloudFormation resource of type Custom::CDKBucketDeployment into the template. The source bucket/key is set to point to the assets bucket.
  3. The custom resource downloads the .zip archive, extracts it and issues aws s3 sync --delete against the destination bucket (in this case websiteBucket).

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` <./lambda/src>`_ and unit tests are under ``lambda/test` <./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

  • [ ] Support “progressive” mode (no --delete) (#953)
  • [ ] Support “blue/green” deployments (#954)

Reference

View in Nuget

csproj:

<PackageReference Include="Amazon.CDK.AWS.S3.Deployment" Version="0.25.3" />

dotnet:

dotnet add package Amazon.CDK.AWS.S3.Deployment --version 0.25.3

packages.config:

<package id="Amazon.CDK.AWS.S3.Deployment" version="0.25.3" />

View in Maven Central

Apache Buildr:

'software.amazon.awscdk:s3-deployment:jar:0.25.3'

Apache Ivy:

<dependency groupId="software.amazon.awscdk" name="s3-deployment" rev="0.25.3"/>

Apache Maven:

<dependency>
  <groupId>software.amazon.awscdk</groupId>
  <artifactId>s3-deployment</artifactId>
  <version>0.25.3</version>
</dependency>

Gradle / Grails:

compile 'software.amazon.awscdk:s3-deployment:0.25.3'

Groovy Grape:

@Grapes(
@Grab(group='software.amazon.awscdk', module='s3-deployment', version='0.25.3')
)

View in NPM

npm:

$ npm i @aws-cdk/aws-s3-deployment@0.25.3

package.json:

{
  "@aws-cdk/aws-s3-deployment": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/aws-s3-deployment@0.25.3

View in NPM

npm:

$ npm i @aws-cdk/aws-s3-deployment@0.25.3

package.json:

{
  "@aws-cdk/aws-s3-deployment": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/aws-s3-deployment@0.25.3

BucketDeployment

class @aws-cdk/aws-s3-deployment.BucketDeployment(scope, id, props)

Language-specific names:

using Amazon.CDK.AWS.S3.Deployment;
import software.amazon.awscdk.services.s3.deployment.BucketDeployment;
const { BucketDeployment } = require('@aws-cdk/aws-s3-deployment');
import { BucketDeployment } from '@aws-cdk/aws-s3-deployment';
Extends:

@aws-cdk/cdk.Construct

Parameters:
prepare()

Inherited from @aws-cdk/cdk.Construct

Perform final modifications before synthesis

This method can be implemented by derived constructs in order to perform

final changes before synthesis. prepare() will be called after child

constructs have been prepared.

This is an advanced framework feature. Only use this if you

understand the implications.

Protected method

toString() → string

Inherited from @aws-cdk/cdk.Construct

Returns a string representation of this construct.

Return type:string
validate() → string[]

Inherited from @aws-cdk/cdk.Construct

Validate the current construct.

This method can be implemented by derived constructs in order to perform

validation logic. It is called on all constructs before synthesis.

Protected method

Returns:An array of validation error messages, or an empty array if there the construct is valid.
Return type:string[]
dependencyRoots

Inherited from @aws-cdk/cdk.Construct

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering

dependency.

Type:@aws-cdk/cdk.IConstruct[] (readonly)
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

Type:@aws-cdk/cdk.ConstructNode (readonly)

BucketDeploymentProps (interface)

class @aws-cdk/aws-s3-deployment.BucketDeploymentProps

Language-specific names:

using Amazon.CDK.AWS.S3.Deployment;
import software.amazon.awscdk.services.s3.deployment.BucketDeploymentProps;
// BucketDeploymentProps is an interface
import { BucketDeploymentProps } from '@aws-cdk/aws-s3-deployment';
destinationBucket

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

Type:@aws-cdk/aws-s3.IBucket
source

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

Type:ISource
destinationKeyPrefix

Key prefix in the destination bucket.

Type:string (optional)
Default:“/” (unzip to root of the destination bucket)
retainOnDelete

If this is set to “false”, the destination files will be deleted when the

resource is deleted or the destination is updated.

NOTICE: if this is set to “false” and destination bucket/prefix is updated,

all files in the previous destination will first be deleted and then

uploaded to the new destination location. This could have availablity

implications on your users.

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

ISource (interface)

class @aws-cdk/aws-s3-deployment.ISource

Language-specific names:

using Amazon.CDK.AWS.S3.Deployment;
import software.amazon.awscdk.services.s3.deployment.ISource;
// ISource is an interface
import { ISource } from '@aws-cdk/aws-s3-deployment';

Represents a source for bucket deployments.

bind(context) → @aws-cdk/aws-s3-deployment.SourceProps

Binds the source to a bucket deployment.

Parameters:context (@aws-cdk/cdk.Construct) – The construct tree context.
Return type:SourceProps
Abstract:Yes

Source

class @aws-cdk/aws-s3-deployment.Source

Language-specific names:

using Amazon.CDK.AWS.S3.Deployment;
import software.amazon.awscdk.services.s3.deployment.Source;
const { Source } = require('@aws-cdk/aws-s3-deployment');
import { Source } from '@aws-cdk/aws-s3-deployment';

Specifies bucket deployment source.

Usage:

Source.bucket(bucket, key)

Source.asset(‘/local/path/to/directory’)

Source.asset(‘/local/path/to/a/file.zip’)

static asset(path) → @aws-cdk/aws-s3-deployment.ISource

Uses a local asset as the deployment source.

Parameters:path (string) – The path to a local .zip file or a directory
Return type:ISource
static bucket(bucket, zipObjectKey) → @aws-cdk/aws-s3-deployment.ISource

Uses a .zip file stored in an S3 bucket as the source for the destination bucket contents.

Parameters:
  • bucket (@aws-cdk/aws-s3.IBucket) – The S3 Bucket
  • zipObjectKey (string) – The S3 object key of the zip file with contents
Return type:

ISource

SourceProps (interface)

class @aws-cdk/aws-s3-deployment.SourceProps

Language-specific names:

using Amazon.CDK.AWS.S3.Deployment;
import software.amazon.awscdk.services.s3.deployment.SourceProps;
// SourceProps is an interface
import { SourceProps } from '@aws-cdk/aws-s3-deployment';
bucket

The source bucket to deploy from.

Type:@aws-cdk/aws-s3.IBucket
zipObjectKey

An S3 object key in the source bucket that points to a zip file.

Type:string