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/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.

const asset = new assets.ZipDirectoryAsset(this, 'SampleAsset', {
  path: path.join(__dirname, 'sample-asset-directory')
});

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

const asset = new assets.FileAsset(this, 'SampleAsset', {
  path: path.join(__dirname, 'file-asset.txt')
});

Attributes

Asset constructs expose the following deploy-time attributes:

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

const asset = new assets.ZipDirectoryAsset(this, 'SampleAsset', {
  path: path.join(__dirname, 'sample-asset-directory')
});

new cdk.Output(this, 'S3BucketName', { value: asset.s3BucketName });
new cdk.Output(this, 'S3ObjectKey', { value: asset.s3ObjectKey });
new cdk.Output(this, 'S3URL', { value: asset.s3Url });

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:

const group = new iam.Group(this, 'MyUserGroup');
asset.grantRead(group);

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.

CloudFormation Resource Metadata

NOTE: This section is relevant for authors of AWS Resource Constructs.

In certain situations, it is desirable for tools to be able to know that a certain CloudFormation resource is using a local asset. For example, SAM CLI can be used to invoke AWS Lambda functions locally for debugging purposes.

To enable such use cases, external tools will consult a set of metadata entries on AWS CloudFormation resources:

  • aws:asset:path points to the local path of the asset.
  • aws:asset:property is the name of the resource property where the asset is used

Using these two metadata entries, tools will be able to identify that assets are used by a certain resource, and enable advanced local experiences.

To add these metadata entries to a resource, use the asset.addResourceMetadata(resource, property) method.

See https://github.com/awslabs/aws-cdk/issues/1432 for more details

Reference

View in Nuget

csproj:

<PackageReference Include="Amazon.CDK.Assets" Version="0.22.0" />

dotnet:

dotnet add package Amazon.CDK.Assets --version 0.22.0

packages.config:

<package id="Amazon.CDK.Assets" version="0.22.0" />

View in Maven Central

Apache Buildr:

'software.amazon.awscdk:cdk-assets:jar:0.22.0'

Apache Ivy:

<dependency groupId="software.amazon.awscdk" name="cdk-assets" rev="0.22.0"/>

Apache Maven:

<dependency>
  <groupId>software.amazon.awscdk</groupId>
  <artifactId>cdk-assets</artifactId>
  <version>0.22.0</version>
</dependency>

Gradle / Grails:

compile 'software.amazon.awscdk:cdk-assets:0.22.0'

Groovy Grape:

@Grapes(
@Grab(group='software.amazon.awscdk', module='cdk-assets', version='0.22.0')
)

View in NPM

npm:

$ npm i @aws-cdk/assets@0.22.0

package.json:

{
  "@aws-cdk/assets": "^0.22.0"
}

yarn:

$ yarn add @aws-cdk/assets@0.22.0

View in NPM

npm:

$ npm i @aws-cdk/assets@0.22.0

package.json:

{
  "@aws-cdk/assets": "^0.22.0"
}

yarn:

$ yarn add @aws-cdk/assets@0.22.0

Asset

class @aws-cdk/assets.Asset(scope, id, props)

Language-specific names:

using Amazon.CDK.Assets;
import software.amazon.awscdk.assets.Asset;
const { Asset } = require('@aws-cdk/assets');
import { Asset } from '@aws-cdk/assets';

An asset represents a local file or directory, which is automatically uploaded to S3

and then can be referenced within a CDK application.

Extends:

@aws-cdk/cdk.Construct

Parameters:
addResourceMetadata(resource, resourceProperty)

Adds CloudFormation template metadata to the specified resource with

information that indicates which resource property is mapped to this local

asset. This can be used by tools such as SAM CLI to provide local

experience such as local invocation and debugging of Lambda functions.

Asset metadata will only be included if the stack is synthesized with the

“aws:cdk:enable-asset-metadata” context key defined, which is the default

behavior when synthesizing via the CDK Toolkit.

