@aws-cdk/assets

AWS CDK Assets

Assets are local files or directories which are needed by a CDK app. A common example is a directory which contains the handler code for a Lambda function, but assets can represent any artifact that is needed for the app's operation.

When deploying a CDK app that includes constructs with assets, the CDK toolkit will first upload all the assets to S3, and only then deploy the stacks. The S3 locations of the uploaded assets will be passed in as CloudFormation Parameters to the relevant stacks.

The following JavaScript example defines an directory asset which is archived as a .zip file and uploaded to S3 during deployment.

Example of a ZipDirectoryAsset

The following JavaScript example defines a file asset, which is uploaded as-is to an S3 bucket during deployment.

Example of a FileAsset

Attributes

Asset constructs expose the following deploy-time attributes:

• s3BucketName - the name of the assets S3 bucket.
• s3ObjectKey - the S3 object key of the asset file (whether it's a file or a zip archive)
• s3Url - the S3 URL of the asset (i.e. https://s3.us-east-1.amazonaws.com/mybucket/mykey.zip)

In the following example, the various asset attributes are exported as stack outputs:

Example of referencing an asset

Permissions

IAM roles, users or groups which need to be able to read assets in runtime will should be granted IAM permissions. To do that use the asset.grantRead(principal) method:

The following examples grants an IAM group read permissions on an asset:

Example of granting read access to an asset

How does it work?

When an asset is defined in a construct, a construct metadata entry aws:cdk:asset is emitted with instructions on where to find the asset and what type of packaging to perform (zip or file). Furthermore, the synthesized CloudFormation template will also include two CloudFormation parameters: one for the asset's bucket and one for the asset S3 key. Those parameters are used to reference the deploy-time values of the asset (using { Ref: "Param" }).

Then, when the stack is deployed, the toolkit will package the asset (i.e. zip the directory), calculate an MD5 hash of the contents and will render an S3 key for this asset within the toolkit's asset store. If the file doesn't exist in the asset store, it is uploaded during deployment.

The toolkit's asset store is an S3 bucket created by the toolkit for each environment the toolkit operates in (environment = account + region).

Now, when the toolkit deploys the stack, it will set the relevant CloudFormation Parameters to point to the actual bucket and key for each asset.

Changelog

0.15.0 (2018-11-06)

Bug Fixes

• aws-autoscaling: allow minSize to be set to 0 (#1015) (67f7fa1)
• aws-codebuild: correctly pass the timeout property to CFN when creating a Project. (#1071) (b1322bb)
• aws-codebuild: correctly set S3 path when using it as artifact. (#1072) (f32cba9)
• aws-kms: add output value when exporting an encryption key (#1036) (cb490be)
• Switch from js-yaml to yaml (#1092) (0b132b5)

Features

• don't upload the same asset multiple times (#1011) (35937b6), closes #989
• app-delivery: CI/CD for CDK Stacks (#1022) (f2fe4e9)
• add a new construct library for ECS (#1058) (ae03ddb)
• applets: integrate into toolkit (#1039) (fdabe95), closes #849 #342 #291
• aws-codecommit: use CloudWatch Events instead of polling by default in the CodePipeline Action. (#1026) (d09d30c)
• aws-dynamodb: allow specifying partition/sort keys in props (#1054) (ec87331), closes #1051
• aws-ec2: AmazonLinuxImage supports AL2 (#1081) (97b57a5), closes #1062
• aws-lambda: high level API for event sources (#1063) (1be3442)
• aws-sqs: improvements to IAM grants API (#1052) (6f2475e)
• codepipeline/cfn: Use fewer statements for pipeline permissions (#1009) (8f4c2ab)
• pkglint: Make sure .snk files are ignored (#1049) (53c8d76), closes #643
• toolkit: deployment ui improvements (#1067) (c832eaf)
• Update to CloudFormation resource specification v2.11.0

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• The ec2.Connections object has been changed to be able to manage multiple security groups. The relevant property has been changed from securityGroup to securityGroups (an array of security group objects).
• aws-codecommit: this modifies the default behavior of the CodeCommit Action. It also changes the internal API contract between the aws-codepipeline-api module and the CodePipeline Actions in the service packages.
• applets: The applet schema has changed to allow Multiple applets can be define in one file by structuring the files like this:
• applets: The applet schema has changed to allow definition of multiple applets in the same file.

The schema now looks like this:

applets:
  MyApplet:
    type: ./my-applet-file
    properties:
      property1: value
      ...

By starting an applet specifier with npm://, applet modules can directly be referenced in NPM. You can include a version specifier (@1.2.3) to reference specific versions.

• aws-sqs: queue.grantReceiveMessages has been removed. It is unlikely that this would be sufficient to interact with a queue. Alternatively you can use queue.grantConsumeMessages or queue.grant('sqs:ReceiveMessage') if there's a need to only grant this action.