This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.
Assets are local files, directories, or Docker images that can be bundled into AWS CDK libraries and apps. For example, an asset might be a directory that contains the handler code for an AWS Lambda function. Assets can represent any artifact that the app needs to operate.
The following tutorial video provides a comprehensive overview of CDK assets, and explains how you can use them in your insfrastructure as code (IaC).
You add assets through APIs that are exposed by specific AWS constructs. For example, when you define a lambda.Function
construct, the code property lets you pass an asset (directory).
Function uses assets to bundle the contents of the directory and use it for the function's code.
Similarly, ecs.ContainerImage.fromAsset uses a Docker image built from a local directory when defining an Amazon ECS task
definition.
Assets in detail
When you refer to an asset in your app, the cloud assembly that's synthesized from your application includes metadata information with instructions for the AWS CDK CLI. The instructions include where to find the asset on the local disk and what type of bundling to perform based on the asset type, such as a directory to compress (zip) or a Docker image to build.
The AWS CDK generates a source hash for assets. This can be used at construction time to determine whether the contents of an asset have changed.
By default, the AWS CDK creates a copy of the asset in the cloud assembly directory, which defaults to
cdk.out, under the source hash. This way, the cloud assembly is self-contained, so if it moved
over to a different host for deployment, it can still be deployed. See Cloud assemblies for
details.
When the AWS CDK deploys an app that references assets (either directly by the app code or through a library), the AWS CDK CLI first prepares and publishes the assets to an Amazon S3 bucket or Amazon ECR repository. (The S3 bucket or repository is created during bootstrapping.) Only then are the resources defined in the stack deployed.
This section describes the low-level APIs available in the framework.
Asset types
The AWS CDK supports the following types of assets:
- Amazon S3 assets
-
These are local files and directories that the AWS CDK uploads to Amazon S3.
- Docker Image
-
These are Docker images that the AWS CDK uploads to Amazon ECR.
These asset types are explained in the following sections.
Amazon S3 assets
You can define local files and directories as assets, and the AWS CDK packages and uploads them to Amazon S3 through the aws-s3-assets module.
The following example defines a local directory asset and a file asset.
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
// Archived and uploaded to Amazon S3 as a .zip file
const directoryAsset = new Asset(this, "SampleZippedDirAsset", {
path: path.join(__dirname, "sample-asset-directory")
});
// Uploaded to Amazon S3 as-is
const fileAsset = new Asset(this, 'SampleSingleFileAsset', {
path: path.join(__dirname, 'file-asset.txt')
});In most cases, you don't need to directly use the APIs in the aws-s3-assets module. Modules that
support assets, such as aws-lambda, have convenience methods so that you can use assets. For Lambda
functions, the fromAsset()
static method enables you to specify a directory or a .zip file in the local file system.
Lambda function example
A common use case is creating Lambda functions with the handler code as an Amazon S3 asset.
The following example uses an Amazon S3 asset to define a Python handler in the local directory
handler. It also creates a Lambda function with the local directory asset as the
code property. Following is the Python code for the handler.
def lambda_handler(event, context):
message = 'Hello World!'
return {
'message': message
}The code for the main AWS CDK app should look like the following.
import * as cdk from 'aws-cdk-lib';
import { Constructs } from 'constructs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as path from 'path';
export class HelloAssetStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
new lambda.Function(this, 'myLambdaFunction', {
code: lambda.Code.fromAsset(path.join(__dirname, 'handler')),
runtime: lambda.Runtime.PYTHON_3_6,
handler: 'index.lambda_handler'
});
}
}The Function method uses assets to bundle the contents of the directory and use it for the
function's code.
Tip
Java .jar files are ZIP files with a different extension. These are uploaded as-is to
Amazon S3, but when deployed as a Lambda function, the files they contain are extracted, which you might not want. To
avoid this, place the .jar file in a directory and specify that directory as the asset.
Deploy-time attributes example
Amazon S3 asset types also expose deploy-time attributes that can be referenced in AWS CDK libraries and apps. The AWS CDK CLI command cdk synth displays asset properties as AWS CloudFormation parameters.
The following example uses deploy-time attributes to pass the location of an image asset into a Lambda function as environment variables. (The kind of file doesn't matter; the PNG image used here is only an example.)
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
import * as path from 'path';
const imageAsset = new Asset(this, "SampleAsset", {
path: path.join(__dirname, "images/my-image.png")
});
new lambda.Function(this, "myLambdaFunction", {
code: lambda.Code.asset(path.join(__dirname, "handler")),
runtime: lambda.Runtime.PYTHON_3_6,
handler: "index.lambda_handler",
environment: {
'S3_BUCKET_NAME': imageAsset.s3BucketName,
'S3_OBJECT_KEY': imageAsset.s3ObjectKey,
'S3_OBJECT_URL': imageAsset.s3ObjectUrl
}
});Permissions
If you use Amazon S3 assets directly through the aws-s3-assets module, IAM roles, users, or groups, and you need to read assets in runtime, then grant those assets IAM permissions through the asset.grantRead method.
The following example grants an IAM group read permissions on a file asset.
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
import * as path from 'path';
const asset = new Asset(this, 'MyFile', {
path: path.join(__dirname, 'my-image.png')
});
const group = new iam.Group(this, 'MyUserGroup');
asset.grantRead(group);Docker image assets
The AWS CDK supports bundling local Docker images as assets through the aws-ecr-assets module.
The following example defines a Docker image that is built locally and pushed to Amazon ECR. Images are built from a local Docker context directory (with a Dockerfile) and uploaded to Amazon ECR by the AWS CDK CLI or your app's CI/CD pipeline. The images can be naturally referenced in your AWS CDK app.
import { DockerImageAsset } from 'aws-cdk-lib/aws-ecr-assets';
const asset = new DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image')
});The my-image directory must include a Dockerfile. The AWS CDK CLI builds a Docker image from
my-image, pushes it to an Amazon ECR repository, and specifies the name of the repository as an AWS CloudFormation
parameter to your stack. Docker image asset types expose deploy-time
attributes that can be referenced in AWS CDK libraries and apps. The AWS CDK CLI command cdk
synth displays asset properties as AWS CloudFormation parameters.
Amazon ECS task definition example
A common use case is to create an Amazon ECS TaskDefinition to run Docker containers. The following example specifies the location of a Docker image asset that the AWS CDK builds locally and pushes to Amazon ECR.
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as ecr_assets from 'aws-cdk-lib/aws-ecr-assets';
import * as path from 'path';
const taskDefinition = new ecs.FargateTaskDefinition(this, "TaskDef", {
memoryLimitMiB: 1024,
cpu: 512
});
const asset = new ecr_assets.DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image')
});
taskDefinition.addContainer("my-other-container", {
image: ecs.ContainerImage.fromDockerImageAsset(asset)
});Deploy-time attributes example
The following example shows how to use the deploy-time attributes repository and
imageUri to create an Amazon ECS task definition with the AWS Fargate launch type. Note that the Amazon ECR
repo lookup requires the image's tag, not its URI, so we snip it from the end of the asset's URI.
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as path from 'path';
import { DockerImageAsset } from 'aws-cdk-lib/aws-ecr-assets';
const asset = new DockerImageAsset(this, 'my-image', {
directory: path.join(__dirname, "..", "demo-image")
});
const taskDefinition = new ecs.FargateTaskDefinition(this, "TaskDef", {
memoryLimitMiB: 1024,
cpu: 512
});
taskDefinition.addContainer("my-other-container", {
image: ecs.ContainerImage.fromEcrRepository(asset.repository, asset.imageUri.split(":").pop())
});Build arguments example
You can provide customized build arguments for the Docker build step through the buildArgs (Python:
build_args) property option when the AWS CDK CLI builds the image during deployment.
const asset = new DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image'),
buildArgs: {
HTTP_PROXY: 'http://10.20.30.2:1234'
}
});Permissions
If you use a module that supports Docker image assets, such as aws-ecs, the AWS CDK manages permissions for you when
you use assets directly or through ContainerImage.fromEcrRepository (Python: from_ecr_repository). If you use Docker image
assets directly, make sure that the consuming principal has permissions to pull the image.
In most cases, you should use asset.repository.grantPull method (Python: grant_pull. This modifies the IAM policy of the
principal to enable it to pull images from this repository. If the principal that is pulling the image is not in the
same account, or if it's an AWS service that doesn't assume a role in your account (such as AWS CodeBuild), you must
grant pull permissions on the resource policy and not on the principal's policy. Use the asset.repository.addToResourcePolicy method (Python: add_to_resource_policy) to grant the
appropriate principal permissions.
AWS CloudFormation resource metadata
Note
This section is relevant only for construct authors. In certain situations, tools need to know that a certain CFN resource is using a local asset. For example, you can use the AWS SAM CLI to invoke Lambda functions locally for debugging purposes. See AWS SAM integration for details.
To enable such use cases, external tools consult a set of metadata entries on AWS CloudFormation resources:
-
aws:asset:path– Points to the local path of the asset. -
aws:asset:property– The name of the resource property where the asset is used.
Using these two metadata entries, tools can 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 (Python:
add_resource_metadata) method.