Parameters:
  • resource (@aws-cdk/cdk.Resource) – The CloudFormation resource which is using this asset.
  • resourceProperty (string) – The property name where this asset is referenced (e.g. “Code” for AWS::Lambda::Function)
grantRead([principal])

Grants read permissions to the principal on the asset’s S3 object.

Parameters:principal (@aws-cdk/aws-iam.IPrincipal (optional)) –
assetPath

Resolved full-path location of this asset.

Type:string (readonly)
bucket

The S3 bucket in which this asset resides.

Type:@aws-cdk/aws-s3.IBucket (readonly)
isZipArchive

Indicates if this asset is a zip archive. Allows constructs to ensure that the

correct file type was used.

Type:boolean (readonly)
s3BucketName

Attribute that represents the name of the bucket this asset exists in.

Type:string (readonly)
s3ObjectKey

Attribute which represents the S3 object key of this asset.

Type:string (readonly)
s3Url

Attribute which represents the S3 URL of this asset.

Type:string (readonly)
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[]
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

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

AssetPackaging (enum)

class @aws-cdk/assets.AssetPackaging

Language-specific names:

using Amazon.CDK.Assets;
import software.amazon.awscdk.assets.AssetPackaging;
const { AssetPackaging } = require('@aws-cdk/assets');
import { AssetPackaging } from '@aws-cdk/assets';

Defines the way an asset is packaged before it is uploaded to S3.

ZipDirectory

Path refers to a directory on disk, the contents of the directory is

archived into a .zip.

File

Path refers to a single file on disk. The file is uploaded as-is.

FileAsset

class @aws-cdk/assets.FileAsset(scope, id, props)

Language-specific names:

using Amazon.CDK.Assets;
import software.amazon.awscdk.assets.FileAsset;
const { FileAsset } = require('@aws-cdk/assets');
import { FileAsset } from '@aws-cdk/assets';

An asset that represents a file on disk.

Extends:

Asset

Parameters:
addResourceMetadata(resource, resourceProperty)

Inherited from @aws-cdk/assets.Asset

Adds CloudFormation template metadata to the specified resource with

information that indicates which resource property is mapped to this local

asset. This can be used by tools such as SAM CLI to provide local

experience such as local invocation and debugging of Lambda functions.

Asset metadata will only be included if the stack is synthesized with the

“aws:cdk:enable-asset-metadata” context key defined, which is the default

behavior when synthesizing via the CDK Toolkit.

Parameters:
  • resource (@aws-cdk/cdk.Resource) – The CloudFormation resource which is using this asset.
  • resourceProperty (string) – The property name where this asset is referenced (e.g. “Code” for AWS::Lambda::Function)
grantRead([principal])

Inherited from @aws-cdk/assets.Asset

Grants read permissions to the principal on the asset’s S3 object.

Parameters:principal (@aws-cdk/aws-iam.IPrincipal (optional)) –
assetPath

Inherited from @aws-cdk/assets.Asset

Resolved full-path location of this asset.

Type:string (readonly)
bucket

Inherited from @aws-cdk/assets.Asset

The S3 bucket in which this asset resides.

Type:@aws-cdk/aws-s3.IBucket (readonly)
isZipArchive

Inherited from @aws-cdk/assets.Asset

Indicates if this asset is a zip archive. Allows constructs to ensure that the

correct file type was used.

Type:boolean (readonly)
s3BucketName

Inherited from @aws-cdk/assets.Asset

Attribute that represents the name of the bucket this asset exists in.

Type:string (readonly)
s3ObjectKey

Inherited from @aws-cdk/assets.Asset

Attribute which represents the S3 object key of this asset.

Type:string (readonly)
s3Url

Inherited from @aws-cdk/assets.Asset

Attribute which represents the S3 URL of this asset.

Type:string (readonly)
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[]
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

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

FileAssetProps (interface)

class @aws-cdk/assets.FileAssetProps

Language-specific names:

using Amazon.CDK.Assets;
import software.amazon.awscdk.assets.FileAssetProps;
// FileAssetProps is an interface
import { FileAssetProps } from '@aws-cdk/assets';
path

File path.

Type:string
readers

A list of principals that should be able to read this file asset from S3.

You can use asset.grantRead(principal) to grant read permissions later.

Type:@aws-cdk/aws-iam.IPrincipal[] (optional)

GenericAssetProps (interface)

class @aws-cdk/assets.GenericAssetProps

Language-specific names:

using Amazon.CDK.Assets;
import software.amazon.awscdk.assets.GenericAssetProps;
// GenericAssetProps is an interface
import { GenericAssetProps } from '@aws-cdk/assets';
packaging

The packaging type for this asset.

Type:AssetPackaging
path

The disk location of the asset.

Type:string
readers

A list of principals that should be able to read this asset from S3.

You can use asset.grantRead(principal) to grant read permissions later.

Type:@aws-cdk/aws-iam.IPrincipal[] (optional)

ZipDirectoryAsset

class @aws-cdk/assets.ZipDirectoryAsset(scope, id, props)

Language-specific names:

using Amazon.CDK.Assets;
import software.amazon.awscdk.assets.ZipDirectoryAsset;
const { ZipDirectoryAsset } = require('@aws-cdk/assets');
import { ZipDirectoryAsset } from '@aws-cdk/assets';

An asset that represents a ZIP archive of a directory on disk.

Extends:

Asset

Parameters:
addResourceMetadata(resource, resourceProperty)

Inherited from @aws-cdk/assets.Asset

Adds CloudFormation template metadata to the specified resource with

information that indicates which resource property is mapped to this local

asset. This can be used by tools such as SAM CLI to provide local

experience such as local invocation and debugging of Lambda functions.

Asset metadata will only be included if the stack is synthesized with the

“aws:cdk:enable-asset-metadata” context key defined, which is the default

behavior when synthesizing via the CDK Toolkit.

Parameters:
  • resource (@aws-cdk/cdk.Resource) – The CloudFormation resource which is using this asset.
  • resourceProperty (string) – The property name where this asset is referenced (e.g. “Code” for AWS::Lambda::Function)
grantRead([principal])

Inherited from @aws-cdk/assets.Asset

Grants read permissions to the principal on the asset’s S3 object.

Parameters:principal (@aws-cdk/aws-iam.IPrincipal (optional)) –
assetPath

Inherited from @aws-cdk/assets.Asset

Resolved full-path location of this asset.

Type:string (readonly)
bucket

Inherited from @aws-cdk/assets.Asset

The S3 bucket in which this asset resides.

Type:@aws-cdk/aws-s3.IBucket (readonly)
isZipArchive

Inherited from @aws-cdk/assets.Asset

Indicates if this asset is a zip archive. Allows constructs to ensure that the

correct file type was used.

Type:boolean (readonly)
s3BucketName

Inherited from @aws-cdk/assets.Asset

Attribute that represents the name of the bucket this asset exists in.

Type:string (readonly)
s3ObjectKey

Inherited from @aws-cdk/assets.Asset

Attribute which represents the S3 object key of this asset.

Type:string (readonly)
s3Url

Inherited from @aws-cdk/assets.Asset

Attribute which represents the S3 URL of this asset.

Type:string (readonly)
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[]
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

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

ZipDirectoryAssetProps (interface)

class @aws-cdk/assets.ZipDirectoryAssetProps

Language-specific names:

using Amazon.CDK.Assets;
import software.amazon.awscdk.assets.ZipDirectoryAssetProps;
// ZipDirectoryAssetProps is an interface
import { ZipDirectoryAssetProps } from '@aws-cdk/assets';
path

Path of the directory.

Type:string
readers

A list of principals that should be able to read this ZIP file from S3.

You can use asset.grantRead(principal) to grant read permissions later.

Type:@aws-cdk/aws-iam.IPrincipal[] (optional)